@reticlehq/server 2.14.0 → 3.2.0

package/dist/pool/playwright-launcher.js

@@ -1,150 +0,0 @@
-/**
- * The real Playwright adapter behind BrowserPool: wraps `chromium.launch` into the pool's small
- * PooledBrowser/Context/Page interfaces. Kept thin and separate so the pool's lifecycle logic stays
- * unit-tested with a fake while this glue is exercised only by the e2e battery (it needs Chromium).
- *
- * Headless by default — the pool exists for fault-tolerant headless multi-agent testing.
- */
-import { BrowserLaunchKind } from '@reticlehq/core/telemetry';
-import { chromiumLaunchOptions } from '../chromium-launch-options.js';
-import { getSessionMetrics } from '../telemetry/session-metrics.js';
-import { classifyConnectFailure } from '../telemetry/connect-failure.js';
-import { chromiumInstallCommand, chromiumInstallDepsCommand, bundledPlaywrightVersion, } from '../cli/chromium-hint.js';
-import { installNetworkMocks } from '../input/network-mock.js';
-/**
- * How a leased tab navigates. Pure, and exported, because the decision in it is worth a test while
- * the rest of this file needs a real Chromium.
- *
- * `waitUntil: 'domcontentloaded'` — NOT Playwright's default of `load`. `load` waits for every
- * subresource, so an app with one that never finishes burns the whole nav budget and the lease then
- * reports "is the app running?" about an app that is running. Measured on the sveltekit fixture:
- * 30,501ms and a false diagnosis. The SDK connect is a module script and runs before
- * DOMContentLoaded, and the pool separately waits for the session to register, so the load event was
- * never what proved the page was usable.
- */
-export function gotoOptions(timeoutMs) {
-    return {
-        waitUntil: 'domcontentloaded',
-        // Absent, not zero: zero means "no timeout" to Playwright, which would turn a slow page into a
-        // lease that never returns.
-        ...(timeoutMs === undefined ? {} : { timeout: timeoutMs }),
-    };
-}
-function wrapBrowser(browser) {
-    return {
-        isConnected: () => browser.isConnected(),
-        newContext: async () => {
-            const context = await browser.newContext();
-            return {
-                newPage: async () => {
-                    const page = await context.newPage();
-                    return {
-                        goto: (url, opts) => page.goto(url, gotoOptions(opts?.timeoutMs)),
-                        close: () => page.close(),
-                        // Playwright returns a Buffer; Uint8Array is what the visual store and differ take.
-                        screenshot: async (opts) => new Uint8Array(await page.screenshot({ fullPage: true === opts?.fullPage })),
-                        // Three moves, same as performGesture: a single move to the center can be a no-op if
-                        // the pointer was already there, and CSS :hover needs a native hit-test to apply.
-                        hover: async (x, y) => {
-                            await page.mouse.move(x, y);
-                            await page.mouse.move(x + 1, y);
-                            await page.mouse.move(x, y);
-                        },
-                        installMocks: (rules) => installNetworkMocks(page, [...rules]),
-                        setViewport: (size) => page.setViewportSize(size),
-                        onCrash: (handler) => page.on('crash', handler),
-                        onConsole: (handler) => page.on('console', (msg) => handler(msg.text())),
-                        onDialog: (handler) => page.on('dialog', (dialog) => handler({ message: dialog.message(), dismiss: () => dialog.dismiss() })),
-                        addInitScript: async (script, arg) => {
-                            const handle = (await page.addInitScript(script, arg));
-                            const dispose = handle?.dispose;
-                            if ('function' !== typeof dispose) {
-                                throw new Error('Storage seeding failed: Playwright page.addInitScript did not return a disposable handle');
-                            }
-                            return { dispose: () => dispose() };
-                        },
-                    };
-                },
-                addCookies: (cookies) => context.addCookies(cookies),
-                close: () => context.close(),
-            };
-        },
-        close: () => browser.close(),
-        onDisconnected: (handler) => browser.on('disconnected', handler),
-    };
-}
-/**
- * The fix for the most common first-run failure: Chromium isn't installed for Playwright.
- *
- * Pinned to the playwright this process bundles. Unpinned, `npx` fetches the latest playwright and
- * installs ITS browser revision — a build this launcher will never look at — so the user follows the
- * advice, it succeeds, and the next launch fails identically. Shares one builder with `doctor` so the
- * two cannot suggest different commands for the same missing browser.
- */
-const CHROMIUM_MISSING_HINT = `Chromium is not installed for Playwright. Run: ${chromiumInstallCommand(bundledPlaywrightVersion())}`;
-/**
- * A DIFFERENT first-run failure from the one above: the browser binary is already there, but the
- * host is missing the OS-level shared libraries (e.g. `libnspr4.so`) Playwright's own
- * host-requirement check refuses to launch without. `npx playwright install chromium` does nothing
- * for this — it re-downloads a binary that was never the problem — so this needs its own hint
- * pointing at `install-deps`, pinned the same way and for the same reason as the one above.
- */
-const CHROMIUM_MISSING_DEPS_HINT = `Chromium is installed, but the host system is missing shared-library dependencies it needs. Run: ${chromiumInstallDepsCommand(bundledPlaywrightVersion())}`;
-/** A Launcher that boots a real headless Chromium and adapts it to the pool's interface. */
-export function playwrightLauncher(opts = {}) {
-    const headless = opts.headless ?? true;
-    // `playwright` is an OPTIONAL dependency. A static value-import here would be pulled in by the
-    // server's main entry (index.ts re-exports this module) and crash the whole process with
-    // ERR_MODULE_NOT_FOUND on any install without Chromium — the CLI, the MCP server, everything.
-    // Import it lazily, only when a browser is actually launched, so absence fails at drive-time
-    // (where it's meaningful) instead of at import-time (where it kills unrelated features).
-    return async () => {
-        const { chromium } = await import('playwright');
-        // A pooled launch serves N parallel leases, so this counts BROWSERS, not contexts — which is the
-        // number that actually costs memory and the one that explains a slow machine.
-        const settle = getSessionMetrics().recordConnectAttempt(BrowserLaunchKind.POOLED);
-        try {
-            const browser = wrapBrowser(await chromium.launch(chromiumLaunchOptions(headless)));
-            settle();
-            return browser;
-        }
-        catch (err) {
-            settle(classifyConnectFailure(err));
-            // Turn Playwright's raw "Executable doesn't exist" into the one command that fixes it.
-            const msg = err instanceof Error ? err.message : String(err);
-            // Checked FIRST: Playwright's host-requirement validation error also contains
-            // "browserType.launch", so the generic check below would otherwise misdiagnose it as a
-            // missing binary and send the user through a fix that changes nothing.
-            if (/host system is missing dependencies/i.test(msg)) {
-                throw new Error(CHROMIUM_MISSING_DEPS_HINT);
-            }
-            if (/executable doesn.?t exist|playwright install|browsertype\.launch/i.test(msg)) {
-                throw new Error(CHROMIUM_MISSING_HINT);
-            }
-            throw err;
-        }
-    };
-}
-const MAX_CONTEXTS_CEILING = 8;
-const MAX_CONTEXTS_FLOOR = 1;
-/**
- * Hard backstop for an EXPLICIT RETICLE_MAX_CONTEXTS. The operator override still wins for any
- * realistic value (well above the CPU-derived ceiling), but a typo/abuse like 5000 can't spawn 5000
- * browser contexts and exhaust memory/FDs — the fork-bomb the function's own comment warns about.
- */
-const MAX_CONTEXTS_HARD_CEILING = 128;
-/**
- * Resolve the pool's concurrency cap. An explicit RETICLE_MAX_CONTEXTS wins (clamped to
- * [1, hard ceiling]); otherwise scale with the machine but never above the CPU-derived ceiling.
- * Pure (env value + cpu count passed in) so it's testable.
- */
-export function resolveMaxContexts(envValue, cpuCount) {
-    if (envValue !== undefined) {
-        const parsed = parseInt(envValue, 10);
-        if (!isNaN(parsed) && parsed >= MAX_CONTEXTS_FLOOR) {
-            return Math.min(MAX_CONTEXTS_HARD_CEILING, parsed);
-        }
-    }
-    const byCpu = Math.max(MAX_CONTEXTS_FLOOR, cpuCount - 1);
-    return Math.min(MAX_CONTEXTS_CEILING, byCpu);
-}

package/dist/pool/storage-seed.d.ts

@@ -1,23 +0,0 @@
-import { type SeedStorage } from '@reticlehq/core';
-import type { InitScriptHandle, PooledContext, PooledCookie, PooledPage } from './browser-pool.js';
-export declare function targetOriginOf(navUrl: string): string | undefined;
-export declare function normalizeCookies(cookies: SeedStorage['cookies'], navUrl: string): PooledCookie[];
-export interface StorageSeedResult {
-    handle?: InitScriptHandle;
-    checkError?: () => void;
-}
-/**
- * Seed initial storage state (cookies, localStorage, sessionStorage) into a leased context and page
- * before the first navigation happens.
- *
- * Cookies are injected into the BrowserContext cookie jar so the initial HTTP GET to the target URL
- * already carries the Cookie header (including httpOnly session cookies).
- *
- * Local and session storage are injected via an init script evaluated after document creation but
- * before any inline or bundled application scripts run. The init script is scoped strictly to the
- * top-level target origin document (not child iframes or external redirect origins).
- *
- * Returns a handle that allows the caller to dispose of the init script once the initial navigation
- * has resolved, ensuring one-time semantics (reloads or future navigations do not reapply the seed).
- */
-export declare function seedStorageInto(context: PooledContext, page: PooledPage, targetUrl: string, seed: SeedStorage): Promise<StorageSeedResult | void>;

package/dist/project/artifact-root.d.ts

@@ -1,84 +0,0 @@
-import { type ProjectCandidate, type ProjectRegistry } from '@reticlehq/core';
-import type { ConfigDiscovery } from '../cli/config-discovery.js';
-/**
- * Which `.reticle/` a session's artifacts belong in.
- *
- * Everything Reticle persists — flows, the capability contract, baselines, capsules, the cross-run
- * project memory — used to resolve against the DAEMON's own `process.cwd()`. That is a statement
- * about where the daemon was launched and it was being read as a statement about which project is
- * being verified. Those are not the same thing and are usually not even the same tree: a user-scoped
- * MCP registration is the common case, and the editor that spawns it starts it wherever it likes.
- *
- * Three field shapes, one defect: `cwd=/` gave `ENOENT: mkdir '/.reticle'`; a daemon started in
- * project A wrote project B's flow into A's checkout and reported success without naming the path;
- * and `verify_change` could only answer "unknown" because no flow could be persisted for it to match
- * against.
- *
- * ## Two sources, one rule
- *
- * Candidates arrive from config discovery (which walks out from the daemon's own directory) and from
- * the user-level project registry (which `init` writes, and which reaches checkouts discovery cannot
- * see). This function takes the merged list and does not know or care which source an entry came
- * from — a privileged source would be a second rule, and two rules for one question is how the
- * answers start disagreeing.
- *
- * ## Why matching on projectId, and not a new wire field
- *
- * HELLO already stamps `projectId`, and `.reticle.json` already declares the same id sitting next to
- * the code it configures. The join is therefore available today, for every SDK already in the field.
- * Adding a `root` to HELLO would move the wire contract, strand every older SDK on the fallback, and
- * buy nothing this does not already give.
- *
- * ## Why it can decline to answer
- *
- * Every non-matching branch returns the daemon root and SAYS which branch it was. A wrong root is
- * worse than no root — it writes a caller's evidence into a tree they never drove — so the ambiguous
- * case refuses rather than picks, exactly as `discoverProjectConfigs` refuses to pick one config.
- * The reason travels with the answer so callers can report the surprise instead of hiding it.
- */
-/** Why the root below is the root. Travels with the answer so a caller can say what happened. */
-export declare const ArtifactRootReason: {
-    /** Exactly one discovered config declares this session's project. The good case. */
-    readonly MATCHED_PROJECT: "matched-project";
-    /** The session declared no projectId — a pre-2.0 SDK. Nothing to match on. */
-    readonly NO_PROJECT_ID: "no-project-id";
-    /** The search ran and nothing it found declares this project. */
-    readonly NO_MATCH: "no-match";
-    /** Two or more checkouts declare this project. Refused rather than guessed. */
-    readonly AMBIGUOUS: "ambiguous";
-};
-export type ArtifactRootReason = (typeof ArtifactRootReason)[keyof typeof ArtifactRootReason];
-interface ArtifactRootQuery {
-    /** The connected session's HELLO projectId, when it sent one. */
-    projectId: string | undefined;
-    /** Every project this machine knows about. Supplied, not gathered here — this stays pure. */
-    candidates: readonly ProjectCandidate[];
-    /** Where artifacts go when the project cannot be identified. Already a `.reticle` path. */
-    daemonRoot: string;
-}
-export interface ArtifactRoot {
-    /** Absolute path to the `.reticle` directory. Always present, on every branch. */
-    root: string;
-    reason: ArtifactRootReason;
-    /**
-     * The competing project directories, on `AMBIGUOUS` only. A caller that has to explain the refusal
-     * needs to name them; a caller that does not can ignore the field.
-     */
-    candidates?: string[];
-}
-/**
- * Resolve the artifact root for one session.
- *
- * Pure: no IO, no cwd, no clock. The filesystem walk belongs to `discoverProjectConfigs` and is
- * passed in, which is what makes every branch below testable without a fixture tree.
- */
-export declare function resolveArtifactRoot(query: ArtifactRootQuery): ArtifactRoot;
-/**
- * Everything this machine knows about where projects live, from both sources.
- *
- * Discovery first, deliberately: it read a `.reticle.json` that exists RIGHT NOW, while the registry
- * is a cache of something `init` saw once. Order only decides which duplicate survives dedupe, and
- * the one confirmed a moment ago is the better survivor.
- */
-export declare function projectCandidatesFrom(discovery: ConfigDiscovery, registry: ProjectRegistry): ProjectCandidate[];
-export {};

package/dist/project/artifact-root.js

@@ -1,112 +0,0 @@
-import { join } from 'node:path';
-import { ReticleDir, projectCandidates, } from '@reticlehq/core';
-/**
- * Which `.reticle/` a session's artifacts belong in.
- *
- * Everything Reticle persists — flows, the capability contract, baselines, capsules, the cross-run
- * project memory — used to resolve against the DAEMON's own `process.cwd()`. That is a statement
- * about where the daemon was launched and it was being read as a statement about which project is
- * being verified. Those are not the same thing and are usually not even the same tree: a user-scoped
- * MCP registration is the common case, and the editor that spawns it starts it wherever it likes.
- *
- * Three field shapes, one defect: `cwd=/` gave `ENOENT: mkdir '/.reticle'`; a daemon started in
- * project A wrote project B's flow into A's checkout and reported success without naming the path;
- * and `verify_change` could only answer "unknown" because no flow could be persisted for it to match
- * against.
- *
- * ## Two sources, one rule
- *
- * Candidates arrive from config discovery (which walks out from the daemon's own directory) and from
- * the user-level project registry (which `init` writes, and which reaches checkouts discovery cannot
- * see). This function takes the merged list and does not know or care which source an entry came
- * from — a privileged source would be a second rule, and two rules for one question is how the
- * answers start disagreeing.
- *
- * ## Why matching on projectId, and not a new wire field
- *
- * HELLO already stamps `projectId`, and `.reticle.json` already declares the same id sitting next to
- * the code it configures. The join is therefore available today, for every SDK already in the field.
- * Adding a `root` to HELLO would move the wire contract, strand every older SDK on the fallback, and
- * buy nothing this does not already give.
- *
- * ## Why it can decline to answer
- *
- * Every non-matching branch returns the daemon root and SAYS which branch it was. A wrong root is
- * worse than no root — it writes a caller's evidence into a tree they never drove — so the ambiguous
- * case refuses rather than picks, exactly as `discoverProjectConfigs` refuses to pick one config.
- * The reason travels with the answer so callers can report the surprise instead of hiding it.
- */
-/** Why the root below is the root. Travels with the answer so a caller can say what happened. */
-export const ArtifactRootReason = {
-    /** Exactly one discovered config declares this session's project. The good case. */
-    MATCHED_PROJECT: 'matched-project',
-    /** The session declared no projectId — a pre-2.0 SDK. Nothing to match on. */
-    NO_PROJECT_ID: 'no-project-id',
-    /** The search ran and nothing it found declares this project. */
-    NO_MATCH: 'no-match',
-    /** Two or more checkouts declare this project. Refused rather than guessed. */
-    AMBIGUOUS: 'ambiguous',
-};
-/**
- * Resolve the artifact root for one session.
- *
- * Pure: no IO, no cwd, no clock. The filesystem walk belongs to `discoverProjectConfigs` and is
- * passed in, which is what makes every branch below testable without a fixture tree.
- */
-export function resolveArtifactRoot(query) {
-    const { projectId, candidates, daemonRoot } = query;
-    if (projectId === undefined || 0 === projectId.length) {
-        return { root: daemonRoot, reason: ArtifactRootReason.NO_PROJECT_ID };
-    }
-    const matches = dedupeByDirectory(candidates.filter((c) => c.projectId === projectId));
-    if (0 === matches.length) {
-        return { root: daemonRoot, reason: ArtifactRootReason.NO_MATCH };
-    }
-    if (matches.length > 1) {
-        return {
-            root: daemonRoot,
-            reason: ArtifactRootReason.AMBIGUOUS,
-            candidates: matches.map((config) => config.directory),
-        };
-    }
-    const [only] = matches;
-    // `matches.length === 1` above, so this is defined — but the codebase forbids `!`, and a default
-    // that can never be taken is cheaper than the alternative spelling.
-    const directory = only?.directory ?? '';
-    if (0 === directory.length) {
-        return { root: daemonRoot, reason: ArtifactRootReason.NO_MATCH };
-    }
-    return { root: join(directory, ReticleDir.ROOT), reason: ArtifactRootReason.MATCHED_PROJECT };
-}
-/**
- * One entry per directory.
- *
- * Discovery and the registry routinely name the SAME checkout — the registry remembers what `init`
- * wrote, and discovery finds that same file whenever the daemon happens to be in the tree. Counting
- * it twice would read as two competing checkouts and make the resolver refuse, which is the one
- * outcome worse than either source alone.
- */
-function dedupeByDirectory(matches) {
-    const seen = new Set();
-    const out = [];
-    for (const candidate of matches) {
-        if (seen.has(candidate.directory))
-            continue;
-        seen.add(candidate.directory);
-        out.push(candidate);
-    }
-    return out;
-}
-/**
- * Everything this machine knows about where projects live, from both sources.
- *
- * Discovery first, deliberately: it read a `.reticle.json` that exists RIGHT NOW, while the registry
- * is a cache of something `init` saw once. Order only decides which duplicate survives dedupe, and
- * the one confirmed a moment ago is the better survivor.
- */
-export function projectCandidatesFrom(discovery, registry) {
-    const discovered = discovery.found.flatMap((config) => config.projectId === undefined || 0 === config.projectId.length
-        ? []
-        : [{ projectId: config.projectId, directory: config.directory }]);
-    return [...discovered, ...projectCandidates(registry)];
-}

package/dist/project/fs-port.d.ts

@@ -1,47 +0,0 @@
-/**
- * The injectable filesystem seam. Server logic depends on this interface, never on node:fs
- * directly — so tests pass an in-memory or temp-dir adapter and never touch the repo's .reticle/.
- */
-export interface FileSystemPort {
-    /** Read a UTF-8 file. Rejects (ENOENT) if absent. */
-    readFile(path: string): Promise<string>;
-    /**
-     * Read a UTF-8 file from a BYTE offset to EOF, returning the tail plus the file's total byte size.
-     * The append-only journal grows unboundedly, so re-reading the whole file per query is O(N-per-call);
-     * this reads only what was appended since the caller's tracked offset. Callers MUST pass an offset
-     * that lands on a `\n` boundary (the journal's line terminator, 1 ASCII byte) so the returned tail
-     * starts on a valid UTF-8 char boundary. Optional — a FileSystemPort that omits it makes readers fall
-     * back to a whole-file read.
-     */
-    readFileFrom?(path: string, byteOffset: number): Promise<{
-        text: string;
-        size: number;
-    }>;
-    writeFile(path: string, data: string): Promise<void>;
-    /** Append UTF-8 text, creating the file if absent — for the append-only JSONL journal. */
-    appendFile(path: string, data: string): Promise<void>;
-    /** Read raw bytes (PNG baselines). Rejects (ENOENT) if absent. */
-    readFileBytes(path: string): Promise<Uint8Array>;
-    /** Write raw bytes (PNG screenshots/diffs). */
-    writeFileBytes(path: string, data: Uint8Array): Promise<void>;
-    /** Recursive + idempotent: no throw if the directory already exists. */
-    mkdir(path: string): Promise<void>;
-    exists(path: string): Promise<boolean>;
-    /** List entries of a directory (for flows/baselines listing). */
-    readdir(path: string): Promise<string[]>;
-    /** Atomically replace `to` with `from` (same-FS rename) — for crash-safe writes. */
-    rename(from: string, to: string): Promise<void>;
-    /** Idempotent remove (no throw if absent) — for retention pruning + cleaning temp files. */
-    rm(path: string): Promise<void>;
-    /** Modification time in epoch ms — for recency-based retention pruning. Rejects if absent. */
-    stat(path: string): Promise<{
-        mtimeMs: number;
-        size: number;
-    }>;
-    /** Resolve symlinks to their real path — for upload trust-boundary checks. Rejects if absent. */
-    realpath(path: string): Promise<string>;
-    /** ENOENT classifier — narrows unknown without `any`, so callers can distinguish missing-file. */
-    isNotFound(error: unknown): boolean;
-}
-/** Production adapter — the single import site of node:fs/promises in the server. */
-export declare function createNodeFileSystem(): FileSystemPort;

package/dist/project/fs-port.js

@@ -1,54 +0,0 @@
-import { access, appendFile, mkdir, open, readdir, readFile, realpath, rename, rm, stat, writeFile, } from 'node:fs/promises';
-/** Production adapter — the single import site of node:fs/promises in the server. */
-export function createNodeFileSystem() {
-    return {
-        readFile: (path) => readFile(path, 'utf8'),
-        readFileFrom: async (path, byteOffset) => {
-            const fh = await open(path, 'r');
-            try {
-                const { size } = await fh.stat();
-                if (byteOffset >= size)
-                    return { text: '', size };
-                const length = size - byteOffset;
-                const buf = Buffer.allocUnsafe(length);
-                await fh.read(buf, 0, length, byteOffset);
-                return { text: buf.toString('utf8'), size };
-            }
-            finally {
-                await fh.close();
-            }
-        },
-        writeFile: (path, data) => writeFile(path, data, 'utf8'),
-        appendFile: (path, data) => appendFile(path, data, 'utf8'),
-        readFileBytes: async (path) => {
-            const buf = await readFile(path);
-            return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
-        },
-        writeFileBytes: (path, data) => writeFile(path, data),
-        mkdir: async (path) => {
-            await mkdir(path, { recursive: true });
-        },
-        exists: async (path) => {
-            try {
-                await access(path);
-                return true;
-            }
-            catch {
-                return false;
-            }
-        },
-        readdir: (path) => readdir(path),
-        rename: (from, to) => rename(from, to),
-        rm: async (path) => {
-            // recursive so a session-journal DIRECTORY can be pruned; force so a missing path is a no-op.
-            // recursive is harmless for the file-removal callers (run/flow artifacts).
-            await rm(path, { recursive: true, force: true });
-        },
-        stat: async (path) => {
-            const s = await stat(path);
-            return { mtimeMs: s.mtimeMs, size: s.size };
-        },
-        realpath: (path) => realpath(path),
-        isNotFound: (error) => 'ENOENT' === error?.code,
-    };
-}

package/dist/project/learned-routes.d.ts

@@ -1,24 +0,0 @@
-import { type ReticleEvent } from '@reticlehq/core';
-interface RouteLearningSession {
-    url: string;
-    onEvent(handler: (event: ReticleEvent) => void): () => void;
-}
-interface RouteLearningBridge {
-    sessions: {
-        all(): RouteLearningSession[];
-    };
-    attachSessionReady(handler: (session: RouteLearningSession) => void): void;
-}
-interface RouteLearningStore {
-    recordRoutes(routes: readonly string[]): Promise<void>;
-}
-/** Coalesce navigation bursts so one crawl does not lock and rewrite project.json per event. */
-export declare const ROUTE_PERSIST_DEBOUNCE_MS = 50;
-/** Convert a validated route-change payload into a bounded route identity. */
-export declare function routeFromEvent(event: ReticleEvent): string | undefined;
-/** Read the same route shape from a session's absolute URL. */
-export declare function routeFromUrl(value: string): string | undefined;
-export declare function routesFromEvents(events: readonly ReticleEvent[]): string[];
-/** Persist initial and subsequent routes for existing and future browser sessions. */
-export declare function attachRouteLearning(bridge: RouteLearningBridge, project: RouteLearningStore): void;
-export {};

package/dist/project/learned-routes.js

@@ -1,63 +0,0 @@
-import { EventType } from '@reticlehq/core';
-/** Coalesce navigation bursts so one crawl does not lock and rewrite project.json per event. */
-export const ROUTE_PERSIST_DEBOUNCE_MS = 50;
-/** Convert a validated route-change payload into a bounded route identity. */
-export function routeFromEvent(event) {
-    if (event.type !== EventType.ROUTE_CHANGE)
-        return undefined;
-    const pathname = event.data['pathname'];
-    if ('string' !== typeof pathname || 0 === pathname.length)
-        return undefined;
-    return pathname;
-}
-/** Read the same route shape from a session's absolute URL. */
-export function routeFromUrl(value) {
-    try {
-        const url = new URL(value);
-        return url.pathname;
-    }
-    catch {
-        return undefined;
-    }
-}
-export function routesFromEvents(events) {
-    return events.flatMap((event) => {
-        const route = routeFromEvent(event);
-        return route === undefined ? [] : [route];
-    });
-}
-/** Persist initial and subsequent routes for existing and future browser sessions. */
-export function attachRouteLearning(bridge, project) {
-    const attached = new WeakSet();
-    const pending = new Set();
-    let flushTimer;
-    const flush = () => {
-        flushTimer = undefined;
-        const routes = [...pending];
-        pending.clear();
-        if (routes.length > 0)
-            void project.recordRoutes(routes).catch(() => undefined);
-    };
-    const queue = (route) => {
-        pending.add(route);
-        if (flushTimer !== undefined)
-            clearTimeout(flushTimer);
-        flushTimer = setTimeout(flush, ROUTE_PERSIST_DEBOUNCE_MS);
-    };
-    const attach = (session) => {
-        if (attached.has(session))
-            return;
-        attached.add(session);
-        const initial = routeFromUrl(session.url);
-        if (initial !== undefined)
-            queue(initial);
-        session.onEvent((event) => {
-            const route = routeFromEvent(event);
-            if (route !== undefined)
-                queue(route);
-        });
-    };
-    for (const session of bridge.sessions.all())
-        attach(session);
-    bridge.attachSessionReady(attach);
-}

package/dist/project/memory-fs.d.ts

@@ -1,10 +0,0 @@
-import type { FileSystemPort } from './fs-port.js';
-interface MemoryFs {
-    fs: FileSystemPort;
-    /** Every file written, keyed by normalised absolute path. */
-    written: Map<string, string>;
-    /** Every directory created. */
-    dirs: Set<string>;
-}
-export declare function createMemoryFs(): MemoryFs;
-export {};

package/dist/project/project-store.d.ts

@@ -1,54 +0,0 @@
-import { ProjectReadError, type ProjectFile, type RunRecord } from '@reticlehq/core';
-import type { FileSystemPort } from './fs-port.js';
-import type { Clock } from '../flows/flows.js';
-/** Never-throws read result (mirrors ReadContractResult). */
-export type ReadProjectResult = {
-    ok: true;
-    file: ProjectFile;
-} | {
-    ok: false;
-    reason: ProjectReadError;
-};
-/**
- * Cross-run outcome memory persisted at .reticle/project.json. Models FlowStore:
- * injected FileSystemPort + Clock, byte-stable serialize, never-throws read. The clock is the
- * single `at`-stamp site so handlers pass an un-stamped record and no Date.now leaks into logic.
- */
-export declare class ProjectStore {
-    #private;
-    constructor(fs: FileSystemPort, root: string, clock: Clock);
-    /** Never throws. Missing → MISSING. Bad JSON / failed schema → MALFORMED. Mirrors readContract. */
-    read(): Promise<ReadProjectResult>;
-    /**
-     * Append a run, stamping `at` from the injected clock (the one clock site). A MISSING **or
-     * MALFORMED** existing file self-heals to a fresh empty file so corrupt history never blocks
-     * recording — unlike the read path, which surfaces MALFORMED honestly. Truncates per policy
-     * (last PER_NAME of any one name, then cap to TOTAL overall) and writes byte-stably.
-     */
-    recordRun(record: Omit<RunRecord, 'at'>): Promise<void>;
-    /**
-     * Add discovered routes to the learned app map. Empty input is a no-op so "nothing observed"
-     * does not materialize as `learned.routes: []`; non-empty updates are serialized per file so
-     * concurrent browser sessions accumulate rather than overwriting one another.
-     */
-    recordRoutes(routes: readonly string[]): Promise<void>;
-    /**
-     * The best observability this project has reached, and the raiser of that bar.
-     *
-     * Read returns undefined on a first run or an unreadable file, which is the honest "no best to
-     * fall from" — never a zero, which would make every first run look like a recovery.
-     */
-    bestObservability(): Promise<{
-        percent: number;
-    } | undefined>;
-    /**
-     * Raise the bar, if this run cleared it. Lowering is deliberately impossible.
-     *
-     * A best that could fall would let a weakened run quietly redefine what good looks like, which is
-     * precisely the gaming the figure exists to resist. Serialized per file so two sessions racing
-     * cannot lose the higher of the two.
-     */
-    raiseObservability(percent: number): Promise<void>;
-    /** The most-recent run for `name` (undefined on missing/malformed/none). Powers diff-vs-last. */
-    lastRun(name: string): Promise<RunRecord | undefined>;
-}