@reticlehq/server 2.14.0 → 3.2.0

package/dist/events/predicate-route.js

@@ -1,258 +0,0 @@
-/**
- * The `route` oracle. Split out of predicate-eval.ts, which was at the file-size backstop.
- *
- * Route is the one predicate with TWO sources of truth — a navigation inside the window and where the
- * app is right now — and keeping that reconciliation in one place is what makes it readable.
- */
-import { EventType, PredicateKind } from '@reticlehq/core';
-import { str } from './predicate-eval.js';
-/**
- * Which fact answered a `route` predicate: a navigation inside the window, or where the app is now.
- *
- * Reported on every route result because the two are different claims. "It changed to /login" proves
- * a redirect; "it was already /login" does not, and an agent asserting a post-login redirect has to
- * be able to tell them apart. Silently conflating them would trade one wrong verdict for another.
- */
-export const RouteDecidedBy = {
-    CHANGE: 'route-change',
-    CURRENT: 'current-route',
-};
-/**
- * The path the router is actually on.
- *
- * Under a hash router the document pathname is `/` on every page and the whole route lives in the
- * fragment — which is why `contains` below matches the full route. `pathname` was left comparing the
- * document path, so `{ pathname: '/posts/12/show' }` could never pass on a HashRouter app, the
- * standard router for a packaged Electron/Tauri renderer. That is a guaranteed false red: Reticle
- * telling a user their working app is broken.
- *
- * The fragment WINS rather than being accepted alongside the document path. Honouring both would
- * make `{ pathname: '/' }` trivially true on every hash-routed page — a green that says nothing
- * about where the app is, which is the failure this predicate exists to prevent.
- */
-export function routePathOf(pathname, hash) {
-    if (!hash.startsWith('#/'))
-        return pathname;
-    const withoutHash = hash.slice(1);
-    const query = withoutHash.indexOf('?');
-    return -1 === query ? withoutHash : withoutHash.slice(0, query);
-}
-function asPayload(value) {
-    if (null === value || 'object' !== typeof value || Array.isArray(value))
-        return undefined;
-    return value;
-}
-function payloadOf(eventOrData) {
-    if (eventOrData['type'] === EventType.ROUTE_CHANGE)
-        return asPayload(eventOrData['data']);
-    // A different event: refuse rather than read whatever happened to sit in `data`.
-    if (undefined !== eventOrData['type'] && undefined !== eventOrData['data'])
-        return undefined;
-    return eventOrData;
-}
-function partsFromPayload(data) {
-    const docPath = str(data['pathname']) ?? str(data['to']);
-    if (docPath === undefined)
-        return undefined;
-    const hash = str(data['hash']) ?? '';
-    const search = str(data['search']) ?? '';
-    return {
-        routePath: routePathOf(docPath, hash),
-        docPath,
-        hash,
-        search,
-        full: `${docPath}${search}${hash}`,
-    };
-}
-/** A `ROUTE_CHANGE` event, or its `data` — one reading, so the sixth copy cannot drift. */
-export function routeOfEvent(eventOrData) {
-    const data = payloadOf(eventOrData);
-    return data === undefined ? undefined : partsFromPayload(data);
-}
-/** Same shape from a session URL (the fallback when the tab hard-loaded and emitted no route event). */
-export function routeOfUrl(url) {
-    if (!URL.canParse(url))
-        return undefined;
-    const parsed = new URL(url);
-    return partsFromPayload({
-        pathname: parsed.pathname,
-        search: parsed.search,
-        hash: parsed.hash,
-    });
-}
-/**
- * The session's live URL, split the way a route-change event already carries it.
- *
- * Absolute (that is what the session tracks), but a relative value is accepted rather than thrown
- * away — an unreadable URL is not worth losing the fallback over.
- */
-function readCurrentRoute(url) {
-    const parts = routeOfUrl(url);
-    const pathname = parts?.docPath ?? url;
-    const search = parts?.search ?? '';
-    const hash = parts?.hash ?? '';
-    return {
-        pathname,
-        routePath: parts?.routePath ?? routePathOf(pathname, hash),
-        full: parts?.full ?? `${pathname}${search}${hash}`,
-        decidedBy: RouteDecidedBy.CURRENT,
-        data: { pathname, search, hash, url, decidedBy: RouteDecidedBy.CURRENT },
-    };
-}
-/** Name the source in the prose too — the structured `decidedBy` is for the agent, this is for a log. */
-function describeRouteSource(reading) {
-    return reading.decidedBy === RouteDecidedBy.CHANGE
-        ? 'route changed to'
-        : 'current route (no route change in the window)';
-}
-export function evalRoute(events, p, 
-/**
- * Where the app is RIGHT NOW, if the caller can say.
- *
- * Without it a route predicate could only ever be answered by a navigation inside the window, so
- * "did the session survive a reload?" — which by definition produces no route change — and "we
- * landed on /login" after a completed navigate were both a guaranteed false red, contradicted by
- * `reticle_snapshot({ mode: 'status' }).route` one call later. Optional so a caller with no session
- * (a replayed window) keeps the old answer instead of inventing a route.
- */
-currentUrl, 
-/** Event-time floor for the window, so a request already in flight before it is not counted. */
-since = 0) {
-    const routes = events.filter((e) => e.type === EventType.ROUTE_CHANGE);
-    const last = routes.at(-1);
-    const changed = last === undefined ? undefined : routeOfEvent(last);
-    const reading = changed !== undefined && last !== undefined
-        ? {
-            pathname: changed.docPath,
-            routePath: changed.routePath,
-            full: changed.full,
-            decidedBy: RouteDecidedBy.CHANGE,
-            data: { ...last.data, decidedBy: RouteDecidedBy.CHANGE },
-        }
-        : currentUrl === undefined || 0 === currentUrl.length
-            ? undefined
-            : readCurrentRoute(currentUrl);
-    if (reading === undefined) {
-        // A navigation the SERVER never answered reads exactly like one the APP prevented, and only one
-        // of those is the user's bug. See unansweredIn.
-        const unanswered = unansweredIn(events, since);
-        if (unanswered !== undefined) {
-            const reason = `no route change, and ${unanswered.count} request(s) started in this window never ` +
-                `completed — first: ${unanswered.method} ${unanswered.url}. A navigation the server has ` +
-                'not answered is indistinguishable from one the app declined, so this is not evidence ' +
-                'against the app. Check the server directly (curl the route) before looking at components';
-            return {
-                pass: false,
-                failureReason: reason,
-                inconclusive: reason,
-                observed: `${unanswered.count} request(s) still in flight, no route change`,
-                expected: `a route change to ${p.pathname ?? p.contains ?? 'any route'}`,
-                assertion: 'route.server-pending',
-            };
-        }
-        return {
-            pass: false,
-            failureReason: 'no route change observed',
-            observed: 'no route change in the window',
-            expected: `a route change to ${p.pathname ?? p.contains ?? 'any route'}`,
-            assertion: 'route.changed',
-        };
-    }
-    // The ROUTER's path, not the document's — see routeOfEvent.
-    const pathname = reading.routePath;
-    if (p.pathname !== undefined && pathname !== p.pathname) {
-        return {
-            pass: false,
-            // No ` is` after the clause: it read "route changed to is '/'".
-            failureReason: `${describeRouteSource(reading)} '${pathname}', expected '${p.pathname}'`,
-            observed: `${describeRouteSource(reading)} '${pathname}'`,
-            expected: `route '${p.pathname}'`,
-            assertion: 'route.pathname',
-        };
-    }
-    // `contains` matches the WHOLE route — path + query + fragment — while `pathname` above stays an
-    // exact path match. A hash router keeps the entire route in the fragment, so matching pathname
-    // alone made `contains` unsatisfiable for every HashRouter app; that is the standard router for a
-    // packaged Electron/Tauri renderer, where an absolute pushState would rewrite the URL to a
-    // nonexistent file.
-    const fullRoute = reading.full;
-    if (p.contains !== undefined && !fullRoute.includes(p.contains)) {
-        return {
-            pass: false,
-            failureReason: `${describeRouteSource(reading)} '${fullRoute}' does not contain '${p.contains}'`,
-            observed: `${describeRouteSource(reading)} '${fullRoute}'`,
-            expected: `a route containing '${p.contains}'`,
-            assertion: 'route.contains',
-        };
-    }
-    return {
-        pass: true,
-        evidence: reading.decidedBy === RouteDecidedBy.CHANGE
-            ? { ...reading.data, viewSettled: sawActivityAfter(events, last?.t ?? 0) }
-            : reading.data,
-    };
-}
-/**
- * Did the page do ANYTHING after the URL moved?
- *
- * A route predicate goes green the instant the URL commits, and on an async-loading page that is a
- * verdict taken over a shell. The reporter's sequence is the whole argument: `allOf [route, console
- * absent]` returned `verified: "yes"`, a snapshot of `main` came back with 9 nodes that read as an
- * empty page, and re-snapshotting moments later showed 22 with the real content — one step from
- * filing "this route renders nothing" against code that was fine.
- *
- * The grade is deliberately NOT changed. Requiring a settle would make every route assertion wait
- * and would flip green suites red, and the report's own acceptance allows either that or evidence
- * saying the view had not settled. This is the second, and it costs nothing that already worked.
- *
- * No clock is read: if the route change is the LAST thing in the window, nothing has been observed
- * since the URL moved, which is exactly the trap. Activity BEFORE the change is ignored — a mutation
- * that predates the navigation says nothing about what the new route rendered.
- *
- * Reported only for a CHANGE reading. A pass decided by "the app is already there" has no commit
- * moment to be too close to, and a caveat there would describe a reading it is not about.
- */
-function sawActivityAfter(events, routeAt) {
-    return events.some((e) => e.t > routeAt && ROUTE_SETTLE_ACTIVITY.has(e.type));
-}
-/**
- * What counts as the view still moving. Same set the `settled` oracle uses, and deliberately the
- * same one: two different answers to "did the page do something" is how a vocabulary rots.
- */
-const ROUTE_SETTLE_ACTIVITY = new Set([
-    EventType.NET_REQUEST,
-    EventType.DOM_ADDED,
-    EventType.DOM_REMOVED,
-    EventType.DOM_ATTR,
-]);
-/**
- * A request that STARTED in this window and never completed.
- *
- * The discriminator the route oracle was missing. `routeChanges: 0, network: 0` is reported the same
- * way whether the app prevented the navigation or the server never answered the request the app
- * made — and only the first is the user's bug. Reticle already saw the pending navigation; it just
- * never said so, and attached a `source:` file:line that pointed at innocent code.
- *
- * Scoped to requests that started INSIDE the window, deliberately. A background poll that predates
- * the action says nothing about this navigation, and counting it would make every route miss on a
- * polling app inconclusive — softening away the finding this oracle exists to make. That is the same
- * trap the duplicate-request and contradiction rules were each narrowed to avoid.
- *
- * Matched on the request id, the way `detectHungRequests` does: a NET_PENDING with no NET_REQUEST
- * carrying the same id.
- */
-function unansweredIn(events, since) {
-    const settled = new Set();
-    for (const e of events)
-        if (e.type === EventType.NET_REQUEST)
-            settled.add(e.data['id']);
-    const open = events.filter((e) => e.type === EventType.NET_PENDING && e.t >= since && !settled.has(e.data['id']));
-    const first = open[0];
-    if (first === undefined)
-        return undefined;
-    return {
-        count: open.length,
-        url: str(first.data['url']) ?? '(unknown url)',
-        method: str(first.data['method']) ?? 'GET',
-    };
-}

package/dist/events/predicate-schema.d.ts

@@ -1,168 +0,0 @@
-import { ElementState, PredicateKind, type ElementDescriptor, type ElementQuery } from '@reticlehq/core';
-import { z } from 'zod';
-export type Predicate = {
-    kind: typeof PredicateKind.ELEMENT;
-    query: ElementQuery;
-    state?: ElementState;
-    absent?: boolean;
-} | {
-    kind: typeof PredicateKind.TEXT;
-    contains: string;
-    visible?: boolean;
-    absent?: boolean;
-    /**
-     * Restrict the match to a subtree, as a CSS selector or a ref — the same field, and the same
-     * meaning, as `scope` on an element query.
-     *
-     * Without it the match is page-wide, and a word that appears both in a background tab label
-     * and in the dialog that just opened satisfies the predicate BEFORE the action runs, so
-     * `act_and_wait` reports `already_true` for an action that did exactly the right thing.
-     */
-    scope?: string;
-    /** Match the scope root itself and check its combined subtree text. Requires `scope`. */
-    self?: boolean;
-} | {
-    kind: typeof PredicateKind.NET;
-    method?: string;
-    urlContains?: string;
-    status?: number;
-    /** Did the call succeed? The honest field for IPC, which has no status code. */
-    ok?: boolean;
-    since?: number;
-    count?: number;
-    /** A substring the RESPONSE body must contain — what the server answered, not what was sent. */
-    bodyContains?: string;
-    /** A substring the REQUEST body must contain — what the UI sent, not what came back. */
-    requestBodyContains?: string;
-    /** Shallow JSON match over the REQUEST body, in the style of `signal.dataMatches`. */
-    requestBodyMatches?: Record<string, unknown>;
-} | {
-    kind: typeof PredicateKind.ROUTE;
-    pathname?: string;
-    contains?: string;
-    since?: number;
-} | {
-    kind: typeof PredicateKind.CONSOLE;
-    level?: string;
-    /**
-     * A substring the captured message must contain. With `absent: true` this flips the meaning
-     * from "no console entries at all" to "THIS message did not appear" — the assertion people
-     * actually write regression checks for (deprecation warnings, no-op handler notices).
-     */
-    contains?: string;
-    absent?: boolean;
-    since?: number;
-} | {
-    kind: typeof PredicateKind.ANIMATION;
-    name?: string;
-    target?: string;
-    completed?: boolean;
-    since?: number;
-} | {
-    kind: typeof PredicateKind.SIGNAL;
-    name?: string;
-    dataMatches?: Record<string, unknown>;
-    /**
-     * Exact number of matching signals in the window — the same cardinality assertion `net`
-     * carries, on the channel the app itself speaks. Omit for presence (≥1).
-     */
-    count?: number;
-    since?: number;
-} | {
-    kind: typeof PredicateKind.STATE;
-    store?: string;
-    path: string;
-    equals?: unknown;
-} | {
-    kind: typeof PredicateKind.SETTLED;
-    quietMs?: number;
-} | {
-    kind: typeof PredicateKind.ALL_OF;
-    predicates: Predicate[];
-} | {
-    kind: typeof PredicateKind.ANY_OF;
-    predicates: Predicate[];
-} | {
-    kind: typeof PredicateKind.NOT;
-    predicate: Predicate;
-};
-interface ResidualQueryChecks {
-    /** Dropped fields this side CAN check, as [field, wanted value] pairs. */
-    checks: [string, string][];
-    /** Dropped fields with no descriptor to check them against — refuse rather than ignore. */
-    unusable: string[];
-}
-/**
- * Split a query's dropped fields into the ones the server can still enforce and the ones it cannot.
- *
- * The alternative — refuse every dropped field — breaks calls that work today and that our own
- * cheatsheet advertises (`{ role: "button", text: "Save" }`), and breaks them into no verdict at all.
- * Enforcing what we can and refusing only the rest keeps those calls working AS WRITTEN, which is the
- * outcome the caller was already assuming.
- */
-export declare function residualQueryChecks(query: ElementQuery): ResidualQueryChecks;
-/** Does this element satisfy every field the locator dropped? */
-export declare function satisfiesResiduals(element: ElementDescriptor, checks: readonly [string, string][]): boolean;
-/** How the element's own reading of a dropped field should be REPORTED back on a failure. */
-export declare function describeResidual(element: ElementDescriptor, field: string): string;
-export declare const PredicateSchema: z.ZodType<Predicate>;
-/**
- * The fields a given predicate kind accepts, read off the schema itself.
- *
- * Derived rather than listed so the two can never disagree: a rejection message that names a stale
- * field set is worse than one that names none, because the agent trusts it and retries into the same
- * wall. Empty for a kind that is not in the union.
- */
-export declare function predicateFieldsFor(kind: string): readonly string[];
-/**
- * Is this tool parameter ACTUALLY the predicate union?
- *
- * Not a name check. `until` is overloaded on this surface — the act/assert family means a predicate
- * by it, while reticle_observe / _network / _console mean a NUMBER, an upper cursor bound — so any
- * caller keying on the word would treat a numeric parameter as a predicate and describe it to the
- * agent as an object. Keying on the schema cannot make that mistake.
- *
- * Lives beside the schema because two callers now ask the question: the lean tool surface, which
- * compacts these parameters, and `reticle_tools`, which spells their grammar out on request. Two
- * spellings of "is this a predicate" is one chance for the surface and the grammar to disagree.
- */
-export declare function isPredicateParam(schema: z.ZodTypeAny): boolean;
-/**
- * Every kind's fields, in one block an agent can write a predicate from.
- *
- * The tool surface advertises the KIND list and points at `reticle_tools` for the fields, because
- * inlining the 12-variant recursive union in the declared JSON Schema costs thousands of characters
- * per predicate parameter, re-sent every turn, to describe a grammar most calls use one variant of.
- * That trade is right — but the pointer has to land somewhere, and it landed on a parameter
- * description reading "same shape as reticle_assert". So the grammar was reachable from nothing, and
- * an agent that could not find `route`'s fields fell back to a `text` check where a route check was
- * meant: the weaker oracle, which is the expensive half of an undiscoverable grammar.
- *
- * Derived from the schema, like `predicateFieldsFor` and for the same reason: a hand-written grammar
- * that drifts is worse than none, because the agent trusts it and retries into the same wall.
- */
-export declare function predicateGrammar(): Readonly<Record<string, string>>;
-/**
- * The keys of a field that is an object, once its wrappers are peeled. Empty for anything else.
- *
- * Exported so the wrapper handling is asserted against THIS function rather than through the
- * rendered sentence. Reached only that way, a wrapper it fails to peel returns `[]`, the old
- * message prints unchanged, and nothing reddens — a regression with no symptom.
- *
- * No top-level predicate field is currently declared behind a wrapper, so the real schema exercises
- * none of these paths; that is exactly why they are worth a case each.
- */
-export declare function nestedKeysOf(schema: z.ZodTypeAny | undefined): readonly string[];
-/**
- * One level into the fields that are themselves objects — `{ query: ['by', 'value', ...] }`.
- *
- * Naming the top-level fields alone leaves `element` unguessable: `query` is an object with its own
- * required shape, and a plain CSS string works in `reticle_snapshot.scope` and `reticle_query.scope`,
- * so assuming it works here is the natural guess. The rejection is the only place that inconsistency
- * can be explained.
- *
- * One level only. Derived from the schema for the same reason `predicateFieldsFor` is: a stale field
- * list is worse than none, because the agent trusts it and retries into the same wall.
- */
-export declare function predicateNestedFieldsFor(kind: string): Readonly<Record<string, readonly string[]>>;
-export {};