@reticlehq/server 2.14.0 → 3.2.0

package/dist/domain/domain-model.js

@@ -1,126 +0,0 @@
-/**
- * Build a compact "domain model" of an app's testable surface for an agent to read BEFORE testing:
- * the demonstrated flows, what each one actually asserts, and — the differentiator — the GAPS
- * between declared intent (capabilities the app registered: signals/testids) and what any flow
- * actually verifies.
- *
- * Why (grounded): automation "checks the DOM, not the intent" — tests pass while real,
- * integrated-system bugs ship (Bolton; Fowler Assertion-Free Testing). An agent that can see "you
- * declared the signal order:placed but no flow asserts it" knows where the real risk is, instead of
- * re-deriving the app's flows by reading all the source. Pairs with the flow assertion grades
- * (flow-classify) so "rigorous" and "domain-aware" reinforce each other.
- *
- * Pure: no IO, no clock. The tool layer loads flows + contract and calls this.
- */
-import { AnchorKind, } from '@reticlehq/core';
-import { classifyFlowAssertions, FlowAssertionGrade } from '../flows/flow-classify.js';
-import { successLabel } from '../flows/flow-success.js';
-import { flowRisk, latestRun, rankByRisk, RiskLevel } from './flow-risk.js';
-function flatten(steps) {
-    const out = [];
-    for (const s of steps) {
-        out.push(s);
-        if (s.steps !== undefined)
-            out.push(...flatten(s.steps));
-    }
-    return out;
-}
-function flowSignals(flow) {
-    const set = new Set();
-    for (const step of flatten(flow.steps)) {
-        if (step.anchor.kind === AnchorKind.SIGNAL)
-            set.add(step.anchor.name);
-        if (step.expect?.signal !== undefined)
-            set.add(step.expect.signal);
-    }
-    if (flow.success?.signal !== undefined)
-        set.add(flow.success.signal);
-    return [...set];
-}
-function flowTestids(flow) {
-    const set = new Set();
-    for (const step of flatten(flow.steps)) {
-        if (step.anchor.kind === AnchorKind.TESTID)
-            set.add(step.anchor.value);
-        if (step.expect?.element?.testid !== undefined)
-            set.add(step.expect.element.testid);
-    }
-    if (flow.success?.element?.testid !== undefined)
-        set.add(flow.success.element.testid);
-    return [...set];
-}
-const EMPTY_CONTRACT = { testids: [], signals: [], stores: [], flows: [] };
-export function buildDomainModel(flows, contract, runs = []) {
-    const caps = contract ?? EMPTY_CONTRACT;
-    const hasHistory = runs.length > 0;
-    const flowSummaries = flows.map((flow) => {
-        const c = classifyFlowAssertions(flow);
-        const summary = {
-            name: flow.name,
-            steps: c.totalSteps,
-            grade: c.grade,
-            asserts: c.hasConsequenceAssertion,
-            signals: flowSignals(flow),
-            testids: flowTestids(flow),
-        };
-        if (flow.success !== undefined)
-            summary.mustHold = successLabel(flow.success);
-        if (c.warning !== undefined)
-            summary.warning = c.warning;
-        if (hasHistory)
-            summary.risk = flowRisk(c.grade, latestRun(flow.name, runs));
-        return summary;
-    });
-    const testedSignals = new Set(flowSummaries.flatMap((f) => f.signals));
-    const testedTestids = new Set(flowSummaries.flatMap((f) => f.testids));
-    const coverage = {
-        asserted: flowSummaries.filter((f) => f.grade === FlowAssertionGrade.ASSERTED).length,
-        presenceOnly: flowSummaries.filter((f) => f.grade === FlowAssertionGrade.PRESENCE_ONLY).length,
-        assertionFree: flowSummaries.filter((f) => f.grade === FlowAssertionGrade.ASSERTION_FREE)
-            .length,
-    };
-    const gaps = {
-        unassertedFlows: flowSummaries.filter((f) => !f.asserts).map((f) => f.name),
-        declaredUntestedSignals: caps.signals.filter((s) => !testedSignals.has(s)),
-        declaredUntestedTestids: caps.testids.filter((t) => !testedTestids.has(t)),
-    };
-    const riskRanked = hasHistory
-        ? rankByRisk(flowSummaries
-            .filter((f) => f.risk !== undefined)
-            .map((f) => ({ name: f.name, risk: f.risk })))
-        : [];
-    // The most actionable fact — the riskiest flow to test first — when run history flagged one.
-    const top = riskRanked[0];
-    const topFlow = top === undefined ? undefined : flowSummaries.find((f) => f.name === top);
-    const topRisk = topFlow?.risk !== undefined &&
-        (topFlow.risk.level === RiskLevel.HIGH || topFlow.risk.level === RiskLevel.MEDIUM)
-        ? { name: topFlow.name, reason: topFlow.risk.reason }
-        : undefined;
-    return {
-        flowCount: flows.length,
-        flows: flowSummaries,
-        declared: { testids: caps.testids.length, signals: caps.signals, stores: caps.stores },
-        coverage,
-        gaps,
-        riskRanked,
-        summary: buildSummary(flows.length, coverage, gaps, topRisk),
-    };
-}
-function buildSummary(flowCount, coverage, gaps, topRisk) {
-    if (0 === flowCount) {
-        return 'No saved flows yet — record the critical journeys (reticle_record{action:"start"}) so the agent learns the app.';
-    }
-    const parts = [
-        `${String(flowCount)} flow${1 === flowCount ? '' : 's'}: ${String(coverage.asserted)} asserted, ${String(coverage.presenceOnly)} presence-only, ${String(coverage.assertionFree)} assertion-free`,
-    ];
-    if (topRisk !== undefined) {
-        parts.push(`test first: ${topRisk.name} (${topRisk.reason})`);
-    }
-    if (gaps.declaredUntestedSignals.length > 0) {
-        parts.push(`${String(gaps.declaredUntestedSignals.length)} declared signal(s) no flow asserts (${gaps.declaredUntestedSignals.join(', ')})`);
-    }
-    if (gaps.unassertedFlows.length > 0) {
-        parts.push(`${String(gaps.unassertedFlows.length)} flow(s) assert no consequence`);
-    }
-    return parts.join('. ') + '.';
-}

package/dist/domain/domain-tools.d.ts

@@ -1,2 +0,0 @@
-import type { ToolDef } from '../tools/tools.js';
-export declare const DOMAIN_TOOLS: ToolDef[];

package/dist/domain/domain-tools.js

@@ -1,94 +0,0 @@
-import { z } from 'zod';
-import { sessionRoot } from '../project/session-root.js';
-import { asNumber, asString } from '../tools/tools-helpers.js';
-import { ReticleTool } from '../tools/tool-names.js';
-import { countSchema } from '../tools/numeric-bounds.js';
-import { readContract } from '../project/reticle-dir.js';
-import { buildDomainModel } from './domain-model.js';
-import { proposeInstrumentation } from '../oracles/self-instrument.js';
-import { instrumentationGapsForFlows } from '../oracles/flow-instrument-gaps.js';
-/**
- * reticle_domain — the "learn the app before testing it" tool. Synthesizes every saved flow + the
- * registered capabilities into a compact domain model: the journeys, what each asserts, and the
- * GAPS (declared signals/testids no flow verifies). An agent reads this once instead of crawling
- * the whole app or reading all the source — and it points straight at untested intent.
- */
-/** Flows detailed when the caller does not ask for a specific count. */
-const DEFAULT_FLOW_DETAIL_LIMIT = 25;
-export const DOMAIN_TOOLS = [
-    {
-        name: ReticleTool.DOMAIN,
-        description: 'Read the app domain model BEFORE testing: every saved flow with its assertion grade, the consequence that MUST hold for it (mustHold = what it actually tests), the anchors/signals it exercises, plus GAPS — declared signals/testids that NO flow asserts (untested intent), and flows that assert no observable consequence. Use this to decide what to test and where the real risk is, instead of crawling the whole app. Reads .reticle/flows/ + .reticle/contract.json (no browser needed).',
-        inputSchema: {
-            limit: countSchema
-                .optional()
-                .describe('Most-recent N flows to detail. Defaults to 25 — the per-flow list grows with every saved flow (measured at ~11KB / ~2,700 tokens at 22 flows) and a large project would spend most of an agent context on flows it is not asking about. `flowCount` is always the true total, and the gaps/coverage summary is computed over ALL flows regardless, so capping the detail never changes the analysis.'),
-        },
-        outputSchema: {
-            flowCount: z.number(),
-            flows: z.array(z.object({
-                name: z.string(),
-                steps: z.number(),
-                grade: z.string(),
-                asserts: z.boolean(),
-                mustHold: z
-                    .string()
-                    .optional()
-                    .describe('The success consequence that must hold for this flow (what it actually tests).'),
-                warning: z.string().optional(),
-                signals: z.array(z.string()),
-                testids: z.array(z.string()),
-            })),
-            declared: z.object({
-                testids: z.number(),
-                signals: z.array(z.string()),
-                stores: z.array(z.string()),
-            }),
-            flowsTruncated: z
-                .number()
-                .optional()
-                .describe('How many flows were omitted from `flows` by `limit`. Absent means the listing is complete. gaps/coverage always cover every flow.'),
-            coverage: z.object({
-                asserted: z.number(),
-                presenceOnly: z.number(),
-                assertionFree: z.number(),
-            }),
-            gaps: z.object({
-                unassertedFlows: z.array(z.string()),
-                declaredUntestedSignals: z.array(z.string()),
-                declaredUntestedTestids: z.array(z.string()),
-            }),
-            riskRanked: z
-                .array(z.string())
-                .describe('Flow names worst-risk first (run history + assertion quality). Test these first.'),
-            summary: z.string(),
-            instrumentation: z
-                .array(z.unknown())
-                .optional()
-                .describe('Ready-to-apply instrumentation proposals for gaps that have a source location — { file, line, insert, rationale }. Apply, re-verify, and the app’s observability compounds.'),
-        },
-        handler: async (deps, args) => {
-            const names = await deps.flows.list();
-            const flows = [];
-            for (const name of names) {
-                const loaded = await deps.flows.load(name);
-                if (loaded.ok)
-                    flows.push(loaded.value);
-            }
-            const contract = await readContract(deps.fs, sessionRoot(deps, asString(args['sessionId'])));
-            const project = await deps.project.read();
-            const runs = project.ok ? project.file.runs : [];
-            const model = buildDomainModel(flows, contract.ok ? contract.capabilities : null, runs);
-            // Self-instrumentation: turn located gaps (unasserted flows with a source stamp) into apply-ready diffs.
-            const stepsByName = new Map(flows.map((f) => [f.name, f.steps]));
-            const instrumentation = proposeInstrumentation(instrumentationGapsForFlows(model.gaps.unassertedFlows, stepsByName));
-            // The per-flow detail is capped; `flowCount`, `gaps` and `coverage` are computed over every
-            // flow, so the ANALYSIS is never truncated — only the listing an agent reads past is.
-            const cap = asNumber(args['limit']) ?? DEFAULT_FLOW_DETAIL_LIMIT;
-            const capped = model.flows.length > cap
-                ? { ...model, flows: model.flows.slice(-cap), flowsTruncated: model.flows.length - cap }
-                : model;
-            return instrumentation.length > 0 ? { ...capped, instrumentation } : capped;
-        },
-    },
-];

package/dist/domain/flow-risk.js

@@ -1,80 +0,0 @@
-/**
- * Risk-rank flows so an agent tests the riskiest first. Risk combines two signals:
- *  - run history (.reticle/project.json): a flow whose last run errored/drifted, or passed but with
- * console/network errors, is riskier than one that passed clean; a never-run flow is unknown.
- * - assertion quality (flow-classify): a flow that asserts no consequence is risky EVEN when it
- * "passes" — a green assertion-free flow is false confidence (Fowler/Dodds), so it can't be
- * trusted to catch a regression.
- *
- * Taking the worse of the two means "passed clean last time" never hides "but it asserts nothing".
- * Pure: no IO, no clock.
- */
-import { RunStatus } from '@reticlehq/core';
-import { FlowAssertionGrade } from '../flows/flow-classify.js';
-export const RiskLevel = {
-    HIGH: 'high',
-    MEDIUM: 'medium',
-    LOW: 'low',
-    UNKNOWN: 'unknown',
-};
-// Test-priority order: a known failure first, then a known weakness, then a NEVER-RUN flow
-// (unvalidated — worth running before a known-clean one), then a clean low-risk flow last.
-const RANK = {
-    [RiskLevel.HIGH]: 3,
-    [RiskLevel.MEDIUM]: 2,
-    [RiskLevel.UNKNOWN]: 1,
-    [RiskLevel.LOW]: 0,
-};
-/** Most recent run for a flow name (by `at`), or undefined if it has never been recorded. */
-export function latestRun(name, runs) {
-    let best;
-    for (const run of runs) {
-        if (run.name === name && (best === undefined || run.at > best.at))
-            best = run;
-    }
-    return best;
-}
-function runRisk(run) {
-    if (run === undefined)
-        return { level: RiskLevel.UNKNOWN, reason: 'never run' };
-    if (run.status === RunStatus.ERROR || run.status === RunStatus.FAIL) {
-        return { level: RiskLevel.HIGH, reason: 'last run failed' };
-    }
-    if (run.status === RunStatus.DRIFT)
-        return { level: RiskLevel.HIGH, reason: 'last run drifted' };
-    const errors = (run.evidence?.consoleErrors ?? 0) + (run.evidence?.networkErrors ?? 0);
-    if (errors > 0) {
-        return {
-            level: RiskLevel.MEDIUM,
-            reason: `last run passed but logged ${String(errors)} error(s)`,
-        };
-    }
-    return { level: RiskLevel.LOW, reason: 'last run passed clean' };
-}
-function gradeRisk(grade) {
-    if (grade === FlowAssertionGrade.ASSERTION_FREE) {
-        return {
-            level: RiskLevel.MEDIUM,
-            reason: 'asserts no consequence — a green run proves little',
-        };
-    }
-    if (grade === FlowAssertionGrade.PRESENCE_ONLY) {
-        return { level: RiskLevel.LOW, reason: 'presence-only assertion' };
-    }
-    return { level: RiskLevel.LOW, reason: 'asserts a consequence' };
-}
-/** The worse of run-history risk and assertion-quality risk. */
-export function flowRisk(grade, run) {
-    const r = runRisk(run);
-    const g = gradeRisk(grade);
-    const top = RANK[r.level] >= RANK[g.level] ? r : g;
-    return run === undefined
-        ? { level: top.level, reason: top.reason }
-        : { level: top.level, reason: top.reason, lastStatus: run.status };
-}
-/** Order flow names worst-risk first (HIGH→UNKNOWN), ties broken by name for stable output. */
-export function rankByRisk(entries) {
-    return [...entries]
-        .sort((a, b) => RANK[b.risk.level] - RANK[a.risk.level] || a.name.localeCompare(b.name))
-        .map((e) => e.name);
-}

package/dist/ee/audit-log.js

@@ -1,11 +0,0 @@
-/**
- * Example enterprise feature (Reticle Enterprise License — see./LICENSE). Demonstrates the pattern every
- * ee feature follows: call assertEnterprise...) first, then do the privileged work. The body here is a
- * stub — the real audit sink is the hosted control plane. It exists now to prove the gate.
- */
-import { assertEnterprise, EnterpriseFeature } from '../license/license.js';
-/** Record an audit event — gated. Throws EnterpriseLicenseError in production without a valid license. */
-export function recordAuditEvent(event, ctx) {
-    assertEnterprise(EnterpriseFeature.AUDIT_LOG, ctx);
-    return event; // stub: a real implementation persists to the enterprise audit store
-}

package/dist/events/body-failures.d.ts

@@ -1,4 +0,0 @@
-import { type ReticleEvent } from '@reticlehq/core';
-import type { OwnContradiction } from './contradictions.js';
-/** Contradictions for 2xx responses whose bodies report failure. One per offending call. */
-export declare function findBodyFailures(events: readonly ReticleEvent[]): OwnContradiction[];

package/dist/events/body-failures.js

@@ -1,113 +0,0 @@
-import { ContradictionKind, EventType } from '@reticlehq/core';
-/**
- * A request that returned 2xx and reported failure INSIDE its body.
- *
- * The status line is not the outcome. Three shapes make this routine rather than exotic:
- *
- *  - **GraphQL** answers HTTP 200 for every error it has ever produced. `errors: [...]` in a 200 body
- *    is the normal way a GraphQL request fails, so any verdict that reads only the status is blind to
- *    the entire error surface of an entire ecosystem.
- *  - **Bulk endpoints** answer 200 for the batch and put per-item results in the body. Measured on a
- *    shipments console: `POST /api/bulk-hold` → 200, banner reads "9 shipments held", and three of
- *    the nine carry `{"ok": false, "error": "carrier_locked"}`. Reticle had that body in hand and
- *    reported `verified: "yes"`.
- *  - **Envelope APIs** answer 200 with `{"success": false}` — common wherever a gateway normalises
- *    status codes.
- *
- * Every channel above the body agrees with the lie: the request succeeded, the UI advanced, the page
- * settled, nothing 5xx'd. Only the payload disagrees, which is why this needs body capture — and why
- * an agent reading a status column can never catch it.
- */
-/** Keys whose truthiness means "this failed". Checked at the top level and per item. */
-const FAILURE_FLAGS = ['ok', 'success', 'succeeded'];
-/** Keys that, when carrying content, name a failure. */
-const ERROR_KEYS = ['error', 'errors', 'errorMessage', 'failureReason'];
-/** Arrays worth walking for per-item outcomes. Bulk APIs converge on a handful of names. */
-const ITEM_KEYS = ['results', 'items', 'data', 'records', 'responses'];
-function isRecord(value) {
-    return 'object' === typeof value && value !== null && !Array.isArray(value);
-}
-/** Whether one object reports a failure of its own. */
-function reportsFailure(item) {
-    if (!isRecord(item))
-        return false;
-    for (const flag of FAILURE_FLAGS) {
-        if (false === item[flag])
-            return true;
-    }
-    for (const key of ERROR_KEYS) {
-        const value = item[key];
-        if (value === undefined || null === value)
-            continue;
-        if (Array.isArray(value)) {
-            if (value.length > 0)
-                return true;
-            continue;
-        }
-        // An empty string or an explicit null is an API saying "no error", not an error.
-        if ('string' === typeof value && 0 === value.length)
-            continue;
-        return true;
-    }
-    return false;
-}
-/** Failed / total across the first item array found. Zero total when the body is not a batch. */
-function itemOutcomes(body) {
-    for (const key of ITEM_KEYS) {
-        const list = body[key];
-        if (!Array.isArray(list) || 0 === list.length)
-            continue;
-        const failed = list.filter(reportsFailure).length;
-        return { failed, total: list.length };
-    }
-    return { failed: 0, total: 0 };
-}
-function parse(raw) {
-    if (typeof raw !== 'string' || 0 === raw.length)
-        return undefined;
-    try {
-        const parsed = JSON.parse(raw);
-        return isRecord(parsed) ? parsed : undefined;
-    }
-    catch {
-        return undefined; // not JSON — nothing to read, and guessing at prose would invent findings
-    }
-}
-const OK_MIN = 200;
-const OK_MAX = 300;
-/** Contradictions for 2xx responses whose bodies report failure. One per offending call. */
-export function findBodyFailures(events) {
-    const found = [];
-    for (const event of events) {
-        if (event.type !== EventType.NET_REQUEST)
-            continue;
-        const status = event.data['status'];
-        if (typeof status !== 'number' || status < OK_MIN || status >= OK_MAX)
-            continue;
-        const body = parse(event.data['responseBody']);
-        if (body === undefined)
-            continue;
-        const url = 'string' === typeof event.data['url'] ? event.data['url'] : '';
-        const method = 'string' === typeof event.data['method'] ? event.data['method'] : '';
-        const where = `${method} ${url} → ${String(status)}`;
-        const { failed, total } = itemOutcomes(body);
-        if (failed > 0) {
-            found.push({
-                kind: ContradictionKind.PARTIAL_FAILURE_IN_OK_RESPONSE,
-                claim: `the request returned ${String(status)} and the page treated it as done`,
-                counter: `its body reports ${String(failed)} of ${String(total)} items FAILED`,
-                detail: `${where} — a batch endpoint's status describes the BATCH, not the items; whatever the UI says it did, ${String(failed)} of them did not happen`,
-            });
-            continue;
-        }
-        if (reportsFailure(body)) {
-            found.push({
-                kind: ContradictionKind.PARTIAL_FAILURE_IN_OK_RESPONSE,
-                claim: `the request returned ${String(status)} and the page treated it as done`,
-                counter: 'its body reports the operation FAILED',
-                detail: `${where} — the status line and the payload disagree; the payload is the outcome (a GraphQL error is always a 200)`,
-            });
-        }
-    }
-    return found;
-}

package/dist/events/contradiction-folds.d.ts

@@ -1,45 +0,0 @@
-import type { ReticleEvent } from '@reticlehq/core';
-import type { Contradiction, ContradictionOptions } from './contradictions.js';
-/**
- * Rules a CONSUMER adds to the contradiction pass, without editing the ones this package ships.
- *
- * Every rule in `contradictions.ts` is a pure fold over a recording — events in, findings out, no
- * session, no clock, no IO. A service embedding this engine wants rules of exactly that shape for
- * itself, and the only thing standing between it and one was that `findContradictions` folds over a
- * list written into its own body. Appending to that list means editing this package, which means a
- * fork, which means the consumer's rules and this package's rules become one tree to merge forever.
- *
- * A registry rather than a parameter on `findContradictions`, deliberately. There are six call sites
- * and a consumer reaches none of them: the tools call the pass internally, and a tool handler is
- * handed a deps bag, not options. Threading a parameter would mean touching every path a verdict can
- * take — and would still miss the one inside `crawl`. Registration happens once, at boot, by whoever
- * composed the process.
- *
- * This is not a public plugin API and should not be documented as one. It has a single intended
- * consumer, which is a service we own, and its shape is free to change in lockstep with it.
- */
-/**
- * One consumer rule.
- *
- * Receives the app's OWN events — dev-tooling traffic is already removed, exactly as it is for the
- * shipped rules. A second answer to "which events count" would be a second product.
- */
-export type ContradictionFold = (events: readonly ReticleEvent[], options: ContradictionOptions) => readonly Contradiction[];
-/**
- * Add a rule to every verdict this engine produces. Returns the undo.
- *
- * The undo is not a convenience: without it a registry is process-global state that tests cannot
- * clean up, so each one starts depending on the order it ran in.
- */
-export declare function registerContradictionFold(fold: ContradictionFold): () => void;
-/** What is registered right now. Exported so a guard can assert the registry is empty by default. */
-export declare function registeredContradictionFolds(): readonly ContradictionFold[];
-/**
- * Run every registered rule, containing anything one of them throws.
- *
- * A registered fold is somebody else's code running inside every verdict path this package has. If a
- * throw could propagate, one defect in a consumer's rule would take down `assert`, `act_and_wait`,
- * `observe` and `crawl` at once — turning a missing finding into a dead engine. Contained and logged:
- * the rules that did run still report, and the failure is visible rather than swallowed.
- */
-export declare function runRegisteredFolds(events: readonly ReticleEvent[], options: ContradictionOptions): Contradiction[];

package/dist/events/contradiction-folds.js

@@ -1,42 +0,0 @@
-import { log } from '../log.js';
-const FOLDS = [];
-/**
- * Add a rule to every verdict this engine produces. Returns the undo.
- *
- * The undo is not a convenience: without it a registry is process-global state that tests cannot
- * clean up, so each one starts depending on the order it ran in.
- */
-export function registerContradictionFold(fold) {
-    FOLDS.push(fold);
-    return () => {
-        const at = FOLDS.indexOf(fold);
-        if (at !== -1)
-            FOLDS.splice(at, 1);
-    };
-}
-/** What is registered right now. Exported so a guard can assert the registry is empty by default. */
-export function registeredContradictionFolds() {
-    return [...FOLDS];
-}
-/**
- * Run every registered rule, containing anything one of them throws.
- *
- * A registered fold is somebody else's code running inside every verdict path this package has. If a
- * throw could propagate, one defect in a consumer's rule would take down `assert`, `act_and_wait`,
- * `observe` and `crawl` at once — turning a missing finding into a dead engine. Contained and logged:
- * the rules that did run still report, and the failure is visible rather than swallowed.
- */
-export function runRegisteredFolds(events, options) {
-    const found = [];
-    for (const fold of FOLDS) {
-        try {
-            found.push(...fold(events, options));
-        }
-        catch (error) {
-            log('contradiction_fold_failed', {
-                error: error instanceof Error ? error.message : String(error),
-            });
-        }
-    }
-    return found;
-}