@descryy/mcp 0.11.5 → 0.11.6

package/dist/session.js

@@ -0,0 +1,779 @@
+/**
+ * One repo, one graph, one process — owns the SQLite handle, config, sources; tools
+ * own nothing. `.descry/config.json` is optional, defaults to local-first, except the
+ * source list (this repo names no adapter, `registry.ts`): unconfigured sessions can
+ * query, not build. Graph opens lazily so a missing one fails as a tool result, not a crash. */
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { basename, isAbsolute, join, resolve } from "node:path";
+import { isConfirmedFactScope } from "@descryy/ir";
+import { computeGraphFreshness, createStoreProvider, distinctFilePaths, gitHead, isGitRepository, NodeSqliteDriver, openStore, rebuildStaleGraph, } from "@descryy/core";
+import { BROWSER_BACKEND_NOT_INSTALLED } from "./browser/provider.js";
+import { createBrowserSessionRegistry } from "./browser/registry.js";
+import { normaliseSpec } from "./registry.js";
+export const CONFIG_RELATIVE_PATH = join(".descry", "config.json");
+export const DEFAULT_GRAPH_RELATIVE_PATH = join(".descry", "graph.db");
+function parseSavedReadiness(raw, configPath, service) {
+    const e = (typeof raw === "object" && raw !== null ? raw : {});
+    const kind = e["kind"];
+    if (kind !== "http" && kind !== "tcp-port" && kind !== "command") {
+        throw new ConfigError(`${configPath}: savedStart.services.${service}.readiness.kind must be "http", "tcp-port" or "command"`);
+    }
+    const path = typeof e["path"] === "string" ? e["path"] : undefined;
+    const expectedStatus = typeof e["expectedStatus"] === "number" ? e["expectedStatus"] : undefined;
+    const host = typeof e["host"] === "string" ? e["host"] : undefined;
+    const command = typeof e["command"] === "string" ? e["command"] : undefined;
+    const rawArgs = e["args"];
+    const args = Array.isArray(rawArgs) && rawArgs.every((a) => typeof a === "string") ? rawArgs : undefined;
+    const timeoutMs = typeof e["timeoutMs"] === "number" ? e["timeoutMs"] : undefined;
+    return {
+        kind,
+        ...(path === undefined ? {} : { path }),
+        ...(expectedStatus === undefined ? {} : { expectedStatus }),
+        ...(host === undefined ? {} : { host }),
+        ...(command === undefined ? {} : { command }),
+        ...(args === undefined ? {} : { args }),
+        ...(timeoutMs === undefined ? {} : { timeoutMs }),
+    };
+}
+/** `savedStart`'s reader, paired with `writeSavedStart` below. Lenient the same way
+ *  `parseConfirmedIncidents` is about a malformed sub-object — coerced to `{}` rather
+ *  than thrown on — because this file's own writer is the only thing that ever
+ *  produces this shape; a hand-edited config that gets it wrong is refused field by
+ *  field below, same as every other section here. */
+function parseSavedStart(raw, configPath) {
+    if (raw === undefined)
+        return undefined;
+    const e = (typeof raw === "object" && raw !== null ? raw : {});
+    const savedAt = e["savedAt"];
+    if (typeof savedAt !== "string" || savedAt === "") {
+        throw new ConfigError(`${configPath}: "savedStart.savedAt" must be a non-empty string`);
+    }
+    const servicesRaw = e["services"];
+    if (typeof servicesRaw !== "object" || servicesRaw === null || Array.isArray(servicesRaw)) {
+        throw new ConfigError(`${configPath}: "savedStart.services" must be an object`);
+    }
+    const services = {};
+    for (const [name, value] of Object.entries(servicesRaw)) {
+        const v = (typeof value === "object" && value !== null ? value : {});
+        const command = typeof v["command"] === "string" ? v["command"] : undefined;
+        const cwd = v["cwd"];
+        if (typeof cwd !== "string" || cwd === "") {
+            throw new ConfigError(`${configPath}: "savedStart.services.${name}.cwd" must be a non-empty string`);
+        }
+        const port = typeof v["port"] === "number" ? v["port"] : undefined;
+        const rawDependsOn = v["dependsOn"];
+        const dependsOn = Array.isArray(rawDependsOn) && rawDependsOn.every((d) => typeof d === "string")
+            ? rawDependsOn
+            : undefined;
+        const rawEnvNames = v["envNames"];
+        const envNames = Array.isArray(rawEnvNames) && rawEnvNames.every((n) => typeof n === "string")
+            ? rawEnvNames
+            : undefined;
+        const attachRaw = v["attach"];
+        let attach;
+        if (attachRaw !== undefined) {
+            const a = (typeof attachRaw === "object" && attachRaw !== null ? attachRaw : {});
+            if (typeof a["pid"] !== "number" || typeof a["logFilePath"] !== "string") {
+                throw new ConfigError(`${configPath}: "savedStart.services.${name}.attach" must have a numeric "pid" and a string "logFilePath"`);
+            }
+            attach = { pid: a["pid"], logFilePath: a["logFilePath"] };
+        }
+        services[name] = {
+            ...(command === undefined ? {} : { command }),
+            cwd,
+            ...(port === undefined ? {} : { port }),
+            ...(dependsOn === undefined ? {} : { dependsOn }),
+            ...(envNames === undefined ? {} : { envNames }),
+            ...(attach === undefined ? {} : { attach }),
+            readiness: parseSavedReadiness(v["readiness"], configPath, name),
+        };
+    }
+    return { services, savedAt };
+}
+function parseConfirmedIncidents(raw, configPath) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw)) {
+        throw new ConfigError(`${configPath}: "confirmedIncidents" must be an array`);
+    }
+    return raw.map((entry, index) => {
+        const e = entry;
+        for (const key of ["repo", "summary", "confirmedBy", "confirmedAt"]) {
+            if (typeof e[key] !== "string" || e[key] === "") {
+                throw new ConfigError(`${configPath}: confirmedIncidents[${index}].${key} must be a non-empty string`);
+            }
+        }
+        const files = e["files"];
+        if (!Array.isArray(files) || files.length === 0 || files.some((f) => typeof f !== "string" || f === "")) {
+            throw new ConfigError(`${configPath}: confirmedIncidents[${index}].files must be a non-empty array of paths — ` +
+                "an incident naming no file has nothing to attach it to");
+        }
+        for (const key of ["errorText", "fixedAtCommit", "observedInRun"]) {
+            if (e[key] !== undefined && (typeof e[key] !== "string" || e[key] === "")) {
+                throw new ConfigError(`${configPath}: confirmedIncidents[${index}].${key} must be a non-empty string when present`);
+            }
+        }
+        const occurrences = e["occurrences"];
+        if (occurrences !== undefined &&
+            (!Array.isArray(occurrences) ||
+                occurrences.length === 0 ||
+                occurrences.some((o) => typeof o !== "string" || o === ""))) {
+            throw new ConfigError(`${configPath}: confirmedIncidents[${index}].occurrences must be a non-empty array of timestamps when present`);
+        }
+        return {
+            repo: e["repo"],
+            summary: e["summary"],
+            files: files,
+            ...(e["errorText"] === undefined ? {} : { errorText: e["errorText"] }),
+            ...(e["fixedAtCommit"] === undefined ? {} : { fixedAtCommit: e["fixedAtCommit"] }),
+            ...(e["observedInRun"] === undefined ? {} : { observedInRun: e["observedInRun"] }),
+            confirmedBy: e["confirmedBy"],
+            confirmedAt: e["confirmedAt"],
+            ...(occurrences === undefined ? {} : { occurrences: occurrences }),
+        };
+    });
+}
+function parseConfirmedFacts(raw, configPath) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw)) {
+        throw new ConfigError(`${configPath}: "confirmedFacts" must be an array`);
+    }
+    return raw.map((entry, index) => {
+        const e = entry;
+        for (const key of ["repo", "blockedBy", "value", "confirmedBy", "confirmedAt"]) {
+            if (typeof e[key] !== "string" || e[key] === "") {
+                throw new ConfigError(`${configPath}: confirmedFacts[${index}].${key} must be a non-empty string`);
+            }
+        }
+        for (const key of ["environment", "confirmedAtCommit", "workspace"]) {
+            if (e[key] !== undefined && (typeof e[key] !== "string" || e[key] === "")) {
+                throw new ConfigError(`${configPath}: confirmedFacts[${index}].${key} must be a non-empty string when present`);
+            }
+        }
+        if (e["scope"] !== undefined && !isConfirmedFactScope(e["scope"])) {
+            throw new ConfigError(`${configPath}: confirmedFacts[${index}].scope must be "repo" or "workspace" when present`);
+        }
+        return {
+            repo: e["repo"],
+            blockedBy: e["blockedBy"],
+            value: e["value"],
+            ...(e["environment"] === undefined ? {} : { environment: e["environment"] }),
+            confirmedBy: e["confirmedBy"],
+            confirmedAt: e["confirmedAt"],
+            // Round-tripped rather than dropped — `confirmedAtCommit` was written by
+            // `writeConfirmedFact`; discarding it on reload would silence the staleness disclosure.
+            ...(e["confirmedAtCommit"] === undefined ? {} : { confirmedAtCommit: e["confirmedAtCommit"] }),
+            ...(e["scope"] === undefined ? {} : { scope: e["scope"] }),
+            ...(e["workspace"] === undefined ? {} : { workspace: e["workspace"] }),
+        };
+    });
+}
+/** `(repo, blockedBy, environment)` — `undefined` environment is its own value, never a wildcard. */
+function sameFactKey(a, b) {
+    return a.repo === b.repo && a.blockedBy === b.blockedBy && a.environment === b.environment;
+}
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConfigError";
+    }
+}
+export async function loadConfig(repoPath) {
+    const configPath = join(repoPath, CONFIG_RELATIVE_PATH);
+    let raw = {};
+    let found = null;
+    try {
+        raw = JSON.parse(await readFile(configPath, "utf8"));
+        found = configPath;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== "ENOENT") {
+            // A config that exists and can't be parsed is refused, not defaulted past —
+            // silently falling back would run the session under settings the user thinks they overrode.
+            throw new ConfigError(`${configPath} exists but could not be read: ${error.message}`);
+        }
+    }
+    if (raw.sources !== undefined && !Array.isArray(raw.sources)) {
+        throw new ConfigError(`${configPath}: "sources" must be an array`);
+    }
+    const sources = (raw.sources ?? []).map((entry, index) => {
+        if (typeof entry === "string")
+            return normaliseSpec(entry);
+        if (typeof entry === "object" && entry !== null && typeof entry.module === "string") {
+            return entry;
+        }
+        throw new ConfigError(`${configPath}: sources[${index}] must be a module specifier or an object with a "module" field`);
+    });
+    const workspace = typeof raw.workspace === "string" && raw.workspace !== "" ? raw.workspace : undefined;
+    const workspaceRepos = parseWorkspaceRepos(raw.workspaceRepos, configPath);
+    const savedStart = parseSavedStart(raw.savedStart, configPath);
+    return {
+        // Directory name is a defensible default and poor identity — changes on clone,
+        // and every repo-scoped node id changes with it. Disclosed in `analyze`, not
+        // discovered when two machines produce different graphs.
+        repo: typeof raw.repo === "string" && raw.repo !== "" ? raw.repo : basename(resolve(repoPath)),
+        workspace,
+        graph: typeof raw.graph === "string" && raw.graph !== "" ? raw.graph : DEFAULT_GRAPH_RELATIVE_PATH,
+        sources,
+        confirmedFacts: parseConfirmedFacts(raw.confirmedFacts, configPath),
+        confirmedIncidents: parseConfirmedIncidents(raw.confirmedIncidents, configPath),
+        workspaceRepos,
+        linkedFacts: await readLinkedFacts(repoPath, workspace, workspaceRepos),
+        ...(savedStart === undefined ? {} : { savedStart }),
+        configPath: found,
+    };
+}
+/**
+ * Fields compared for staleness (13.3.16 / N2). Deliberately excludes `linkedFacts`:
+ * it is derived from sibling repos' own files at load time, not something a local
+ * edit to *this* repo's config changes, and diffing it here would double-count
+ * `workspaceRepos` drift under a second name.
+ */
+const DRIFT_FIELDS = [
+    "repo",
+    "workspace",
+    "graph",
+    "sources",
+    "confirmedFacts",
+    "confirmedIncidents",
+    "workspaceRepos",
+    "savedStart",
+    "configPath",
+];
+function driftedKeys(onDisk, loaded) {
+    return DRIFT_FIELDS.filter((key) => JSON.stringify(onDisk[key]) !== JSON.stringify(loaded[key]));
+}
+/**
+ * 13.3.16 (N2): a count match on `sources` is not a content match — two sessions
+ * swapping one adapter for another, or changing an adapter's options, leave
+ * `sources.length` unchanged, which is exactly the gap that let a concurrent edit
+ * go undetected and left a graph stuck at R0 with no disclosure of why. Every
+ * field is compared by value, and the note names which ones actually changed —
+ * `graph`, `confirmedFacts`/`confirmedIncidents` and `workspaceRepos` were
+ * previously not compared at all.
+ */
+export function configDriftNote(onDisk, loaded) {
+    if (onDisk === null)
+        return undefined;
+    const changed = driftedKeys(onDisk, loaded);
+    if (changed.length === 0)
+        return undefined;
+    return ("The on-disk .descry/config.json no longer matches what this server loaded at startup " +
+        `(changed: ${changed.join(", ")}). Configuration is read once per process, not on every call ` +
+        "(session.ts) — this run is still using the configuration this server started with, not the " +
+        "current file. Restart the MCP server for on-disk changes to take effect; the notes below " +
+        "describe the stale, running configuration, not what is actually on disk now.");
+}
+/**
+ * 13.3.16 (N2) steps 2-3: called once per tool call from `server.ts`, not only from
+ * `analyze`, so every reply discloses a stale session rather than the one tool that
+ * happened to re-read the config. A config that cannot even be read right now
+ * (deleted mid-session, or edited into something `loadConfig` refuses) is itself
+ * drift and must not read as "no drift" merely because there is nothing to diff
+ * against — the previous `.catch(() => null)` collapsed that case into silence.
+ */
+export async function checkConfigDrift(session) {
+    if (!existsSync(session.repoPath))
+        return { stale: false, note: undefined };
+    try {
+        const onDisk = await loadConfig(session.repoPath);
+        const note = configDriftNote(onDisk, session.config);
+        return { stale: note !== undefined, note };
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return {
+            stale: true,
+            note: `The on-disk .descry/config.json could not be read as of this call (${reason}). This run ` +
+                "is still using the configuration loaded at startup; whether that configuration still " +
+                "matches what is on disk now cannot be determined.",
+        };
+    }
+}
+/**
+ * Lane "map-freshness" item 3 — starting value only, **not measured**
+ * (lightweight mode: this lane could not run a 1-file-change refresh against
+ * a large reference repo and time it). `DEC-NEXT-auto-refresh-budget` records
+ * this exact number and says plainly that it is a guess, not a measurement —
+ * whoever next runs `npm run build && npm run lint && node --test` with a
+ * real reference repo available should replace it with a measured p50/p95
+ * and update that decision file rather than this comment alone.
+ */
+export const AUTO_REFRESH_BUDGET_MS = 10_000;
+/**
+ * Lane "map-freshness" item 1 — whether the stored graph still matches the
+ * repository on disk, read once per call from `server.ts`, the same place
+ * `checkConfigDrift` is read from. `undefined` when there is nothing honest
+ * to report: the graph is empty (`baseStamp().commitSha === null` — nothing
+ * to be fresh or stale *relative to*, same reasoning `computeGraphFreshness`
+ * itself already documents) or the stamp/driver could not be read at all
+ * (`freshnessField()` in `render.ts` reports that as `unknown` once a real
+ * `commitSha` exists downstream, never as a false `current`).
+ *
+ * Deliberately not a `Session` method (`Session#checkFreshness()` in an
+ * earlier note here was this function's own working name) — `checkConfigDrift`
+ * is a standalone function taking `session` for the same reason: it needs no
+ * private state this class doesn't already expose, and keeping it a plain
+ * function keeps this module free of a growing method surface for what are,
+ * one at a time, one-shot per-call reads.
+ */
+export async function checkFreshness(session) {
+    let commitSha;
+    try {
+        commitSha = session.provider().baseStamp().commitSha;
+    }
+    catch {
+        return undefined;
+    }
+    if (commitSha === null)
+        return undefined;
+    try {
+        const indexedFiles = distinctFilePaths(session.store().driver);
+        return await computeGraphFreshness({ repoPath: session.repoPath, commitSha, indexedFiles });
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseWorkspaceRepos(raw, configPath) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw)) {
+        throw new ConfigError(`${configPath}: "workspaceRepos" must be an array`);
+    }
+    return raw.map((entry, index) => {
+        const e = entry;
+        for (const key of ["path", "repo"]) {
+            if (typeof e[key] !== "string" || e[key] === "") {
+                throw new ConfigError(`${configPath}: workspaceRepos[${index}].${key} must be a non-empty string`);
+            }
+        }
+        return { path: e["path"], repo: e["repo"] };
+    });
+}
+/** Workspace-scoped facts from this workspace's *other* repos, one level only (no
+ *  recursive follow of a sibling's own `workspaceRepos`). Every failure here is silent
+ *  by design — a broken/uncloned sibling must not block this session; `questions` discloses it. */
+async function readLinkedFacts(repoPath, workspace, repos) {
+    if (workspace === undefined || repos.length === 0)
+        return [];
+    const self = resolve(repoPath);
+    const out = [];
+    for (const entry of repos) {
+        if (resolve(entry.path) === self)
+            continue;
+        const path = join(entry.path, CONFIG_RELATIVE_PATH);
+        let facts;
+        try {
+            const raw = JSON.parse(await readFile(path, "utf8"));
+            facts = parseConfirmedFacts(raw.confirmedFacts, path);
+        }
+        catch {
+            continue;
+        }
+        // Checked on the fact itself, not inferred from being found in a linked repo —
+        // a repo-scoped fact in a linked config still does not cross.
+        for (const fact of facts) {
+            if (fact.scope === "workspace" && fact.workspace === workspace)
+                out.push(fact);
+        }
+    }
+    return out;
+}
+/** `.descry/config.json`'s writer, paired with `loadConfig`. One writer used by both
+ *  `descry init` and `link_workspace` so they can't drift into writing different
+ *  shapes. Patches `repo`/`workspace` only — other fields survive untouched. */
+export async function writeConfig(repoPath, patch) {
+    const path = join(repoPath, CONFIG_RELATIVE_PATH);
+    let existing = {};
+    try {
+        existing = JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (error) {
+        // An unparseable config is fixed here (start from empty), unlike `loadConfig`
+        // which refuses — this writer's job is to repair, not run a session. ENOENT
+        // takes the same path.
+        void error;
+        existing = {};
+    }
+    const previousWorkspace = typeof existing.workspace === "string" ? existing.workspace : undefined;
+    const next = { ...existing, repo: patch.repo };
+    if (patch.workspace !== undefined)
+        next.workspace = patch.workspace;
+    await mkdir(join(repoPath, ".descry"), { recursive: true });
+    await writeFile(path, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+    return { path, previousWorkspace };
+}
+/** `workspaceRepos`' writer — one writer per field a shared file owns (see
+ *  `writeConfig`, `writeConfirmedFact`, `writeSources`). Replaces the whole list
+ *  rather than merging: membership is one declaration made at one moment. */
+export async function writeWorkspaceRepos(repoPath, repos) {
+    const path = join(repoPath, CONFIG_RELATIVE_PATH);
+    let existing = {};
+    try {
+        existing = JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (error) {
+        void error;
+        existing = {};
+    }
+    const next = {
+        ...existing,
+        workspaceRepos: repos.map((r) => ({ path: r.path, repo: r.repo })),
+    };
+    await mkdir(join(repoPath, ".descry"), { recursive: true });
+    await writeFile(path, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+    return { path };
+}
+/** `confirmedFacts`' writer, separate from `writeConfig` (one writer per field). Keyed
+ *  on exact `(repo, blockedBy, environment)` (DEC-223 §3) — undefined environment is its
+ *  own key, not a wildcard. Same key replaces; a different environment adds a new fact. */
+export async function writeConfirmedFact(repoPath, fact) {
+    const path = join(repoPath, CONFIG_RELATIVE_PATH);
+    let existing = {};
+    try {
+        existing = JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (error) {
+        void error;
+        existing = {};
+    }
+    const priorRaw = Array.isArray(existing["confirmedFacts"]) ? existing["confirmedFacts"] : [];
+    const prior = parseConfirmedFacts(priorRaw, path);
+    const replaced = prior.find((f) => sameFactKey(f, fact)) ?? null;
+    const rest = prior.filter((f) => !sameFactKey(f, fact));
+    const next = { ...existing, confirmedFacts: [...rest, fact] };
+    await mkdir(join(repoPath, ".descry"), { recursive: true });
+    await writeFile(path, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+    return { path, replaced };
+}
+/** `confirmedIncidents`' writer — appends a genuinely new incident, but merges a
+ *  resubmission of the same content into the record already on file (UAT phase 5,
+ *  F9). `confirmedAt` used to be the dedup key alongside `summary`, and a retried
+ *  submission always carries a fresh timestamp — so every retry minted a second
+ *  `INCIDENT` node, silently doubling its weight in blast-radius bias and
+ *  `similar_incidents` scoring. Identity is now content (`repo` + `summary` +
+ *  `errorText`, matching `confirmedIncidentId`), and a match appends this call's
+ *  timestamp to `occurrences` and unions `files` rather than minting a new record.
+ *  A retry and a genuine recurrence look identical from content alone; both are
+ *  representable and countable this way, and neither doubles the graph. */
+export async function writeConfirmedIncident(repoPath, incident) {
+    const path = join(repoPath, CONFIG_RELATIVE_PATH);
+    let existing = {};
+    try {
+        existing = JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (error) {
+        void error;
+        existing = {};
+    }
+    const priorRaw = Array.isArray(existing["confirmedIncidents"]) ? existing["confirmedIncidents"] : [];
+    const prior = parseConfirmedIncidents(priorRaw, path);
+    const same = (a) => a.repo === incident.repo &&
+        a.summary === incident.summary &&
+        (a.errorText ?? "") === (incident.errorText ?? "");
+    const match = prior.find(same) ?? null;
+    let next;
+    let record;
+    let occurrences;
+    if (match === null) {
+        next = [...prior, incident];
+        record = incident;
+        occurrences = 1;
+    }
+    else {
+        record = {
+            ...match,
+            // The incident may have been reported with a narrower or wider file list
+            // each time — the union is what it has ever been correlated to.
+            files: [...new Set([...match.files, ...incident.files])].sort(),
+            ...(incident.fixedAtCommit === undefined ? {} : { fixedAtCommit: incident.fixedAtCommit }),
+            occurrences: [...(match.occurrences ?? [match.confirmedAt]), incident.confirmedAt],
+        };
+        next = [...prior.filter((i) => !same(i)), record];
+        occurrences = record.occurrences.length;
+    }
+    await mkdir(join(repoPath, ".descry"), { recursive: true });
+    await writeFile(path, `${JSON.stringify({ ...existing, confirmedIncidents: next }, null, 2)}\n`, "utf8");
+    return { path, total: next.length, merged: match !== null, occurrences, record, records: next };
+}
+/** `savedStart`'s writer, one writer per field like the others. Called only by
+ *  `observe-runtime.ts`'s `run`, and only once that run's execution state is
+ *  `"COMPLETED"` — never on a failed run, so this field's presence already means
+ *  "reached readiness at least once" without this writer having to track that
+ *  itself. Overwrites unconditionally: the newest successful run is what is worth
+ *  remembering, not a merge with whatever an older one declared. `services` must
+ *  already exclude secret values by the time it reaches here — this writer trusts
+ *  its caller the same way `writeConfirmedIncident` does, rather than re-scanning
+ *  a shape it did not define. */
+export async function writeSavedStart(repoPath, services) {
+    const path = join(repoPath, CONFIG_RELATIVE_PATH);
+    let existing = {};
+    try {
+        existing = JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (error) {
+        void error;
+        existing = {};
+    }
+    const savedAt = new Date().toISOString();
+    const next = { ...existing, savedStart: { services, savedAt } };
+    await mkdir(join(repoPath, ".descry"), { recursive: true });
+    await writeFile(path, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+    return { path, savedAt };
+}
+/** `sources`' writer, one writer per field like the others. Unconditional — the caller
+ *  (`descry init`) decides whether overwriting is appropriate, not this primitive. */
+export async function writeSources(repoPath, sources) {
+    const path = join(repoPath, CONFIG_RELATIVE_PATH);
+    let existing = {};
+    try {
+        existing = JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (error) {
+        void error;
+        existing = {};
+    }
+    const next = { ...existing, sources: [...sources] };
+    await mkdir(join(repoPath, ".descry"), { recursive: true });
+    await writeFile(path, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+    return { path };
+}
+export class Session {
+    repoPath;
+    // Not `readonly` — `reloadConfig()` is the one caller-initiated exception to
+    // "configuration is read once per process" (UAT phase 5, §0 gap 2). Every
+    // other read of this field still sees whatever `reloadConfig()` last set,
+    // exactly as it did the config loaded at startup.
+    config;
+    #store = null;
+    #provider = null;
+    #browserSessions = null;
+    #browserDriverFactory = null;
+    /**
+     * Literal credential values a browser session on this connection was seeded
+     * with — B1.
+     *
+     * Held so the things this server *writes* can be checked against them. Exact
+     * values, never patterns, because `@descryy/core`'s redactor is
+     * literal-substring for the reason its own header gives: a "looks like a
+     * token" regex either destroys real data or misses a secret shaped unlike
+     * it. Per connection, in memory only, and compared against rather than
+     * printed at every call site that reads it.
+     */
+    #browserSecrets = new Set();
+    #openGraph;
+    #calls = [];
+    #nextCallId = 1;
+    /**
+     * Where a `${credential:NAME}` step resolves its value, for a
+     * `browser_run_scenario` replay on this connection — RG-1(4) / lane
+     * "delivery". Mutable, not constructor-injected, and `undefined` by
+     * default: every existing `new Session(...)` call site (54 of them at
+     * last count) stays unchanged, and a caller that wants sign-in-by-profile
+     * sets it after construction, the same way `config` is mutated in place
+     * by `reloadConfig()`. `replayScenario` (`browser/scenario-runner.ts`)
+     * already accepts this exact type and already refuses a `${credential:...}`
+     * step by name when it is `undefined` — this field is what lets
+     * `browser-run-scenario.ts`'s tool actually have one to pass, which
+     * nothing did before.
+     */
+    credentialStore = undefined;
+    /**
+     * Lane "map-freshness" item 3 — how long `server.ts`'s auto-refresh
+     * (`ensureFreshGraph`) will let a `behind` graph's refresh run before
+     * giving up and answering from the old graph instead, with the `behind`
+     * disclosure standing in place of a "refreshed" one. `undefined` (the
+     * default for every existing call site) means "use `AUTO_REFRESH_BUDGET_MS`"
+     * — mutable, same shape as `credentialStore` above. `0` skips the refresh
+     * outright, which is how a test reaches the answer-from-the-old-graph path
+     * deterministically: a near-zero timeout does not, because the budget only
+     * stops sources that check the abort signal (see `ensureFreshGraph`).
+     */
+    autoRefreshBudgetMs = undefined;
+    constructor(repoPath, config, openGraph) {
+        this.repoPath = repoPath;
+        this.config = config;
+        this.#openGraph = openGraph ?? ((path) => openStore(path));
+    }
+    static async open(options) {
+        const repoPath = resolve(options.repoPath);
+        const config = options.config ?? (await loadConfig(repoPath));
+        return new Session(repoPath, config, options.openGraph);
+    }
+    /**
+     * Re-reads `.descry/config.json` from disk and replaces `config` in place —
+     * the explicit, caller-initiated reload UAT phase 5 (§0 gap 2) asked for.
+     *
+     * Deliberately not a file watcher: a watcher would re-run every trust check
+     * (`module-trust.ts`) on a specifier the instant a file the *scanned
+     * repository* controls changes, with no human in the loop — exactly the
+     * hazard those checks exist to gate. This method exists so a caller (a
+     * tool's own `reload` argument) can ask for the same effect on purpose,
+     * with an addressee for the trust decision that follows.
+     *
+     * Returns which top-level fields actually changed, using the identical
+     * comparison `checkConfigDrift`'s disclosure already makes, so "reload
+     * happened" and "reload changed something" stay distinguishable — a
+     * reload that finds nothing different is not a no-op that failed silently.
+     */
+    async reloadConfig() {
+        const fresh = await loadConfig(this.repoPath);
+        const changed = driftedKeys(fresh, this.config);
+        this.config = fresh;
+        return { changed };
+    }
+    get graphPath() {
+        return isAbsolute(this.config.graph)
+            ? this.config.graph
+            : join(this.repoPath, this.config.graph);
+    }
+    /** Open on first use; reuse thereafter. */
+    store() {
+        if (this.#store === null)
+            this.#store = this.#openGraph(this.graphPath);
+        return this.#store;
+    }
+    /** `analyze`'s own repair path — the only caller entitled to one (others refuse a
+     *  version mismatch per DEC-017). Opens a short-lived driver directly, bypassing an
+     *  injected test store; no-op there since an in-memory fixture is never stale. */
+    repairStaleGraph() {
+        if (this.#store !== null)
+            return { rebuilt: false };
+        const driver = new NodeSqliteDriver();
+        try {
+            driver.open(this.graphPath);
+            return rebuildStaleGraph(driver);
+        }
+        catch {
+            // Anything from opening (missing dir, corrupt file) is not this method's job —
+            // `store()` right after hits the same path via its own disclosed error handling.
+            return { rebuilt: false };
+        }
+        finally {
+            driver.close();
+        }
+    }
+    provider() {
+        if (this.#provider === null)
+            this.#provider = createStoreProvider(this.store().driver);
+        return this.#provider;
+    }
+    /** Repo root for an analysis run. Commit sha comes from git and is never defaulted
+     *  when git is absent — every node/edge is stamped with it, and a placeholder would
+     *  make the staleness stamp a lie nothing downstream could detect. */
+    async root() {
+        if (!(await isGitRepository(this.repoPath))) {
+            throw new ConfigError(`${this.repoPath} is not a git repository. Every node is stamped with the commit it was ` +
+                "read at, so there is nothing honest to record for a directory with no history.");
+        }
+        return {
+            repo: this.config.repo,
+            ...(this.config.workspace === undefined ? {} : { workspace: this.config.workspace }),
+            absolutePath: this.repoPath,
+            commitSha: await gitHead(this.repoPath),
+        };
+    }
+    /** Live browser sessions for this connection (`mcp-browser-tools.md` §4). Created
+     *  lazily, same reason as the graph — most connections never touch a browser tool.
+     *  Lives here, not a module-level map, so "per connection, never global" actually holds. */
+    browserSessions() {
+        if (this.#browserSessions === null)
+            this.#browserSessions = createBrowserSessionRegistry();
+        return this.#browserSessions;
+    }
+    /** The browser this connection drives, or a named reason there is none. Unavailable
+     *  by default — `@descryy/runtime-browser` isn't installed yet — reported as a refusal
+     *  with a remedy, never a silently-empty page (rule 7). */
+    browserBackend() {
+        if (this.#browserDriverFactory === null)
+            return BROWSER_BACKEND_NOT_INSTALLED;
+        return { available: true, createDriver: this.#browserDriverFactory };
+    }
+    /** Installs the driver this connection's browser tools use. A method, not a
+     *  constructor arg — most sessions never touch a browser and shouldn't have to
+     *  name one to be constructed. */
+    useBrowserDriver(driver) {
+        // One-driver form — every test that doesn't care about stack parsing wants this
+        // and shouldn't have to write a factory.
+        this.#browserDriverFactory = () => Promise.resolve(driver);
+    }
+    /** Installs a factory that builds a driver per session. A factory, not a driver,
+     *  because the stack-trace parser (`browser_start_session`'s `stackParser`) is
+     *  language-specific and named per call. */
+    useBrowserDriverFactory(factory) {
+        this.#browserDriverFactory = factory;
+    }
+    /** Record credential values a browser session was seeded with, so anything this server writes can refuse to carry them. */
+    noteBrowserSecrets(values) {
+        for (const value of values)
+            if (value.length > 0)
+                this.#browserSecrets.add(value);
+    }
+    /** The credential values this connection knows about. Compared against, never rendered. */
+    browserSecrets() {
+        return [...this.#browserSecrets];
+    }
+    /** Synchronous teardown, no I/O to wait on. A browser session can't close
+     *  synchronously, so that reap lives in `dispose()` — this stays the method
+     *  every existing no-browser caller keeps using unchanged. */
+    close() {
+        this.#browserSessions?.stop();
+        this.#store?.close();
+        this.#store = null;
+        this.#provider = null;
+    }
+    /** Full teardown, including any live browser — what a client disconnect must
+     *  reach (§4). A leaked Chromium costs the developer's machine, not just a file
+     *  descriptor. Awaits the reap first so the evidence flush has a live registry. */
+    async dispose() {
+        if (this.#browserSessions !== null)
+            await this.#browserSessions.reapAll("clientDisconnect");
+        this.close();
+    }
+    /** Mints the next call id without recording anything yet. `server.ts` calls this
+     *  before render so the reply can carry `callId`, then records under the same id
+     *  with `recordCallWithId` — one id used for both. */
+    allocateCallId() {
+        return `call-${this.#nextCallId++}`;
+    }
+    /** `verify_claim`'s fact boundary — called once per call with the exact
+     *  `structuredContent` the host received. IDs are scoped to this process only, so a
+     *  citation from a different run can't resolve (§2's G1 negative control). */
+    recordCall(tool, args, result) {
+        return this.recordCallWithId(this.allocateCallId(), tool, args, result);
+    }
+    /** `recordCall` under an id minted earlier by `allocateCallId`, not one minted here
+     *  — so `recordedCall(id)` can find the exact id a caller read off the reply's
+     *  `callId`, which didn't exist until after the envelope was built. */
+    recordCallWithId(id, tool, args, result) {
+        const call = { id, tool, args, result, at: Date.now() };
+        this.#calls.push(call);
+        return call;
+    }
+    /** All calls recorded this session, oldest first. */
+    recordedCalls() {
+        return this.#calls;
+    }
+    recordedCall(id) {
+        return this.#calls.find((c) => c.id === id);
+    }
+}
+/**
+ * What this repository's last successful `observe_runtime` run saved, if any — the
+ * accessor a caller outside `observe-runtime.ts` should use rather than reaching into
+ * `session.config` directly, so the field it reads stays this file's own concern.
+ *
+ * Exported for the browser tools (lane "preflight-browser" / lane 5): a saved
+ * service's `readiness` can carry an `http` path and, if declared, a fixed `port` —
+ * enough to recover a URL to navigate to without requiring a fresh `observe_runtime`
+ * call first. Not wired into any browser tool from here — that composition belongs
+ * to the tools that own it.
+ */
+export function loadSavedStart(session) {
+    return session.config.savedStart;
+}
+//# sourceMappingURL=session.js.map