@reticlehq/server 2.14.0 → 3.2.0

package/dist/memory/journal/ambient-store.js

@@ -0,0 +1,52 @@
+import { dirname } from 'node:path';
+import { reticleDirPaths } from '../project/dir/reticle-dir.js';
+import { AmbientFileSchema } from './on-disk/ambient-file.js';
+import { onlyStableAmbient } from '@reticlehq/engine/window/ambient.js';
+/** Bumped on any breaking change to the persisted ambient-map shape. */
+const AMBIENT_FILE_VERSION = 1;
+/**
+ * Persists the learned ambient-churn region map at `.reticle/ambient.json`. Local, single-project
+ * memory (stays OSS — OSS-VS-SERVER). Loads never throw: missing/malformed/wrong-version degrades to
+ * an empty map, so a bad file never breaks a drive — the layer just re-learns the ambient regions.
+ */
+export class AmbientStore {
+    #fs;
+    #path;
+    constructor(fs, root) {
+        this.#fs = fs;
+        this.#path = reticleDirPaths(root).ambient;
+    }
+    async load() {
+        let text;
+        try {
+            text = await this.#fs.readFile(this.#path);
+        }
+        catch (error) {
+            if (this.#fs.isNotFound(error))
+                return {};
+            throw error;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            return {};
+        }
+        const result = AmbientFileSchema.safeParse(parsed);
+        // Ref-keyed entries are dropped on the way IN as well as out: a file written before this rule
+        // existed is full of them, and seeding a session with another session's ref numbering is the
+        // defect itself. An older file therefore degrades to its stable entries rather than misfiring.
+        return result.success ? onlyStableAmbient(result.data.regions) : {};
+    }
+    async save(counts) {
+        await this.#fs.mkdir(dirname(this.#path));
+        // Only what means anything in the next session. A ref is an address within ONE session's
+        // numbering, so persisting it teaches the next session to suppress an element it never saw.
+        const regions = onlyStableAmbient(counts);
+        const body = `${JSON.stringify({ version: AMBIENT_FILE_VERSION, regions }, null, 2)}\n`;
+        const tmp = `${this.#path}.tmp`;
+        await this.#fs.writeFile(tmp, body);
+        await this.#fs.rename(tmp, this.#path);
+    }
+}

package/dist/memory/journal/attach-journal.d.ts

@@ -0,0 +1,37 @@
+import type { FileSystemPort } from '../project/fs/fs-port.js';
+import { JournalRecorder, type JournalReader } from './journal-recorder.js';
+/** The minimal Session surface the journal attachment needs (Session satisfies it structurally). */
+export interface JournalTarget {
+    readonly id: string;
+    /**
+     * The `.reticle` this session's artifacts belong in, stamped on session-create before this runs.
+     *
+     * The journal used to go to the daemon's own root — wherever the agent was launched — while the
+     * run artifact written at teardown already used this one. The journal is the worse half to
+     * misroute: it carries URLs, request and response bodies and DOM text from the app under test, so
+     * a daemon started in a backend wrote that app's traffic into a repository nobody instrumented,
+     * and the `.reticle/.gitignore` meant to keep journals out of a shared repo was being written into
+     * the OTHER tree. Undefined only when no project could be resolved, which keeps the old fallback.
+     */
+    readonly artifactRoot?: string | undefined;
+    /** Milliseconds since the session connected — the recorder's injected clock. */
+    elapsed(): number;
+    setJournal(recorder: JournalRecorder, reader?: JournalReader): void;
+}
+interface JournalAttachDeps {
+    fs: FileSystemPort;
+    reticleRoot: string;
+    /** Journaling is on by default; the opt-out (`.reticle.json` journal:false / env) sets this false. */
+    enabled: boolean;
+}
+/**
+ * Build the per-session journal attachment the bridge fires on session creation. Off when disabled;
+ * skips a session whose id is not a safe path segment (never crashes the live session over a
+ * journaling concern). The recorder's clock is the session's own elapsed time.
+ *
+ * The skip is LOGGED, because it is otherwise invisible: the session connects and drives perfectly
+ * well, and the only difference is that its durable causal record does not exist, so every query
+ * reading back through the journal returns nothing with no explanation.
+ */
+export declare function makeJournalAttach(deps: JournalAttachDeps): (session: JournalTarget) => void;
+export {};

package/dist/memory/journal/attach-journal.js

@@ -0,0 +1,26 @@
+import { log } from '../../log.js';
+import { isValidSessionId } from '../project/dir/reticle-dir.js';
+import { JournalRecorder } from './journal-recorder.js';
+import { SessionJournal } from './session-journal.js';
+/**
+ * Build the per-session journal attachment the bridge fires on session creation. Off when disabled;
+ * skips a session whose id is not a safe path segment (never crashes the live session over a
+ * journaling concern). The recorder's clock is the session's own elapsed time.
+ *
+ * The skip is LOGGED, because it is otherwise invisible: the session connects and drives perfectly
+ * well, and the only difference is that its durable causal record does not exist, so every query
+ * reading back through the journal returns nothing with no explanation.
+ */
+export function makeJournalAttach(deps) {
+    return (session) => {
+        if (!deps.enabled)
+            return;
+        if (!isValidSessionId(session.id)) {
+            log('journal_skipped_unsafe_session_id', { sessionId: session.id });
+            return;
+        }
+        const journal = new SessionJournal(deps.fs, session.artifactRoot ?? deps.reticleRoot, session.id);
+        // Same SessionJournal is both the write sink and the read fall-through for queries after eviction.
+        session.setJournal(new JournalRecorder(journal, { now: () => session.elapsed() }), journal);
+    };
+}

package/dist/memory/journal/drive-flow.d.ts

@@ -0,0 +1,74 @@
+import type { FlowExpect, FlowName } from '@reticlehq/core';
+/**
+ * What this module needs a recorded step to BE, named structurally rather than imported.
+ *
+ * The recorder's own `RecordedStep` lives two directories away, under
+ * `language/flows/recording/tape/`. Importing it made TEARDOWN reach into the recorder's internals
+ * for three field names, and the reach guard's advice is the right one: the question is not whether
+ * the dependency is allowed, it is whether the thing reached for is in the right place. A tape is
+ * data, and this module only reads it.
+ */
+export interface TapeStep {
+    tool: string;
+    args: Record<string, unknown>;
+    stable: boolean;
+    expect?: FlowExpect;
+    /** Recorder-internal, and the field journeys are cut on. Never written to the saved flow. */
+    route?: string;
+}
+/** The compiled shape a flow store accepts. Structural, for the same reason as `TapeStep`. */
+export interface DriveProgram {
+    name: string;
+    version: number;
+    steps: TapeStep[];
+    startPath?: string;
+}
+/**
+ * What a session drove, saved as a replayable flow — without anybody asking for it.
+ *
+ * The agent-facing route to this is `record{start}` then `flow_save`, and it is a route agents do
+ * not take. The corpus says so: **3 of 33 flows are mutation-testable and 6 of 112 steps declare a
+ * consequence.** The engine catches 84 of the 86 bugs it structurally can, so the ceiling on this
+ * product is not detection, it is how many flows exist that could go red — and every drive that is
+ * never saved is a regression test that was paid for and thrown away.
+ *
+ * So it is not a tool and not a rule. It runs at teardown, in code, on every session.
+ */
+/** The one condition on saving, and the reason the whole thing is safe. */
+export declare function carriesAnAssertion(steps: readonly TapeStep[]): boolean;
+/**
+ * A stable name for what this session drove — led by what it proved.
+ *
+ * Two properties, and the name used to have only the second. It has to be STABLE: teardown fires on
+ * every socket close and a reconnecting tab keeps its id, so a name that moves leaves one journey
+ * scattered across several files, each a partial copy of the others. And it has to be READABLE,
+ * because `presenter-controls.ts` renders it straight into the replay button's `textContent` — so
+ * the label a person actually sees was `drive-sdc991872-6d66-4adf-8780-f931c62905f9`, twice, for two
+ * different journeys. A session id is a fact about the socket, not about the feature.
+ *
+ * So the claim leads, the route follows, and a SHORT session discriminator trails: two sessions that
+ * prove the same thing on the same route stay separate files rather than overwriting each other,
+ * which is the one thing the full id was buying that the claim cannot.
+ */
+export declare function driveFlowName(sessionId: string, route?: string, steps?: readonly TapeStep[]): FlowName;
+export interface DriveFlowOutcome {
+    /** The flows that were written — one per journey the session contained. */
+    readonly saved?: readonly string[];
+    /**
+     * Steps that were driven and NOT saved because none of them declared a consequence.
+     *
+     * Reported rather than silently dropped. A tape with no `expect` replays green forever whatever
+     * the app does, so auto-saving one manufactures a permanent pass — which is the exact failure this
+     * product exists to prevent, and it would do it at a rate of one per session. Counting them is how
+     * "the agent drove and proved nothing" stays visible instead of looking like nothing happened.
+     */
+    readonly unprovenSteps?: number;
+}
+/** A flow per journey, so two journeys in one session are two regression tests rather than one. */
+export declare function driveFlowsFrom(sessionId: string, tape: {
+    steps: readonly TapeStep[];
+    startPath?: string;
+} | undefined): {
+    programs: DriveProgram[];
+    outcome: DriveFlowOutcome;
+};

package/dist/memory/journal/drive-flow.js

@@ -0,0 +1,157 @@
+import { REPLAY_PROGRAM_VERSION, asFlowName } from '@reticlehq/core';
+/**
+ * What a session drove, saved as a replayable flow — without anybody asking for it.
+ *
+ * The agent-facing route to this is `record{start}` then `flow_save`, and it is a route agents do
+ * not take. The corpus says so: **3 of 33 flows are mutation-testable and 6 of 112 steps declare a
+ * consequence.** The engine catches 84 of the 86 bugs it structurally can, so the ceiling on this
+ * product is not detection, it is how many flows exist that could go red — and every drive that is
+ * never saved is a regression test that was paid for and thrown away.
+ *
+ * So it is not a tool and not a rule. It runs at teardown, in code, on every session.
+ */
+/** The one condition on saving, and the reason the whole thing is safe. */
+export function carriesAnAssertion(steps) {
+    return steps.some((step) => step.expect !== undefined);
+}
+/** Squeeze any string into one safe, lower-case filename segment. */
+const segment = (value, max) => value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, max)
+    .replace(/-$/, '');
+/**
+ * What this flow PROVED, in a few words, from the first step that claims anything.
+ *
+ * Ordered by the evidence ladder the rest of the product uses: a signal is the app saying the thing
+ * happened in its own words, a request is the next best, a store read is one step removed, and the
+ * DOM-shaped claims are the weakest. Naming a flow after the strongest thing it proves is the same
+ * judgement the honesty grade makes, reused where a human reads it.
+ *
+ * Returns '' when a step claims nothing nameable, and the caller keeps the old session-only name.
+ */
+function provedSlug(steps) {
+    for (const step of steps) {
+        const expect = step.expect;
+        if (expect === undefined)
+            continue;
+        if (expect.signal !== undefined)
+            return segment(expect.signal, 32);
+        if (expect.net !== undefined) {
+            const method = segment(expect.net.method ?? '', 6);
+            const where = segment(expect.net.urlContains ?? '', 24);
+            const joined = [method, where].filter((part) => '' !== part).join('-');
+            if ('' !== joined)
+                return joined;
+        }
+        if (expect.state !== undefined)
+            return segment(expect.state.path, 32);
+        if (expect.route?.pathname !== undefined)
+            return segment(expect.route.pathname, 24);
+        if (expect.text?.contains !== undefined)
+            return segment(expect.text.contains, 24);
+    }
+    return '';
+}
+/**
+ * A stable name for what this session drove — led by what it proved.
+ *
+ * Two properties, and the name used to have only the second. It has to be STABLE: teardown fires on
+ * every socket close and a reconnecting tab keeps its id, so a name that moves leaves one journey
+ * scattered across several files, each a partial copy of the others. And it has to be READABLE,
+ * because `presenter-controls.ts` renders it straight into the replay button's `textContent` — so
+ * the label a person actually sees was `drive-sdc991872-6d66-4adf-8780-f931c62905f9`, twice, for two
+ * different journeys. A session id is a fact about the socket, not about the feature.
+ *
+ * So the claim leads, the route follows, and a SHORT session discriminator trails: two sessions that
+ * prove the same thing on the same route stay separate files rather than overwriting each other,
+ * which is the one thing the full id was buying that the claim cannot.
+ */
+export function driveFlowName(sessionId, route, steps = []) {
+    const safe = sessionId.replace(/[^a-zA-Z0-9-]/g, '-').slice(0, 40);
+    const proved = provedSlug(steps);
+    // The route is part of the name, so two journeys in one session do not overwrite each other —
+    // and so a re-drive of the same journey rewrites its own flow rather than adding a near-duplicate.
+    const leg = (route ?? '')
+        .replace(/[^a-zA-Z0-9]+/g, '-')
+        .replace(/^-|-$/g, '')
+        .slice(0, 24);
+    // Minted here, not at the call site. This function is where a drive's flow name comes into
+    // existence, and every character it can emit has just been forced through the safe-segment
+    // replacements above — so this IS the validated boundary the brand is meant to be created at.
+    // Returning `string` pushed a cast onto each caller, which is the hole `flowPath`'s parameter
+    // type was added to close.
+    // Nothing nameable was proved, so keep the name this function has always produced.
+    if ('' === proved) {
+        return asFlowName(0 === leg.length ? `drive-${safe}` : `drive-${safe}-${leg}`);
+    }
+    // Enough of the session to keep two of them apart, and little enough to read past.
+    const discriminator = safe.replace(/-/g, '').slice(0, 8);
+    const parts = ['drive', proved, ...(0 === leg.length ? [] : [leg]), discriminator];
+    return asFlowName(parts.join('-'));
+}
+/**
+ * Turn this session's ambient tape into a flow, when it is worth one.
+ *
+ * Pure over the tape: the caller supplies it and writes the result, so the decision — save, or
+ * count as unproven — is testable without a store, a session or a disk.
+ */
+/**
+ * Cut a session's tape into journeys at ROUTE boundaries.
+ *
+ * A deliberate recording is one journey because somebody said where it started and where it ended.
+ * An ambient tape is a whole session: sign in, go somewhere, do a thing, go somewhere else. Saved
+ * whole it is one flow that begins at the login screen, and a SUITE of those fails from the second
+ * one on — the app is already authenticated, so the login steps no longer apply. That hazard is
+ * already written down in `bench/harness/suite-rre.mjs`, which works around it by recording its
+ * flows post-login by hand; this is the same fix, done by the recorder instead of by a person.
+ *
+ * MEASURED before the fix: 24 of 24 auto-captured flows embedded a login step, and none carried a
+ * `startPath` at all.
+ *
+ * The route is the boundary because it is the one the FLOW FORMAT already uses: replay navigates to
+ * `startPath` before step 1, so a segment that declares its route is independent of wherever the
+ * previous flow happened to leave the tab.
+ */
+function segmentsByRoute(steps) {
+    const out = [];
+    for (const step of steps) {
+        const last = out.at(-1);
+        if (last !== undefined && last.route === step.route) {
+            last.steps.push(step);
+            continue;
+        }
+        out.push({ ...(step.route === undefined ? {} : { route: step.route }), steps: [step] });
+    }
+    return out;
+}
+/** A flow per journey, so two journeys in one session are two regression tests rather than one. */
+export function driveFlowsFrom(sessionId, tape) {
+    if (tape === undefined || 0 === tape.steps.length)
+        return { programs: [], outcome: {} };
+    const programs = [];
+    let unproven = 0;
+    for (const segment of segmentsByRoute(tape.steps)) {
+        if (!carriesAnAssertion(segment.steps)) {
+            unproven += segment.steps.length;
+            continue;
+        }
+        const startPath = segment.route ?? tape.startPath;
+        programs.push({
+            name: driveFlowName(sessionId, startPath, segment.steps),
+            version: REPLAY_PROGRAM_VERSION,
+            // The route is recorder-internal and has no business on disk — `startPath` is where the
+            // on-disk flow says the same thing, in the field replay actually reads.
+            steps: segment.steps.map(({ route: _route, ...step }) => step),
+            ...(startPath === undefined ? {} : { startPath }),
+        });
+    }
+    return {
+        programs,
+        outcome: {
+            ...(0 === programs.length ? {} : { saved: programs.map((p) => p.name) }),
+            ...(0 === unproven ? {} : { unprovenSteps: unproven }),
+        },
+    };
+}

package/dist/memory/journal/drive-run-flush.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Publish a drive's evidence while the drive is still happening.
+ *
+ * The run artifact a drive's verdicts live in used to be written by session TEARDOWN and nowhere
+ * else, and the sync daemon can only push artifacts that exist — so the dashboard showed nothing
+ * until the tab closed, and a dashboard that is correct only after you stop working is one nobody
+ * looks at while working. (`drive-run.ts` fixed the step before this: a live drive produced no
+ * artifact at all, because only flow replay wrote one.)
+ *
+ * SAFE TO CALL REPEATEDLY, not a second writer racing the first. `recordDriveRun` derives its run id
+ * from the SESSION (`driveRunId(session.id)`) so a tab that reconnects appends to the same ledger,
+ * which makes the write idempotent: the same session rewrites its own run and the cloud supersedes
+ * by run id.
+ *
+ * DEBOUNCED, because the fold reads the whole journal and rewrites the whole artifact, so doing it
+ * per verdict would make a fast drive quadratic in its own length. The value is "current within
+ * seconds", not "within microseconds".
+ *
+ * Teardown still flushes, and must: the debounce may have a write pending when the tab closes, and
+ * the last verdicts of a session are the ones somebody is waiting on.
+ */
+/** Only what a flush needs. The real Session satisfies it structurally, as everywhere else here. */
+export interface FlushableSession {
+    readonly id: string;
+}
+export interface DriveRunFlushDeps<S extends FlushableSession> {
+    /** Find the live session a verdict came from, or undefined when it has already gone. */
+    resolve: (sessionId: string) => S | undefined;
+    /** Write this session's run artifact. The same call teardown makes. */
+    write: (session: S) => Promise<void>;
+    /** Injected so the test does not wait three real seconds. */
+    debounceMs?: number;
+}
+/**
+ * Flush a session's run shortly after each verdict, coalescing bursts.
+ *
+ * Returns a handle so a caller can flush a session immediately (teardown does) and stop the timers.
+ */
+export declare function attachDriveRunFlush<S extends FlushableSession>(deps: DriveRunFlushDeps<S>): {
+    flushNow: (sessionId: string) => Promise<void>;
+    stop: () => void;
+};

package/dist/memory/journal/drive-run-flush.js

@@ -0,0 +1,82 @@
+/**
+ * Publish a drive's evidence while the drive is still happening.
+ *
+ * The run artifact a drive's verdicts live in used to be written by session TEARDOWN and nowhere
+ * else, and the sync daemon can only push artifacts that exist — so the dashboard showed nothing
+ * until the tab closed, and a dashboard that is correct only after you stop working is one nobody
+ * looks at while working. (`drive-run.ts` fixed the step before this: a live drive produced no
+ * artifact at all, because only flow replay wrote one.)
+ *
+ * SAFE TO CALL REPEATEDLY, not a second writer racing the first. `recordDriveRun` derives its run id
+ * from the SESSION (`driveRunId(session.id)`) so a tab that reconnects appends to the same ledger,
+ * which makes the write idempotent: the same session rewrites its own run and the cloud supersedes
+ * by run id.
+ *
+ * DEBOUNCED, because the fold reads the whole journal and rewrites the whole artifact, so doing it
+ * per verdict would make a fast drive quadratic in its own length. The value is "current within
+ * seconds", not "within microseconds".
+ *
+ * Teardown still flushes, and must: the debounce may have a write pending when the tab closes, and
+ * the last verdicts of a session are the ones somebody is waiting on.
+ */
+import { HookEvent } from '@reticlehq/core/hooks';
+import { onHook } from '../../hooks/hook-bus.js';
+import { log } from '../../log.js';
+/** Long enough to collapse a burst of verdicts, short enough that a human reads it as "live". */
+const FLUSH_DEBOUNCE_MS = 3_000;
+/**
+ * Flush a session's run shortly after each verdict, coalescing bursts.
+ *
+ * Returns a handle so a caller can flush a session immediately (teardown does) and stop the timers.
+ */
+export function attachDriveRunFlush(deps) {
+    const pending = new Map();
+    const wait = deps.debounceMs ?? FLUSH_DEBOUNCE_MS;
+    /** Reported once per distinct failure: a disk that cannot be written says so, not every verdict. */
+    const reported = new Set();
+    const flush = async (sessionId) => {
+        const timer = pending.get(sessionId);
+        if (timer !== undefined) {
+            clearTimeout(timer);
+            pending.delete(sessionId);
+        }
+        const session = deps.resolve(sessionId);
+        // Gone already. Teardown owns the final write, so there is nothing to rescue and nothing wrong.
+        if (session === undefined)
+            return;
+        try {
+            await deps.write(session);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (reported.has(message))
+                return;
+            reported.add(message);
+            log(`drive run flush failed: ${message}`);
+        }
+    };
+    const off = onHook(HookEvent.VERDICT, (payload) => {
+        const sessionId = 'sessionId' in payload ? payload.sessionId : undefined;
+        if (sessionId === undefined)
+            return;
+        const existing = pending.get(sessionId);
+        if (existing !== undefined)
+            clearTimeout(existing);
+        const timer = setTimeout(() => {
+            void flush(sessionId);
+        }, wait);
+        // The daemon must be able to exit with a flush pending. This is a nicety on a timer, not an
+        // obligation, and holding the process open for it would make `reticle` feel broken on exit.
+        timer.unref?.();
+        pending.set(sessionId, timer);
+    });
+    return {
+        flushNow: flush,
+        stop: () => {
+            off();
+            for (const timer of pending.values())
+                clearTimeout(timer);
+            pending.clear();
+        },
+    };
+}

package/dist/memory/journal/envelope-store.d.ts

@@ -0,0 +1,16 @@
+import type { FileSystemPort } from '../project/fs/fs-port.js';
+import { type RouteEnvelope } from './envelope.js';
+/**
+ * Persists the learned per-route envelopes at `.reticle/envelopes.json`. Local, single-project statistics
+ * (single-player memory stays OSS — OSS-VS-SERVER). Loads never throw: a missing, malformed, or
+ * wrong-version file degrades to no envelopes, so a bad baseline can never crash a drive; the deviation
+ * report just falls back to the causal summary until the envelope rebuilds.
+ */
+export declare class EnvelopeStore {
+    #private;
+    constructor(fs: FileSystemPort, root: string);
+    /** Absolute path of the backing file — the key a caller uses to serialize its read-modify-write. */
+    get path(): string;
+    load(): Promise<Map<string, RouteEnvelope>>;
+    save(envelopes: ReadonlyMap<string, RouteEnvelope>): Promise<void>;
+}

package/dist/memory/journal/envelope-store.js

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+import { dirname } from 'node:path';
+import { reticleDirPaths } from '../project/dir/reticle-dir.js';
+import { RouteEnvelopeSchema } from './envelope.js';
+/** Bumped on any breaking change to the persisted envelope shape (matches the runs/contract convention). */
+const ENVELOPE_FILE_VERSION = 1;
+const EnvelopeFileSchema = z.object({
+    version: z.literal(ENVELOPE_FILE_VERSION),
+    routes: z.record(RouteEnvelopeSchema),
+});
+/**
+ * Persists the learned per-route envelopes at `.reticle/envelopes.json`. Local, single-project statistics
+ * (single-player memory stays OSS — OSS-VS-SERVER). Loads never throw: a missing, malformed, or
+ * wrong-version file degrades to no envelopes, so a bad baseline can never crash a drive; the deviation
+ * report just falls back to the causal summary until the envelope rebuilds.
+ */
+export class EnvelopeStore {
+    #fs;
+    #path;
+    constructor(fs, root) {
+        this.#fs = fs;
+        this.#path = reticleDirPaths(root).envelopes;
+    }
+    /** Absolute path of the backing file — the key a caller uses to serialize its read-modify-write. */
+    get path() {
+        return this.#path;
+    }
+    async load() {
+        let text;
+        try {
+            text = await this.#fs.readFile(this.#path);
+        }
+        catch (error) {
+            if (this.#fs.isNotFound(error))
+                return new Map();
+            throw error;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            return new Map();
+        }
+        const result = EnvelopeFileSchema.safeParse(parsed);
+        if (!result.success)
+            return new Map();
+        return new Map(Object.entries(result.data.routes));
+    }
+    async save(envelopes) {
+        await this.#fs.mkdir(dirname(this.#path));
+        const routes = {};
+        for (const [route, envelope] of envelopes)
+            routes[route] = envelope;
+        const body = `${JSON.stringify({ version: ENVELOPE_FILE_VERSION, routes }, null, 2)}\n`;
+        // Atomic publish: write a temp sibling then rename, so a crash never leaves a half-written baseline.
+        const tmp = `${this.#path}.tmp`;
+        await this.#fs.writeFile(tmp, body);
+        await this.#fs.rename(tmp, this.#path);
+    }
+}