@reticlehq/server 3.6.0 → 3.7.0

package/dist/features/harness/explore/goal-search.js

@@ -0,0 +1,144 @@
+/**
+ * Search before grading: a goal the drive did not end on is hunted for, the way a person would,
+ * before anything is said about it.
+ *
+ * Every Harness miss in the persona drives had one shape: it graded where it stood. It judged an
+ * Impact text on /runs, stopped one click short of "Team", read an empty search result as the
+ * answer, called an opened menu a wrong guess, and walked past a goal it had reached. This hunt is
+ * deterministic (no model) and bounded: from the page the drive ended on it tries the toggles and
+ * tabs, then the controls the journey names (a menu that opens is followed into its items), then the
+ * same page without its query, then the pages the map says show the goal, then the pages the drive
+ * reached. It never fills a field
+ * and never presses a name on the never-pressed list. Each place it looks is kept, so "not found"
+ * says where it searched, and a goal it did not find is undecided, never a failure.
+ */
+import { ReticleTool } from '@reticlehq/core';
+import { lookFor } from '../goals.js';
+import { journeyNames, namedControls, navLinks, overlayOpen, parseTree, readPage, toggles, withoutQuery, } from './page-tree.js';
+/** Presses the hunt may spend: enough for a menu, its item and a tab, or a few toggles. */
+export const SEARCH_MOVES = 10;
+/** Shortest heading matched against the journey; shorter ones match by accident. */
+const MIN_HEADING = 4;
+/** How deep a chain of presses goes from one page: menu, item, tab. */
+const MAX_DEPTH = 3;
+const label = (line) => `${line.role} "${line.name}"`;
+/** Hunt for `goal`, leaving the tab where it was found. */
+export async function searchForGoal(invoke, options) {
+    const { goal } = options;
+    const journey = options.journey ?? '';
+    const searched = [];
+    const looked = new Set();
+    const pressed = new Set();
+    let left = options.moves ?? SEARCH_MOVES;
+    let at;
+    let reopened = false;
+    /** Look here, then press what a person would press here, deeper while presses are left. */
+    const explore = async (depth) => {
+        const page = await readPage(invoke);
+        if (page === undefined)
+            return false;
+        searched.push(page.route);
+        looked.add(page.route);
+        if (await lookFor(invoke, goal, options.own)) {
+            at = page.route;
+            return true;
+        }
+        if (MAX_DEPTH <= depth)
+            return false;
+        // Read again, settled by the look: a page read as it loaded offered none of its controls.
+        const lines = parseTree((await readPage(invoke))?.tree ?? page.tree);
+        // A menu or dialog the drive left open hides the page behind it: the live drive's hunt read the
+        // workspace switcher and nothing else. Close it by reloading the page, once, and look again.
+        if (0 === depth && !reopened && overlayOpen(lines)) {
+            reopened = true;
+            return (await go(page.route)) && explore(0);
+        }
+        // What the journey names on this page first ("press Run plan"), then the toggles, then the
+        // named links that leave it: a switcher pressed as a toggle opened its menu over the plan page,
+        // and the button the journey named was never pressed.
+        const named = namedControls(lines, journey);
+        const leaving = new Set(navLinks(lines));
+        const tries = [
+            ...new Set([
+                ...named.filter((l) => !leaving.has(l)),
+                ...toggles(lines),
+                ...named.filter((l) => leaving.has(l)),
+            ].map(label)),
+        ];
+        const overlaid = overlayOpen(lines);
+        for (const name of tries) {
+            const key = `${page.route}: ${name}`;
+            if (pressed.has(key))
+                continue;
+            if (left <= 0)
+                return false;
+            // Found again on a fresh read: a ref does not survive the page coming back.
+            const now = await readPage(invoke);
+            const line = parseTree(now?.tree ?? '').find((l) => l.ref !== undefined && label(l) === name);
+            if (line?.ref === undefined)
+                continue;
+            pressed.add(key);
+            left -= 1;
+            searched.push(key);
+            try {
+                await invoke(ReticleTool.ACT, { ref: line.ref, action: 'click' });
+            }
+            catch {
+                continue;
+            }
+            if (await explore(depth + 1))
+                return true;
+            // Back where it pressed from, with nothing it opened left over the page to hide the rest.
+            const back = await readPage(invoke);
+            const leftOpen = !overlaid && overlayOpen(parseTree(back?.tree ?? ''));
+            if (back !== undefined && (back.route !== page.route || leftOpen))
+                await go(page.route);
+        }
+        return false;
+    };
+    const go = async (route) => {
+        try {
+            await invoke(ReticleTool.NAVIGATE, { url: route });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    const start = await readPage(invoke);
+    if (await explore(0))
+        return { found: true, ...(at === undefined ? {} : { at }), searched };
+    // A search or a filter that emptied the list, undone.
+    const elsewhere = [
+        ...(start === undefined || withoutQuery(start.route) === start.route
+            ? []
+            : [withoutQuery(start.route)]),
+        ...mappedPagesFor(options.map, goal, journey),
+        // Newest first: the drive's last page before it moved on is where a saved thing shows.
+        ...[...(options.reached ?? [])].reverse(),
+    ];
+    for (const route of elsewhere) {
+        if (looked.has(route) || left <= 0)
+            continue;
+        if (!(await go(route)))
+            continue;
+        if (await explore(1))
+            return { found: true, ...(at === undefined ? {} : { at }), searched };
+    }
+    const gaveUpAt = searched.at(-1);
+    return { found: false, searched, ...(gaveUpAt === undefined ? {} : { gaveUpAt }) };
+}
+/** The mapped pages that show the goal, then the ones the journey names by heading. */
+export function mappedPagesFor(map, goal, journey) {
+    if (map === undefined)
+        return [];
+    const wanted = goal.toLowerCase();
+    const said = journey.toLowerCase();
+    const showing = map.pages.filter((p) => p.texts.some((t) => t.toLowerCase().includes(wanted)));
+    // A page whose controls name what the journey asks for: Memory is a link on Flows.
+    const leading = map.pages.filter((p) => p.controls.some((c) => journeyNames(said, /"([^"]*)"/.exec(c)?.[1] ?? '')));
+    const named = map.pages.filter((p) => p.heading !== undefined &&
+        MIN_HEADING <= p.heading.length &&
+        said.includes(p.heading.toLowerCase()));
+    return [...new Set([...showing, ...leading, ...named].map((p) => p.route))];
+}

package/dist/features/harness/explore/page-tree.d.ts

@@ -0,0 +1,49 @@
+export type Invoke = (name: string, args: Record<string, unknown>) => Promise<unknown>;
+/** One element line: `  - button "Team" (ref=e252) [pressed]`. */
+export interface TreeLine {
+    depth: number;
+    role: string;
+    name: string;
+    ref?: string;
+    states: string[];
+    /** The element's own text, `[text="…"]`, when it has no name to carry it. */
+    text?: string;
+    /** The roles of the lines it sits inside, nearest last. */
+    within: string[];
+}
+export interface PageRead {
+    route: string;
+    tree: string;
+}
+export declare function parseTree(tree: string): TreeLine[];
+/** The page's own address: path, query and hash, without the parameters Reticle adds. */
+export declare function routeOf(route: string): string;
+/** The same page with no query: a search or a filter undone. */
+export declare function withoutQuery(route: string): string;
+/** Read the page in full. Undefined when it cannot be read. */
+export declare function readPage(invoke: Invoke): Promise<PageRead | undefined>;
+/** Whether a menu or dialog is open, so the read shows it and little else. */
+export declare function overlayOpen(lines: readonly TreeLine[]): boolean;
+/** Links in the app's navigation: where a person goes to look around. */
+export declare function navLinks(lines: readonly TreeLine[]): (TreeLine & {
+    ref: string;
+})[];
+/**
+ * Toggles and tabs not already on: a button beside a pressed sibling (Mine | Team), and tabs, radios
+ * and switches. Pressing one changes what the page shows without leaving it.
+ */
+export declare function toggles(lines: readonly TreeLine[]): (TreeLine & {
+    ref: string;
+})[];
+/**
+ * Controls the journey names ("open Account, choose Settings, then Members and access"): the plan
+ * is a hint, and these are where it points. A name like `Account: Leo Martin · Pro` matches on the
+ * part before its colon.
+ */
+export declare function namedControls(lines: readonly TreeLine[], journey: string): (TreeLine & {
+    ref: string;
+})[];
+/** Whether the journey names a control: its name, or the part before its colon, as whole words. */
+export declare function journeyNames(journey: string, name: string): boolean;
+/** The words a page shows, as a reader would list them: headings, text and labels, not controls. */
+export declare function textsOf(lines: readonly TreeLine[], max: number): string[];

package/dist/features/harness/explore/page-tree.js

@@ -0,0 +1,148 @@
+/**
+ * A page as the exploratory Harness reads it: one full snapshot, and the controls on it that a
+ * person hunting for something would try — nav links, toggles and tabs, and whatever the journey
+ * names. Pure over the snapshot's line format (core's `snapshot-tree.ts`); no browser here.
+ */
+import { RETICLE_URL_PARAM, ReticleTool, asRecord } from '@reticlehq/core';
+const LINE = /^(\s*)-\s+([a-z]+)(?:\s+"((?:[^"\\]|\\.)*)")?(.*)$/;
+const REF = /\(ref=(e\d+)\)/;
+const STATES = /\[([a-z,]+)\]\s*$/;
+const OWN_TEXT = /\[text="((?:[^"\\]|\\.)*)"\]/;
+export function parseTree(tree) {
+    const out = [];
+    const stack = [];
+    for (const raw of tree.split('\n')) {
+        const m = LINE.exec(raw);
+        if (null === m)
+            continue;
+        const depth = (m[1] ?? '').length;
+        while (0 < stack.length && (stack.at(-1)?.depth ?? 0) >= depth)
+            stack.pop();
+        const rest = m[4] ?? '';
+        const ref = REF.exec(rest)?.[1];
+        const text = OWN_TEXT.exec(rest)?.[1];
+        out.push({
+            depth,
+            role: m[2] ?? '',
+            name: m[3] ?? '',
+            ...(ref === undefined ? {} : { ref }),
+            ...(text === undefined ? {} : { text }),
+            states: (STATES.exec(rest)?.[1] ?? '').split(',').filter((s) => 0 < s.length),
+            within: stack.map((s) => s.role),
+        });
+        stack.push({ depth, role: m[2] ?? '' });
+    }
+    return out;
+}
+/** The page's own address: path, query and hash, without the parameters Reticle adds. */
+export function routeOf(route) {
+    const [pathAndQuery = '', ...hash] = route.split('#');
+    const [path = '', query] = pathAndQuery.split('?');
+    const ours = Object.values(RETICLE_URL_PARAM);
+    const kept = (query ?? '')
+        .split('&')
+        .filter((pair) => 0 < pair.length && !ours.some((p) => pair.startsWith(`${p}=`)))
+        .join('&');
+    return `${path || '/'}${0 === kept.length ? '' : `?${kept}`}${0 === hash.length ? '' : `#${hash.join('#')}`}`;
+}
+/** The same page with no query: a search or a filter undone. */
+export function withoutQuery(route) {
+    const [pathAndQuery = '', ...hash] = route.split('#');
+    const path = pathAndQuery.split('?')[0] ?? '';
+    return `${0 === path.length ? '/' : path}${0 === hash.length ? '' : `#${hash.join('#')}`}`;
+}
+/** Read the page in full. Undefined when it cannot be read. */
+export async function readPage(invoke) {
+    try {
+        const result = asRecord(await invoke(ReticleTool.SNAPSHOT, { mode: 'full' }));
+        const tree = result['tree'];
+        const route = asRecord(result['status'])['route'];
+        return 'string' === typeof tree
+            ? { tree, route: routeOf('string' === typeof route ? route : '/') }
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Names the hunt never presses: each is a write, or leaves the session. The action tool's own
+ * destructive-action gate still applies; this keeps the search from even asking.
+ */
+const NEVER_PRESSED = /\b(?:sign ?out|log ?out|delete|remove|leave|revoke|join|cancel|archive|reset|disconnect|accept|decline|mark as|resolve|ignore|invite|pay|buy|upgrade|save|submit|send|create|new)\b/i;
+const pressable = (line) => line.ref !== undefined && 0 < line.name.length && !NEVER_PRESSED.test(line.name);
+const NAV_LANDMARKS = new Set(['navigation', 'complementary', 'banner']);
+const TOGGLE_ROLES = new Set(['tab', 'radio', 'switch']);
+const TOGGLE_GROUPS = new Set(['group', 'toolbar', 'radiogroup', 'tablist']);
+/** Roles that, open, make the rest of the page inert to a reader. */
+const OVERLAYS = new Set(['menu', 'dialog', 'alertdialog', 'listbox']);
+/** Whether a menu or dialog is open, so the read shows it and little else. */
+export function overlayOpen(lines) {
+    return lines.some((l) => OVERLAYS.has(l.role));
+}
+const PRESSED = 'pressed';
+const CHECKED = 'checked';
+/** Links in the app's navigation: where a person goes to look around. */
+export function navLinks(lines) {
+    return lines.filter((l) => 'link' === l.role && l.within.some((r) => NAV_LANDMARKS.has(r)) && pressable(l));
+}
+/**
+ * Toggles and tabs not already on: a button beside a pressed sibling (Mine | Team), and tabs, radios
+ * and switches. Pressing one changes what the page shows without leaving it.
+ */
+export function toggles(lines) {
+    return lines.filter((l, i) => {
+        if (!pressable(l) || l.states.includes(PRESSED) || l.states.includes(CHECKED))
+            return false;
+        if (TOGGLE_ROLES.has(l.role))
+            return true;
+        // Only inside a group of its kind (Mine | Team, Map | List). A banner's "Hide sidebar" is
+        // pressed too, and the workspace switcher beside it was pressed as a toggle on a live drive.
+        if ('button' !== l.role || !TOGGLE_GROUPS.has(l.within.at(-1) ?? ''))
+            return false;
+        const siblings = [lines[i - 1], lines[i + 1]].filter((s) => s !== undefined && s.depth === l.depth && 'button' === s.role);
+        return siblings.some((s) => s.states.includes(PRESSED));
+    });
+}
+/** Shortest name matched against the journey's words; shorter ones match by accident. */
+const MIN_NAMED = 4;
+const ROLES_FOLLOWED = new Set(['link', 'button', 'menuitem', 'tab']);
+/**
+ * Controls the journey names ("open Account, choose Settings, then Members and access"): the plan
+ * is a hint, and these are where it points. A name like `Account: Leo Martin · Pro` matches on the
+ * part before its colon.
+ */
+export function namedControls(lines, journey) {
+    const said = journey.toLowerCase();
+    return lines.filter((l) => ROLES_FOLLOWED.has(l.role) && pressable(l) && journeyNames(said, l.name));
+}
+/** Whether the journey names a control: its name, or the part before its colon, as whole words. */
+export function journeyNames(journey, name) {
+    const head = (name.split(':')[0] ?? '').trim().toLowerCase();
+    return (MIN_NAMED <= head.length && new RegExp(`\\b${escape(head)}\\b`).test(journey.toLowerCase()));
+}
+const escape = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/** Roles a person acts on rather than reads. */
+const INTERACTIVE = new Set([
+    'link',
+    'button',
+    'textbox',
+    'searchbox',
+    'checkbox',
+    'radio',
+    'switch',
+    'combobox',
+    'option',
+    'menuitem',
+    'tab',
+    'slider',
+    'spinbutton',
+]);
+/** The words a page shows, as a reader would list them: headings, text and labels, not controls. */
+export function textsOf(lines, max) {
+    const words = lines.flatMap((l) => [
+        ...(INTERACTIVE.has(l.role) || 0 === l.name.length ? [] : [l.name]),
+        ...(l.text === undefined ? [] : [l.text]),
+    ]);
+    return [...new Set(words)].slice(0, max);
+}

package/dist/features/harness/explore/site-map.d.ts

@@ -0,0 +1,34 @@
+import { type HarnessMap, type HarnessMapPage } from '@reticlehq/core/artifacts';
+import type { ToolOutcome } from '../harness.js';
+import { type Invoke, type PageRead } from './page-tree.js';
+/** Presses the survey may spend: a dashboard's navigation and its toggles, not its rows. */
+export declare const SURVEY_PRESSES = 12;
+/** A map older than this is surveyed again; a younger one is reused and refreshed from drives. */
+export declare const MAP_FRESH_MS: number;
+/**
+ * Whether the app was surveyed for the run that started at `since` (or there is no map at all): a
+ * run that reused a fresh map does not sweep the whole app again.
+ */
+export declare function surveyedSince(map: HarnessMap | undefined, since: number): boolean;
+/** One page read, as the map keeps it. */
+export declare function pageFrom(read: PageRead, at: number, reachedBy?: string): HarnessMapPage;
+/** Pages merged by route, the newest read winning, newest first, within the map's bound. */
+export declare function mergePages(map: HarnessMap, pages: readonly HarnessMapPage[], surveyedAt?: number): HarnessMap;
+/** The pages a drive read in full, for refreshing the map from what it saw. */
+export declare function pagesReadIn(calls: readonly ToolOutcome[], at: number): HarnessMapPage[];
+/**
+ * Survey the app from where the tab stands, and leave the tab where it started. Every press is
+ * found again by its name on a fresh read of the start page, since a ref does not survive a reload.
+ */
+export declare function surveyApp(invoke: Invoke, now: () => number, presses?: number): Promise<HarnessMap | undefined>;
+/** The map from its file's text, or undefined when there is none or it does not parse. */
+export declare function parseMap(text: string | undefined): HarnessMap | undefined;
+/** The map as the platform takes it: pages only, the fields its engine reads. */
+export declare function mapForPlatform(map: HarnessMap): {
+    pages: {
+        route: string;
+        heading?: string;
+        texts: string[];
+        controls: string[];
+    }[];
+};

package/dist/features/harness/explore/site-map.js

@@ -0,0 +1,150 @@
+/**
+ * Map first: before the Harness pursues a goal, it surveys the app, cheaply and with no model.
+ *
+ * Persona drives missed goals that sat one page away: the drive committed to a route, a prediction
+ * missed, and it graded where it stood. A person new to an app looks around first. The survey reads
+ * the start page, presses each nav link and each toggle once (never a field, never a name on the
+ * never-pressed list), reads where that leads, and goes back. The map is kept per app and refreshed
+ * by every drive's own reads, so the survey runs again only when the map is old.
+ */
+import { PredicateKind, ReticleTool, SnapshotMode, asRecord } from '@reticlehq/core';
+import { HarnessMapLimit, HarnessMapSchema, } from '@reticlehq/core/artifacts';
+import { navLinks, overlayOpen, parseTree, readPage, routeOf, textsOf, toggles, } from './page-tree.js';
+/** Presses the survey may spend: a dashboard's navigation and its toggles, not its rows. */
+export const SURVEY_PRESSES = 12;
+/** A map older than this is surveyed again; a younger one is reused and refreshed from drives. */
+export const MAP_FRESH_MS = 24 * 60 * 60 * 1000;
+/** How long a page gets to settle after a press before it is read. */
+const SETTLE_MS = 3000;
+/**
+ * Whether the app was surveyed for the run that started at `since` (or there is no map at all): a
+ * run that reused a fresh map does not sweep the whole app again.
+ */
+export function surveyedSince(map, since) {
+    return map === undefined || since <= map.surveyedAt;
+}
+/** One page read, as the map keeps it. */
+export function pageFrom(read, at, reachedBy) {
+    const lines = parseTree(read.tree);
+    const heading = lines.find((l) => 'heading' === l.role && 0 < l.name.length)?.name;
+    const clip = (t) => t.slice(0, HarnessMapLimit.TEXT);
+    return {
+        route: clip(read.route),
+        ...(heading === undefined ? {} : { heading: clip(heading) }),
+        texts: textsOf(lines, HarnessMapLimit.TEXTS).map(clip),
+        controls: lines
+            .filter((l) => l.ref !== undefined && 0 < l.name.length)
+            .slice(0, HarnessMapLimit.CONTROLS)
+            .map((l) => clip(`${l.role} "${l.name}"`)),
+        ...(reachedBy === undefined ? {} : { reachedBy: clip(reachedBy) }),
+        at,
+    };
+}
+/** Pages merged by route, the newest read winning, newest first, within the map's bound. */
+export function mergePages(map, pages, surveyedAt = map.surveyedAt) {
+    const byRoute = new Map(map.pages.map((p) => [p.route, p]));
+    for (const page of pages) {
+        const was = byRoute.get(page.route);
+        if (was === undefined || was.at <= page.at) {
+            const reachedBy = page.reachedBy ?? was?.reachedBy;
+            byRoute.set(page.route, { ...page, ...(reachedBy === undefined ? {} : { reachedBy }) });
+        }
+    }
+    const pagesOut = [...byRoute.values()]
+        .sort((a, b) => b.at - a.at)
+        .slice(0, HarnessMapLimit.PAGES);
+    return { surveyedAt, pages: pagesOut };
+}
+/** The pages a drive read in full, for refreshing the map from what it saw. */
+export function pagesReadIn(calls, at) {
+    return calls.flatMap((call) => {
+        // Only a full read of an unobstructed page: a quick read has no text, and a page behind an open
+        // menu reads as the menu. Either one once replaced the survey's page and emptied the map.
+        if (ReticleTool.SNAPSHOT !== call.name || call.isError)
+            return [];
+        if (SnapshotMode.FULL !== asRecord(call.args)['mode'])
+            return [];
+        const result = asRecord(call.result);
+        const tree = result['tree'];
+        const route = asRecord(result['status'])['route'];
+        if ('string' !== typeof tree || 'string' !== typeof route)
+            return [];
+        if (overlayOpen(parseTree(tree)))
+            return [];
+        return [pageFrom({ tree, route: routeOf(route) }, at)];
+    });
+}
+const label = (line) => `${line.role} "${line.name}"`;
+async function settle(invoke) {
+    try {
+        await invoke(ReticleTool.WAIT_FOR, {
+            predicate: { kind: PredicateKind.SETTLED },
+            timeout_ms: SETTLE_MS,
+        });
+    }
+    catch {
+        /* a page that never settles is read as it stands */
+    }
+}
+/**
+ * Survey the app from where the tab stands, and leave the tab where it started. Every press is
+ * found again by its name on a fresh read of the start page, since a ref does not survive a reload.
+ */
+export async function surveyApp(invoke, now, presses = SURVEY_PRESSES) {
+    let start = await readPage(invoke);
+    if (start === undefined)
+        return undefined;
+    // A menu left open hides the page behind it: reload it once before reading what it offers.
+    if (overlayOpen(parseTree(start.tree))) {
+        await invoke(ReticleTool.NAVIGATE, { url: start.route }).catch(() => undefined);
+        start = (await readPage(invoke)) ?? start;
+    }
+    const pages = [pageFrom(start, now())];
+    const startLines = parseTree(start.tree);
+    const targets = [...navLinks(startLines), ...toggles(startLines)]
+        .map(label)
+        .filter((name, i, all) => all.indexOf(name) === i)
+        .slice(0, presses);
+    for (const target of targets) {
+        try {
+            const here = await readPage(invoke);
+            const line = parseTree(here?.tree ?? '').find((l) => l.ref !== undefined && label(l) === target);
+            if (line?.ref === undefined)
+                continue;
+            await invoke(ReticleTool.ACT, { ref: line.ref, action: 'click' });
+            await settle(invoke);
+            const read = await readPage(invoke);
+            if (read !== undefined)
+                pages.push(pageFrom(read, now(), target));
+            if (read !== undefined && read.route !== start.route)
+                await invoke(ReticleTool.NAVIGATE, { url: start.route });
+        }
+        catch {
+            /* a press that fails is a page the map does not have */
+        }
+    }
+    return mergePages({ surveyedAt: now(), pages: [] }, pages, now());
+}
+/** The map from its file's text, or undefined when there is none or it does not parse. */
+export function parseMap(text) {
+    if (text === undefined)
+        return undefined;
+    try {
+        const parsed = HarnessMapSchema.safeParse(JSON.parse(text));
+        return parsed.success ? parsed.data : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The map as the platform takes it: pages only, the fields its engine reads. */
+export function mapForPlatform(map) {
+    return {
+        pages: map.pages.map((p) => ({
+            route: p.route,
+            ...(p.heading === undefined ? {} : { heading: p.heading }),
+            texts: p.texts,
+            controls: p.controls,
+        })),
+    };
+}

package/dist/features/harness/goals.d.ts

@@ -1,21 +1,82 @@
+/** One goal: text the page must show, or — when the persona negated it — must not. */
+export interface Goal {
+    text: string;
+    /** The persona said the page must NOT show it: an absence goal, graded by asserting it is not there. */
+    absent?: true;
+}
 export interface GoalCheck {
-    /** The text that had to be on the page. */
+    /** The text that had to be on the page (or, for an absence goal, not on it). */
     text: string;
+    /** Set for an absence goal. */
+    absent?: true;
     /** The engine's verdict on it: only `yes` is proved. */
     verified: string;
+    /** Why it was not checked, when it was not. */
+    reason?: string;
 }
-/** The observable goals in a persona: whatever it quoted. */
+/**
+ * Whether `shown` — one element's text, maybe cut short with "…" — is text the Harness wrote itself
+ * rather than the app: one of `own` (its journey, the names of the plan and the flows it saved), in
+ * full or cut short, holding `goal`. A Harness asked to rename a plan stopped on the /plans list and
+ * was graded PROVED on every quote: the plan it had just saved was named after the journey, and the
+ * journey quoted them all. An element showing exactly the goal is the app's, whoever else wrote it.
+ */
+export declare function writtenByHarness(shown: string, goal: string, own: readonly string[]): boolean;
+/** The end state a goal quotes: its last quoted text that it does not negate. */
+export declare function endOf(goal: string): string | undefined;
+/** The observable goals in a persona: whatever it quoted, each marked absent when it was negated. */
+export declare function parseGoals(persona: string | undefined): Goal[];
+/** The texts a persona says must be on the page: the quoted goals it did not negate. */
 export declare function goalsIn(persona: string | undefined): string[];
 /**
  * Check each goal on the page the drive ended on, recording ONE assert for the drive.
  *
  * Each quote used to be its own assert, and every assert is a check in the drive's run, so a goal
  * that quotes where it starts ("from "Count is 0" to "Count is 1"") recorded a "no" for the start
- * text a working app had rightly replaced, and the run synced as a failing flow. The page is read
- * once to answer each quote; the one recorded assert covers the quotes shown, or all of them when
- * none is, so a goal the page never reached still leaves a failed check behind. A check that cannot
- * run is `unknown`, never skipped.
+ * text a working app had rightly replaced, and the run synced as a failing flow. The page is let
+ * settle, read once, and each goal is scrolled to by its text — one below the fold read `unknown`
+ * on a drive that never scrolled. The one recorded assert covers the goals found. A goal not found
+ * is undecided, not failed: nothing here knows the drive reached the page that would show it. A
+ * check that cannot run is `unknown`, never skipped.
  */
-export declare function checkGoals(invoke: (name: string, args: Record<string, unknown>) => Promise<unknown>, goals: readonly string[]): Promise<GoalCheck[]>;
+export declare function checkGoals(invoke: (name: string, args: Record<string, unknown>) => Promise<unknown>, goals: readonly (string | Goal)[], 
+/** The page as it read before the drive: a goal it already showed proves nothing at the end. */
+opening?: string, 
+/** Text the Harness wrote itself (its journey, its plan's and flows' names): never evidence. */
+own?: readonly string[]): Promise<GoalCheck[]>;
+/**
+ * Whether the page shows `text` once it has settled, scrolled to if need be — how a person looks
+ * for something before saying it is not there. Records no check.
+ */
+export declare function lookFor(invoke: (name: string, args: Record<string, unknown>) => Promise<unknown>, text: string, 
+/** Text the Harness wrote itself: a match inside it is not the page showing the goal. */
+own?: readonly string[]): Promise<boolean>;
+/** The page as it reads now, or undefined when it cannot be read. Taken before a drive starts. */
+export declare function readOpening(invoke: (name: string, args: Record<string, unknown>) => Promise<unknown>): Promise<string | undefined>;
+/**
+ * The end state the caller declared, checked like any assert.
+ *
+ * Quoted text only proves some words are on the last page, which is how a drive that never used the
+ * app could pass: from the field, "it only checks that I have certain titles on my page". An `expect`
+ * names an OUTCOME — a route reached, a request made, state changed — in the same predicate grammar
+ * as reticle_assert, and is graded the same way. A check that cannot run is `unknown`.
+ */
+export declare function checkExpect(invoke: (name: string, args: Record<string, unknown>) => Promise<unknown>, predicate: Record<string, unknown>): Promise<GoalCheck>;
+/** Whether the drive met the goals it was given: undefined when it was given none. */
+export declare function goalsMet(checks: readonly GoalCheck[]): boolean | undefined;
+/**
+ * Whether the drive met its goal, as the answer and the run report it. The driver's own `goalMet`
+ * is its word, never evidence: a run answered `goalMet: true` after zero actions on a tab that
+ * already showed the end state, and another with both its goals `unknown`. With goals, met exactly
+ * when every one was proved; with none, the driver's word stands, and only after an action ran.
+ * Undefined when nothing judged it.
+ */
+export declare function goalOfDrive(claimed: boolean | undefined, checks: readonly GoalCheck[], acted: boolean): boolean | undefined;
 /** One line naming the goals the drive did not prove, or undefined when it proved them all. */
 export declare function unprovedGoals(checks: readonly GoalCheck[]): string | undefined;
+/**
+ * The goals a drive is graded on: every quote, less a value the drive typed — an input, never
+ * evidence — except the journey's end (its last text to show), which stays even when typed: saving
+ * "Order 7" and then seeing it listed is the journey. Absence goals always stay.
+ */
+export declare function endGoalsOf(goals: readonly Goal[], typed: readonly string[]): Goal[];