@reticlehq/server 3.9.0 → 3.10.0

package/dist/features/exhaust/session-port.js

@@ -6,11 +6,22 @@
  * rejected. So every call reads the CURRENT session, and anything that may have navigated waits for
  * the successor before it answers — the same wait `navigate { reload }` does.
  */
-import { ActionType, ReticleCommand, ReticleTool, SnapshotMode, asRecord, asString, } from '@reticlehq/core';
+import { ActionType, EventType, ReticleCommand, ReticleTool, SnapshotMode, asNumber, asRecord, asString, } from '@reticlehq/core';
 import { RELOAD_RECONNECT_TIMEOUT_MS, waitForReconnect, } from '../../portal/session/session-reconnect.js';
 import { isSessionReplacedError } from '../../portal/session/facts/session-replaced.js';
+import { FIELD_ATTRS } from './explorer.js';
+/** How long a press waits for the requests it started to answer. */
+export const PENDING_WAIT_MS = 10_000;
+const PENDING_POLL_MS = 100;
+/** A request that was sent and has not answered: a `net.pending` with no `net.request` of its id. */
+function inFlight(events) {
+    const answered = new Set(events.filter((e) => EventType.NET_REQUEST === e.type).map((e) => asString(e.data['id'])));
+    return events.some((e) => EventType.NET_PENDING === e.type && !answered.has(asString(e.data['id'])));
+}
 export function sessionPort(input) {
     let current = input.start;
+    /** The URL the page had before the last action, for `back`. */
+    let lastUrl;
     /** Wait for the document that replaced `before`. False when none arrived in time. */
     const successor = async (before) => {
         const back = await waitForReconnect({
@@ -21,77 +32,135 @@ export function sessionPort(input) {
             sleep: input.sleep,
         });
         const next = input.sessions.get(before.id);
-        if (!back || next === undefined)
+        if (!back || next === undefined) {
             return false;
+        }
         current = next;
         return true;
     };
-    const look = async () => {
+    const read = async (mode) => {
         for (let attempt = 0; attempt < 2; attempt += 1) {
             try {
-                const res = await current.command(ReticleCommand.SNAPSHOT, {
-                    mode: SnapshotMode.INTERACTIVE,
-                });
+                const res = await current.command(ReticleCommand.SNAPSHOT, { mode });
                 const body = asRecord(res.result);
                 const route = asString(asRecord(body['status'])['route']);
                 return { tree: asString(body['tree']) ?? '', ...(route === undefined ? {} : { route }) };
             }
             catch (error) {
                 // A click that followed a real link leaves the next read on a dead document.
-                if (!isSessionReplacedError(error) || !(await successor(current)))
+                if (!isSessionReplacedError(error) || !(await successor(current))) {
                     break;
+                }
             }
         }
         return { tree: '' };
     };
+    /** Send a command that replaces the document, then wait for the new one and let it settle. */
+    const load = async (name, args) => {
+        const was = current;
+        try {
+            const res = await was.command(name, args);
+            if (!res.ok) {
+                return false;
+            }
+        }
+        catch (error) {
+            if (!isSessionReplacedError(error)) {
+                return false;
+            }
+        }
+        if (!(await successor(was))) {
+            return false;
+        }
+        await input.sleep(input.settleMs);
+        return true;
+    };
     return {
         current: () => current,
-        look,
-        async reset() {
-            const before = current;
+        look: () => read(SnapshotMode.INTERACTIVE),
+        lookFull: () => read(SnapshotMode.FULL),
+        reset: () => load(ReticleCommand.NAVIGATE, { url: input.startUrl }),
+        reload: () => load(ReticleCommand.REFRESH, {}),
+        // ponytail: a load of the URL the page had before the last action, not the browser's history
+        // back, which no page command sends. An app that keeps state in its history entries comes back
+        // fresh here; add a history command if a finding needs it.
+        back: () => lastUrl === undefined
+            ? Promise.resolve(false)
+            : load(ReticleCommand.NAVIGATE, { url: lastUrl }),
+        async fieldAttrs(control) {
+            const [, role, name] = /^(\S+)(?:\s+"((?:[^"\\]|\\.)*)")?/.exec(control) ?? [];
+            if (role === undefined) {
+                return undefined;
+            }
             try {
-                const res = await before.command(ReticleCommand.NAVIGATE, { url: input.startUrl });
-                if (!res.ok)
-                    return false;
+                const res = await current.command(ReticleCommand.QUERY, {
+                    role,
+                    ...(name === undefined ? {} : { name }),
+                    attrs: [...FIELD_ATTRS],
+                });
+                const first = asRecord(res.result)['elements'];
+                const attrs = Array.isArray(first) ? asRecord(asRecord(first[0])['attrs']) : {};
+                const out = {};
+                for (const [key, value] of Object.entries(attrs)) {
+                    if ('string' === typeof value) {
+                        out[key] = value;
+                    }
+                }
+                return out;
             }
-            catch (error) {
-                if (!isSessionReplacedError(error))
-                    return false;
+            catch {
+                return undefined;
             }
-            if (!(await successor(before)))
-                return false;
-            await input.sleep(input.settleMs);
-            return true;
         },
-        async act(ref, action, value) {
+        async act(ref, action, value, opts) {
             const session = current;
+            lastUrl = session.url;
             const since = session.elapsed();
             session.beginAction?.(ReticleTool.CRAWL, { ref, action });
             let ok = false;
             let replaced = false;
+            let source;
             try {
                 const res = await session.command(ReticleCommand.ACT, {
                     ref,
                     action: 'fill' === action ? ActionType.FILL : ActionType.CLICK,
                     args: value === undefined ? {} : { value },
                 });
-                ok = res.ok && false !== asRecord(res.result)['dispatched'];
+                const body = asRecord(res.result);
+                ok = res.ok && false !== body['dispatched'];
+                const src = asRecord(body['source']);
+                const file = asString(src['file']);
+                const line = asNumber(src['line']);
+                source = file === undefined || line === undefined ? undefined : { file, line };
             }
             catch (error) {
                 // Following a real link replaces the document mid-command: the click WORKED.
-                if (!isSessionReplacedError(error))
+                if (!isSessionReplacedError(error)) {
                     throw error;
+                }
                 replaced = true;
                 ok = true;
             }
             finally {
                 session.finishAction?.();
             }
-            await input.sleep(input.settleMs);
-            const events = session.eventsSince(since);
-            if (replaced && (await successor(session)))
-                return { ok, events: [...events, ...current.eventsSince(0)] };
-            return { ok, events };
+            let events = session.eventsSince(since);
+            if (false !== opts?.settle) {
+                await input.sleep(input.settleMs);
+                events = session.eventsSince(since);
+                // A slow write answers long after the page settles. Wait for the requests this press
+                // started, up to a bound, so its answer, its error and a second copy are in its events.
+                const poll = Math.max(input.settleMs, PENDING_POLL_MS);
+                for (let i = 0; i < Math.floor(PENDING_WAIT_MS / poll) && inFlight(events); i += 1) {
+                    await input.sleep(poll);
+                    events = session.eventsSince(since);
+                }
+            }
+            const found = source === undefined ? {} : { source };
+            if (replaced && (await successor(session))) {
+                return { ok, events: [...events, ...current.eventsSince(0)], ...found };
+            }
+            return { ok, events, ...found };
         },
         ...(input.setMocks === undefined
             ? {}

package/dist/features/grade/grade-answer.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Check a run's final answer against a value read from the app when the grade runs. Pure.
+ *
+ * A fixed answer string goes stale when the data changes. Here the expected answer is the output of
+ * a declared source (a database query, an endpoint), read at grade time. A source with no rows means
+ * that the task cannot be done, and the answer must be one of the `none` words (default `N/A`).
+ *
+ * Match kinds. Text is folded first: Unicode normal form, lower case, spacing, quotes and a final
+ * full stop.
+ * - `exact`: the answer is the one expected value. With more than one row, it is `set`.
+ * - `number`: the answer is one number, and nothing else. `$`, `%` and digit-group commas are
+ *   removed. It equals the first value within 0.005.
+ * - `set`: the answer is a list, split on commas, semicolons and new lines, or also on " and ". It
+ *   holds each expected value one time and nothing more. Order is not checked.
+ * - `includes`: the answer contains each expected value. A long answer that names every record
+ *   also passes, so use it only where the answer cannot list all choices.
+ */
+import { z } from 'zod';
+export declare const AnswerMatch: {
+    readonly EXACT: "exact";
+    readonly NUMBER: "number";
+    readonly SET: "set";
+    readonly INCLUDES: "includes";
+};
+export type AnswerMatch = (typeof AnswerMatch)[keyof typeof AnswerMatch];
+/** The default answer for a task that cannot be done. */
+export declare const DEFAULT_NONE = "N/A";
+export declare const AnswerSpecSchema: z.ZodObject<{
+    source: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"command">;
+        label: z.ZodString;
+        command: z.ZodString;
+        container: z.ZodOptional<z.ZodString>;
+        ignore: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"http">;
+        label: z.ZodString;
+        url: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        ignore: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"file">;
+        label: z.ZodString;
+        path: z.ZodString;
+        at: z.ZodOptional<z.ZodString>;
+        container: z.ZodOptional<z.ZodString>;
+        ignore: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>], "kind">;
+    match: z.ZodDefault<z.ZodEnum<{
+        number: "number";
+        includes: "includes";
+        set: "set";
+        exact: "exact";
+    }>>;
+    none: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type AnswerSpec = z.infer<typeof AnswerSpecSchema>;
+/** The `--expect` file of `reticle grade judge`. */
+export declare const ExpectSchema: z.ZodObject<{
+    answer: z.ZodObject<{
+        source: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"command">;
+            label: z.ZodString;
+            command: z.ZodString;
+            container: z.ZodOptional<z.ZodString>;
+            ignore: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"http">;
+            label: z.ZodString;
+            url: z.ZodString;
+            path: z.ZodOptional<z.ZodString>;
+            ignore: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"file">;
+            label: z.ZodString;
+            path: z.ZodString;
+            at: z.ZodOptional<z.ZodString>;
+            container: z.ZodOptional<z.ZodString>;
+            ignore: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>], "kind">;
+        match: z.ZodDefault<z.ZodEnum<{
+            number: "number";
+            includes: "includes";
+            set: "set";
+            exact: "exact";
+        }>>;
+        none: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export interface AnswerCheck {
+    ok: boolean;
+    /** The expected answer, as text. */
+    expected: string;
+    /** Why the answer did not match. */
+    reason?: string;
+}
+export declare function foldText(text: string): string;
+/** Check `answer` against the rows the answer source gave at grade time. */
+export declare function checkAnswer(rows: readonly string[], answer: string | undefined, spec: Pick<AnswerSpec, 'match' | 'none'>): AnswerCheck;

package/dist/features/grade/grade-answer.js

@@ -0,0 +1,112 @@
+/**
+ * Check a run's final answer against a value read from the app when the grade runs. Pure.
+ *
+ * A fixed answer string goes stale when the data changes. Here the expected answer is the output of
+ * a declared source (a database query, an endpoint), read at grade time. A source with no rows means
+ * that the task cannot be done, and the answer must be one of the `none` words (default `N/A`).
+ *
+ * Match kinds. Text is folded first: Unicode normal form, lower case, spacing, quotes and a final
+ * full stop.
+ * - `exact`: the answer is the one expected value. With more than one row, it is `set`.
+ * - `number`: the answer is one number, and nothing else. `$`, `%` and digit-group commas are
+ *   removed. It equals the first value within 0.005.
+ * - `set`: the answer is a list, split on commas, semicolons and new lines, or also on " and ". It
+ *   holds each expected value one time and nothing more. Order is not checked.
+ * - `includes`: the answer contains each expected value. A long answer that names every record
+ *   also passes, so use it only where the answer cannot list all choices.
+ */
+import { z } from 'zod';
+import { StateSourceSchema } from '../compare/outside/state-sources.js';
+export const AnswerMatch = {
+    EXACT: 'exact',
+    NUMBER: 'number',
+    SET: 'set',
+    INCLUDES: 'includes',
+};
+/** The default answer for a task that cannot be done. */
+export const DEFAULT_NONE = 'N/A';
+/** Two numbers closer than this are equal: money has two decimals. */
+const NUMBER_TOLERANCE = 0.005;
+export const AnswerSpecSchema = z.strictObject({
+    source: StateSourceSchema,
+    match: z
+        .enum([AnswerMatch.EXACT, AnswerMatch.NUMBER, AnswerMatch.SET, AnswerMatch.INCLUDES])
+        .default(AnswerMatch.EXACT),
+    none: z.array(z.string().min(1)).min(1).default([DEFAULT_NONE]),
+});
+/** The `--expect` file of `reticle grade judge`. */
+export const ExpectSchema = z.strictObject({
+    answer: AnswerSpecSchema,
+});
+const COLUMN_BREAK = /\t/g;
+const LIST_BREAK = /\s*[,;\n]\s*/;
+const LIST_BREAK_AND = /\s*(?:[,;\n]|\band\b)\s*/;
+const NUMBER_NOISE = /[$%\s]|,(?=\d{3}\b)/g;
+const NUMBER_ONLY = /^[-+]?(?:\d+\.?\d*|\.\d+)$/;
+export function foldText(text) {
+    return text
+        .normalize('NFKC')
+        .toLowerCase()
+        .replace(/\s+/g, ' ')
+        .trim()
+        .replace(/^["'`]+|["'`]+$/g, '')
+        .replace(/\.$/, '')
+        .trim();
+}
+/** The number the text is, or undefined when it is not exactly one number. */
+function numberOf(text) {
+    const bare = foldText(text).replace(NUMBER_NOISE, '');
+    return NUMBER_ONLY.test(bare) ? Number(bare) : undefined;
+}
+const items = (text, breaks) => text
+    .split(breaks)
+    .map(foldText)
+    .filter((item) => '' !== item);
+/** A list split on commas, or also on "and": a value such as "Black and White Tee" keeps its "and". */
+const sameList = (values, answer) => sameSet(values, items(answer, LIST_BREAK)) || sameSet(values, items(answer, LIST_BREAK_AND));
+function sameSet(expected, got) {
+    if (expected.length !== got.length) {
+        return false;
+    }
+    const left = [...got];
+    return expected.every((value) => {
+        const at = left.indexOf(value);
+        if (at < 0) {
+            return false;
+        }
+        left.splice(at, 1);
+        return true;
+    });
+}
+/** Check `answer` against the rows the answer source gave at grade time. */
+export function checkAnswer(rows, answer, spec) {
+    const values = rows.map((row) => foldText(row.replace(COLUMN_BREAK, ' '))).filter((v) => v);
+    const expected = 0 === values.length ? (spec.none[0] ?? DEFAULT_NONE) : values.join(', ');
+    if (answer === undefined) {
+        return { ok: false, expected, reason: 'no answer was given' };
+    }
+    const got = foldText(answer);
+    if (0 === values.length) {
+        const ok = spec.none.some((word) => foldText(word) === got);
+        return ok ? { ok, expected } : { ok, expected, reason: 'the task cannot be done' };
+    }
+    let ok;
+    switch (spec.match) {
+        case AnswerMatch.NUMBER: {
+            const want = numberOf(values[0] ?? '');
+            const have = numberOf(answer);
+            ok = want !== undefined && have !== undefined && Math.abs(want - have) < NUMBER_TOLERANCE;
+            break;
+        }
+        case AnswerMatch.INCLUDES:
+            ok = values.every((value) => got.includes(value));
+            break;
+        case AnswerMatch.SET:
+            ok = sameList(values, answer);
+            break;
+        case AnswerMatch.EXACT:
+            ok = 1 === values.length ? values[0] === got : sameList(values, answer);
+            break;
+    }
+    return ok ? { ok, expected } : { ok, expected, reason: `the answer is not ${expected}` };
+}

package/dist/features/grade/grade-noise.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Noise by cell, not by line. Pure.
+ *
+ * An app writes the time of a run into a row (`updated_at`). The two correct runs then differ in that
+ * cell, and the line rule ignores those two lines. But the candidate writes a third time, so its
+ * line is new, and a correct run failed. Here, for each row (table and id) that differs between the
+ * two correct runs, the cells that differ are noise. A removed line and an added line of the same row
+ * that differ only in noise cells are not a difference. A cell the two correct runs agree on (a date
+ * the task sets) is never noise.
+ */
+import { type Row } from './grade-renumber.js';
+export interface NoiseCells {
+    /** The reference's own line for each noisy row. */
+    reference: Map<string, Row>;
+    /** The cells that differ, for each noisy row. */
+    cells: Map<string, Set<number>>;
+}
+/** For each row the two correct runs wrote differently, the cells that differ. */
+export declare function noiseCells(referenceOnly: readonly string[], againOnly: readonly string[]): NoiseCells;
+/**
+ * The added lines less those that differ from the reference's line of the same row only in noise
+ * cells. The reference's line is already noise, so no removed line pairs with it.
+ */
+export declare function withoutNoiseCells(added: readonly string[], noise: NoiseCells): {
+    added: string[];
+    ignored: number;
+};

package/dist/features/grade/grade-noise.js

@@ -0,0 +1,55 @@
+/**
+ * Noise by cell, not by line. Pure.
+ *
+ * An app writes the time of a run into a row (`updated_at`). The two correct runs then differ in that
+ * cell, and the line rule ignores those two lines. But the candidate writes a third time, so its
+ * line is new, and a correct run failed. Here, for each row (table and id) that differs between the
+ * two correct runs, the cells that differ are noise. A removed line and an added line of the same row
+ * that differ only in noise cells are not a difference. A cell the two correct runs agree on (a date
+ * the task sets) is never noise.
+ */
+import { parse } from './grade-renumber.js';
+const rowKey = (row) => `${row.table}\t${row.id}`;
+/** The cells that differ between the same row of two lines. Undefined when the rows differ in shape. */
+function changedCells(a, b) {
+    if (a.cells.length !== b.cells.length) {
+        return undefined;
+    }
+    return a.cells.flatMap((cell, i) => (cell === b.cells[i] ? [] : [i]));
+}
+/** For each row the two correct runs wrote differently, the cells that differ. */
+export function noiseCells(referenceOnly, againOnly) {
+    const again = new Map();
+    for (const line of againOnly) {
+        const row = parse(line);
+        if (row !== undefined) {
+            again.set(rowKey(row), row);
+        }
+    }
+    const out = { reference: new Map(), cells: new Map() };
+    for (const line of referenceOnly) {
+        const row = parse(line);
+        const other = row === undefined ? undefined : again.get(rowKey(row));
+        const cells = row === undefined || other === undefined ? undefined : changedCells(row, other);
+        if (row !== undefined && cells !== undefined) {
+            out.reference.set(rowKey(row), row);
+            out.cells.set(rowKey(row), new Set(cells));
+        }
+    }
+    return out;
+}
+/**
+ * The added lines less those that differ from the reference's line of the same row only in noise
+ * cells. The reference's line is already noise, so no removed line pairs with it.
+ */
+export function withoutNoiseCells(added, noise) {
+    const kept = added.filter((line) => {
+        const row = parse(line);
+        const key = row === undefined ? '' : rowKey(row);
+        const ours = noise.reference.get(key);
+        const allowed = noise.cells.get(key);
+        const cells = row === undefined || ours === undefined ? undefined : changedCells(ours, row);
+        return cells === undefined || allowed === undefined || !cells.every((c) => allowed.has(c));
+    });
+    return { added: kept, ignored: added.length - kept.length };
+}

package/dist/features/grade/grade-renumber.d.ts

@@ -0,0 +1,12 @@
+export interface Row {
+    /** `state <label>`: the table. */
+    table: string;
+    id: string;
+    cells: string[];
+}
+export declare function parse(line: string): Row | undefined;
+export declare function renumber(removed: readonly string[], added: readonly string[], reference: readonly string[], candidate: readonly string[]): {
+    removed: string[];
+    added: string[];
+    renumbered: number;
+};

package/dist/features/grade/grade-renumber.js

@@ -0,0 +1,86 @@
+/**
+ * Match rows that an app deleted and wrote again with a new id. Pure.
+ *
+ * Many apps save a record by deleting its child rows and inserting them again. The rows hold the
+ * same values, but the database gives them new auto-increment ids. A run that saves a record two
+ * times then differs from a run that saves it one time, on every child row, although the data
+ * means the same. That made a correct run fail.
+ *
+ * A text row is `state <label> <id>\t<cell>\t...`. A removed row and an added row of the same
+ * table are one record when all their cells after the id are equal, after each id already matched
+ * is replaced by its new id. The match records old id -> new id, so a row that refers to the
+ * old id (a link to the deleted row) matches next. The loop stops when no row matches.
+ *
+ * A match needs two integer ids, an old id that the candidate no longer has in that table, and a
+ * new id that the reference did not have in that table. So a changed value in a first column that
+ * is not an id is not hidden. The caller reports how many rows matched, because this removes
+ * lines from the difference.
+ */
+const CELL = '\t';
+const INTEGER = /^\d+$/;
+export function parse(line) {
+    const [first, ...cells] = line.split(CELL);
+    if (first === undefined || 0 === cells.length) {
+        return undefined;
+    }
+    const space = first.lastIndexOf(' ');
+    const id = first.slice(space + 1);
+    return space < 0 || !INTEGER.test(id) ? undefined : { table: first.slice(0, space), id, cells };
+}
+/** The ids each table has in a snapshot. */
+function idsOf(lines) {
+    const out = new Map();
+    for (const line of lines) {
+        const row = parse(line);
+        if (row !== undefined) {
+            const ids = out.get(row.table) ?? new Set();
+            ids.add(row.id);
+            out.set(row.table, ids);
+        }
+    }
+    return out;
+}
+const keyOf = (table, cells) => [table, ...cells].join(CELL);
+export function renumber(removed, added, reference, candidate) {
+    const before = idsOf(reference);
+    const after = idsOf(candidate);
+    const newId = new Map();
+    const left = removed.map(parse);
+    const right = added.map(parse);
+    const gone = new Set();
+    const come = new Set();
+    let progress = true;
+    while (progress) {
+        progress = false;
+        const open = new Map();
+        right.forEach((row, j) => {
+            if (row !== undefined && !come.has(j)) {
+                const key = keyOf(row.table, row.cells);
+                open.set(key, [...(open.get(key) ?? []), j]);
+            }
+        });
+        left.forEach((row, i) => {
+            if (row === undefined || gone.has(i) || (after.get(row.table)?.has(row.id) ?? false)) {
+                return;
+            }
+            const key = keyOf(row.table, row.cells.map((cell) => newId.get(cell) ?? cell));
+            const j = (open.get(key) ?? []).find((k) => {
+                const id = right[k]?.id ?? '';
+                return !come.has(k) && !(before.get(row.table)?.has(id) ?? false);
+            });
+            const to = j === undefined ? undefined : right[j]?.id;
+            if (j === undefined || to === undefined || (newId.get(row.id) ?? to) !== to) {
+                return;
+            }
+            newId.set(row.id, to);
+            gone.add(i);
+            come.add(j);
+            progress = true;
+        });
+    }
+    return {
+        removed: removed.filter((_, i) => !gone.has(i)),
+        added: added.filter((_, j) => !come.has(j)),
+        renumbered: gone.size,
+    };
+}

package/dist/features/grade/grade-state.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Grade a finished run of an app from snapshots of its stored data. Pure.
+ *
+ * A snapshot is the state lines of `readStateSources`, and optionally a `url` line for the page the
+ * run ended on. Three snapshots go in: the reference (the app after the correct steps), again (the
+ * app after the same correct steps, from the same start), and the candidate (the app after the steps
+ * to grade). A line that differs between the two reference snapshots is noise and is ignored, and so
+ * is a change to a cell of a row that the two references wrote differently (see `grade-noise.ts`). Any
+ * other line that differs between the reference and the candidate is a difference, and the grade
+ * fails. A source that could not be read makes the grade unverified, never a pass.
+ *
+ * A row the candidate deleted and wrote again with a new id and the same values is not a difference
+ * (see `grade-renumber.ts`). The grade counts these rows.
+ *
+ * State lines are sorted rows, so the diff is a count of each line, not an ordered diff. That keeps
+ * the cost linear in the number of rows, and a source of many thousand rows is cheap.
+ */
+import { z } from 'zod';
+export declare const GradeVerdict: {
+    readonly PASS: "pass";
+    readonly FAIL: "fail";
+    /** The grade proves nothing: a source could not be read, or the answer could not be checked. */
+    readonly UNVERIFIED: "unverified";
+};
+export type GradeVerdict = (typeof GradeVerdict)[keyof typeof GradeVerdict];
+export declare const SnapshotSchema: z.ZodObject<{
+    lines: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type Snapshot = z.infer<typeof SnapshotSchema>;
+/** The line that holds the page a run ended on. */
+export declare const URL_PREFIX = "url";
+/**
+ * The page a run ended on, as one line: the origin and path without a final slash, and the query
+ * values sorted by name. The fragment is removed. Text that is not a URL is kept as it is.
+ */
+export declare function urlLine(url: string): string;
+export interface StateGrade {
+    verdict: GradeVerdict;
+    /** Lines only the reference has, less noise. */
+    removed: string[];
+    /** Lines only the candidate has, less noise. */
+    added: string[];
+    /** Lines that differed but were ignored, because they also differed between the two references. */
+    ignored: number;
+    /** The reads that failed, on any snapshot. */
+    unread: string[];
+    /** Rows the candidate deleted and wrote again with a new id and the same values. Not differences. */
+    renumbered: number;
+}
+export declare function gradeState(reference: Snapshot, again: Snapshot, candidate: Snapshot): StateGrade;