@reticlehq/server 2.14.0 → 3.2.0

package/dist/memory/project/artifact-root-resolver.js

@@ -0,0 +1,89 @@
+/**
+ * Which `.reticle` a connected session's artifacts belong in — the IO half.
+ *
+ * `resolveArtifactRoot` and `unmatchedRoot` next door are pure on purpose; this is the file that
+ * goes to disk for them: the user-level project registry, config discovery, and the one question
+ * that decides whether the daemon may write into its own working directory at all.
+ *
+ * It lives here rather than in the daemon bootstrap because it is a subject, not wiring — and
+ * because the bootstrap is at its line cap, which is the cohesion signal that rule doing its job.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { PROJECT_REGISTRY_FILE, emptyProjectRegistry, parseProjectRegistry, } from '@reticlehq/core/artifacts';
+import { ReticleDir } from '@reticlehq/core';
+import { discoverProjectConfigs, hasProjectConfig, } from '../../command/cli/config/config-discovery.js';
+import { log } from '../../log.js';
+import { ArtifactRootReason, projectCandidatesFrom, resolveArtifactRoot, unmatchedRoot, } from './artifact-root.js';
+/**
+ * Is the daemon's own directory a Reticle project, or is it a guest there?
+ *
+ * Answered ONCE per resolver rather than per session: a directory does not become a project between
+ * two tabs connecting, and this is the IO half `unmatchedRoot` deliberately does not do.
+ */
+function daemonSitsInAProject(daemonRoot) {
+    try {
+        // Either mark counts. `.reticle.json` means somebody ran `init` here; an existing `.reticle/`
+        // means Reticle has been invited into this tree before, including by a version that predates
+        // the config file. A directory with neither has never agreed to hold anybody's session data.
+        return existsSync(daemonRoot) || hasProjectConfig(dirname(daemonRoot));
+    }
+    catch {
+        // Unreadable is not a licence to write. Treat it as somebody else's directory.
+        return false;
+    }
+}
+export function artifactRootResolver(daemonRoot) {
+    const daemonIsProject = daemonSitsInAProject(daemonRoot);
+    return (projectId, origin) => {
+        let registry = emptyProjectRegistry();
+        try {
+            const path = join(homedir(), ReticleDir.ROOT, PROJECT_REGISTRY_FILE);
+            registry = existsSync(path)
+                ? parseProjectRegistry(JSON.parse(readFileSync(path, 'utf8')))
+                : registry;
+        }
+        catch {
+            // A cache that cannot be read is an empty cache, never an error: the daemon still resolves
+            // through discovery, and falls back to its own root exactly as it did before this existed.
+        }
+        let discovery = { found: [], searched: [] };
+        try {
+            discovery = discoverProjectConfigs(process.cwd());
+        }
+        catch {
+            // Same reasoning: a diagnostic search that throws must not take a tool call with it.
+        }
+        const resolved = resolveArtifactRoot({
+            projectId,
+            candidates: projectCandidatesFrom(discovery, registry),
+            daemonRoot,
+        });
+        if (resolved.reason === ArtifactRootReason.MATCHED_PROJECT)
+            return resolved;
+        // Could not name the project. The old code wrote into the daemon's directory anyway and said
+        // nothing, which put `.reticle/` — journals included — into repositories nobody had
+        // instrumented. Evidence still has to live somewhere, so it goes to the user's own
+        // `~/.reticle/unmatched/<projectId>` instead, and the daemon says so rather than leaving
+        // somebody to find the files.
+        const root = unmatchedRoot({
+            daemonRoot,
+            daemonIsProject,
+            home: homedir(),
+            ...(projectId === undefined ? {} : { projectId }),
+            // Only reached when no project id survives the guard. Without it every app that never
+            // stamped one shares a single directory -- and that directory holds the durable half, so one
+            // app's learned expectations become another's.
+            ...(origin === undefined ? {} : { origin }),
+        });
+        if (root !== daemonRoot) {
+            log('artifact_root_unmatched', {
+                projectId: projectId ?? null,
+                reason: resolved.reason,
+                root,
+            });
+        }
+        return { ...resolved, root };
+    };
+}

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

@@ -0,0 +1,109 @@
+import { type ProjectCandidate, type ProjectId, type ProjectRegistry } from '@reticlehq/core';
+import type { ConfigDiscovery } from '../../command/cli/config/config-discovery.js';
+/**
+ * Which `.reticle/` a session's artifacts belong in.
+ *
+ * Everything Reticle persists — flows, the capability contract, baselines, capsules, the cross-run
+ * project memory — used to resolve against the DAEMON's own `process.cwd()`, which says where the
+ * daemon was launched and not which project is being verified. Usually not even the same tree: a
+ * user-scoped MCP registration is the common case, and the editor that spawns it starts it wherever
+ * it likes. Three shapes of the same defect: `cwd=/` gave `ENOENT: mkdir '/.reticle'`; a daemon
+ * started in project A wrote project B's flow into A's checkout and reported success without naming
+ * the path; and `verify_change` could only answer "unknown" because no flow could be persisted.
+ *
+ * Candidates arrive from config discovery (which walks out from the daemon's own directory) and from
+ * the user-level project registry (which `init` writes, and which reaches checkouts discovery cannot
+ * see). This function does not know which source an entry came from: a privileged source would be a
+ * second rule for one question.
+ *
+ * Matched on `projectId` because HELLO already stamps it and `.reticle.json` already declares it, so
+ * the join works for every SDK already in the field. A `root` on HELLO would move the wire contract
+ * and strand every older SDK on the fallback.
+ *
+ * It can DECLINE: every non-matching branch returns the daemon root and says which branch it was. A
+ * wrong root writes a caller's evidence into a tree they never drove, so the ambiguous case refuses
+ * rather than picks, and the reason travels with the answer.
+ */
+/** Why the root below is the root. Travels with the answer so a caller can say what happened. */
+export declare const ArtifactRootReason: {
+    /** Exactly one discovered config declares this session's project. The good case. */
+    readonly MATCHED_PROJECT: "matched-project";
+    /** The session declared no projectId — a pre-2.0 SDK. Nothing to match on. */
+    readonly NO_PROJECT_ID: "no-project-id";
+    /** The search ran and nothing it found declares this project. */
+    readonly NO_MATCH: "no-match";
+    /** Two or more checkouts declare this project. Refused rather than guessed. */
+    readonly AMBIGUOUS: "ambiguous";
+};
+export type ArtifactRootReason = (typeof ArtifactRootReason)[keyof typeof ArtifactRootReason];
+interface ArtifactRootQuery {
+    /** The connected session's HELLO projectId, when it sent one. */
+    projectId: ProjectId | undefined;
+    /** Every project this machine knows about. Supplied, not gathered here — this stays pure. */
+    candidates: readonly ProjectCandidate[];
+    /** Where artifacts go when the project cannot be identified. Already a `.reticle` path. */
+    daemonRoot: string;
+}
+export interface ArtifactRoot {
+    /** Absolute path to the `.reticle` directory. Always present, on every branch. */
+    root: string;
+    reason: ArtifactRootReason;
+    /**
+     * The competing project directories, on `AMBIGUOUS` only. A caller that has to explain the refusal
+     * needs to name them; a caller that does not can ignore the field.
+     */
+    candidates?: string[];
+}
+/**
+ * Resolve the artifact root for one session.
+ *
+ * Pure: no IO, no cwd, no clock. The filesystem walk belongs to `discoverProjectConfigs` and is
+ * passed in, which is what makes every branch below testable without a fixture tree.
+ */
+export declare function resolveArtifactRoot(query: ArtifactRootQuery): ArtifactRoot;
+/**
+ * Everything this machine knows about where projects live, from both sources.
+ *
+ * Discovery first, deliberately: it read a `.reticle.json` that exists RIGHT NOW, while the registry
+ * is a cache of something `init` saw once. Order only decides which duplicate survives dedupe, and
+ * the one confirmed a moment ago is the better survivor.
+ */
+export declare function projectCandidatesFrom(discovery: ConfigDiscovery, registry: ProjectRegistry): ProjectCandidate[];
+/** Where evidence goes when no project could be named and the daemon is a guest in this tree. */
+export declare const UNMATCHED_SUBDIR = "unmatched";
+/**
+ * The fallback root for a session whose project could not be resolved.
+ *
+ * Falling back to the daemon's own root was unconditional and silent, and that is how Reticle came
+ * to create `.reticle/` — session journals included, carrying URLs, request and response bodies and
+ * page text — in a user's BACKEND directory. Their editor starts the daemon there; the directory
+ * was never instrumented and never agreed to hold anybody's session data. They deleted it, and the
+ * next session wrote it again.
+ *
+ * Two cases, and only one of them was ever the intended behaviour:
+ *
+ *   - the daemon is sitting IN a Reticle project (a developer who ran `reticle serve` in their own
+ *     app). Its root is the right answer, and it is the case the old fallback was written for.
+ *   - the daemon is a guest — no `.reticle.json`, no `.reticle/` already there. Then the evidence
+ *     goes to the user's own `~/.reticle/unmatched/<projectId>`, which is Reticle's to write.
+ *
+ * It is never dropped. A verdict with nowhere to live is a worse failure than one in an unexpected
+ * place, and the caller says out loud where it went.
+ *
+ * `projectId` arrives in HELLO from the page, so it is untrusted input on a path join and is held
+ * to one safe segment — the same guard session ids and flow names already pass.
+ */
+export declare function unmatchedRoot(query: {
+    daemonRoot: string;
+    /** Whether the daemon's own directory is a Reticle project — an IO question, answered by the caller. */
+    daemonIsProject: boolean;
+    /** The user's home directory. Passed in rather than read, so this stays pure. */
+    home: string;
+    projectId?: ProjectId | undefined;
+    /**
+     * Where the session was served from, when it is known. Used ONLY when no project id survives the
+     * segment guard — a real id always wins, because it is an identity and this is a stand-in.
+     */
+    origin?: string | undefined;
+}): string;
+export {};

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

@@ -0,0 +1,157 @@
+import { join } from 'node:path';
+import { SAFE_SEGMENT_PATTERN, ReticleDir, fnv1a, projectCandidates, } from '@reticlehq/core';
+/**
+ * Which `.reticle/` a session's artifacts belong in.
+ *
+ * Everything Reticle persists — flows, the capability contract, baselines, capsules, the cross-run
+ * project memory — used to resolve against the DAEMON's own `process.cwd()`, which says where the
+ * daemon was launched and not which project is being verified. Usually not even the same tree: a
+ * user-scoped MCP registration is the common case, and the editor that spawns it starts it wherever
+ * it likes. Three shapes of the same defect: `cwd=/` gave `ENOENT: mkdir '/.reticle'`; a daemon
+ * started in project A wrote project B's flow into A's checkout and reported success without naming
+ * the path; and `verify_change` could only answer "unknown" because no flow could be persisted.
+ *
+ * Candidates arrive from config discovery (which walks out from the daemon's own directory) and from
+ * the user-level project registry (which `init` writes, and which reaches checkouts discovery cannot
+ * see). This function does not know which source an entry came from: a privileged source would be a
+ * second rule for one question.
+ *
+ * Matched on `projectId` because HELLO already stamps it and `.reticle.json` already declares it, so
+ * the join works for every SDK already in the field. A `root` on HELLO would move the wire contract
+ * and strand every older SDK on the fallback.
+ *
+ * It can DECLINE: every non-matching branch returns the daemon root and says which branch it was. A
+ * wrong root writes a caller's evidence into a tree they never drove, so the ambiguous case refuses
+ * rather than picks, and the reason travels with the answer.
+ */
+/** Why the root below is the root. Travels with the answer so a caller can say what happened. */
+export const ArtifactRootReason = {
+    /** Exactly one discovered config declares this session's project. The good case. */
+    MATCHED_PROJECT: 'matched-project',
+    /** The session declared no projectId — a pre-2.0 SDK. Nothing to match on. */
+    NO_PROJECT_ID: 'no-project-id',
+    /** The search ran and nothing it found declares this project. */
+    NO_MATCH: 'no-match',
+    /** Two or more checkouts declare this project. Refused rather than guessed. */
+    AMBIGUOUS: 'ambiguous',
+};
+/**
+ * Resolve the artifact root for one session.
+ *
+ * Pure: no IO, no cwd, no clock. The filesystem walk belongs to `discoverProjectConfigs` and is
+ * passed in, which is what makes every branch below testable without a fixture tree.
+ */
+export function resolveArtifactRoot(query) {
+    const { projectId, candidates, daemonRoot } = query;
+    if (projectId === undefined || 0 === projectId.length) {
+        return { root: daemonRoot, reason: ArtifactRootReason.NO_PROJECT_ID };
+    }
+    const matches = dedupeByDirectory(candidates.filter((c) => c.projectId === projectId));
+    if (0 === matches.length) {
+        return { root: daemonRoot, reason: ArtifactRootReason.NO_MATCH };
+    }
+    if (matches.length > 1) {
+        return {
+            root: daemonRoot,
+            reason: ArtifactRootReason.AMBIGUOUS,
+            candidates: matches.map((config) => config.directory),
+        };
+    }
+    const [only] = matches;
+    // `matches.length === 1` above, so this is defined — but the codebase forbids `!`, and a default
+    // that can never be taken is cheaper than the alternative spelling.
+    const directory = only?.directory ?? '';
+    if (0 === directory.length) {
+        return { root: daemonRoot, reason: ArtifactRootReason.NO_MATCH };
+    }
+    return { root: join(directory, ReticleDir.ROOT), reason: ArtifactRootReason.MATCHED_PROJECT };
+}
+/**
+ * One entry per directory.
+ *
+ * Discovery and the registry routinely name the SAME checkout — the registry remembers what `init`
+ * wrote, and discovery finds that same file whenever the daemon happens to be in the tree. Counting
+ * it twice would read as two competing checkouts and make the resolver refuse, which is the one
+ * outcome worse than either source alone.
+ */
+function dedupeByDirectory(matches) {
+    const seen = new Set();
+    const out = [];
+    for (const candidate of matches) {
+        if (seen.has(candidate.directory))
+            continue;
+        seen.add(candidate.directory);
+        out.push(candidate);
+    }
+    return out;
+}
+/**
+ * Everything this machine knows about where projects live, from both sources.
+ *
+ * Discovery first, deliberately: it read a `.reticle.json` that exists RIGHT NOW, while the registry
+ * is a cache of something `init` saw once. Order only decides which duplicate survives dedupe, and
+ * the one confirmed a moment ago is the better survivor.
+ */
+export function projectCandidatesFrom(discovery, registry) {
+    const discovered = discovery.found.flatMap((config) => config.projectId === undefined || 0 === config.projectId.length
+        ? []
+        : [{ projectId: config.projectId, directory: config.directory }]);
+    return [...discovered, ...projectCandidates(registry)];
+}
+/** Where evidence goes when no project could be named and the daemon is a guest in this tree. */
+export const UNMATCHED_SUBDIR = 'unmatched';
+/** What a project with NO identity at all is called on disk. Never blank, so the path is always real. */
+const UNNAMED_PROJECT = 'unnamed';
+/**
+ * The bucket for a project that could not name itself but was served from somewhere.
+ *
+ * `unnamed` used to take every one of these, which made it not a project's directory but the union
+ * of every project that ever failed to identify itself — sharing one `project.json`, one
+ * `envelopes.json`, one `flake.json` and one `assertion-tiers.json`. Those are the durable half:
+ * learned routes, per-route expectations, a quarantine ledger and an anti-downgrade floor. One
+ * app's floor silently becoming another app's floor is a wrong answer, not untidy disk.
+ *
+ * And it is the ORDINARY path, not an edge: a page that never stamped an id is an app instrumented
+ * without a build plugin, a page loaded before the plugin ran, or any tree where the daemon is a
+ * guest.
+ *
+ * The origin is the next-best identity available at that moment. It does not pretend to be a
+ * project id — two apps served on one port at different times still share a bucket — but that is a
+ * far smaller wrong than every unidentified app in the world sharing one.
+ */
+const ORIGIN_BUCKET_PREFIX = 'origin-';
+/**
+ * The fallback root for a session whose project could not be resolved.
+ *
+ * Falling back to the daemon's own root was unconditional and silent, and that is how Reticle came
+ * to create `.reticle/` — session journals included, carrying URLs, request and response bodies and
+ * page text — in a user's BACKEND directory. Their editor starts the daemon there; the directory
+ * was never instrumented and never agreed to hold anybody's session data. They deleted it, and the
+ * next session wrote it again.
+ *
+ * Two cases, and only one of them was ever the intended behaviour:
+ *
+ *   - the daemon is sitting IN a Reticle project (a developer who ran `reticle serve` in their own
+ *     app). Its root is the right answer, and it is the case the old fallback was written for.
+ *   - the daemon is a guest — no `.reticle.json`, no `.reticle/` already there. Then the evidence
+ *     goes to the user's own `~/.reticle/unmatched/<projectId>`, which is Reticle's to write.
+ *
+ * It is never dropped. A verdict with nowhere to live is a worse failure than one in an unexpected
+ * place, and the caller says out loud where it went.
+ *
+ * `projectId` arrives in HELLO from the page, so it is untrusted input on a path join and is held
+ * to one safe segment — the same guard session ids and flow names already pass.
+ */
+export function unmatchedRoot(query) {
+    if (query.daemonIsProject)
+        return query.daemonRoot;
+    const id = query.projectId ?? '';
+    const named = SAFE_SEGMENT_PATTERN.test(id) && !id.includes('..');
+    return join(query.home, ReticleDir.ROOT, UNMATCHED_SUBDIR, named ? id : unnamedSegment(query.origin));
+}
+/** Hashed, not spelled: an origin carries a host and a port, and neither belongs in a path segment. */
+function unnamedSegment(origin) {
+    if (origin === undefined || 0 === origin.trim().length)
+        return UNNAMED_PROJECT;
+    return `${ORIGIN_BUCKET_PREFIX}${fnv1a(origin.trim())}`;
+}

package/dist/memory/project/dir/fill-value-store.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The values a drive types into this project's fields, kept so they are paid for once.
+ *
+ * A generated field value is not a model's opinion to be re-asked every run. It is a FIXTURE: the
+ * same label on the same app wants the same value tomorrow, a replay must send exactly what the
+ * recording sent or it is not a replay, and a human who dislikes "Acme Corp" should be able to open
+ * a file and write something else rather than argue with a model about it. So it lives beside the
+ * flows it belongs to, in git, in the project's own directory.
+ *
+ * Read once at the start of a drive and written once at the end: a drive that fills twenty fields
+ * must not write the file twenty times, and nothing else in the process is competing for it.
+ *
+ * Every failure is silent and answers "no values". A drive must never fail over a fixtures file,
+ * and the fallback -- the label heuristic -- is what every drive used before this existed.
+ */
+import type { FileSystemPort } from '../fs/fs-port.js';
+/** What a drive holds while it runs: a read-through map plus whatever it learned. */
+export interface FillValueStore {
+    get(label: string): string | undefined;
+    set(label: string, value: string): void;
+    /** Persist, if anything was learned. Silent on failure, like every read here. */
+    flush(): Promise<void>;
+}
+/**
+ * A store that remembers within one drive and writes nothing.
+ *
+ * Used when there is no project directory to write to. A drive must never fail over its fixtures
+ * file, and that includes failing to FIND one: the values still de-duplicate inside the run, they
+ * are simply not carried into the next one.
+ */
+export declare function memoryFillValues(): FillValueStore;
+export declare function openFillValues(fs: FileSystemPort, root: string | undefined): Promise<FillValueStore>;

package/dist/memory/project/dir/fill-value-store.js

@@ -0,0 +1,88 @@
+/**
+ * The values a drive types into this project's fields, kept so they are paid for once.
+ *
+ * A generated field value is not a model's opinion to be re-asked every run. It is a FIXTURE: the
+ * same label on the same app wants the same value tomorrow, a replay must send exactly what the
+ * recording sent or it is not a replay, and a human who dislikes "Acme Corp" should be able to open
+ * a file and write something else rather than argue with a model about it. So it lives beside the
+ * flows it belongs to, in git, in the project's own directory.
+ *
+ * Read once at the start of a drive and written once at the end: a drive that fills twenty fields
+ * must not write the file twenty times, and nothing else in the process is competing for it.
+ *
+ * Every failure is silent and answers "no values". A drive must never fail over a fixtures file,
+ * and the fallback -- the label heuristic -- is what every drive used before this existed.
+ */
+import { ReticleDir } from '@reticlehq/core';
+import { join } from 'node:path';
+/** Stamped so a later format change can tell an old file from a broken one. */
+const VERSION = 1;
+/** A label is a UI string and can be anything; a value that is not a string is not usable. */
+function parse(text) {
+    try {
+        const raw = JSON.parse(text);
+        if ('object' !== typeof raw || null === raw)
+            return {};
+        const values = raw.values;
+        if ('object' !== typeof values || null === values)
+            return {};
+        const out = {};
+        for (const [label, value] of Object.entries(values))
+            if ('string' === typeof value && 0 < value.length)
+                out[label] = value;
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * A store that remembers within one drive and writes nothing.
+ *
+ * Used when there is no project directory to write to. A drive must never fail over its fixtures
+ * file, and that includes failing to FIND one: the values still de-duplicate inside the run, they
+ * are simply not carried into the next one.
+ */
+export function memoryFillValues() {
+    const values = new Map();
+    return {
+        get: (label) => values.get(label),
+        set: (label, value) => void values.set(label, value),
+        flush: () => Promise.resolve(),
+    };
+}
+export async function openFillValues(fs, root) {
+    if (root === undefined || 0 === root.length)
+        return memoryFillValues();
+    const path = join(root, ReticleDir.FILL_VALUES_FILE);
+    let values = {};
+    try {
+        if (await fs.exists(path))
+            values = parse(await fs.readFile(path));
+    }
+    catch {
+        /* an unreadable fixtures file is the same as an absent one */
+    }
+    let learned = false;
+    return {
+        get: (label) => values[label],
+        set: (label, value) => {
+            if (values[label] === value)
+                return;
+            values[label] = value;
+            learned = true;
+        },
+        async flush() {
+            if (!learned)
+                return;
+            try {
+                await fs.mkdir(root);
+                const file = { version: VERSION, values };
+                await fs.writeFile(path, `${JSON.stringify(file, null, 2)}\n`);
+            }
+            catch {
+                /* the drive already happened; losing the cache costs a regeneration, not a result */
+            }
+        },
+    };
+}

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

@@ -0,0 +1,139 @@
+import { type ProjectId, type FlowName, type SessionId } from '@reticlehq/core';
+import { ContractReadError, type CapabilitiesContract, type RunId } from '@reticlehq/core';
+import type { FileSystemPort } from '../fs/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/fill-values.json (what a drive types into each labelled field — git-checked) */
+    fillValues: 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: RunId): string;
+/** The journal directory for `sessionId` (.reticle/sessions/<id>). Guard the id first. */
+export declare function sessionDirPath(root: string, sessionId: SessionId): string;
+/** The append-only event ledger path for a session (.reticle/sessions/<id>/events.jsonl). */
+export declare function journalEventsPath(root: string, sessionId: SessionId): string;
+/** The append-only action ledger path for a session (.reticle/sessions/<id>/actions.jsonl). */
+export declare function journalActionsPath(root: string, sessionId: SessionId): string;
+/**
+ * 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 declare function journalClosedPath(root: string, sessionId: SessionId): string;
+/**
+ * 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 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?: ProjectId): 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?: ProjectId): string;
+/**
+ * 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 declare function flowParentDir(root: string, name: FlowName, projectId?: ProjectId): string;
+/**
+ * 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 declare function isValidFlowName(name: string): name is FlowName;
+export declare function baselinePath(root: string, name: string): string;
+/**
+ * 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 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>;