@reticlehq/server 3.6.0 → 3.7.0

package/dist/command/cli/demo/demo-page.d.ts

@@ -1,78 +0,0 @@
-/**
- * The page the tutorial drives when the user has no app of their own yet.
- *
- * `reticle tutorial` used to print four steps and stop. Printing is not teaching: the reader is told
- * that a verdict is the point, and then watches nothing produce one. So the tour now RUNS — against a
- * page served from here, because the alternative (drive whatever is in front of the user) is how a
- * first run ends on a login wall, and a tutorial that fails on step one teaches that Reticle does not
- * work.
- *
- * It carries the real SDK, not a stub. A demo instrumented by something other than the thing being
- * demonstrated proves nothing about the thing being demonstrated.
- *
- * WHY THERE IS NO IMPORT MAP WRITTEN DOWN HERE. The SDK is ESM with bare specifiers, the shipped
- * server has no bundler, and the obvious fix — a hand-written map of specifier to path — is the exact
- * defect this repository keeps paying for: two lists that must agree, where the one nobody updated is
- * the one that breaks. A dependency added to the SDK would leave this map short by one, the page
- * would fail to load a module, and the tour would report that the user's setup is broken.
- *
- * So the map is DISCOVERED. Start at the SDK entry, scan the files beside it for bare specifiers,
- * resolve each one, and repeat. It cannot be short by one, because nothing here knows the names.
- *
- * The walk follows imports out of OUR packages only; a third-party one is mounted whole and not
- * read. That is a deliberate line, not an oversight. Reading zod means walking several thousand
- * files to learn something that has not changed in this repository's lifetime, and it measurably
- * cost about a minute — on the one command whose whole job is a good first impression. The drift
- * this guards against is our own SDK gaining a dependency, which is the thing that actually moves;
- * a third-party leaf that grows a bare runtime import would fail loudly on the page instead, which
- * is a worse message but not a silent one.
- */
-/** The signal the demo app fires when it saves — the consequence the tour declares in advance. */
-export declare const DEMO_SIGNAL = "demo:saved";
-/** Controls the tour points at. Named here so the page and the run cannot disagree about them. */
-export declare const DemoTestId: {
-    readonly SAVE: "demo-save";
-    readonly NAME: "demo-name";
-    readonly STATUS: "demo-status";
-};
-export interface SdkMount {
-    /** URL prefix the page fetches under. */
-    prefix: string;
-    /** Directory on disk it serves from. */
-    dir: string;
-}
-export interface SdkGraph {
-    /** Bare specifier to the URL the page should load it from. */
-    imports: Record<string, string>;
-    mounts: SdkMount[];
-    /** URL of the SDK entry module itself. */
-    entry: string;
-}
-/**
- * Resolve the SDK and everything it reaches, as URLs a page can fetch.
- *
- * `resolve` is injected so a test can describe a dependency graph without one existing on disk —
- * and because the real one is `import.meta.resolve`, which answers against THIS module's location
- * and so cannot be pointed at a fixture.
- */
-export declare function sdkGraph(resolve?: (spec: string) => string): SdkGraph;
-/**
- * The demo app, and the one line that makes it verifiable.
- *
- * Saving fires a SIGNAL as well as changing the text. Both are here on purpose: the text is what a
- * person sees, the signal is what the app itself says happened, and the tour waits on the signal
- * because that is the difference it exists to teach — a rendered word can be a coincidence, and an
- * app declaring its own state cannot.
- */
-export declare function demoPageHtml(graph: SdkGraph, token: string, bridgeUrl: string): string;
-/**
- * Serve the demo on a port the OS picks.
- *
- * Port 0 rather than a chosen number: this starts while a daemon, a dev server and possibly another
- * copy of this tour are already running, and a tutorial whose first act is a port collision has
- * taught the wrong lesson about the product.
- */
-export declare function serveDemoPage(html: string, graph: SdkGraph): Promise<{
-    url: string;
-    close: () => Promise<void>;
-}>;

package/dist/command/cli/demo/demo-page.js

@@ -1,249 +0,0 @@
-/**
- * The page the tutorial drives when the user has no app of their own yet.
- *
- * `reticle tutorial` used to print four steps and stop. Printing is not teaching: the reader is told
- * that a verdict is the point, and then watches nothing produce one. So the tour now RUNS — against a
- * page served from here, because the alternative (drive whatever is in front of the user) is how a
- * first run ends on a login wall, and a tutorial that fails on step one teaches that Reticle does not
- * work.
- *
- * It carries the real SDK, not a stub. A demo instrumented by something other than the thing being
- * demonstrated proves nothing about the thing being demonstrated.
- *
- * WHY THERE IS NO IMPORT MAP WRITTEN DOWN HERE. The SDK is ESM with bare specifiers, the shipped
- * server has no bundler, and the obvious fix — a hand-written map of specifier to path — is the exact
- * defect this repository keeps paying for: two lists that must agree, where the one nobody updated is
- * the one that breaks. A dependency added to the SDK would leave this map short by one, the page
- * would fail to load a module, and the tour would report that the user's setup is broken.
- *
- * So the map is DISCOVERED. Start at the SDK entry, scan the files beside it for bare specifiers,
- * resolve each one, and repeat. It cannot be short by one, because nothing here knows the names.
- *
- * The walk follows imports out of OUR packages only; a third-party one is mounted whole and not
- * read. That is a deliberate line, not an oversight. Reading zod means walking several thousand
- * files to learn something that has not changed in this repository's lifetime, and it measurably
- * cost about a minute — on the one command whose whole job is a good first impression. The drift
- * this guards against is our own SDK gaining a dependency, which is the thing that actually moves;
- * a third-party leaf that grows a bare runtime import would fail loudly on the page instead, which
- * is a worse message but not a silent one.
- */
-import { fileURLToPath } from 'node:url';
-import { createServer } from 'node:http';
-import { dirname, join, relative, extname, sep } from 'node:path';
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
-/** Where the tour starts. Everything else on the page is reached from here. */
-const SDK_ENTRY = '@reticlehq/browser';
-/** The signal the demo app fires when it saves — the consequence the tour declares in advance. */
-export const DEMO_SIGNAL = 'demo:saved';
-/** Controls the tour points at. Named here so the page and the run cannot disagree about them. */
-export const DemoTestId = {
-    SAVE: 'demo-save',
-    NAME: 'demo-name',
-    STATUS: 'demo-status',
-};
-/** What the status line says before anything has been proved. */
-const STATUS_BEFORE = 'nothing saved yet';
-/** Bare specifiers this cannot serve and must not try to: the page is a browser. */
-const NOT_SERVABLE = /^node:/;
-/**
- * The packages whose imports are followed. See the note at the top for why the walk stops here.
- *
- * `open-verification` is listed by NAME because it is ours without being in the scope: it left the
- * org to stand on its own as the specification, and matching on `@reticlehq/` alone would silently
- * demote it to an unscanned third-party leaf. Today its only dependency is zod, which core already
- * pulls in, so nothing would have broken yet — which is exactly the kind of gap that is cheap now
- * and expensive on the day the spec grows a second dependency.
- */
-const OURS = /^(@reticlehq\/|open-verification$)/;
-const JS_CONTENT_TYPE = 'text/javascript; charset=utf-8';
-const HTML_CONTENT_TYPE = 'text/html; charset=utf-8';
-/**
- * A compiled package's own imports, read off disk.
- *
- * Test files are skipped: `dist` carries compiled specs, and those import `vitest` and `node:fs`,
- * which are not part of what a page loads and would send the walk looking for packages that only
- * exist in this repository.
- */
-function bareSpecifiersIn(dir) {
-    const found = new Set();
-    const walk = (at) => {
-        for (const entry of readdirSync(at, { withFileTypes: true })) {
-            const name = entry.name;
-            const path = join(at, name);
-            if (entry.isDirectory()) {
-                if ('node_modules' !== name)
-                    walk(path);
-                continue;
-            }
-            if (!name.endsWith('.js') || name.endsWith('.test.js'))
-                continue;
-            // `from` as a keyword, not the tail of a string: core's `z.discriminatedUnion('from', [...])`
-            // read as an import of everything up to the next quote. A specifier never holds whitespace.
-            for (const match of readFileSync(path, 'utf8').matchAll(/(?<![\w$.'"])from\s*'([^.'\s][^'\s]*)'/g)) {
-                const spec = match[1];
-                if (spec !== undefined && !NOT_SERVABLE.test(spec))
-                    found.add(spec);
-            }
-        }
-    };
-    walk(dir);
-    return found;
-}
-/** The directory holding a resolved entry's `package.json` — what has to be mounted whole. */
-function packageRootOf(entryPath) {
-    let at = dirname(entryPath);
-    for (;;) {
-        if (existsSync(join(at, 'package.json')))
-            return at;
-        const up = dirname(at);
-        if (up === at)
-            return undefined;
-        at = up;
-    }
-}
-/**
- * Resolve the SDK and everything it reaches, as URLs a page can fetch.
- *
- * `resolve` is injected so a test can describe a dependency graph without one existing on disk —
- * and because the real one is `import.meta.resolve`, which answers against THIS module's location
- * and so cannot be pointed at a fixture.
- */
-export function sdkGraph(resolve = defaultResolve) {
-    const imports = {};
-    const mounts = [];
-    const roots = new Map();
-    const queue = [SDK_ENTRY];
-    const seen = new Set();
-    let entry = '';
-    while (queue.length > 0) {
-        const spec = queue.shift();
-        if (spec === undefined || seen.has(spec))
-            continue;
-        seen.add(spec);
-        const entryPath = resolve(spec);
-        const root = packageRootOf(entryPath);
-        if (root === undefined) {
-            throw new Error(`the demo page cannot serve ${spec}: it resolves outside any package`);
-        }
-        let prefix = roots.get(root);
-        if (prefix === undefined) {
-            prefix = `/sdk/${String(mounts.length)}/`;
-            roots.set(root, prefix);
-            mounts.push({ prefix, dir: root });
-        }
-        const url = prefix + relative(root, entryPath).split(sep).join('/');
-        if (SDK_ENTRY === spec)
-            entry = url;
-        else
-            imports[spec] = url;
-        if (OURS.test(spec)) {
-            for (const next of bareSpecifiersIn(dirname(entryPath)))
-                queue.push(next);
-        }
-    }
-    return { imports, mounts, entry };
-}
-function defaultResolve(spec) {
-    return fileURLToPath(import.meta.resolve(spec));
-}
-/**
- * The demo app, and the one line that makes it verifiable.
- *
- * Saving fires a SIGNAL as well as changing the text. Both are here on purpose: the text is what a
- * person sees, the signal is what the app itself says happened, and the tour waits on the signal
- * because that is the difference it exists to teach — a rendered word can be a coincidence, and an
- * app declaring its own state cannot.
- */
-export function demoPageHtml(graph, token, bridgeUrl) {
-    const importMap = JSON.stringify({ imports: graph.imports });
-    const connect = JSON.stringify({ session: 'demo', url: bridgeUrl, token });
-    return `<!doctype html>
-<html lang="en"><head><meta charset="utf-8"><title>Reticle demo</title>
-<script type="importmap">${importMap}</script>
-<style>
- body{font:16px/1.5 system-ui,sans-serif;margin:0;padding:2.5rem 1.5rem;max-width:34rem}
- h1{font-size:1.3rem;margin:0 0 .25rem}
- p.lede{color:#555;margin:0 0 2rem}
- label{display:block;font-weight:600;margin:0 0 .4rem}
- input{font:inherit;padding:.5rem .6rem;width:100%;box-sizing:border-box;border:1px solid #bbb;border-radius:6px}
- button{font:inherit;margin-top:1rem;padding:.55rem 1.1rem;border:0;border-radius:6px;background:#111;color:#fff;cursor:pointer}
- p.status{margin-top:1.5rem;padding:.75rem;background:#f4f4f5;border-radius:6px}
-</style></head>
-<body>
- <h1>Reticle demo</h1>
- <p class="lede">A tiny app, instrumented with the real SDK. The tutorial is about to drive it.</p>
- <label for="${DemoTestId.NAME}">Display name</label>
- <input id="${DemoTestId.NAME}" data-testid="${DemoTestId.NAME}" value="Ada">
- <button data-testid="${DemoTestId.SAVE}">Save</button>
- <p class="status" data-testid="${DemoTestId.STATUS}">${STATUS_BEFORE}</p>
-<script type="module">
- import { reticle } from ${JSON.stringify(graph.entry)};
- reticle.connect(${connect});
- const status = document.querySelector('[data-testid="${DemoTestId.STATUS}"]');
- document.querySelector('[data-testid="${DemoTestId.SAVE}"]').addEventListener('click', () => {
-   const name = document.querySelector('[data-testid="${DemoTestId.NAME}"]').value;
-   status.textContent = 'saved ' + name;
-   reticle.signal(${JSON.stringify(DEMO_SIGNAL)}, { name });
- });
-</script>
-</body></html>`;
-}
-/**
- * Serve the demo on a port the OS picks.
- *
- * Port 0 rather than a chosen number: this starts while a daemon, a dev server and possibly another
- * copy of this tour are already running, and a tutorial whose first act is a port collision has
- * taught the wrong lesson about the product.
- */
-export function serveDemoPage(html, graph) {
-    const server = createServer((req, res) => {
-        const path = (req.url ?? '/').split('?')[0] ?? '/';
-        if ('/' === path) {
-            res.writeHead(200, { 'content-type': HTML_CONTENT_TYPE });
-            res.end(html);
-            return;
-        }
-        for (const mount of graph.mounts) {
-            if (!path.startsWith(mount.prefix))
-                continue;
-            const file = join(mount.dir, path.slice(mount.prefix.length));
-            // A request that climbed out of the mount is not served, whatever it points at.
-            if (!file.startsWith(mount.dir + sep))
-                break;
-            // One read, no prior exists/stat check: a missing file or a directory throws here, and there
-            // is no window between a check and the read for the path to change under it.
-            let body;
-            try {
-                body = readFileSync(file);
-            }
-            catch {
-                break;
-            }
-            res.writeHead(200, {
-                'content-type': '.js' === extname(file) ? JS_CONTENT_TYPE : 'application/octet-stream',
-            });
-            res.end(body);
-            return;
-        }
-        res.writeHead(404);
-        res.end('not found');
-    });
-    return new Promise((resolve, reject) => {
-        server.once('error', reject);
-        server.listen(0, '127.0.0.1', () => {
-            const address = server.address();
-            if (null === address || 'string' === typeof address) {
-                reject(new Error('the demo page could not be served: no port was assigned'));
-                return;
-            }
-            resolve({
-                url: `http://127.0.0.1:${String(address.port)}/`,
-                close: () => new Promise((done) => {
-                    server.close(() => {
-                        done();
-                    });
-                }),
-            });
-        });
-    });
-}

package/dist/command/cli/demo/demo-run.d.ts

@@ -1,38 +0,0 @@
-/**
- * The tutorial, run rather than printed.
- *
- * `reticle tutorial` described four steps and produced nothing. The last of those steps says that a
- * drive without a verdict has no result — and the tour itself ended without one, which is the lesson
- * taught by counter-example. So the same four steps now execute, against the demo page, and every
- * line the reader sees is a thing that actually happened.
- *
- * The steps are NOT re-listed here. They come from `tutorialScript`, the same source the printed tour
- * reads, because two descriptions of one sequence drift and the one nobody updated is the one
- * somebody follows.
- *
- * Tools are called in-process rather than over the daemon's MCP transport. This command starts the
- * daemon it drives, so it already holds the session; going back out over a socket to reach a server
- * inside this process would add a transport that can fail to a tour whose job is to not fail. The
- * funnel telemetry is unaffected either way — `runTool` is the chokepoint that reports it, and both
- * routes pass through it.
- */
-export interface DemoTourOptions {
-    port: number;
-    headless: boolean;
-    /** Every line the reader sees, in order. Injected so a test reads the tour instead of a terminal. */
-    say: (line: string) => void;
-    now?: () => number;
-}
-/** A tour either reached a verdict or it did not; the exit code says which. */
-export interface DemoTourResult {
-    code: number;
-    verified: string | undefined;
-}
-/**
- * Run the tour, and report whether it ended at a proof.
- *
- * A step that cannot be taken stops the tour and says which one. Carrying on past a failed step
- * would end at a verdict taken against a page the earlier steps never reached — which is precisely
- * the false green the fourth step is there to warn about.
- */
-export declare function runDemoTour(options: DemoTourOptions): Promise<DemoTourResult>;

package/dist/command/cli/demo/demo-run.js

@@ -1,138 +0,0 @@
-/**
- * The tutorial, run rather than printed.
- *
- * `reticle tutorial` described four steps and produced nothing. The last of those steps says that a
- * drive without a verdict has no result — and the tour itself ended without one, which is the lesson
- * taught by counter-example. So the same four steps now execute, against the demo page, and every
- * line the reader sees is a thing that actually happened.
- *
- * The steps are NOT re-listed here. They come from `tutorialScript`, the same source the printed tour
- * reads, because two descriptions of one sequence drift and the one nobody updated is the one
- * somebody follows.
- *
- * Tools are called in-process rather than over the daemon's MCP transport. This command starts the
- * daemon it drives, so it already holds the session; going back out over a socket to reach a server
- * inside this process would add a transport that can fail to a tour whose job is to not fail. The
- * funnel telemetry is unaffected either way — `runTool` is the chokepoint that reports it, and both
- * routes pass through it.
- */
-import { ReticleTool } from '@reticlehq/core';
-// TOOLS comes through the package barrel rather than from `surface/tools/tools.js` directly. That
-// aggregator composes the tool arrays out of five directories, and anything importing it back is how
-// this package accumulated cycles; the barrel sits above both it and this file, which is the
-// direction that does not close a loop.
-import { start, TOOLS } from '../../../index.js';
-import { runTool } from '../../../surface/tools/invoke-tool.js';
-import { buildVerifyDeps } from '../cli-verify.js';
-import { readOrCreatePairingTokenSync, defaultPairingTokenDir, } from '../../../portal/bridge/pairing-token.js';
-import { tutorialScript, TutorialAudience, demoPlan } from '../tutorial.js';
-import { sdkGraph, demoPageHtml, serveDemoPage, DEMO_SIGNAL } from './demo-page.js';
-/** How long to wait for the demo page to dial the bridge before giving up on it. */
-const SESSION_TIMEOUT_MS = 30_000;
-const SESSION_POLL_MS = 250;
-/** Only `verified: "yes"` is a pass — see the contract every verdict tool here is held to. */
-const PROVED = 'yes';
-function toolNamed(name) {
-    const found = TOOLS.find((t) => t.name === name);
-    if (found === undefined) {
-        throw new Error(`the tutorial cannot run: ${name} is not in the tool registry`);
-    }
-    return found;
-}
-function asRecord(value) {
-    return 'object' === typeof value && null !== value ? value : {};
-}
-function asText(value) {
-    return 'string' === typeof value ? value : undefined;
-}
-/** The controls `reticle_query` found, in the shape the safety rule reads them. */
-function controlsIn(result) {
-    const raw = asRecord(result)['elements'];
-    if (!Array.isArray(raw))
-        return [];
-    const out = [];
-    for (const item of raw) {
-        const el = asRecord(item);
-        const ref = asText(el['ref']);
-        const name = asText(el['name']);
-        if (ref === undefined || name === undefined)
-            continue;
-        const role = asText(el['role']);
-        out.push(role === undefined ? { ref, name } : { ref, name, role });
-    }
-    return out;
-}
-async function waitForSession(running, now) {
-    const deadline = now() + SESSION_TIMEOUT_MS;
-    while (now() < deadline) {
-        if (running.bridge.sessions.count() > 0)
-            return true;
-        await new Promise((resolve) => setTimeout(resolve, SESSION_POLL_MS));
-    }
-    return running.bridge.sessions.count() > 0;
-}
-/**
- * Run the tour, and report whether it ended at a proof.
- *
- * A step that cannot be taken stops the tour and says which one. Carrying on past a failed step
- * would end at a verdict taken against a page the earlier steps never reached — which is precisely
- * the false green the fourth step is there to warn about.
- */
-export async function runDemoTour(options) {
-    const now = options.now ?? (() => Date.now());
-    const steps = new Map(tutorialScript(TutorialAudience.HUMAN).map((s) => [s.id, s]));
-    const announce = (id) => {
-        const step = steps.get(id);
-        if (step === undefined)
-            return;
-        options.say('');
-        options.say(step.say);
-        options.say(`  why: ${step.why}`);
-    };
-    const graph = sdkGraph();
-    const token = readOrCreatePairingTokenSync(defaultPairingTokenDir()) ?? '';
-    const bridgeUrl = `ws://localhost:${String(options.port)}/reticle`;
-    const page = await serveDemoPage(demoPageHtml(graph, token, bridgeUrl), graph);
-    let running;
-    try {
-        running = await start({ port: options.port, driveUrl: page.url, headless: options.headless });
-        const deps = buildVerifyDeps(running, process.cwd(), now);
-        const call = async (name, args) => await runTool(toolNamed(name), deps, args);
-        announce('connect');
-        if (!(await waitForSession(running, now))) {
-            options.say('  the demo page never dialled the bridge, so there is nothing to show.');
-            return { code: 1, verified: undefined };
-        }
-        options.say(`  one session connected: the demo app at ${page.url}`);
-        announce('look');
-        const snapshot = asRecord(await call(ReticleTool.SNAPSHOT, { mode: 'interactive' }));
-        for (const line of (asText(snapshot['tree']) ?? '').split('\n'))
-            options.say(`  ${line}`);
-        announce('declare');
-        const found = controlsIn(await call(ReticleTool.QUERY, { role: 'button' }));
-        const plan = demoPlan(found);
-        if (!plan.ok) {
-            options.say(`  ${plan.because}`);
-            return { code: 1, verified: undefined };
-        }
-        options.say(`  "${plan.name}" is safe to press. Saving should make the app say so itself:`);
-        options.say(`  reticle_act_and_wait { ref: "${plan.ref}", action: "click", until: {`);
-        options.say(`    kind: "signal", name: "${DEMO_SIGNAL}" } }`);
-        announce('verdict');
-        const verdict = asRecord(await call(ReticleTool.ACT_AND_WAIT, {
-            ref: plan.ref,
-            action: 'click',
-            until: { kind: 'signal', name: DEMO_SIGNAL },
-        }));
-        const verified = asText(verdict['verified']);
-        const because = asText(verdict['verifiedReason']) ?? asText(verdict['failureReason']);
-        options.say(`  verified: ${verified ?? 'unknown'}`);
-        if (because !== undefined)
-            options.say(`  because: ${because}`);
-        return { code: PROVED === verified ? 0 : 1, verified };
-    }
-    finally {
-        await page.close();
-        await running?.close?.();
-    }
-}

package/dist/judgement/hunt/hunt-report.d.ts

@@ -1,49 +0,0 @@
-/**
- * Aggregate many crawl runs into the one number the core claim needs.
- *
- * Detection already exists: `reticle_crawl` drives every reachable control and reports contradictions
- * — two channels disagreeing about the same click. It found `swallowed-500-login` and, separately,
- * `ui-advanced-request-failed` on a control whose assertion was green, neither of them planted.
- *
- * What was missing is the arithmetic that turns those into evidence. The claim worth making is not
- * "Reticle can find bugs"; it is:
- *
- *   "Run over N already-merged, already-green changes, it found X real bugs their own tests
- *    certified as passing."
- *
- * That needs no control arm, which is why it is the cheapest credible proof available: the
- * counterfactual is already established, because those changes SHIPPED. An A/B is the second study,
- * and this tells you where to point it.
- *
- * Pure functions over already-collected reports — the driving is `reticle_crawl`'s job, and running
- * it across a commit range is a shell loop. This is only the part that must not be done by eye.
- */
-export interface HuntAnomaly {
-    kind: string;
-    ref?: string;
-    desc?: string;
-    detail?: string;
-}
-/** One crawl over one checkout. `label` is whatever identifies it — a commit sha, a PR number. */
-export interface HuntRun {
-    label: string;
-    anomalies: readonly HuntAnomaly[];
-    /** Controls actually driven. A run that drove nothing proves nothing and is reported separately. */
-    stepsRun?: number;
-}
-interface HuntSummary {
-    runs: number;
-    /** Runs that actually drove at least one control. The denominator that can honestly be quoted. */
-    runsWithCoverage: number;
-    /** Runs where at least one CONTRADICTION was found — the headline numerator. */
-    runsWithContradictions: number;
-    contradictions: number;
-    /** Single-channel faults (console errors, failed requests, dead controls). Context, not the claim. */
-    singleChannelFaults: number;
-    byKind: Record<string, number>;
-    /** Labels with contradictions, so each one can be confirmed by hand before it is counted. */
-    flagged: string[];
-    headline: string;
-}
-export declare function summarizeHunt(runs: readonly HuntRun[]): HuntSummary;
-export {};

package/dist/judgement/hunt/hunt-report.js

@@ -1,84 +0,0 @@
-/**
- * Aggregate many crawl runs into the one number the core claim needs.
- *
- * Detection already exists: `reticle_crawl` drives every reachable control and reports contradictions
- * — two channels disagreeing about the same click. It found `swallowed-500-login` and, separately,
- * `ui-advanced-request-failed` on a control whose assertion was green, neither of them planted.
- *
- * What was missing is the arithmetic that turns those into evidence. The claim worth making is not
- * "Reticle can find bugs"; it is:
- *
- *   "Run over N already-merged, already-green changes, it found X real bugs their own tests
- *    certified as passing."
- *
- * That needs no control arm, which is why it is the cheapest credible proof available: the
- * counterfactual is already established, because those changes SHIPPED. An A/B is the second study,
- * and this tells you where to point it.
- *
- * Pure functions over already-collected reports — the driving is `reticle_crawl`'s job, and running
- * it across a commit range is a shell loop. This is only the part that must not be done by eye.
- */
-/** The contradiction kinds — cross-channel disagreement, as opposed to a single-channel fault. */
-const CONTRADICTION_KINDS = [
-    'ui-advanced-request-failed',
-    'signal-contradicted',
-    'response-ignored',
-    'duplicate-request',
-    'request-never-settled',
-    'failure-misattributed',
-];
-const isContradiction = (kind) => CONTRADICTION_KINDS.includes(kind);
-export function summarizeHunt(runs) {
-    const byKind = {};
-    const flagged = [];
-    let contradictions = 0;
-    let singleChannelFaults = 0;
-    let runsWithCoverage = 0;
-    for (const run of runs) {
-        // A run that drove nothing is not evidence of cleanliness. Counting it in the denominator would
-        // dilute the rate with checkouts where the app never even came up — the arithmetic equivalent of
-        // reporting a green because no test ran.
-        if ((run.stepsRun ?? 0) > 0)
-            runsWithCoverage += 1;
-        let flaggedThisRun = false;
-        for (const anomaly of run.anomalies) {
-            byKind[anomaly.kind] = (byKind[anomaly.kind] ?? 0) + 1;
-            if (isContradiction(anomaly.kind)) {
-                contradictions += 1;
-                flaggedThisRun = true;
-            }
-            else {
-                singleChannelFaults += 1;
-            }
-        }
-        if (flaggedThisRun)
-            flagged.push(run.label);
-    }
-    return {
-        runs: runs.length,
-        runsWithCoverage,
-        runsWithContradictions: flagged.length,
-        contradictions,
-        singleChannelFaults,
-        byKind,
-        flagged,
-        headline: buildHeadline(runsWithCoverage, flagged.length, contradictions),
-    };
-}
-/**
- * The sentence that goes in front of someone, phrased so it cannot overstate itself.
- *
- * It counts CHECKOUTS with a finding rather than raw findings, because one broken control clicked
- * five times is one bug and five anomalies. It also says "candidate": every flag still has to be
- * confirmed by hand before it is a bug, and a number that skips that step is the kind of evidence
- * this project exists to distrust.
- */
-function buildHeadline(withCoverage, flaggedRuns, contradictions) {
-    if (0 === withCoverage) {
-        return 'no run drove a single control — nothing was measured, which is not the same as nothing being wrong';
-    }
-    if (0 === flaggedRuns) {
-        return `${String(withCoverage)} merged changes crawled, no cross-channel contradictions found — confirm coverage was real before reading this as clean`;
-    }
-    return `${String(flaggedRuns)} of ${String(withCoverage)} merged, already-green changes carried a candidate false green (${String(contradictions)} contradictions) — each needs manual confirmation before it is counted`;
-}

package/dist/language/flows/buddy-status.d.ts

@@ -1,25 +0,0 @@
-/**
- * The buddy channel. The co-dev experience for the HUMAN: a single ambient line they can park in
- * a statusline or terminal and glance at — never a wall of output, never something they have to ask for.
- *
- * The rule this encodes: say the reassuring thing briefly and the alarming thing specifically. "41 flows
- * nominal" needs no detail; a deviation needs its name, because a status line that says only "1 deviation"
- * forces the human to go digging, which is exactly the work the buddy exists to remove.
- */
-interface BuddyStatusInput {
-    /** Every saved flow. */
-    total: number;
-    /** Flows with a passing artifact. */
-    passing: number;
-    /** Flows that changed files put at risk and that have NO passing artifact — the actionable set. */
-    deviations: readonly string[];
-    /** Flows quarantined as flaky — surfaced, never blocking. */
-    quarantined: readonly string[];
-}
-/**
- * One line, safe to print on every save. Shape:
- * `✓ 41 flows nominal`
- * `✗ 2 deviations: checkout, billing · 39 nominal · 1 flaky quarantined`
- */
-export declare function formatBuddyStatus(input: BuddyStatusInput): string;
-export {};