@reticlehq/server 3.2.0 → 3.4.0

package/dist/judgement/outcome/predicate-to-expect.js

@@ -1,148 +0,0 @@
-import { PredicateKind } from '@reticlehq/core';
-/** Merge two partial expectations; later keys win only where the earlier one said nothing. */
-function merge(into, from) {
-    return { ...from, ...into };
-}
-export function predicateToExpect(predicate) {
-    switch (predicate.kind) {
-        case PredicateKind.SIGNAL: {
-            if (predicate.name === undefined)
-                return undefined;
-            const signal = { signal: predicate.name };
-            if (predicate.dataMatches !== undefined)
-                signal.signalData = predicate.dataMatches;
-            if (predicate.count !== undefined)
-                signal.signalCount = predicate.count;
-            return signal;
-        }
-        case PredicateKind.ROUTE: {
-            // Carried, not invented: the agent said "until the route is X" in so many words. The kinds
-            // below this comment's twin in the header — animation, anyOf, not — stay refused because
-            // there the file would gain a claim nobody made.
-            const route = {};
-            if (predicate.pathname !== undefined)
-                route.pathname = predicate.pathname;
-            if (predicate.contains !== undefined)
-                route.contains = predicate.contains;
-            return 0 === Object.keys(route).length ? undefined : { route };
-        }
-        case PredicateKind.NET: {
-            const net = {};
-            if (predicate.method !== undefined)
-                net.method = predicate.method;
-            if (predicate.urlContains !== undefined)
-                net.urlContains = predicate.urlContains;
-            if (predicate.status !== undefined)
-                net.status = predicate.status;
-            if (predicate.count !== undefined)
-                net.count = predicate.count;
-            return 0 === Object.keys(net).length ? undefined : { net };
-        }
-        case PredicateKind.CONSOLE: {
-            // `contains` has no representation in FlowExpect.console (core keeps `level` and `absent`
-            // and nothing else). Copying the rest through anyway would record an assertion the agent
-            // never made: {console, level:'warn', contains:'no-op', absent:true} would save "no warn
-            // entries at all", a false red on any unrelated warning, and in the presence direction it
-            // saves a strictly weaker claim than the one chosen. This file's own rule applies: record
-            // nothing rather than something different, so the flow stays assertion-free there instead.
-            if (predicate.contains !== undefined)
-                return undefined;
-            const console_ = {};
-            if (predicate.level !== undefined)
-                console_.level = predicate.level;
-            if (predicate.absent !== undefined)
-                console_.absent = predicate.absent;
-            return 0 === Object.keys(console_).length ? undefined : { console: console_ };
-        }
-        case PredicateKind.ELEMENT: {
-            const element = {};
-            if (predicate.query.testid !== undefined)
-                element.testid = predicate.query.testid;
-            if (predicate.query.role !== undefined)
-                element.role = predicate.query.role;
-            if (predicate.query.name !== undefined)
-                element.name = predicate.query.name;
-            return 0 === Object.keys(element).length ? undefined : { element };
-        }
-        case PredicateKind.STATE: {
-            const state = { path: predicate.path };
-            if (predicate.store !== undefined)
-                state.store = predicate.store;
-            if (predicate.equals !== undefined)
-                state.equals = predicate.equals;
-            return { state };
-        }
-        case PredicateKind.ALL_OF: {
-            // `settled` members drop out on their own by returning undefined.
-            let combined;
-            for (const part of predicate.predicates) {
-                const expect = predicateToExpect(part);
-                if (expect === undefined)
-                    continue;
-                combined = combined === undefined ? expect : merge(combined, expect);
-            }
-            return combined;
-        }
-        default:
-            // settled | route | animation | anyOf | not — nothing FlowExpect can say honestly.
-            return undefined;
-    }
-}
-/**
- * The subset a REPLAY actually enforces.
- *
- * The rule has never changed: never write an assertion into a flow file that nothing evaluates. A
- * flow reporting `grade: "asserted"` while its assertion is read by no one is a false green, in the
- * feature whose entire purpose is preventing them.
- *
- * What changed is the SET. This kept only `element.testid` and `state`, because for a long time
- * those were the only kinds replay checked — and the note here said lifting it "requires replay to
- * evaluate them per step". Replay now does exactly that: `assertStepExpect` compiles every
- * remaining kind through `successToPredicate` and waits on it. The condition was met and the filter
- * was not updated, so the two drifted.
- *
- * That drift had a cost, and it fell on the agent. `reticle_act_and_wait { until }` IS the agent
- * saying what success means, and `net` is overwhelmingly what it says. Every one of those was
- * discarded at capture, so an agent-recorded flow reached disk assertion-free BY CONSTRUCTION and
- * `reticle_verify` then correctly called it `unverifiable` — the record → save → verify path
- * completing all the way to a run that could never be a pass. Found by driving it.
- *
- * The list below is exactly what `successToPredicate` reads, including an element located by
- * role or name. A testid is also asserted directly against the DOM by the step runner. Anything
- * it cannot compile is still dropped.
- */
-export function enforcedOnReplay(expect) {
-    if (expect === undefined)
-        return undefined;
-    const kept = {};
-    // The step runner asserts a testid against the live DOM before the predicate engine. Role and
-    // name are not that path: successToPredicate compiles them, and dropping them here made a
-    // recorded `until` by button name vanish so the saved flow could not go red.
-    const element = expect.element;
-    if (undefined !== element &&
-        (undefined !== element.testid || undefined !== element.role || undefined !== element.name)) {
-        kept.element = element;
-    }
-    // Everything `successToPredicate` can compile. Replay evaluates EVERY kind of expect through it
-    // (see assertStepExpect); this list is what that function actually reads.
-    if (expect.state !== undefined)
-        kept.state = expect.state;
-    if (expect.signal !== undefined)
-        kept.signal = expect.signal;
-    if (expect.signalData !== undefined)
-        kept.signalData = expect.signalData;
-    if (expect.signalCount !== undefined)
-        kept.signalCount = expect.signalCount;
-    if (expect.net !== undefined)
-        kept.net = expect.net;
-    if (expect.console !== undefined)
-        kept.console = expect.console;
-    // `route` joined the list the day FlowExpect gained the field. This filter and
-    // `successToPredicate` are two allowlists for one question — "can replay check this?" — and the
-    // note above records them drifting once already. They drifted again here, in the same direction,
-    // within an hour: the field was added, the mapping was added, and a route assertion still reached
-    // disk as nothing because THIS list had not heard of it. Found by driving, not by a test.
-    if (expect.route !== undefined)
-        kept.route = expect.route;
-    return 0 === Object.keys(kept).length ? undefined : kept;
-}

package/dist/judgement/phenomena/phenomena.d.ts

@@ -1,26 +0,0 @@
-import { PhenomenonType, type JournalAction, type ReticleEvent } from '@reticlehq/core';
-/**
- * A detected phenomenon — a named, evidence-backed anomaly over the journal. Deterministic matchers, no
- * scanning by the agent: the layer names the fault, the agent acts on the name. `pre-hydration-click`
- * lands once the hydration signal (a later item) exists; the three here need only journal data.
- */
-export interface Finding {
-    phenomenon: PhenomenonType;
-    evidence: Record<string, unknown>;
-}
-/** A request that started (NET_PENDING) but never completed (no NET_REQUEST with the same id). */
-export declare function detectHungRequests(events: readonly ReticleEvent[]): Finding[];
-/** A 5xx response observed while the page was hidden — an error the user never sees. */
-export declare function detectHidden500(events: readonly ReticleEvent[]): Finding[];
-/** An act that dispatched but attributed no events — the app did nothing. */
-export declare function detectDeadClicks(actions: readonly JournalAction[]): Finding[];
-/**
- * A click that landed BEFORE React hydration attached handlers — a silent no-op. Detectable only in-app:
- * the hydration-complete signal's time vs the click action's dispatch. No signal ⇒ can't tell (not a
- * React app, or hydration never completed), so we don't guess.
- */
-export declare function detectPreHydrationClicks(events: readonly ReticleEvent[], actions: readonly JournalAction[]): Finding[];
-/** A React error boundary that caught and swallowed — surfaced on the signal channel by the adapter. */
-export declare function detectSwallowedErrors(events: readonly ReticleEvent[]): Finding[];
-/** Run every journal-only matcher over a session's events + actions. */
-export declare function detectPhenomena(events: readonly ReticleEvent[], actions: readonly JournalAction[]): Finding[];

package/dist/judgement/phenomena/phenomena.js

@@ -1,101 +0,0 @@
-import { EventType, FlowStepTool, PhenomenonType, RETICLE_ERROR_BOUNDARY_SIGNAL, RETICLE_HYDRATION_SIGNAL, } from '@reticlehq/core';
-/** ACT tools that represent a user-style interaction (a "click"), for dead-click detection. */
-const CLICK_TOOLS = new Set([FlowStepTool.ACT, FlowStepTool.ACT_AND_WAIT]);
-/** A request that started (NET_PENDING) but never completed (no NET_REQUEST with the same id). */
-export function detectHungRequests(events) {
-    const completed = new Set();
-    for (const event of events) {
-        if (event.type === EventType.NET_REQUEST)
-            completed.add(event.data['id']);
-    }
-    const findings = [];
-    for (const event of events) {
-        if (event.type !== EventType.NET_PENDING)
-            continue;
-        if (completed.has(event.data['id']))
-            continue;
-        findings.push({
-            phenomenon: PhenomenonType.HUNG_REQUEST,
-            evidence: { id: event.data['id'], method: event.data['method'], url: event.data['url'] },
-        });
-    }
-    return findings;
-}
-/** A 5xx response observed while the page was hidden — an error the user never sees. */
-export function detectHidden500(events) {
-    const findings = [];
-    let hidden = false;
-    for (const event of events) {
-        if (event.type === EventType.PAGE_HEALTH) {
-            const h = event.data['hidden'];
-            if ('boolean' === typeof h)
-                hidden = h;
-            continue;
-        }
-        if (event.type !== EventType.NET_REQUEST)
-            continue;
-        const status = event.data['status'];
-        if (hidden && 'number' === typeof status && status >= 500) {
-            findings.push({
-                phenomenon: PhenomenonType.HIDDEN_500,
-                evidence: { url: event.data['url'], status, method: event.data['method'] },
-            });
-        }
-    }
-    return findings;
-}
-/** An act that dispatched but attributed no events — the app did nothing. */
-export function detectDeadClicks(actions) {
-    const findings = [];
-    for (const action of actions) {
-        if (!CLICK_TOOLS.has(action.tool))
-            continue;
-        if (action.seqRange !== undefined)
-            continue; // it caused something → not dead
-        findings.push({
-            phenomenon: PhenomenonType.DEAD_CLICK,
-            evidence: { actionId: action.actionId, tool: action.tool, args: action.args },
-        });
-    }
-    return findings;
-}
-/**
- * A click that landed BEFORE React hydration attached handlers — a silent no-op. Detectable only in-app:
- * the hydration-complete signal's time vs the click action's dispatch. No signal ⇒ can't tell (not a
- * React app, or hydration never completed), so we don't guess.
- */
-export function detectPreHydrationClicks(events, actions) {
-    const hydration = events.find((e) => e.type === EventType.SIGNAL && e.data['name'] === RETICLE_HYDRATION_SIGNAL);
-    if (hydration === undefined)
-        return [];
-    return actions
-        .filter((a) => CLICK_TOOLS.has(a.tool) && a.tRange.from < hydration.t)
-        .map((a) => ({
-        phenomenon: PhenomenonType.PRE_HYDRATION_CLICK,
-        evidence: { actionId: a.actionId, clickedAt: a.tRange.from, hydratedAt: hydration.t },
-    }));
-}
-/** A React error boundary that caught and swallowed — surfaced on the signal channel by the adapter. */
-export function detectSwallowedErrors(events) {
-    const findings = [];
-    for (const event of events) {
-        if (event.type === EventType.SIGNAL && event.data['name'] === RETICLE_ERROR_BOUNDARY_SIGNAL) {
-            const detail = event.data['data'];
-            findings.push({
-                phenomenon: PhenomenonType.SWALLOWED_ERROR,
-                evidence: 'object' === typeof detail && detail !== null ? detail : {},
-            });
-        }
-    }
-    return findings;
-}
-/** Run every journal-only matcher over a session's events + actions. */
-export function detectPhenomena(events, actions) {
-    return [
-        ...detectHungRequests(events),
-        ...detectHidden500(events),
-        ...detectDeadClicks(actions),
-        ...detectPreHydrationClicks(events, actions),
-        ...detectSwallowedErrors(events),
-    ];
-}

package/dist/language/flows/flow-report.d.ts

@@ -1,22 +0,0 @@
-import { type FlowFile, type FlowReplayResult } from '@reticlehq/core';
-/**
- * Render a HUMAN-facing confidence report for a replayed flow — the artifact a developer reads to
- * trust the test without re-running it. It answers the three confidence questions in one page:
- * WHY — the declared business intent (+ whether it is actually asserted).
- * WHAT — the journey: a mermaid flow diagram + a per-step page → action → consequence table.
- * PROOF — the verdict (pass/drift/fail), the observed evidence (signals/network), and the
- * measured cost (deterministic replay tokens vs an LLM re-drive).
- *
- * Pure: no IO, no clock. Markdown out (mermaid is the one place mermaid earns its tokens — a human
- * renders it). Token figures are passed in (measured by the caller), never faked.
- */
-interface FlowReportInput {
-    flow: FlowFile;
-    replay: FlowReplayResult;
-    /** Measured deterministic replay cost (o200k proxy), for the "PROOF / cost" line. Optional. */
-    replayTokens?: number;
-    /** Measured per-run LLM re-drive cost of a step-driving tool, for the ratio. Optional. */
-    competitorTokens?: number;
-}
-export declare function buildFlowReport(input: FlowReportInput): string;
-export {};

package/dist/language/flows/flow-report.js

@@ -1,106 +0,0 @@
-import { ReplayStatus, } from '@reticlehq/core';
-import { classifyFlowAssertions } from './flow-classify.js';
-import { SUCCESS_STEP_TOOL } from './flow-success.js';
-const VERDICT_GLYPH = {
-    [ReplayStatus.OK]: '✅ pass',
-    [ReplayStatus.DRIFT]: '⚠️ drift',
-    [ReplayStatus.ERROR]: '❌ fail',
-};
-/** A mermaid-safe node id (mermaid ids must be alnum/underscore). */
-function nodeId(index) {
-    return `s${index}`;
-}
-/** Escape a label for a mermaid `["..."]` node (quotes/newlines break the parser). */
-function mermaidLabel(text) {
-    return text.replace(/"/g, "'").replace(/\n/g, ' ').slice(0, 80);
-}
-/** A short action verb for a step row ("act" is the tool; the anchor carries the target). */
-function stepAction(step) {
-    return step.tool === SUCCESS_STEP_TOOL ? 'assert outcome' : step.anchor;
-}
-/** The mermaid flowchart of the journey: one node per step, page-labelled, consequence on the edge. */
-function mermaidDiagram(steps) {
-    const lines = ['```mermaid', 'flowchart TD'];
-    steps.forEach((step, i) => {
-        const page = step.page !== undefined ? `${step.page} — ` : '';
-        const glyph = step.ok ? '' : ' ✗';
-        lines.push(`  ${nodeId(i)}["${mermaidLabel(`${page}${stepAction(step)}${glyph}`)}"]`);
-        if (i > 0) {
-            const edge = steps[i - 1]?.consequence;
-            const label = edge !== undefined ? `|"${mermaidLabel(edge)}"|` : '';
-            lines.push(`  ${nodeId(i - 1)} -->${label} ${nodeId(i)}`);
-        }
-    });
-    lines.push('```');
-    return lines.join('\n');
-}
-/** The per-step journey table (page → action → consequence → result). */
-function journeyTable(steps) {
-    const rows = [
-        '| # | page | action | consequence | result |',
-        '|---|------|--------|-------------|--------|',
-    ];
-    for (const step of steps) {
-        const page = step.page ?? '—';
-        const consequence = step.consequence ?? '—';
-        const result = step.ok
-            ? 'ok'
-            : step.drift !== undefined
-                ? `drift (${step.drift.anchor})`
-                : 'fail';
-        rows.push(`| ${step.step} | ${page} | ${stepAction(step)} | ${consequence} | ${result} |`);
-    }
-    return rows.join('\n');
-}
-/** Distinct observed consequences across the journey — the evidence the verdict rests on. */
-function evidenceList(steps) {
-    const seen = new Set();
-    for (const step of steps) {
-        if (step.consequence !== undefined) {
-            for (const part of step.consequence.split(';'))
-                seen.add(part.trim());
-        }
-    }
-    if (0 === seen.size)
-        return '_No observable consequence captured._';
-    return [...seen].map((e) => `- ${e}`).join('\n');
-}
-export function buildFlowReport(input) {
-    const { flow, replay, replayTokens, competitorTokens } = input;
-    const grade = classifyFlowAssertions(flow);
-    const verdict = VERDICT_GLYPH[replay.status] ?? replay.status;
-    const intent = flow.intent ?? '_(no intent declared)_';
-    const intentLine = flow.intent !== undefined
-        ? grade.intentVerified
-            ? `**Intent:** ${flow.intent} — **verified** (an observable outcome is asserted).`
-            : `**Intent:** ${flow.intent} — ⚠️ declared but NOT asserted (add a consequence oracle).`
-        : `**Intent:** ${intent}`;
-    const out = [];
-    out.push(`# Flow report — \`${flow.name}\``);
-    out.push('');
-    out.push(intentLine);
-    out.push(`**Verdict:** ${verdict}  ·  **steps:** ${replay.steps.length}`);
-    if (replayTokens !== undefined) {
-        const ratio = competitorTokens !== undefined && replayTokens > 0
-            ? `  ·  **${Math.round(competitorTokens / replayTokens)}×** cheaper than an LLM re-drive`
-            : '';
-        out.push(`**Cost:** ${replayTokens} tokens (deterministic replay, no LLM)${ratio}`);
-    }
-    if (replay.decision !== undefined) {
-        out.push('');
-        out.push(`> **Next action:** ${replay.decision.nextAction}`);
-        if (replay.decision.whereInSource !== undefined) {
-            out.push(`> **Where:** \`${replay.decision.whereInSource}\``);
-        }
-    }
-    out.push('');
-    out.push('## Journey');
-    out.push(mermaidDiagram(replay.steps));
-    out.push('');
-    out.push(journeyTable(replay.steps));
-    out.push('');
-    out.push('## Evidence');
-    out.push(evidenceList(replay.steps));
-    out.push('');
-    return out.join('\n');
-}