@reticlehq/server 2.14.0 → 3.2.0

package/dist/memory/project/dir/reticle-dir.js

@@ -0,0 +1,229 @@
+import { dirname, join } from 'node:path';
+import { realmOf } from '@reticlehq/core';
+import { CONTRACT_FILE_VERSION, ContractFileSchema, ContractReadError, FLOW_NAME_PATTERN, SAFE_SEGMENT_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),
+        fillValues: join(root, ReticleDir.FILL_VALUES_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);
+}
+/**
+ * The event ledger's closure report for a session (.reticle/sessions/<id>/events.closed.json).
+ *
+ * A sidecar rather than a header inside `events.jsonl`, because the ledger is append-only and
+ * readers track a byte offset into it: a header would have to be rewritten in place, which shrinks
+ * or shifts the file and silently invalidates every cursor pointing at it.
+ */
+export function journalClosedPath(root, sessionId) {
+    return join(sessionDirPath(root, sessionId), ReticleDir.JOURNAL_EVENTS_CLOSED_FILE);
+}
+/**
+ * A sessionId must be a single safe path segment before it is joined into a disk path (rejects
+ * '../', slashes, absolute, dotfiles). Session labels are user/tab-supplied, so this guard runs
+ * before any journal write.
+ *
+ * `SAFE_SEGMENT_PATTERN`, NOT the flow pattern the two once shared. Flow names became namespaced —
+ * `onboarding/signup` is a real address — and for a moment that widened this guard along with it,
+ * which would have let a tab-supplied label pick a nested directory to write into. A flow name is
+ * an address; a session id is a directory name. Same shape once, different questions now.
+ */
+export function isValidSessionId(sessionId) {
+    return SAFE_SEGMENT_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 SAFE_SEGMENT_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 realmOf(runtime).hasOwnBaselineDirectory && runtime !== undefined
+        ? join(visual, runtime)
+        : visual;
+}
+/** 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);
+}
+/**
+ * The directory that must exist before a flow of this name can be written.
+ *
+ * `flowDir` answers where flows live; this answers where THIS one goes, and they stopped being the
+ * same thing when names became namespaced. `onboarding/signup` is a file inside `onboarding/`, and
+ * creating only the flows root leaves the write failing on a directory nobody made — which reads as
+ * "saving is broken" rather than "a namespace has never been created".
+ *
+ * Derived from the resolved path rather than by splitting the name, so it cannot disagree with
+ * `flowPath` about where the file actually goes.
+ */
+export function flowParentDir(root, name, projectId) {
+    return dirname(flowPath(root, name, projectId));
+}
+/**
+ * A flow name may be NAMESPACED — `onboarding/signup` — and still never escapes `.reticle/`.
+ *
+ * Traversal is impossible by construction rather than by this filter: no segment may contain a dot,
+ * so `..` cannot be spelled, and every segment must start with a letter or digit, so a leading,
+ * trailing or doubled separator cannot either. The explicit `..` check is kept as a belt on top of
+ * braces, costing nothing and surviving a future loosening of the pattern.
+ */
+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/` and `.reticle/flows/` (recursive mkdir, safe to re-run).
+ *
+ * `baselines/` is NOT created: `BaselineStore` is an in-memory `Map` that dies with the daemon, so
+ * the directory could only ever be empty, and advertising it as a shareable artifact store is worse
+ * than not having it.
+ */
+export async function ensureReticleDir(fs, root) {
+    const p = reticleDirPaths(root);
+    await fs.mkdir(p.root);
+    await fs.mkdir(p.flows);
+}
+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 };
+}

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

@@ -0,0 +1,68 @@
+/**
+ * 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.
+     *
+     * `maxBytes` caps what ONE call materialises as a single string. It is not a performance knob: V8
+     * cannot build a string longer than 0x1fffffe8 characters, and `Buffer.prototype.toString` THROWS
+     * past that rather than returning a shorter one — so a tail bigger than the ceiling is not a slow
+     * read, it is a failed one. When the cap bites, the NEWEST bytes are kept (a journal tail is read
+     * to answer about what just happened).
+     *
+     * Two guarantees make the returned text safe to account for in bytes, and an implementation owes
+     * both:
+     *
+     *   - `from` is where the text ACTUALLY starts. It equals `byteOffset` when nothing was skipped,
+     *     and a caller can compare the two to see that a cap bit. (Omitted by a port that does not
+     *     implement the cap — read that as `byteOffset`, since such a port never skips.)
+     *   - When the cap moves the start, `from` lands just past a `\n`, so the text begins at a record
+     *     boundary and never with the replacement char of a character the window cut in half. A
+     *     window holding no `\n` at all returns empty text with `from` at the end of what was read.
+     *
+     * `size` is the file's length as `fstat` reported it, which is NOT where the returned text ends:
+     * a truncation between the stat and the read, or any short read, returns less. Advance a cursor
+     * by what arrived, never by `size`.
+     */
+    readFileFrom?(path: string, byteOffset: number, maxBytes?: number): Promise<{
+        text: string;
+        size: number;
+        from?: 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/memory/project/fs/fs-port.js

@@ -0,0 +1,82 @@
+import { access, appendFile, mkdir, open, readdir, readFile, realpath, rename, rm, stat, writeFile, } from 'node:fs/promises';
+/** The JSONL record terminator, as a byte — the only boundary a capped tail read can align to. */
+const NEWLINE_BYTE = 0x0a;
+/** 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, maxBytes) => {
+            const fh = await open(path, 'r');
+            try {
+                const { size } = await fh.stat();
+                if (byteOffset >= size)
+                    return { text: '', size, from: byteOffset };
+                // Keep the newest bytes when the tail is over the caller's ceiling. Clamped into the file
+                // rather than trusted: a ceiling of zero would otherwise size a negative buffer.
+                const cut = maxBytes === undefined ? byteOffset : Math.max(byteOffset, size - Math.max(maxBytes, 0));
+                const capped = cut > byteOffset;
+                // One byte BEFORE that cut, so a cut landing exactly on a record boundary is recognised as
+                // one instead of sacrificing the record after it.
+                const start = capped ? cut - 1 : byteOffset;
+                const length = size - start;
+                const buf = Buffer.allocUnsafe(length);
+                const { bytesRead } = await fh.read(buf, 0, length, start);
+                // ONLY what the read returned. `allocUnsafe` hands back whatever was last in that heap
+                // block, and `fstat` runs one syscall ahead of `read` — so a file truncated in between, or
+                // any short read, would otherwise decode that memory and hand it back as journal text.
+                const got = buf.subarray(0, bytesRead);
+                if (!capped)
+                    return { text: got.toString('utf8'), size, from: start };
+                // The ceiling moved the start, so the window may open inside a record whose head was never
+                // read. Drop up to the first boundary in BYTES, before decoding: `\n` is one byte and
+                // cannot occur inside a multi-byte sequence, so everything past it is intact UTF-8 and a
+                // whole number of records.
+                const newline = got.indexOf(NEWLINE_BYTE);
+                // No boundary in the whole window: there is no record here that can be read, and half of
+                // one is worse than none. `from` still says how far the read reached.
+                if (-1 === newline)
+                    return { text: '', size, from: start + bytesRead };
+                return {
+                    text: got.subarray(newline + 1).toString('utf8'),
+                    size,
+                    from: start + newline + 1,
+                };
+            }
+            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/memory/project/learned-routes.d.ts

@@ -0,0 +1,38 @@
+import { type ReticleEvent } from '@reticlehq/core';
+interface RouteLearningSession {
+    url: string;
+    /**
+     * The `.reticle` this session's artifacts belong in, stamped on session-create. Undefined only
+     * for a caller that does not stamp one, which resolves to the daemon's own root.
+     */
+    artifactRoot?: string | undefined;
+    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.
+ *
+ * `storeFor` resolves the store for ONE session's artifact root, rather than the daemon being handed
+ * a single store bound to its own `process.cwd()`. That binding was right only when the daemon
+ * happened to be started inside the app it was driving — and a user-scoped MCP registration, the
+ * common case, starts it wherever the editor's cwd is. The routes of every app then landed in that
+ * directory, which is how a `.reticle/` kept reappearing in a backend nobody had instrumented,
+ * while the driven project's own memory never filled.
+ */
+export declare function attachRouteLearning(bridge: RouteLearningBridge, storeFor: (root: string | undefined) => RouteLearningStore): void;
+export {};

package/dist/memory/project/learned-routes.js

@@ -0,0 +1,79 @@
+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.
+ *
+ * `storeFor` resolves the store for ONE session's artifact root, rather than the daemon being handed
+ * a single store bound to its own `process.cwd()`. That binding was right only when the daemon
+ * happened to be started inside the app it was driving — and a user-scoped MCP registration, the
+ * common case, starts it wherever the editor's cwd is. The routes of every app then landed in that
+ * directory, which is how a `.reticle/` kept reappearing in a backend nobody had instrumented,
+ * while the driven project's own memory never filled.
+ */
+export function attachRouteLearning(bridge, storeFor) {
+    const attached = new WeakSet();
+    // Keyed by STORE rather than by root path: `storeFor` already answers one store per root, so this
+    // cannot disagree with it about which roots are distinct.
+    const pending = new Map();
+    let flushTimer;
+    const flush = () => {
+        flushTimer = undefined;
+        const batches = [...pending];
+        pending.clear();
+        for (const [store, routes] of batches) {
+            if (routes.size > 0)
+                void store.recordRoutes([...routes]).catch(() => undefined);
+        }
+    };
+    const queue = (store, route) => {
+        const routes = pending.get(store) ?? new Set();
+        routes.add(route);
+        pending.set(store, routes);
+        if (flushTimer !== undefined)
+            clearTimeout(flushTimer);
+        flushTimer = setTimeout(flush, ROUTE_PERSIST_DEBOUNCE_MS);
+    };
+    const attach = (session) => {
+        if (attached.has(session))
+            return;
+        attached.add(session);
+        const store = storeFor(session.artifactRoot);
+        const initial = routeFromUrl(session.url);
+        if (initial !== undefined)
+            queue(store, initial);
+        session.onEvent((event) => {
+            const route = routeFromEvent(event);
+            if (route !== undefined)
+                queue(store, route);
+        });
+    };
+    for (const session of bridge.sessions.all())
+        attach(session);
+    bridge.attachSessionReady(attach);
+}

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

@@ -0,0 +1,10 @@
+import type { FileSystemPort } from './fs/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/memory/project/project-for-root.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The project memory store for ONE artifact root.
+ *
+ * `deps.project` is bound to the daemon's own root at construction, which is right only when the
+ * daemon happens to have been started inside the app it is driving — and a user-scoped MCP
+ * registration, the common case, starts it wherever the editor's cwd is. So every run record, every
+ * learned route and every observability high-water mark was written into that directory: a
+ * `.reticle/` appearing in a backend nobody instrumented, and a driven project whose own memory
+ * stayed empty. The cloud half of `recordReplayRun` had already been moved onto the session's root
+ * and its local half left behind, which is how a replay outcome could reach the dashboard and not
+ * the project it belonged to.
+ *
+ * Reads and writes both go through here, deliberately: a write that resolves to the app while a
+ * read still answers from the daemon's directory is worse than either alone — the record lands and
+ * is then invisible to the tool that exists to report it.
+ *
+ * Rebinding is cheap (a filesystem port, a root and a clock) and the single-project case allocates
+ * nothing: when the resolved root IS the daemon's, `deps.project` comes back unchanged.
+ */
+import { ProjectStore } from './project-store.js';
+import type { FileSystemPort } from './fs/fs-port.js';
+import type { ToolDeps } from '../../surface/tools/tool-kit.js';
+export declare function projectForRoot(deps: ToolDeps, root: string): ProjectStore;
+/**
+ * The same question asked by the daemon rather than by a tool: one store per artifact root, so a
+ * session's learned routes land in the app that was driven and not in whatever directory the daemon
+ * was launched from. The daemon's own store is seeded in, so the single-project case allocates
+ * nothing and keeps the instance every other caller already holds.
+ */
+export declare function projectStoreResolver(fs: FileSystemPort, daemonStore: ProjectStore, daemonRoot: string, now: () => number): (root: string | undefined) => ProjectStore;

package/dist/memory/project/project-for-root.js

@@ -0,0 +1,43 @@
+/**
+ * The project memory store for ONE artifact root.
+ *
+ * `deps.project` is bound to the daemon's own root at construction, which is right only when the
+ * daemon happens to have been started inside the app it is driving — and a user-scoped MCP
+ * registration, the common case, starts it wherever the editor's cwd is. So every run record, every
+ * learned route and every observability high-water mark was written into that directory: a
+ * `.reticle/` appearing in a backend nobody instrumented, and a driven project whose own memory
+ * stayed empty. The cloud half of `recordReplayRun` had already been moved onto the session's root
+ * and its local half left behind, which is how a replay outcome could reach the dashboard and not
+ * the project it belonged to.
+ *
+ * Reads and writes both go through here, deliberately: a write that resolves to the app while a
+ * read still answers from the daemon's directory is worse than either alone — the record lands and
+ * is then invisible to the tool that exists to report it.
+ *
+ * Rebinding is cheap (a filesystem port, a root and a clock) and the single-project case allocates
+ * nothing: when the resolved root IS the daemon's, `deps.project` comes back unchanged.
+ */
+import { ProjectStore } from './project-store.js';
+export function projectForRoot(deps, root) {
+    if (root === deps.reticleRoot)
+        return deps.project;
+    return new ProjectStore(deps.fs, root, { now: deps.now });
+}
+/**
+ * The same question asked by the daemon rather than by a tool: one store per artifact root, so a
+ * session's learned routes land in the app that was driven and not in whatever directory the daemon
+ * was launched from. The daemon's own store is seeded in, so the single-project case allocates
+ * nothing and keeps the instance every other caller already holds.
+ */
+export function projectStoreResolver(fs, daemonStore, daemonRoot, now) {
+    const byRoot = new Map([[daemonRoot, daemonStore]]);
+    return (root) => {
+        const key = root ?? daemonRoot;
+        let found = byRoot.get(key);
+        if (found === undefined) {
+            found = new ProjectStore(fs, key, { now });
+            byRoot.set(key, found);
+        }
+        return found;
+    };
+}

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

@@ -0,0 +1,54 @@
+import { ProjectReadError, type ProjectFile, type RunRecord } from '@reticlehq/core';
+import type { FileSystemPort } from './fs/fs-port.js';
+import type { Clock } from '../../machine/clock.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>;
+}