@reticlehq/server 2.14.0 → 3.2.0

package/dist/project/project-store.js

@@ -1,201 +0,0 @@
-import { PROJECT_FILE_VERSION, PROJECT_ROUTE_CAP, PROJECT_RUN_CAP, ProjectFileSchema, ProjectReadError, } from '@reticlehq/core';
-import { reticleDirPaths } from './reticle-dir.js';
-import { withFileLock } from './file-lock.js';
-const JSON_INDENT = 2;
-const EMPTY_PROJECT = { version: PROJECT_FILE_VERSION, runs: [] };
-/**
- * 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 class ProjectStore {
-    #fs;
-    #root;
-    #clock;
-    constructor(fs, root, clock) {
-        this.#fs = fs;
-        this.#root = root;
-        this.#clock = clock;
-    }
-    /**
-     * Byte-stable serializer: fixed field order (rebuilt literals, never insertion order), 2-space
-     * indent + trailing newline. `runs` stays chronological (append order = the data, never sorted);
-     * `learned` arrays ARE sorted for diff-stability. Two semantically-equal files → identical bytes.
-     */
-    #serialize(file) {
-        const envelope = {
-            version: PROJECT_FILE_VERSION,
-            ...(file.learned !== undefined ? { learned: serializeLearned(file.learned) } : {}),
-            runs: file.runs.map(serializeRun),
-        };
-        return `${JSON.stringify(envelope, null, JSON_INDENT)}\n`;
-    }
-    /** Never throws. Missing → MISSING. Bad JSON / failed schema → MALFORMED. Mirrors readContract. */
-    async read() {
-        const path = reticleDirPaths(this.#root).project;
-        if (!(await this.#fs.exists(path)))
-            return { ok: false, reason: ProjectReadError.MISSING };
-        let text;
-        try {
-            text = await this.#fs.readFile(path);
-        }
-        catch (error) {
-            return {
-                ok: false,
-                reason: this.#fs.isNotFound(error) ? ProjectReadError.MISSING : ProjectReadError.MALFORMED,
-            };
-        }
-        let parsed;
-        try {
-            parsed = JSON.parse(text);
-        }
-        catch {
-            return { ok: false, reason: ProjectReadError.MALFORMED };
-        }
-        const result = ProjectFileSchema.safeParse(parsed);
-        if (!result.success)
-            return { ok: false, reason: ProjectReadError.MALFORMED };
-        return { ok: true, file: result.data };
-    }
-    /**
-     * 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.
-     */
-    async recordRun(record) {
-        const path = reticleDirPaths(this.#root).project;
-        // Serialized per file: a parallel flow_verify records N runs concurrently, and an unlocked
-        // read-append-write drops every run but the last writer's (each read the same base list).
-        await withFileLock(path, async () => {
-            const existing = await this.read();
-            const base = existing.ok ? existing.file : EMPTY_PROJECT;
-            const stamped = { ...record, at: this.#clock.now() };
-            const runs = truncate([...base.runs, stamped]);
-            const next = { ...base, runs };
-            await this.#fs.mkdir(reticleDirPaths(this.#root).root);
-            await this.#fs.writeFile(path, this.#serialize(next));
-        });
-    }
-    /**
-     * 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.
-     */
-    async recordRoutes(routes) {
-        const additions = routes.filter((route) => route.length > 0);
-        if (0 === additions.length)
-            return;
-        const path = reticleDirPaths(this.#root).project;
-        await withFileLock(path, async () => {
-            const existing = await this.read();
-            const base = existing.ok ? existing.file : EMPTY_PROJECT;
-            const current = base.learned?.routes ?? [];
-            const merged = [...new Set([...current, ...additions])].slice(0, PROJECT_ROUTE_CAP);
-            if (merged.length === current.length &&
-                merged.every((route, index) => route === current[index]))
-                return;
-            const learned = { ...base.learned, routes: merged };
-            const next = { ...base, learned };
-            await this.#fs.mkdir(reticleDirPaths(this.#root).root);
-            await this.#fs.writeFile(path, this.#serialize(next));
-        });
-    }
-    /**
-     * 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.
-     */
-    async bestObservability() {
-        const existing = await this.read();
-        return existing.ok ? existing.file.learned?.bestObservability : 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.
-     */
-    async raiseObservability(percent) {
-        const path = reticleDirPaths(this.#root).project;
-        await withFileLock(path, async () => {
-            const existing = await this.read();
-            const base = existing.ok ? existing.file : EMPTY_PROJECT;
-            const current = base.learned?.bestObservability?.percent;
-            if (current !== undefined && percent <= current)
-                return;
-            const learned = {
-                ...base.learned,
-                bestObservability: { percent, at: this.#clock.now() },
-            };
-            await this.#fs.mkdir(reticleDirPaths(this.#root).root);
-            await this.#fs.writeFile(path, this.#serialize({ ...base, learned }));
-        });
-    }
-    /** The most-recent run for `name` (undefined on missing/malformed/none). Powers diff-vs-last. */
-    async lastRun(name) {
-        const read = await this.read();
-        if (!read.ok)
-            return undefined;
-        for (let i = read.file.runs.length - 1; i >= 0; i -= 1) {
-            const run = read.file.runs[i];
-            if (run !== undefined && run.name === name)
-                return run;
-        }
-        return undefined;
-    }
-}
-/** Field-ordered rebuild of one run record so serialization is byte-stable. */
-function serializeRun(run) {
-    return {
-        kind: run.kind,
-        name: run.name,
-        status: run.status,
-        at: run.at,
-        ...(run.summary !== undefined ? { summary: run.summary } : {}),
-        ...(run.evidence !== undefined ? { evidence: run.evidence } : {}),
-        ...(run.durationMs !== undefined ? { durationMs: run.durationMs } : {}),
-    };
-}
-/** Sorted, field-ordered rebuild of the learned map for diff-stability. */
-function serializeLearned(learned) {
-    return {
-        ...(learned.flows !== undefined ? { flows: [...learned.flows].sort() } : {}),
-        ...(learned.routes !== undefined ? { routes: [...learned.routes].sort() } : {}),
-    };
-}
-/**
- * Cap project memory while GUARANTEEING each flow keeps its last-known-good. Pass 1 reserves the
- * most-recent run of every distinct name (never evicted by the TOTAL cap), so a fresh session can always
- * answer "did my last run of this flow pass?" locally — the durable, free regression memory the solo
- * loop needs. Pass 2 fills the remaining budget with additional recent runs (PER_NAME per name, TOTAL
- * overall). Chronological order (oldest→newest) is preserved.
- */
-function truncate(runs) {
-    const perName = new Map();
-    const kept = new Set();
-    // Pass 1 (newest→oldest): reserve each name's latest run. Kept regardless of the TOTAL cap.
-    const seen = new Set();
-    for (let i = runs.length - 1; i >= 0; i -= 1) {
-        const run = runs[i];
-        if (run === undefined || seen.has(run.name))
-            continue;
-        seen.add(run.name);
-        kept.add(i);
-        perName.set(run.name, 1);
-    }
-    // Pass 2 (newest→oldest): fill the rest with extra recent runs, respecting PER_NAME and TOTAL.
-    for (let i = runs.length - 1; i >= 0 && kept.size < PROJECT_RUN_CAP.TOTAL; i -= 1) {
-        const run = runs[i];
-        if (run === undefined || kept.has(i))
-            continue;
-        const count = perName.get(run.name) ?? 0;
-        if (count >= PROJECT_RUN_CAP.PER_NAME)
-            continue;
-        perName.set(run.name, count + 1);
-        kept.add(i);
-    }
-    return runs.filter((_, i) => kept.has(i));
-}

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

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

package/dist/project/project-tools.js

@@ -1,155 +0,0 @@
-import { z } from 'zod';
-import { ProjectReadError, RunStatus } from '@reticlehq/core';
-import { ReticleTool } from '../tools/tool-names.js';
-import { countSchema } from '../tools/numeric-bounds.js';
-import { sessionIdShape } from '../tools/tool-kit.js';
-import { asNumber, asString } from '../tools/tools-helpers.js';
-import { cloudFetch, fetchProjectRegressionFromCloud, resolveCloudConfig, } from '../cloud/cloud-sync.js';
-import { RunStore } from '../runs/run-store.js';
-import { diffRuns as diffVerificationRuns, } from '../runs/run-diff.js';
-const REGRESSION_STATUSES = new Set([
-    RunStatus.FAIL,
-    RunStatus.DRIFT,
-    RunStatus.ERROR,
-]);
-function diffRuns(previous, current) {
-    const consoleErrorsDelta = numericDelta(previous.evidence?.consoleErrors, current.evidence?.consoleErrors);
-    const driftStepsDelta = numericDelta(previous.evidence?.driftSteps, current.evidence?.driftSteps);
-    return {
-        statusChanged: previous.status !== current.status,
-        previousStatus: previous.status,
-        currentStatus: current.status,
-        // Regressed = current is a non-pass outcome that the previous run was not.
-        regressed: REGRESSION_STATUSES.has(current.status) && !REGRESSION_STATUSES.has(previous.status),
-        ...(consoleErrorsDelta !== undefined ? { consoleErrorsDelta } : {}),
-        ...(driftStepsDelta !== undefined ? { driftStepsDelta } : {}),
-    };
-}
-function numericDelta(before, after) {
-    if (before === undefined && after === undefined)
-        return undefined;
-    return (after ?? 0) - (before ?? 0);
-}
-/**
- * Pull the team's server-side regression memory when logged in. This is what keeps a context-lost or
- * brand-new agent (whose local project.json may be empty) oriented: the same reticle_project call folds in
- * "what's broken vs before" from the cloud. Absent creds / unreachable → undefined (agent stays local).
- */
-async function cloudRegression(deps, sessionId) {
-    const config = resolveCloudConfig(process.env);
-    if (null === config)
-        return undefined;
-    let projectId;
-    try {
-        projectId = deps.sessions.resolve(sessionId).projectId;
-    }
-    catch {
-        projectId = undefined;
-    }
-    const report = await fetchProjectRegressionFromCloud(config, projectId, cloudFetch);
-    return report ?? undefined;
-}
-/** The two most-recent runs for `name`, oldest-first, or undefined if there are fewer than two. */
-/** Runs returned when the caller does not ask for a specific count. */
-const DEFAULT_RUN_LIMIT = 25;
-function lastTwoFor(runs, name) {
-    const matching = runs.filter((r) => r.name === name);
-    const n = matching.length;
-    if (n < 2)
-        return undefined;
-    const previous = matching[n - 2];
-    const current = matching[n - 1];
-    if (previous === undefined || current === undefined)
-        return undefined;
-    return [previous, current];
-}
-/**
- * The cross-run memory tools. `reticle_project` reads .reticle/project.json (optionally
- * scoped to a name, with a diff-vs-last summary); `reticle_run_record` explicitly records an outcome
- * (the manual companion to the auto-record on reticle_flow_replay). Both keep the agent's "did this
- * behave like last run?" question answerable without re-deriving it from raw observations.
- */
-/**
- * The per-flow diff between the two most-recent verification ARTIFACTS (.reticle/runs), or undefined when
- * fewer than two exist. Never throws — a missing/unreadable artifact must not break reading run history.
- */
-async function lastTwoRunArtifacts(deps) {
-    try {
-        const pair = await new RunStore(deps.fs, deps.reticleRoot).latestTwo();
-        return pair === undefined ? undefined : diffVerificationRuns(pair[0], pair[1]);
-    }
-    catch {
-        return undefined;
-    }
-}
-export const PROJECT_TOOLS = [
-    {
-        name: ReticleTool.PROJECT,
-        description: 'Read cross-run history from .reticle/project.json — the memory of how past runs behaved. With { name } it also returns the last run for that flow plus a diff-vs-last summary (status change, regressed flag, consoleErrors/driftSteps deltas) so you can answer "did it behave like last time?". `diff` is the lightweight status/console/drift delta vs the previous run of that NAME; `runDiff` is the per-flow duration/status delta between the two most-recent full verification artifacts ("step 3: 412ms -> 987ms (+140%), +2 requests"). When logged in to Reticle, also returns `cloud`: the team\'s server-side regression report (broken/changed flows vs before) — the durable memory a fresh or context-lost agent can rely on even when local history is empty. Returns { runs, learned?, lastRun?, diff?, runDiff?, cloud? } or { error, reason, cloud? }.',
-        inputSchema: {
-            name: z.string().optional().describe('Filter runs by this name. Omit to return all runs.'),
-            limit: countSchema
-                .optional()
-                .describe('Most-recent N runs to return. Defaults to 25 — the full history is unbounded and grows with every run (measured at ~20KB / ~5,000 tokens on a modest project), which is a large slice of an agent context for data it mostly does not read. `totalRuns` always reports the true count, so a cap is never silent.'),
-            ...sessionIdShape,
-        },
-        outputSchema: {
-            runs: z.array(z.unknown()),
-            totalRuns: z
-                .number()
-                .optional()
-                .describe('How many runs exist in total. Compare against runs.length to see if it was capped.'),
-            diff: z.unknown().optional(),
-            runDiff: z.unknown().optional(),
-            cloud: z.unknown().optional(),
-        },
-        handler: async (deps, args) => {
-            const cloud = await cloudRegression(deps, asString(args['sessionId']));
-            const withCloud = (obj) => cloud === undefined ? obj : { ...obj, cloud };
-            const read = await deps.project.read();
-            if (!read.ok) {
-                return withCloud({
-                    error: read.reason === ProjectReadError.MISSING
-                        ? 'no .reticle/project.json yet — run a flow (reticle_flow_replay) or reticle_run_record first'
-                        : '.reticle/project.json is malformed — it will self-heal on the next recorded run',
-                    reason: read.reason,
-                });
-            }
-            const name = asString(args['name']);
-            // The most recent N, in the order they happened. The history is append-only and unbounded —
-            // measured at ~20KB (~5,000 tokens) across 176 runs on this repo — and an agent asking "how
-            // did this behave before" wants the recent past, not every run ever recorded. `totalRuns`
-            // travels with it so the cap is never silent, per the repo's no-silent-caps rule.
-            //
-            // Order is left alone deliberately. Reversing to newest-first was tried and reverted: it read
-            // better but broke an existing contract for no reason the bound required, and a caller relying
-            // on chronological order would have been silently handed the reverse.
-            const cap = asNumber(args['limit']) ?? DEFAULT_RUN_LIMIT;
-            const recent = (runs) => runs.slice(-cap);
-            if (name === undefined) {
-                return withCloud({
-                    runs: recent(read.file.runs),
-                    totalRuns: read.file.runs.length,
-                    learned: read.file.learned,
-                });
-            }
-            const lastRun = await deps.project.lastRun(name);
-            const pair = lastTwoFor(read.file.runs, name);
-            //: the RICH run diff (per-flow duration deltas past a noise floor, status changes, new/removed
-            // flows, verdict change) over the last two verification ARTIFACTS. That lives alongside — not
-            // instead of — the lightweight RunRecord diff above: `diff` answers "did this named run behave like
-            // last time?" from project.json, while `runDiff` answers "what changed between the last two full
-            // verification runs?" from .reticle/runs. Best-effort: no artifacts simply means no runDiff.
-            const runDiff = await lastTwoRunArtifacts(deps);
-            const forName = read.file.runs.filter((r) => r.name === name);
-            return withCloud({
-                runs: recent(forName),
-                totalRuns: forName.length,
-                learned: read.file.learned,
-                lastRun,
-                ...(pair !== undefined ? { diff: diffRuns(pair[0], pair[1]) } : {}),
-                ...(runDiff === undefined ? {} : { runDiff }),
-            });
-        },
-    },
-];

package/dist/project/reticle-dir.d.ts

@@ -1,102 +0,0 @@
-import type { FlowName, SessionId } from '@reticlehq/core';
-import { ContractReadError, type CapabilitiesContract, type RunId } from '@reticlehq/core';
-import type { FileSystemPort } from './fs-port.js';
-/** Resolved absolute paths inside a `.reticle/` root. Pure: join only, no IO, no cwd. */
-export interface ReticleDirPaths {
-    /**.../.reticle */
-    root: string;
-    /**.../.reticle/contract.json */
-    contract: string;
-    /**.../.reticle/flows */
-    flows: string;
-    /**.../.reticle/baselines */
-    baselines: string;
-    /**.../.reticle/project.json (cross-run outcome memory) */
-    project: string;
-    /**.../.reticle/impact.json (what Reticle has done for this user, local only) */
-    impact: string;
-    /**.../.reticle/intent.json (what changes were supposed to make true — git-checked) */
-    intent: string;
-    /**.../.reticle/visual (PNG baselines + diffs) */
-    visual: string;
-    /**.../.reticle/runs (verification-run artifacts) */
-    runs: string;
-    /**.../.reticle/sessions (durable causal journal, one dir per session) */
-    sessions: string;
-    /**.../.reticle/envelopes.json (learned per-route expected envelopes) */
-    envelopes: string;
-    /**.../.reticle/ambient.json (learned ambient-churn region map) */
-    ambient: string;
-    /** .../.reticle/capsules (fail-to-pass bug capsules) */
-    capsules: string;
-    /**.../.reticle/flake.json (per-flow flake ledger) */
-    flake: string;
-    /**.../.reticle/assertion-tiers.json (last-passing assertion tiers; anti-reward-hacking baseline) */
-    tiers: string;
-}
-export declare function reticleDirPaths(root: string): ReticleDirPaths;
-/** The verification-run artifact path for `runId`.reticle/runs/<runId>.json). */
-export declare function runPath(root: string, runId: string): string;
-/** The journal directory for `sessionId` (.reticle/sessions/<id>). Guard the id first. */
-export declare function sessionDirPath(root: string, sessionId: string): string;
-/** The append-only event ledger path for a session (.reticle/sessions/<id>/events.jsonl). */
-export declare function journalEventsPath(root: string, sessionId: string): string;
-/** The append-only action ledger path for a session (.reticle/sessions/<id>/actions.jsonl). */
-export declare function journalActionsPath(root: string, sessionId: string): string;
-/**
- * A sessionId must be a single safe path segment before it is joined into a disk path — same guard as
- * run/flow ids (rejects '../', slashes, absolute, dotfiles). Session labels are user/tab-supplied, so
- * this guard runs before any journal write.
- */
-export declare function isValidSessionId(sessionId: string): sessionId is SessionId;
-/**
- * A runId must be a single safe path segment — same guard as flow names (rejects '../', '/', '\\',
- * absolute, dotfiles). uuid-style ids (hyphens/underscores) pass. Guards every disk op before join.
- */
-export declare function isValidRunId(runId: string): runId is RunId;
-/** The PNG baseline path for `name`.reticle/visual/<name>.png). */
-export declare function visualPath(root: string, name: string, runtime?: string): string;
-/**
- * The directory a visual artifact belongs in, scoped by the runtime that produced it.
- *
- * An Electron window, a Tauri webview and a browser tab render the same url differently — different
- * chrome, different fonts, a different device pixel ratio, a webview that is not the browser at all.
- * One shared baseline makes every cross-runtime diff wrong, and the quiet direction is the dangerous
- * one: a baseline overwritten from another runtime turns a later real regression into a pass.
- *
- * Scoped the way flows already are. A DESKTOP runtime gets a subdir; web, an unknown runtime, and
- * everything captured before this existed stay on the flat path — the SDK has no screenshotter, so
- * every pre-existing baseline came from a driven browser, and moving them would orphan them.
- */
-export declare function visualDir(root: string, runtime?: string): string;
-/** The overlay-diff PNG path for `name`.reticle/visual/<name>.diff.png). */
-export declare function visualDiffPath(root: string, name: string, runtime?: string): string;
-/**
- * Path to a flow file. With a `projectId`, the flow lives in a per-project subdir
- * (`.reticle/flows/<projectId>/<name>.json`) so a shared daemon serving many apps can't collide two
- * apps' flows of the same name; without one it's the flat legacy path (`.reticle/flows/<name>.json`),
- * which is also where pre-existing (untagged) flows stay. Callers pass ONLY a validated projectId.
- */
-export declare function flowPath(root: string, name: FlowName, projectId?: string): string;
-/** The directory a flow write targets: the per-project subdir, or the flat flows root for global. */
-export declare function flowDir(root: string, projectId?: string): string;
-/**
- * A flow name must be a single safe path segment — rejects '../', '/', '\\', absolute, dotfiles.
- * Guards every disk op before a path is ever joined, so a traversal name never escapes .reticle/.
- */
-export declare function isValidFlowName(name: string): name is FlowName;
-export declare function baselinePath(root: string, name: string): string;
-/** Idempotent: creates .reticle/,.reticle/flows/,.reticle/baselines/ (recursive mkdir → safe to re-run). */
-export declare function ensureReticleDir(fs: FileSystemPort, root: string): Promise<void>;
-/** Write the contract to .reticle/contract.json (auto-creating .reticle/ first). */
-export declare function writeContract(fs: FileSystemPort, root: string, capabilities: CapabilitiesContract, now: () => number): Promise<void>;
-export type ReadContractResult = {
-    ok: true;
-    capabilities: CapabilitiesContract;
-    generatedAt: number;
-} | {
-    ok: false;
-    reason: ContractReadError;
-};
-/** Never throws. Missing → MISSING. Bad JSON / failed schema → MALFORMED. */
-export declare function readContract(fs: FileSystemPort, root: string): Promise<ReadContractResult>;

package/dist/project/reticle-dir.js

@@ -1,188 +0,0 @@
-import { join } from 'node:path';
-import { AppRuntime } from '@reticlehq/core/telemetry';
-import { CONTRACT_FILE_VERSION, ContractFileSchema, ContractReadError, FLOW_NAME_PATTERN, ReticleDir, } from '@reticlehq/core';
-export function reticleDirPaths(root) {
-    return {
-        root,
-        contract: join(root, ReticleDir.CONTRACT_FILE),
-        flows: join(root, ReticleDir.FLOWS_SUBDIR),
-        baselines: join(root, ReticleDir.BASELINES_SUBDIR),
-        project: join(root, ReticleDir.PROJECT_FILE),
-        impact: join(root, ReticleDir.IMPACT_FILE),
-        intent: join(root, ReticleDir.INTENT_FILE),
-        visual: join(root, ReticleDir.VISUAL_SUBDIR),
-        runs: join(root, ReticleDir.RUNS_SUBDIR),
-        sessions: join(root, ReticleDir.SESSIONS_SUBDIR),
-        envelopes: join(root, ReticleDir.ENVELOPES_FILE),
-        ambient: join(root, ReticleDir.AMBIENT_FILE),
-        capsules: join(root, ReticleDir.CAPSULES_SUBDIR),
-        flake: join(root, ReticleDir.FLAKE_FILE),
-        tiers: join(root, ReticleDir.TIERS_FILE),
-    };
-}
-/** The verification-run artifact path for `runId`.reticle/runs/<runId>.json). */
-export function runPath(root, runId) {
-    return join(root, ReticleDir.RUNS_SUBDIR, `${runId}.json`);
-}
-/** The journal directory for `sessionId` (.reticle/sessions/<id>). Guard the id first. */
-export function sessionDirPath(root, sessionId) {
-    return join(root, ReticleDir.SESSIONS_SUBDIR, sessionId);
-}
-/** The append-only event ledger path for a session (.reticle/sessions/<id>/events.jsonl). */
-export function journalEventsPath(root, sessionId) {
-    return join(sessionDirPath(root, sessionId), ReticleDir.JOURNAL_EVENTS_FILE);
-}
-/** The append-only action ledger path for a session (.reticle/sessions/<id>/actions.jsonl). */
-export function journalActionsPath(root, sessionId) {
-    return join(sessionDirPath(root, sessionId), ReticleDir.JOURNAL_ACTIONS_FILE);
-}
-/**
- * A sessionId must be a single safe path segment before it is joined into a disk path — same guard as
- * run/flow ids (rejects '../', slashes, absolute, dotfiles). Session labels are user/tab-supplied, so
- * this guard runs before any journal write.
- */
-export function isValidSessionId(sessionId) {
-    return FLOW_NAME_PATTERN.test(sessionId) && !sessionId.includes('..');
-}
-/**
- * A runId must be a single safe path segment — same guard as flow names (rejects '../', '/', '\\',
- * absolute, dotfiles). uuid-style ids (hyphens/underscores) pass. Guards every disk op before join.
- */
-export function isValidRunId(runId) {
-    return FLOW_NAME_PATTERN.test(runId) && !runId.includes('..');
-}
-/** The PNG baseline path for `name`.reticle/visual/<name>.png). */
-export function visualPath(root, name, runtime) {
-    return join(visualDir(root, runtime), `${name}.png`);
-}
-/**
- * The directory a visual artifact belongs in, scoped by the runtime that produced it.
- *
- * An Electron window, a Tauri webview and a browser tab render the same url differently — different
- * chrome, different fonts, a different device pixel ratio, a webview that is not the browser at all.
- * One shared baseline makes every cross-runtime diff wrong, and the quiet direction is the dangerous
- * one: a baseline overwritten from another runtime turns a later real regression into a pass.
- *
- * Scoped the way flows already are. A DESKTOP runtime gets a subdir; web, an unknown runtime, and
- * everything captured before this existed stay on the flat path — the SDK has no screenshotter, so
- * every pre-existing baseline came from a driven browser, and moving them would orphan them.
- */
-export function visualDir(root, runtime) {
-    const visual = join(root, ReticleDir.VISUAL_SUBDIR);
-    return runtime === undefined || AppRuntime.WEB === runtime ? visual : join(visual, runtime);
-}
-/** The overlay-diff PNG path for `name`.reticle/visual/<name>.diff.png). */
-export function visualDiffPath(root, name, runtime) {
-    return join(visualDir(root, runtime), `${name}.diff.png`);
-}
-/**
- * Path to a flow file. With a `projectId`, the flow lives in a per-project subdir
- * (`.reticle/flows/<projectId>/<name>.json`) so a shared daemon serving many apps can't collide two
- * apps' flows of the same name; without one it's the flat legacy path (`.reticle/flows/<name>.json`),
- * which is also where pre-existing (untagged) flows stay. Callers pass ONLY a validated projectId.
- */
-export function flowPath(root, name, projectId) {
-    const flowsDir = join(root, ReticleDir.FLOWS_SUBDIR);
-    return projectId === undefined
-        ? join(flowsDir, `${name}.json`)
-        : join(flowsDir, projectId, `${name}.json`);
-}
-/** The directory a flow write targets: the per-project subdir, or the flat flows root for global. */
-export function flowDir(root, projectId) {
-    const flowsDir = join(root, ReticleDir.FLOWS_SUBDIR);
-    return projectId === undefined ? flowsDir : join(flowsDir, projectId);
-}
-/**
- * A flow name must be a single safe path segment — rejects '../', '/', '\\', absolute, dotfiles.
- * Guards every disk op before a path is ever joined, so a traversal name never escapes .reticle/.
- */
-export function isValidFlowName(name) {
-    return FLOW_NAME_PATTERN.test(name) && !name.includes('..');
-}
-export function baselinePath(root, name) {
-    return join(root, ReticleDir.BASELINES_SUBDIR, `${name}.json`);
-}
-/** Idempotent: creates .reticle/,.reticle/flows/,.reticle/baselines/ (recursive mkdir → safe to re-run). */
-export async function ensureReticleDir(fs, root) {
-    const p = reticleDirPaths(root);
-    await fs.mkdir(p.root);
-    await fs.mkdir(p.flows);
-    await fs.mkdir(p.baselines);
-}
-const JSON_INDENT = 2;
-/**
- * Serialize capabilities into a byte-stable, diffable string: arrays sorted lexicographically,
- * flows sorted by name, object keys emitted in a fixed declared order (NOT insertion order),
- * 2-space indent, trailing newline. Two semantically-equal registries → identical bytes.
- */
-function stableSerialize(capabilities, generatedAt) {
-    const envelope = {
-        version: CONTRACT_FILE_VERSION,
-        generatedAt,
-        capabilities: {
-            testids: [...capabilities.testids].sort(),
-            signals: [...capabilities.signals].sort(),
-            stores: [...capabilities.stores].sort(),
-            flows: [...capabilities.flows]
-                .map((f) => ({ name: f.name, steps: [...f.steps] }))
-                .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)),
-            ...(capabilities.governance !== undefined
-                ? { governance: serializeGovernance(capabilities.governance) }
-                : {}),
-        },
-    };
-    return `${JSON.stringify(envelope, null, JSON_INDENT)}\n`;
-}
-/** Field-ordered, sorted rebuild of declared governance for byte-stable serialization. */
-function serializeGovernance(g) {
-    return {
-        ...(g.owner !== undefined ? { owner: g.owner } : {}),
-        ...(g.safety !== undefined ? { safety: [...g.safety].sort() } : {}),
-        ...(g.scope !== undefined ? { scope: [...g.scope].sort() } : {}),
-        ...(g.redact !== undefined ? { redact: [...g.redact].sort() } : {}),
-        ...(g.risk !== undefined
-            ? {
-                risk: [...g.risk]
-                    .map((z) => ({
-                    surface: z.surface,
-                    ...(z.paths !== undefined ? { paths: [...z.paths].sort() } : {}),
-                    ...(z.note !== undefined ? { note: z.note } : {}),
-                }))
-                    .sort((a, b) => (a.surface < b.surface ? -1 : a.surface > b.surface ? 1 : 0)),
-            }
-            : {}),
-    };
-}
-/** Write the contract to .reticle/contract.json (auto-creating .reticle/ first). */
-export async function writeContract(fs, root, capabilities, now) {
-    await ensureReticleDir(fs, root);
-    await fs.writeFile(reticleDirPaths(root).contract, stableSerialize(capabilities, now()));
-}
-/** Never throws. Missing → MISSING. Bad JSON / failed schema → MALFORMED. */
-export async function readContract(fs, root) {
-    const path = reticleDirPaths(root).contract;
-    if (!(await fs.exists(path)))
-        return { ok: false, reason: ContractReadError.MISSING };
-    let text;
-    try {
-        text = await fs.readFile(path);
-    }
-    catch (error) {
-        // Handles the exists/read TOCTOU race: a vanished file reads as MISSING, anything else MALFORMED.
-        return {
-            ok: false,
-            reason: fs.isNotFound(error) ? ContractReadError.MISSING : ContractReadError.MALFORMED,
-        };
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(text);
-    }
-    catch {
-        return { ok: false, reason: ContractReadError.MALFORMED };
-    }
-    const result = ContractFileSchema.safeParse(parsed);
-    if (!result.success)
-        return { ok: false, reason: ContractReadError.MALFORMED };
-    return { ok: true, capabilities: result.data.capabilities, generatedAt: result.data.generatedAt };
-}