@reticlehq/server 3.3.0 → 3.4.0

package/dist/judgement/capsule/minimize.js

@@ -1,22 +0,0 @@
-/**
- * Bug-capsule minimization — first cut: prefix-trim. A recorded flow that fails is often mostly setup;
- * the capsule should be the SMALLEST flow that still reproduces the failure, so a regression flow stays
- * fast and legible. Prefix-trim drops leading steps while the failure persists — the cheap, deterministic
- * v1 (delta-debugging over arbitrary subsets is a later refinement). The `stillFails` predicate is
- * injected (a real replay), so this stays pure and unit-testable.
- */
-/**
- * Return the shortest trailing sub-flow that still fails, by removing leading steps one at a time while
- * `stillFails` holds. Never trims below one step. Deterministic given a deterministic predicate.
- */
-export async function prefixTrim(steps, stillFails) {
-    let kept = [...steps];
-    while (kept.length > 1) {
-        const trimmed = kept.slice(1);
-        if (await stillFails(trimmed))
-            kept = trimmed;
-        else
-            break;
-    }
-    return kept;
-}

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

@@ -1,27 +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.
- */
-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[];
-export {};

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');
-}