@descryy/mcp 0.1.1 → 0.2.0

package/dist/tools/observe-runtime.js

@@ -0,0 +1,951 @@
+/**
+ * `observe_runtime` — boot or attach to a real application, watch it, and write
+ * what was witnessed into the graph as R4 facts.
+ *
+ * **The second tool that writes, and the first that writes something no
+ * re-index can reproduce.** `analyze` re-derives the graph from source already
+ * on disk, so nothing it writes is a new claim about the world. This one runs
+ * a real process and records what it saw happen, which is the one accuracy
+ * source architecture §11B.3 calls *"the core technical moat"* and the one a
+ * purely static tool is structurally unable to reach: *"a purely static
+ * code-graph tool is capped at R3 permanently. It has no runtime."*
+ *
+ * ## What this composes, and what it invents
+ *
+ * It invents no mechanism. Every stage already existed, gate-verified, in
+ * `descry-runtime`, and every one of them was dormant — the whole point of
+ * `DEC-NEXT-mcp-runtime-dependency-boundary-for-r4-evidence`, which measured
+ * that `applyRuntimeObservations` had **zero production callers anywhere**,
+ * not in `descry-desktop` and not in `descry-runtime`'s own pipeline. Four
+ * shipped components in a row, and this tool is the wire between them:
+ *
+ * 1. `runInstrumentedExecution` (`@descryy/runtime-orchestrator`) spawns or
+ *    attaches the declared services, starts the adapter's collectors, drains
+ *    them for a stated window, and writes every item through `EvidenceStore`.
+ * 2. `correlateExecution` (`@descryy/runtime-evidence-correlation`) resolves
+ *    each evidence item to the graph node it is *about* — the resolve-then-
+ *    attribute pass. This answers identity, not edges.
+ * 3. `confirmObservedFrontendCaller` (`@descryy/runtime-graph-correlator`)
+ *    turns a captured call-site stack plus a resolved endpoint into a
+ *    `RuntimeEdgeObservation`, and
+ * 4. calls `applyRuntimeObservations` (`@descryy/core`) with it, which
+ *    promotes, mints or contradicts the edge and writes the EARNED ledger.
+ *
+ * ## Why stage 3 exists rather than deriving edges from stage 2 directly
+ *
+ * `uat-phase-1-bug-fixes.md` Phase 2 describes step 2 as producing
+ * `RuntimeEdgeObservation[]`. It does not, and the difference is load-bearing
+ * rather than pedantic: `correlateExecution` returns
+ * `CorrelationAttribution`s — *(evidenceId, graphNodeId)* pairs saying which
+ * single node an observation is about. An edge needs **two** endpoints and a
+ * witnessed relationship between them, and manufacturing one by pairing up
+ * attributions that happen to co-occur in the same run would mint edges from
+ * temporal coincidence. That is precisely the wrong-direction failure rule 2
+ * exists to prevent, arriving through the one mechanism built to make the
+ * graph *more* trustworthy.
+ *
+ * So the observation comes from the one shipped producer that can honestly
+ * make one: a captured stack naming the caller, against an endpoint the same
+ * observation named. Both endpoints come from the observation itself. Every
+ * other correlated item is reported in the counts and produces no edge, which
+ * is a disclosed gap rather than a silent one.
+ *
+ * ## What this closure can actually witness today — measured, not assumed
+ *
+ * The wire is complete and the arrow it carries is narrow, and the second half
+ * of that sentence is worth stating plainly because a reader would otherwise
+ * infer it from a zero. HTTP evidence carrying a call-site stack is emitted by
+ * exactly one collector in `descry-runtime`: the browser network collector,
+ * via its `fetch()` initiator capture. Checked across every collector in this
+ * server's dependency closure — `InboundProxy` emits `{method, path, status}`
+ * and no stack; `ExternalRequestCollector` sets `stackTrace: null` outright,
+ * because it parses a log line the application printed and a printed line
+ * carries no stack; `LogCollector` (the only thing the TypeScript runtime
+ * adapter builds) attaches a stack to log and error lines, which resolve a
+ * FUNCTION and name no endpoint.
+ *
+ * So a backend-only run resolves both kinds of node and writes no edge. The
+ * composition is right, the gate is real, and the arrow is currently reachable
+ * only from a browser-driven run — which `runInstrumentedExecution`'s own
+ * contract explicitly does not do ("does not drive a browser"), and which is
+ * therefore a different orchestration rather than a missing argument here.
+ * `STANDING_NOTES` says this on every call, whatever the counts come back as,
+ * because "no edge was written" and "nothing here could have written one" are
+ * different statements and only the second one is a fact about Descry.
+ *
+ * ## Why no denial is ever emitted
+ *
+ * `applyRuntimeObservations` accepts `held: false`. Nothing here ever sends
+ * one, and `confirmObservedFrontendCaller`'s own header explains why: a run
+ * establishes that a call *happened*; it cannot establish that one did not,
+ * because a run exercises the paths it happens to take. Demoting a correct
+ * edge on the strength of a route this run did not visit would be worse than
+ * never running.
+ *
+ * ## Class and tier
+ *
+ * `action` — DEC-278's own test is *"can this call's effect change a later
+ * finding without the developer having said so"*, and this one spawns
+ * processes and writes R4 edges that cap every later reliability class
+ * differently. It is gated by the same two-call `confirmToken` handshake
+ * `questions` uses, and additionally by the environment profile's declared
+ * `safetyLevel` (DEC-270): booting a service is a **write** against the
+ * target, so a `readOnly` profile refuses. An all-attach run is genuinely
+ * read-only — `ServiceConfiguration.attach`'s own contract is that Descry
+ * never executes code in, or applies limits to, a process it did not spawn —
+ * so it is allowed under `readOnly`, and that distinction is stated in the
+ * disclosures rather than inferred silently.
+ *
+ * `evidence` — it reports what was witnessed and what was written. It draws no
+ * conclusion about the user's code; nothing here reads or writes a finding, a
+ * hypothesis or a category (RT-027).
+ *
+ * ## No new query tools
+ *
+ * None are needed and none are added. `impact`, `propagation` and the rest
+ * already read the `resolution` field, so an edge this tool promotes to R4
+ * becomes visible through every one of them on the next call, with no change
+ * to any of them.
+ */
+import { mkdir } from "node:fs/promises";
+import { dirname, isAbsolute, join } from "node:path";
+import { buildGraph, counts, createConfirmedIncidentSource, persistGraph, } from "@descryy/core";
+import { evaluateAction, validateProfile } from "@descryy/runtime-environment-profile";
+import { correlateExecution } from "@descryy/runtime-evidence-correlation";
+import { EvidenceStore } from "@descryy/runtime-evidence-store";
+import { confirmObservedFrontendCaller } from "@descryy/runtime-graph-correlator";
+import { runInstrumentedExecution } from "@descryy/runtime-orchestrator";
+import { answer, optionalInteger, optionalString, ToolInputError, } from "./kit.js";
+import { loadRuntimeAdapter, RuntimeAdapterLoadError } from "../runtime-registry.js";
+import { writeConfirmedIncident } from "../session.js";
+import { runtimeObservedIncident } from "./runtime-incident.js";
+/** Where evidence lands when the call does not say. Beside the graph, not inside it. */
+export const DEFAULT_EVIDENCE_RELATIVE_PATH = join(".descry", "evidence.db");
+/** How long collectors are drained after the services report ready, when unstated. */
+const DEFAULT_OBSERVE_MS = 5_000;
+const DEFAULT_TIMEOUT_MS = 60_000;
+const DEFAULT_READINESS_TIMEOUT_MS = 30_000;
+const READINESS_KINDS = ["http", "tcp-port", "command"];
+const SCHEMA = {
+    type: "object",
+    properties: {
+        profile: {
+            type: "object",
+            description: "The environment this run targets. Every field is declared by you and never inferred from " +
+                "any other (DEC-270): a profile named \"staging\" with safetyLevel \"readOnly\" is read-only, " +
+                "and a profile named \"local\" with safetyLevel \"readOnly\" is too.",
+            properties: {
+                name: { type: "string", description: "Free-form. Matched against no vocabulary anywhere." },
+                url: { type: "string", description: "The target's base URL. Must parse." },
+                safetyLevel: {
+                    type: "string",
+                    enum: ["readOnly", "write", "destructiveWithApproval"],
+                    description: "Booting a service is a write against the target, so \"readOnly\" refuses a run that " +
+                        "spawns anything. A run in which every service uses \"attach\" spawns nothing and is " +
+                        "permitted under \"readOnly\".",
+                },
+                credentialRef: {
+                    type: "string",
+                    description: "An opaque key into a credential store — never the secret itself.",
+                },
+                mode: { type: "string", enum: ["localBooted", "localAttached", "remote", "production"] },
+            },
+            required: ["name", "url", "safetyLevel", "credentialRef", "mode"],
+            additionalProperties: false,
+        },
+        services: {
+            type: "object",
+            description: "One entry per service, keyed by the name evidence will be attributed to. At least one is " +
+                "required. Exactly one of \"command\" or \"attach\" per service.",
+            additionalProperties: {
+                type: "object",
+                properties: {
+                    command: { type: "string", description: "How to start it. Omit when using \"attach\"." },
+                    cwd: {
+                        type: "string",
+                        description: "Working directory. Relative paths resolve against the repository root.",
+                    },
+                    port: {
+                        type: "integer",
+                        description: "Explicit opt-in only. Omit to get an ephemeral port. An attached service should set " +
+                            "this when you already know what the running target bound — nothing here can allocate " +
+                            "one on its behalf.",
+                    },
+                    dependsOn: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Service names that must be ready first. Declared, never inferred.",
+                    },
+                    env: { type: "object", additionalProperties: { type: "string" } },
+                    attach: {
+                        type: "object",
+                        description: "Observe a process that is already running instead of spawning one. Descry never " +
+                            "executes code in, signals, or applies resource limits to a process it did not spawn.",
+                        properties: {
+                            pid: { type: "integer" },
+                            logFilePath: {
+                                type: "string",
+                                description: "A file the target already writes its stdout/stderr to.",
+                            },
+                        },
+                        required: ["pid", "logFilePath"],
+                        additionalProperties: false,
+                    },
+                    readiness: {
+                        type: "object",
+                        description: "Required per service — a run refuses rather than treat \"the process started\" as " +
+                            "\"the service is up\". Only the three mechanisms expressible as JSON are offered here; " +
+                            "\"log-pattern\" and \"custom-hook\" need a function and are not reachable through this " +
+                            "tool, which is disclosed on every call rather than left to be discovered.",
+                        properties: {
+                            kind: { type: "string", enum: [...READINESS_KINDS] },
+                            path: {
+                                type: "string",
+                                description: "kind \"http\": path appended to http://127.0.0.1:<resolved port>. Defaults to \"/\".",
+                            },
+                            expectedStatus: { type: "integer", description: "kind \"http\": defaults to any 2xx/3xx." },
+                            host: { type: "string", description: "kind \"tcp-port\": defaults to 127.0.0.1." },
+                            command: { type: "string", description: "kind \"command\": the executable to run." },
+                            args: { type: "array", items: { type: "string" }, description: "kind \"command\"." },
+                            timeoutMs: { type: "integer", description: `Defaults to ${DEFAULT_READINESS_TIMEOUT_MS}.` },
+                        },
+                        required: ["kind"],
+                        additionalProperties: false,
+                    },
+                },
+                required: ["cwd", "readiness"],
+                additionalProperties: false,
+            },
+        },
+        adapter: {
+            type: "object",
+            description: "The runtime adapter to observe with, named as a module specifier and imported at run time. " +
+                "This server depends on none of descry-runtime's per-language runtime adapters by design, and " +
+                "names none of them anywhere — including here, which is why this description carries no " +
+                "example specifier. Install the one matching the service's runtime alongside this server and " +
+                "name its package here; descry-runtime publishes one runtime adapter package per supported " +
+                "runtime, and its README lists them.",
+            properties: {
+                module: { type: "string" },
+                export: {
+                    type: "string",
+                    description: "Defaults to the single export matching create*RuntimeAdapter. Two matches is an error, " +
+                        "not a coin toss — name one here.",
+                },
+                options: { type: "object", description: "Passed to the factory. Adapter-specific and opaque here." },
+            },
+            required: ["module"],
+            additionalProperties: false,
+        },
+        scopeByService: {
+            type: "object",
+            description: "Service name → which repository its symbols resolve in. A service with no entry has its " +
+                "symbol evidence left alone and its name reported, never resolved against a repository " +
+                "nobody named. Defaults to this session's own repo for every declared service.",
+            additionalProperties: {
+                type: "object",
+                properties: {
+                    repo: { type: "string" },
+                    repoRoot: { type: "string", description: "Absolute on-disk root, so observed absolute paths translate exactly." },
+                    cwd: { type: "string" },
+                },
+                required: ["repo"],
+                additionalProperties: false,
+            },
+        },
+        observeForMs: {
+            type: "integer",
+            description: `How long to drain collector output after the services are up. Defaults to ${DEFAULT_OBSERVE_MS}. ` +
+                "There is no \"the application is done\" signal at this layer — a server runs until stopped — " +
+                "so you state the observation window rather than this tool guessing at one.",
+        },
+        timeoutMs: { type: "integer", description: `Whole-execution budget. Defaults to ${DEFAULT_TIMEOUT_MS}.` },
+        environmentTier: {
+            type: "string",
+            enum: ["tier-0-ci-attached", "tier-1-preview", "tier-2-container", "tier-2b-api-only", "tier-3-static-only"],
+            description: "Recorded on the execution. Defaults to \"tier-2-container\" and is deliberately not derived " +
+                "from \"profile.mode\" — DEC-270's rule is that a declared field is declared, not inferred " +
+                "from a neighbouring one.",
+        },
+        fidelityLevel: {
+            type: "integer",
+            enum: [1, 2, 3, 4],
+            description: "1 rule-aware stub · 2 real code + disposable DB · 3 real code + redacted recordings · " +
+                "4 real staging. Defaults to 2. Not derived from anything else, same reason as environmentTier.",
+        },
+        evidencePath: {
+            type: "string",
+            description: `Where the evidence database lives. Defaults to ${DEFAULT_EVIDENCE_RELATIVE_PATH} under the repository root.`,
+        },
+        confirmToken: {
+            type: "string",
+            description: "The token returned by an unconfirmed call. This tool performs nothing without it: the first " +
+                "call describes what running would do and returns a token, and only a second call presenting " +
+                "that exact token runs anything — with the arguments frozen when the token was minted, never " +
+                "whatever the second call supplies.",
+        },
+    },
+    required: ["profile", "services", "adapter"],
+    additionalProperties: false,
+};
+// ---------------------------------------------------------------------------
+// Argument reading. Hand-written, same reasoning as `kit.ts`'s own readers.
+// ---------------------------------------------------------------------------
+function asRecord(value, what) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new ToolInputError(`"${what}" must be an object`);
+    }
+    return value;
+}
+function readProfile(args) {
+    const raw = asRecord(args["profile"], "profile");
+    const field = (key) => {
+        const value = raw[key];
+        if (typeof value !== "string")
+            throw new ToolInputError(`"profile.${key}" must be a string`);
+        return value;
+    };
+    const candidate = {
+        name: field("name"),
+        url: field("url"),
+        safetyLevel: field("safetyLevel"),
+        credentialRef: field("credentialRef"),
+        mode: field("mode"),
+    };
+    const errors = validateProfile(candidate);
+    if (errors.length > 0) {
+        // The profile package's own error codes, verbatim — this tool adds no
+        // interpretation to a validation it did not perform.
+        throw new ToolInputError(`"profile" is not valid: ${errors.join(", ")}`);
+    }
+    return candidate;
+}
+function readAdapterSpec(args) {
+    const raw = asRecord(args["adapter"], "adapter");
+    const module = raw["module"];
+    if (typeof module !== "string" || module === "") {
+        throw new ToolInputError('"adapter.module" is required and must be a non-empty string');
+    }
+    const exportName = raw["export"];
+    if (exportName !== undefined && typeof exportName !== "string") {
+        throw new ToolInputError('"adapter.export" must be a string');
+    }
+    const options = raw["options"];
+    if (options !== undefined && (typeof options !== "object" || options === null)) {
+        throw new ToolInputError('"adapter.options" must be an object');
+    }
+    return {
+        module,
+        ...(typeof exportName === "string" ? { export: exportName } : {}),
+        ...(options === undefined ? {} : { options: options }),
+    };
+}
+function readServices(args, repoPath) {
+    const raw = asRecord(args["services"], "services");
+    const names = Object.keys(raw);
+    if (names.length === 0)
+        throw new ToolInputError('"services" must declare at least one service');
+    return names.map((name) => {
+        const entry = asRecord(raw[name], `services.${name}`);
+        const command = entry["command"];
+        const attachRaw = entry["attach"];
+        if ((command === undefined) === (attachRaw === undefined)) {
+            throw new ToolInputError(`services.${name} must declare exactly one of "command" or "attach" — ` +
+                (command === undefined ? "it declares neither" : "it declares both"));
+        }
+        if (command !== undefined && typeof command !== "string") {
+            throw new ToolInputError(`"services.${name}.command" must be a string`);
+        }
+        const cwd = entry["cwd"];
+        if (typeof cwd !== "string" || cwd === "") {
+            throw new ToolInputError(`"services.${name}.cwd" is required and must be a non-empty string`);
+        }
+        const port = entry["port"];
+        if (port !== undefined && (typeof port !== "number" || !Number.isInteger(port) || port < 0)) {
+            throw new ToolInputError(`"services.${name}.port" must be a non-negative integer`);
+        }
+        const dependsOn = entry["dependsOn"];
+        if (dependsOn !== undefined &&
+            (!Array.isArray(dependsOn) || dependsOn.some((d) => typeof d !== "string"))) {
+            throw new ToolInputError(`"services.${name}.dependsOn" must be an array of strings`);
+        }
+        const env = entry["env"];
+        if (env !== undefined) {
+            const record = asRecord(env, `services.${name}.env`);
+            for (const [key, value] of Object.entries(record)) {
+                if (typeof value !== "string") {
+                    throw new ToolInputError(`"services.${name}.env.${key}" must be a string`);
+                }
+            }
+        }
+        let attach;
+        if (attachRaw !== undefined) {
+            const a = asRecord(attachRaw, `services.${name}.attach`);
+            const pid = a["pid"];
+            const logFilePath = a["logFilePath"];
+            if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0) {
+                throw new ToolInputError(`"services.${name}.attach.pid" must be a positive integer`);
+            }
+            if (typeof logFilePath !== "string" || logFilePath === "") {
+                throw new ToolInputError(`"services.${name}.attach.logFilePath" is required`);
+            }
+            attach = { pid, logFilePath };
+        }
+        const configuration = {
+            ...(typeof command === "string" ? { command } : {}),
+            cwd: isAbsolute(cwd) ? cwd : join(repoPath, cwd),
+            ...(port === undefined ? {} : { port: port }),
+            ...(dependsOn === undefined ? {} : { dependsOn: dependsOn }),
+            ...(env === undefined ? {} : { env: env }),
+            ...(attach === undefined ? {} : { attach }),
+        };
+        return {
+            name,
+            configuration,
+            readiness: readReadiness(entry["readiness"], name, configuration.cwd),
+            attached: attach !== undefined,
+        };
+    });
+}
+/**
+ * The JSON→`ReadinessCheck` mapping, and the two mechanisms it cannot express.
+ *
+ * `log-pattern` needs a `read()` closing over the `ManagedProcess` the
+ * controller owns, and `custom-hook` is a function outright. Neither survives a
+ * JSON boundary, and inventing a string-shaped stand-in for either would offer
+ * a mechanism that silently is not the one named. They are absent from the
+ * schema's enum and stated in the disclosures instead — rule 7, honest
+ * degradation, applied to a capability rather than to a result.
+ */
+function readReadiness(raw, service, cwd) {
+    const entry = asRecord(raw, `services.${service}.readiness`);
+    const kind = entry["kind"];
+    if (typeof kind !== "string" || !READINESS_KINDS.includes(kind)) {
+        throw new ToolInputError(`"services.${service}.readiness.kind" must be one of: ${READINESS_KINDS.join(", ")}`);
+    }
+    const timeoutMs = entry["timeoutMs"];
+    if (timeoutMs !== undefined &&
+        (typeof timeoutMs !== "number" || !Number.isInteger(timeoutMs) || timeoutMs < 1)) {
+        throw new ToolInputError(`"services.${service}.readiness.timeoutMs" must be a positive integer`);
+    }
+    // Every field is validated **here**, not inside `checks`. The controller does
+    // not call `checks()` until the service has already spawned, so a bad
+    // argument validated lazily would surface as a failed run with a live process
+    // to clean up rather than as a rejected call that started nothing — and
+    // `ToolInputError`'s whole contract is that it is something the caller can
+    // fix before anything happens.
+    const path = typeof entry["path"] === "string" ? entry["path"] : "/";
+    const expectedStatus = entry["expectedStatus"];
+    if (expectedStatus !== undefined && typeof expectedStatus !== "number") {
+        throw new ToolInputError(`"services.${service}.readiness.expectedStatus" must be a number`);
+    }
+    const host = typeof entry["host"] === "string" ? entry["host"] : "127.0.0.1";
+    const command = entry["command"];
+    const commandArgs = entry["args"];
+    if (kind === "command") {
+        if (typeof command !== "string" || command === "") {
+            throw new ToolInputError(`"services.${service}.readiness.command" is required for kind "command"`);
+        }
+        if (commandArgs !== undefined &&
+            (!Array.isArray(commandArgs) || commandArgs.some((a) => typeof a !== "string"))) {
+            throw new ToolInputError(`"services.${service}.readiness.args" must be an array of strings`);
+        }
+    }
+    const checks = (info) => {
+        if (kind === "http") {
+            return [
+                {
+                    kind: "http",
+                    url: `http://127.0.0.1:${String(info.port)}${path.startsWith("/") ? path : `/${path}`}`,
+                    ...(typeof expectedStatus === "number" ? { expectedStatus } : {}),
+                },
+            ];
+        }
+        if (kind === "tcp-port") {
+            return [{ kind: "tcp-port", host, port: info.port }];
+        }
+        return [
+            {
+                kind: "command",
+                command: command,
+                ...(commandArgs === undefined ? {} : { args: commandArgs }),
+                cwd,
+            },
+        ];
+    };
+    return {
+        checks,
+        timeoutMs: typeof timeoutMs === "number" ? timeoutMs : DEFAULT_READINESS_TIMEOUT_MS,
+    };
+}
+function readScopes(args, declared, fallback) {
+    const scopes = {};
+    for (const service of declared)
+        scopes[service.name] = fallback;
+    const raw = args["scopeByService"];
+    if (raw === undefined)
+        return scopes;
+    for (const [name, value] of Object.entries(asRecord(raw, "scopeByService"))) {
+        const entry = asRecord(value, `scopeByService.${name}`);
+        const repo = entry["repo"];
+        if (typeof repo !== "string" || repo === "") {
+            throw new ToolInputError(`"scopeByService.${name}.repo" is required and must be a non-empty string`);
+        }
+        const repoRoot = entry["repoRoot"];
+        const cwd = entry["cwd"];
+        if (repoRoot !== undefined && typeof repoRoot !== "string") {
+            throw new ToolInputError(`"scopeByService.${name}.repoRoot" must be a string`);
+        }
+        if (cwd !== undefined && typeof cwd !== "string") {
+            throw new ToolInputError(`"scopeByService.${name}.cwd" must be a string`);
+        }
+        scopes[name] = {
+            repo,
+            ...(repoRoot === undefined ? {} : { repoRoot }),
+            ...(cwd === undefined ? {} : { cwd }),
+        };
+    }
+    return scopes;
+}
+// ---------------------------------------------------------------------------
+// The run
+// ---------------------------------------------------------------------------
+const EMPTY_WRITE = {
+    promoted: [],
+    created: [],
+    confirmed: [],
+    refused: [],
+    contradictions: [],
+    staleR4: [],
+};
+/**
+ * The disclosure every call carries, whatever it did.
+ *
+ * Stated unconditionally rather than only when it bites: a caller who does not
+ * know that `log-pattern` readiness is unreachable here will write a
+ * `tcp-port` check that passes the instant the socket binds and read the
+ * resulting empty evidence as "the service produced nothing".
+ */
+const STANDING_NOTES = [
+    "Readiness here offers only the three mechanisms JSON can state — http, tcp-port and command. " +
+        "log-pattern and custom-hook need a function and are unreachable through this tool; a run that " +
+        "needs one of those is not degraded here, it is unsupported here.",
+    "Edges are written only where an observation named both endpoints itself: a captured call-site " +
+        "stack resolving to a function, against an endpoint the same observation named. Every other " +
+        "correlated evidence item resolves a node and produces no edge, which is a gap in what this run " +
+        "could prove rather than evidence that no such edge exists.",
+    "That combination — HTTP evidence carrying a call-site stack — is produced today only by a browser " +
+        "network collector, which is not in this server's dependency closure. Backend collectors attach a " +
+        "stack to log and error lines (resolving a function) and attach none to HTTP traffic (resolving an " +
+        "endpoint), so a backend-only run resolves both kinds of node and writes no edge. That is a real " +
+        "limit of what can be witnessed here, not a failure of this run, and it is stated on every call " +
+        "rather than inferred from a zero.",
+    "No denial is ever recorded. A run establishes that a call happened; it cannot establish that one " +
+        "did not, because it exercises only the paths it took. Nothing here demotes an edge.",
+];
+async function run(args, ctx) {
+    const session = ctx.session;
+    const profile = readProfile(args);
+    const adapterSpec = readAdapterSpec(args);
+    const declared = readServices(args, session.repoPath);
+    const observeForMs = optionalInteger(args, "observeForMs", 1) ?? DEFAULT_OBSERVE_MS;
+    const timeoutMs = optionalInteger(args, "timeoutMs", 1) ?? DEFAULT_TIMEOUT_MS;
+    const fidelityRaw = optionalInteger(args, "fidelityLevel", 1) ?? 2;
+    if (fidelityRaw > 4)
+        throw new ToolInputError('"fidelityLevel" must be 1, 2, 3 or 4');
+    const environmentTier = optionalString(args, "environmentTier") ?? "tier-2-container";
+    const evidenceArg = optionalString(args, "evidencePath");
+    const evidencePath = evidenceArg === undefined
+        ? join(session.repoPath, DEFAULT_EVIDENCE_RELATIVE_PATH)
+        : isAbsolute(evidenceArg)
+            ? evidenceArg
+            : join(session.repoPath, evidenceArg);
+    const notes = [...STANDING_NOTES];
+    const base = session.provider().baseStamp();
+    const refuse = (headline, data = {}) => answer({
+        headline,
+        state: "refused",
+        nameLevel: true,
+        // Nothing ran, so nothing was resolved. A refusal reporting the tier its
+        // successful path would have reached is the leaked-default this repo's
+        // own UAT already caught once elsewhere.
+        resolutionFloor: 0,
+        commitSha: base.commitSha,
+        graphBuiltAt: base.graphBuiltAt,
+        irSchemaVersion: base.irSchemaVersion,
+        commitSpread: base.commitSpread,
+        notes,
+        data: {
+            executionId: null,
+            executionState: null,
+            adapterLanguage: null,
+            evidencePath,
+            services: [],
+            evidenceByType: {},
+            correlation: null,
+            wrote: EMPTY_WRITE,
+            ...data,
+        },
+    });
+    // --- the safety gate ------------------------------------------------------
+    // Spawning is a write against the target; attaching is not (Descry never
+    // executes code in, signals, or applies limits to a process it did not
+    // spawn). So the action's shape depends on what was declared, and the
+    // profile's declared level decides — never the profile's name.
+    const spawns = declared.some((service) => !service.attached);
+    const action = { write: spawns, destructive: false };
+    const decision = evaluateAction(profile, action);
+    if (decision !== "allow") {
+        return refuse(`Profile "${profile.name}" declares safetyLevel "${profile.safetyLevel}", which does not permit ` +
+            `${spawns ? "spawning a service" : "this run"}. Nothing was started and nothing was written. ` +
+            (spawns
+                ? "A run in which every service uses \"attach\" spawns nothing and is permitted under readOnly."
+                : ""));
+    }
+    if (!spawns) {
+        notes.push("Every declared service is attached to rather than spawned, so this run started nothing and " +
+            "applied no resource, filesystem or network policy to any process — Descry does not constrain " +
+            "a process it did not spawn.");
+    }
+    // --- the graph must exist -------------------------------------------------
+    // Correlation resolves evidence against this graph. Against an empty one it
+    // resolves nothing, and reporting that as a clean run with no findings would
+    // be the exact "empty means broken" collapse the five states exist to stop.
+    const driver = session.store().driver;
+    const stored = counts(driver);
+    if (stored.nodes === 0) {
+        return refuse("This repository has no graph yet, so there is nothing for a run's evidence to be resolved " +
+            "against. Run analyze first — an observation that cannot name a node cannot become a fact.");
+    }
+    // --- the adapter ----------------------------------------------------------
+    ctx.progress(`Loading runtime adapter ${adapterSpec.module}`);
+    let adapter;
+    try {
+        adapter = await loadRuntimeAdapter(adapterSpec);
+    }
+    catch (error) {
+        if (error instanceof RuntimeAdapterLoadError) {
+            notes.push("This server depends on none of descry-runtime's language adapters by design, so the adapter " +
+                "must be installed alongside it and named in the call. Nothing was started.");
+            return refuse(error.message);
+        }
+        throw error;
+    }
+    notes.push(`Observed with the runtime adapter for "${adapter.language}", loaded from ${adapterSpec.module}.`);
+    const root = await session.root();
+    const scopes = readScopes(args, declared, {
+        repo: root.repo,
+        repoRoot: root.absolutePath,
+    });
+    const services = {};
+    const readiness = {};
+    for (const service of declared) {
+        services[service.name] = service.configuration;
+        readiness[service.name] = service.readiness;
+    }
+    const configuration = {
+        environmentTier: environmentTier,
+        fidelityLevel: fidelityRaw,
+        timeoutMs,
+        services,
+    };
+    await mkdir(dirname(evidencePath), { recursive: true });
+    const evidenceStore = new EvidenceStore({ path: evidencePath });
+    try {
+        ctx.progress(`Running ${declared.length} service(s), observing for ${String(observeForMs)}ms`);
+        const execution = await runInstrumentedExecution({
+            execution: {
+                application: root.repo,
+                repository: root.repo,
+                commit: root.commitSha,
+                configuration,
+            },
+            runOptions: { readiness },
+            adapter,
+            store: evidenceStore,
+            observeForMs,
+        });
+        const observed = describeServices(execution.execution.processes, declared);
+        const evidenceByType = tally(execution.evidence);
+        if (execution.validationError !== null) {
+            // The controller refused before spawning anything. That is a fact about
+            // the declaration, not about the application — no evidence, no
+            // correlation, and emphatically not "the service is clean".
+            return refuse(`The execution refused to start: ${execution.validationError}. Nothing was spawned, no ` +
+                "evidence was collected, and no graph edge was written.", {
+                executionState: execution.execution.state,
+                adapterLanguage: adapter.language,
+                services: observed,
+                evidenceByType,
+            });
+        }
+        ctx.progress(`Correlating ${String(execution.evidence.length)} evidence item(s) against the graph`);
+        const pass = correlateExecution({
+            store: evidenceStore,
+            driver,
+            executionId: execution.execution.executionId,
+            scopeByService: scopes,
+        });
+        const correlation = {
+            considered: pass.considered,
+            skipped: pass.skipped,
+            attributed: pass.attributed.length,
+            refused: pass.refusals.length,
+            unscopedServices: pass.unscopedServices,
+            harnessErrors: pass.harnessErrors.map((e) => `${e.detail} (${String(e.occurrences)}×)`),
+        };
+        if (pass.unscopedServices.length > 0) {
+            // Two different sentences, because they call for two different actions
+            // and the first one used to be printed for both. A named service with no
+            // scope is something the caller can fix by supplying one. The `(no
+            // service)` sentinel is not: `correlateExecution` looks a scope up by
+            // `evidence.service`, and no collector in this dependency closure stamps
+            // one — measured by the conformance run, which prints a real V8 stack
+            // resolving to a real graph node and watches it go unasked. Telling a
+            // caller to name a scope they have no key for would send them after a
+            // fix that does not exist, which is the honest-degradation rule failing
+            // in the one place it acts.
+            const named = pass.unscopedServices.filter((s) => s !== "(no service)");
+            const anonymous = pass.unscopedServices.length - named.length;
+            if (named.length > 0) {
+                notes.push(`Symbol evidence from ${named.join(", ")} was left unresolved: no scope named which ` +
+                    "repository those symbols belong to, and resolving them against a repository nobody " +
+                    "named would resolve the wrong one's identically-named file. Supply " +
+                    '"scopeByService" for those services to have them resolved.');
+            }
+            if (anonymous > 0) {
+                notes.push("Some evidence carried a source location but no service name, so no scope could be " +
+                    "looked up for it and its symbols were never resolved. This is not a missing argument: " +
+                    "nothing in this server's runtime closure stamps a service name onto collector " +
+                    "evidence, so there is no key a caller could supply a scope under. The items are " +
+                    "counted as skipped rather than dropped, and what they would have resolved to is " +
+                    "unknown rather than absent.");
+            }
+        }
+        if (pass.harnessErrors.length > 0) {
+            notes.push(`${String(pass.harnessErrors.length)} correlation failure(s) were the machinery breaking rather ` +
+                "than a resolver honestly declining — each is written into the evidence stream as a " +
+                "COLLECTOR_ERROR, and the counts below are correspondingly incomplete.");
+        }
+        // A service that died is a witnessed failure, and this run is the only
+        // thing that will ever have seen it. Recorded before the edge write so a
+        // failure in one does not silently cost the other.
+        // See `runtime-incident.ts` for why an EXCEPTION alone is not an incident.
+        const incident = runtimeObservedIncident({
+            repo: root.repo,
+            repoRoot: root.absolutePath,
+            runId: execution.execution.executionId,
+            services: observed,
+            exceptionLocations: execution.evidence
+                .filter((e) => e.eventType === "EXCEPTION")
+                .map((e) => ({ file: e.sourceLocation?.file ?? null })),
+            exceptionTexts: execution.evidence
+                .filter((e) => e.eventType === "EXCEPTION")
+                .map((e) => (typeof e.payload === "string" ? e.payload : JSON.stringify(e.payload)))
+                .map((text) => text.split("\n")[0] ?? "")
+                .filter((line) => line !== ""),
+        });
+        if (incident !== null) {
+            ctx.progress("Recording the observed failure as an incident");
+            await writeConfirmedIncident(session.repoPath, incident);
+            const projected = await createConfirmedIncidentSource({
+                repo: root.repo,
+                incidents: [...(session.config.confirmedIncidents ?? []), incident],
+            }).emit({ root });
+            persistGraph(driver, [projected], buildGraph([projected], {
+                nodeExists: (id) => session.provider().node(id) !== undefined,
+            }));
+            notes.push(`A service died during this run (${incident.summary}), so it was recorded as an incident ` +
+                `correlated to ${String(incident.files.length)} file(s) this repository owns, and written ` +
+                "durably to .descry/config.json — a run is gone once the process exits. The correlation " +
+                "is every file an exception stack named during the run, which is not a claim about the " +
+                "cause: nothing here knows which exception killed the process, and choosing the last one " +
+                "would be recency standing in for causality.");
+        }
+        ctx.progress("Writing observed edges into the graph");
+        const wrote = writeObservations({
+            driver,
+            pass,
+            evidenceStore,
+            repo: root.repo,
+            repoRoot: root.absolutePath,
+            runId: execution.execution.executionId,
+            commitSha: root.commitSha,
+        });
+        const written = wrote.promoted.length + wrote.created.length;
+        if (written === 0) {
+            notes.push("No edge was written. Either no observation carried a call-site stack that resolved to a " +
+                "function this graph holds, or every one it did carry was already at R4. Both are real " +
+                "outcomes of this run, and neither says the graph's existing edges are wrong.");
+        }
+        const headline = `Observed ${String(execution.evidence.length)} evidence item(s) across ${String(declared.length)} ` +
+            `service(s); ${String(pass.attributed.length)} resolved to graph nodes; ` +
+            `${String(wrote.promoted.length)} edge(s) promoted to R4 and ${String(wrote.created.length)} minted at R4.`;
+        return answer({
+            headline,
+            // Deliberately not `empty` when nothing was witnessed: `empty` is a claim
+            // about the population, and "this run took no path that exercised the
+            // code" is not "this code does nothing". The counts say what happened.
+            state: "ok",
+            nameLevel: true,
+            // R4 unconditionally, and honestly so — every fact in `wrote` was
+            // witnessed at runtime, which is the one resolution level that does not
+            // rest on inference (DEC-115). The correlated-but-unwritten items are
+            // not claimed here at all; they resolved a node and asserted nothing, so
+            // a run that wrote nothing reports R0 rather than borrowing the tier its
+            // successful path would have reached.
+            resolutionFloor: (written > 0 ? 4 : 0),
+            commitSha: base.commitSha,
+            graphBuiltAt: base.graphBuiltAt,
+            irSchemaVersion: base.irSchemaVersion,
+            commitSpread: base.commitSpread,
+            notes,
+            data: {
+                executionId: execution.execution.executionId,
+                executionState: execution.execution.state,
+                adapterLanguage: adapter.language,
+                evidencePath,
+                services: observed,
+                evidenceByType,
+                correlation,
+                wrote,
+            },
+        });
+    }
+    finally {
+        evidenceStore.close();
+    }
+}
+/**
+ * One row per **declared** service, not one per spawned process — a service
+ * that never started must appear with `started: false` rather than vanish from
+ * the list, which is the difference between "it ran and did nothing" and "it
+ * never ran".
+ */
+function describeServices(processes, declared) {
+    const byService = new Map();
+    for (const handle of processes) {
+        if (handle.serviceName !== null)
+            byService.set(handle.serviceName, handle);
+    }
+    return declared.map((service) => {
+        const handle = byService.get(service.name);
+        return {
+            service: service.name,
+            started: handle !== undefined,
+            attached: service.attached,
+            port: handle?.port ?? null,
+            exitedAt: handle?.exitedAt ?? null,
+            exitCode: handle?.exitCode ?? null,
+            signal: handle?.signal ?? null,
+        };
+    });
+}
+function tally(evidence) {
+    const byType = {};
+    for (const item of evidence)
+        byType[item.eventType] = (byType[item.eventType] ?? 0) + 1;
+    return byType;
+}
+/**
+ * The R4 write, and the one join this tool performs itself.
+ *
+ * For every evidence item the correlation pass resolved to an endpoint, if that
+ * same item also carried a call-site stack, ask `confirmObservedFrontendCaller`
+ * whether the stack names a function — and when it does, it writes. Both
+ * endpoints of the resulting edge come from the one observation; nothing here
+ * pairs two separate items together. See the module header for why that
+ * restraint is the whole design rather than a limitation of it.
+ */
+function writeObservations(input) {
+    const promoted = [];
+    const created = [];
+    const confirmed = [];
+    const refused = [];
+    const contradictions = [];
+    const staleR4 = [];
+    // One evidence item can be attributed twice (an endpoint and a second naming
+    // the same line carries). Keyed on both so the same (evidence, endpoint) pair
+    // is never confirmed twice within one run.
+    const seen = new Set();
+    for (const attribution of input.pass.attributed) {
+        // `endpoint` only, and `log-text-endpoint` deliberately excluded. That
+        // family fires when a backend log LINE mentions a route and carries its
+        // own stack frame — which establishes that the function logged about the
+        // endpoint, not that it called it. The commonest real shape is a handler
+        // logging "GET /invoices -> 500", and that function SERVES the endpoint
+        // rather than USING it, so an edge minted from it could point the wrong
+        // way. Rule 2: a wrong edge corrupts diff scoping, impact scores and
+        // root-cause traversal; a missing one is a disclosed gap. Omitted.
+        if (attribution.family !== "endpoint")
+            continue;
+        const key = `${attribution.evidenceId}::${attribution.graphNodeId}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const evidence = input.evidenceStore.getById(attribution.evidenceId);
+        if (evidence === null || evidence.stackTrace === null)
+            continue;
+        const outcome = confirmObservedFrontendCaller(input.driver, {
+            endpointNodeId: attribution.graphNodeId,
+            stackTrace: evidence.stackTrace,
+            repo: input.repo,
+            runId: input.runId,
+            commitSha: input.commitSha,
+            repoRoot: input.repoRoot,
+        });
+        promoted.push(...outcome.confirmation.promoted);
+        created.push(...outcome.confirmation.created);
+        confirmed.push(...outcome.confirmation.confirmed);
+        refused.push(...outcome.confirmation.refused.map((r) => r.reason));
+        contradictions.push(...outcome.confirmation.contradictions.map((c) => c.detail));
+        staleR4.push(...outcome.confirmation.staleR4.map((s) => s.detail));
+    }
+    return { promoted, created, confirmed, refused, contradictions, staleR4 };
+}
+/**
+ * What confirming this call would do, in the caller's own terms.
+ *
+ * Always returns a sentence — unlike `questions`, whose unconfirmed shape is a
+ * genuine pure read of the question queue, there is no argument to this tool
+ * that makes it not run anything. Every valid call spawns or attaches, and
+ * every one of them can write.
+ */
+function describeAction(args) {
+    const services = args["services"];
+    if (typeof services !== "object" || services === null)
+        return undefined;
+    const names = Object.keys(services);
+    if (names.length === 0)
+        return undefined;
+    const entries = services;
+    const spawned = names.filter((n) => entries[n]?.attach === undefined);
+    const attached = names.filter((n) => entries[n]?.attach !== undefined);
+    const parts = [];
+    if (spawned.length > 0)
+        parts.push(`start ${spawned.length} service(s) (${spawned.join(", ")})`);
+    if (attached.length > 0)
+        parts.push(`attach to ${attached.length} already-running service(s) (${attached.join(", ")})`);
+    return (`${parts.join(" and ")}, observe them, and write any edge the run witnesses into this ` +
+        "repository's graph at R4 — a durable fact that raises every later finding resting on it to " +
+        "reliability class A, and that survives re-indexing. Nothing is ever demoted or deleted.");
+}
+export const observeRuntimeTool = {
+    name: "observe_runtime",
+    class: "action",
+    tier: "evidence",
+    version: "1.0.0",
+    title: "Run the application and record what was observed",
+    description: "Boot or attach to the declared services, watch them with a runtime adapter, resolve what was " +
+        "observed against this repository's graph, and record the edges the run actually witnessed at R4 " +
+        "— the one resolution level static analysis cannot reach. Promoted and newly minted edges become " +
+        "visible through impact, propagation and every other tool immediately, with no second call: they " +
+        "already read the resolution field. Running takes a two-call confirmation — the first call " +
+        "performs nothing and returns a token describing what it would do; call again with " +
+        "\"confirmToken\" to actually run it. The environment profile's declared safetyLevel is checked " +
+        "before anything starts: booting is a write, attaching is not.",
+    inputSchema: SCHEMA,
+    run,
+    describeAction,
+};
+//# sourceMappingURL=observe-runtime.js.map