@descryy/mcp 0.1.2 → 0.3.0

package/dist/tools/observe-runtime.js

@@ -0,0 +1,1192 @@
+/**
+ * `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 what it can carry changed when the runtime packages
+ * were published at 0.1.0 and pinned here — so this paragraph is the record of
+ * a limit that was real and is now lifted, kept rather than deleted because the
+ * shape of it recurs.
+ *
+ * **It used to be that no producer of the required pair — HTTP evidence
+ * carrying a call-site stack — was in this server's closure.** The browser
+ * network collector never has been. The outbound-fetch instrumentation in
+ * `@descryy/runtime-external-service-observation` existed, was proven in
+ * `descry-runtime`, and was not installed here at all. So a run resolved both
+ * kinds of node and wrote no edge, and `STANDING_NOTES` said so on every call
+ * because "no edge was written" and "nothing here could have written one" are
+ * different statements.
+ *
+ * **That second producer is now in the closure**, transitively through
+ * `@descryy/runtime-orchestrator`, which applies the adapter's
+ * `outboundHttpLaunch()` between the interpreter and the script so the client
+ * is patched before any application code can capture an unpatched one. Measured
+ * end to end in `observe-runtime-outbound.conformance.test.ts`: two real
+ * processes, 17 `EXTERNAL_REQUEST` items alongside 18 `BACKEND_LOG`, one
+ * `USES_API` edge minted at R4, and the first `strongly supported` reply this
+ * server has produced.
+ *
+ * **Two limits remain, and they are stated rather than inferred from a zero.**
+ * An *attached* service is not launched by Descry, so the instrumentation
+ * cannot be installed into it and its outbound calls carry no stack. And
+ * browser-side traffic still needs `@descryy/runtime-browser`, which is not
+ * here. Both are in `STANDING_NOTES`.
+ *
+ * The rule that outlives all of it: a disclosure about the closure is a fact
+ * about *this build*, not about what `descry-runtime` can do. The two came
+ * apart once already, when the cross-boundary lane landed and this file still
+ * claimed the capability was absent. Re-check it against the installed tree
+ * when the pins move, not against the source repository.
+ * 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 { independentSignalTypes } from "@descryy/ir";
+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: "The directory this service is started in. Relative paths resolve against the " +
+                            "repository root. REQUIRED with \"command\". With \"attach\" it is required only " +
+                            "for a \"command\" readiness check, which is an executable Descry runs in it; for " +
+                            "an \"http\" or \"tcp-port\" check it is not needed at all, because nothing is " +
+                            "started and Descry never executes code in a process it did not spawn.",
+                    },
+                    // The description below is the fix for the single most expensive
+                    // ergonomic gap this tool has: three failed runs in one real
+                    // investigation, all the same root cause wearing different clothes,
+                    // and the explanation both times living in a source comment.
+                    port: {
+                        type: "integer",
+                        description: "The port readiness checks against, and the two modes need opposite things from you. " +
+                            "With \"attach\": REQUIRED whenever readiness is \"http\" or \"tcp-port\" — the target " +
+                            "chose its port before Descry saw it, and nothing in a pid or a log path reveals which, " +
+                            "so this is refused up front rather than guessed. With \"command\": omit to get an " +
+                            "ephemeral port, which is passed to your command as PORT; set it only if your command " +
+                            "hardcodes a port, and then it must be THAT port — a readiness check against a port " +
+                            "your command did not bind fails while the service is perfectly healthy.",
+                    },
+                    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: ["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`);
+        }
+        // Read once, here, because two separate rules below need it: whether a
+        // `cwd` is required at all, and whether an attached service must state its
+        // port.
+        const readinessRaw = entry["readiness"];
+        const readinessKind = typeof readinessRaw === "object" && readinessRaw !== null && !Array.isArray(readinessRaw)
+            ? readinessRaw["kind"]
+            : undefined;
+        // `cwd` is required exactly where something will be executed in it, and
+        // nowhere else. Descry spawns nothing for an attached service and never
+        // executes code in a process it did not spawn, so for an attached service
+        // with an `http` or `tcp-port` check the value is inert — demanding it
+        // makes the caller invent a path that changes nothing. A `command` check
+        // *is* executed, in this directory, so it still needs one.
+        //
+        // The runtime contract's `ServiceConfiguration.cwd` is non-optional, so
+        // something must be supplied downstream either way; the repository root is
+        // the inert choice, and it is inert precisely because nothing runs there
+        // on this path.
+        // (`DEC-388`.)
+        const cwdRaw = entry["cwd"];
+        if (cwdRaw !== undefined && (typeof cwdRaw !== "string" || cwdRaw === "")) {
+            throw new ToolInputError(`"services.${name}.cwd" must be a non-empty string`);
+        }
+        if (cwdRaw === undefined && attachRaw === undefined) {
+            throw new ToolInputError(`"services.${name}.cwd" is required and must be a non-empty string: it is the directory ` +
+                `"${name}" is started in.`);
+        }
+        if (cwdRaw === undefined && attachRaw !== undefined && readinessKind === "command") {
+            throw new ToolInputError(`"services.${name}.cwd" is required when "${name}" uses "attach" with a "command" ` +
+                "readiness check: the check is an executable Descry runs, and it runs in this " +
+                "directory. Attaching needs no cwd otherwise — nothing is started.");
+        }
+        const cwd = cwdRaw ?? repoPath;
+        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 };
+            // A spawned service gets an ephemeral port allocated for it; an attached
+            // one cannot, because the target chose its own port before Descry
+            // existed and nothing in a pid or a log path reveals which. The
+            // controller's refusal to guess is deliberate and right — but expressed
+            // as `port ?? 0`, it surfaces to a caller as a readiness check timing
+            // out against port 0 some seconds later, with the actual explanation
+            // living in a source comment they cannot see. Twice in one real
+            // investigation that cost a full failed run to rediscover. So it is
+            // refused here, by name, before anything starts.
+            //
+            // Only for the two checks that resolve a port. A "command" check runs an
+            // executable and never asks where the service listens, so demanding a
+            // port for it would be a second wrong answer in the other direction.
+            if ((readinessKind === "http" || readinessKind === "tcp-port") && port === undefined) {
+                throw new ToolInputError(`"services.${name}.port" is required when "${name}" uses "attach" with a ` +
+                    `"${readinessKind}" readiness check: the check needs a port and an attached target's ` +
+                    "port cannot be allocated or inferred — it is whatever the already-running process " +
+                    "bound. State it, or use a \"command\" readiness check, which needs none.");
+            }
+        }
+        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 here by the outbound-fetch " +
+        "instrumentation in @descryy/runtime-external-service-observation, which this server installs into a " +
+        "spawned service before any application code runs. So an observed outbound call CAN write this edge, " +
+        "and a run that makes none writes none: the backend collectors attach a stack to log and error lines " +
+        "(resolving a function) and none to inbound HTTP traffic (resolving an endpoint), so a service that " +
+        "never calls out resolves both kinds of node and still writes nothing. A zero here means this run " +
+        "observed no outbound call it could attribute, not that no such call exists in your code.",
+    "Two things this still cannot witness. An ATTACHED service is not launched by Descry, so the client " +
+        "instrumentation cannot be installed into it and its outbound calls carry no call-site stack. And " +
+        "browser-side requests need @descryy/runtime-browser, which is not in this server's closure — the " +
+        "browser_* tools refuse with a named remedy rather than appearing to work.",
+    "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.",
+];
+/**
+ * Said on every run that attaches, because it explains an absence that
+ * otherwise reads as a Descry defect — and did, in a real investigation, until
+ * it was measured.
+ *
+ * A request fired partway through an observation window did not appear in the
+ * evidence, and appeared in the log file afterwards. The obvious reading is
+ * that observation stopped early. It did not: reproduced end to end against a
+ * real attached service, a request fired at t≈5s of a 12s window landed in the
+ * evidence store, timestamped correctly. What actually happens is one layer
+ * out — a process whose stdout is redirected to a file is block-buffered, not
+ * line-buffered, because the descriptor is not a terminal. Measured directly:
+ * three lines written over 0.6s were still entirely absent from the file three
+ * seconds later, and arrived only when the process flushed.
+ *
+ * Nothing in Descry can see those bytes; they are in the target's own
+ * userspace buffer. So this is not a gap to close, it is a boundary to state —
+ * and stating it is what separates "we did not see it" from "it was not
+ * there", which is the whole difference this tool exists to preserve.
+ *
+ * Written for any redirected process, naming no language or framework: the
+ * behaviour is the C standard library's, and a note scoped to one ecosystem
+ * would invite one more such note per ecosystem.
+ */
+const ATTACH_BUFFERING_NOTE = "Attaching reads a file the target writes; it can only see what the target has already flushed " +
+    "there. A process whose output is redirected to a file is usually block-buffered rather than " +
+    "line-buffered — its own runtime holds whole lines in a userspace buffer, invisible from outside, " +
+    "until the buffer fills or the process flushes. Output produced during this window may therefore " +
+    "arrive in the file after the window closed and be absent here, which is a fact about the " +
+    "target's buffering and not evidence that it did nothing. Run the target with its output " +
+    "unbuffered or line-buffered if the timing matters.";
+/**
+ * Every argument this tool takes, read and validated in one place.
+ *
+ * Extracted from `run` so that `describeAction` can call it too. That is the
+ * whole point of the extraction: an `action` tool's first call is the one a
+ * caller makes *before* it has a token, and therefore the only cheap place to
+ * learn its arguments are wrong. Minting a token, and a paragraph describing
+ * an action, for a declaration that cannot possibly run asks a developer to
+ * confirm something that was never going to happen — and delivers the real
+ * refusal on the second call, after the confirmation.
+ *
+ * Nothing here touches the filesystem, spawns anything or reads the graph: it
+ * is argument reading and nothing else, which is what makes it safe to run at
+ * mint time, outside the call budget.
+ *
+ * Ruled in `documents/decisions-inbox/DEC-387.md`.
+ *
+ * Exported for its own test: several of the argument rules are conditional and
+ * cheaper to assert directly than through a full run.
+ */
+export function readArguments(args, repoPath) {
+    const profile = readProfile(args);
+    const adapterSpec = readAdapterSpec(args);
+    const declared = readServices(args, 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(repoPath, DEFAULT_EVIDENCE_RELATIVE_PATH)
+        : isAbsolute(evidenceArg)
+            ? evidenceArg
+            : join(repoPath, evidenceArg);
+    return { profile, adapterSpec, declared, observeForMs, timeoutMs, fidelityRaw, environmentTier, evidencePath };
+}
+async function run(args, ctx) {
+    const session = ctx.session;
+    const { profile, adapterSpec, declared, observeForMs, timeoutMs, fidelityRaw, environmentTier, evidencePath } = readArguments(args, session.repoPath);
+    const notes = [...STANDING_NOTES];
+    // Added on the refusal paths too, deliberately. A caller who attaches and is
+    // then refused for some unrelated reason will fix that reason and attach
+    // again; telling them about the buffering only on the success path means
+    // telling them after the run whose result it would have explained.
+    if (declared.some((service) => service.attached))
+        notes.push(ATTACH_BUFFERING_NOTE);
+    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),
+            // G3's precondition and G4's `E`, declared because this run actually
+            // watched something. Only on a path where evidence really came back: a
+            // completed run that collected nothing witnessed nothing, and saying
+            // otherwise would assert a precondition on an empty array.
+            //
+            // Note this is deliberately *not* gated on `written > 0`. Whether an
+            // edge could be written is a fact about the graph path, and rule 3
+            // already caps the category through `resolutionFloor` just above — a
+            // run that saw three channels and wrote no edge is reported
+            // `unconfirmed` by the cap, not by pretending it saw nothing. Two
+            // separate facts, each stated once.
+            ...(execution.evidence.length === 0
+                ? {}
+                : { runtimeEvidence: { independentSignalTypes: witnessedSignalTypes(execution.evidence) } }),
+            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;
+}
+/**
+ * One evidence row onto one of `@descryy/ir`'s six `RUNTIME_SIGNAL_TYPES`, or
+ * `null`.
+ *
+ * **Decided by `eventType`, with `source` consulted only where the event type
+ * is genuinely ambiguous** — an exception can come off a browser console or a
+ * backend process, and nothing but the collector says which. The obvious
+ * alternative, reading `source` alone, is wrong and was measured to be wrong
+ * rather than reasoned about: every row this repository's own conformance run
+ * produces carries `source: "backend-process"`, and `EVIDENCE_SOURCES` also
+ * has a `backend-log` value that nothing in the shipped dependency closure
+ * emits. A source-driven table would have counted zero channels on every real
+ * run while passing a hand-built test — the exact shape of failure that gets
+ * caught by running the thing.
+ *
+ * **Everything not listed returns `null` and is counted as nothing.** That is
+ * `RuntimeEvidence`'s own rule, not caution added here: `TEST_*` is excluded
+ * by design (its evidentiary weight is `M`'s, never double-counted as a
+ * channel too), harness actions are Descry driving the application rather than
+ * observing it, process lifecycle is a fact about the process rather than
+ * about its behaviour, and a collector or version-mismatch error is a fact
+ * about the run. A kind this table has not ruled on must fail closed, because
+ * the alternative — mapping it to the nearest-looking channel — raises `E`,
+ * and therefore the reported category, with nobody having decided that it
+ * should.
+ */
+function signalOf(item) {
+    switch (item.eventType) {
+        case "CONSOLE_MESSAGE":
+            return "browser-console";
+        case "NETWORK_REQUEST":
+        case "NETWORK_RESPONSE":
+        case "HTTP_ERROR":
+        case "WEBSOCKET_CLOSED":
+            return "network";
+        case "SCREENSHOT":
+        case "VIDEO":
+            return "browser-visual";
+        case "BACKEND_LOG":
+            return "backend-log";
+        case "DATABASE_QUERY":
+            return "database";
+        case "EXTERNAL_REQUEST":
+            return "external-service";
+        // The ambiguous pair, and the only place `source` decides: a thrown error
+        // reaches Descry through whichever collector saw it, and that collector is
+        // the channel.
+        case "EXCEPTION":
+        case "STACK_TRACE":
+            return item.source === "browser-console" ? "browser-console" : "backend-log";
+        default:
+            return null;
+    }
+}
+/**
+ * `E` for this run — how many of the six channels it actually saw.
+ *
+ * The count itself is `@descryy/ir`'s `independentSignalTypes`, deliberately:
+ * the clamp to six and the drop of `null` signals are that function's rules,
+ * and a second implementation of them here is a second place for the
+ * vocabulary to drift. This function's only job is the translation above.
+ *
+ * Exported for its own test — the mapping decides whether a witnessed answer
+ * reads `strongly supported` or `unconfirmed`, which is too load-bearing to be
+ * asserted only through a category two layers downstream.
+ */
+export function witnessedSignalTypes(evidence) {
+    return independentSignalTypes(evidence.map((item) => ({ signal: signalOf(item), detail: item.eventType })));
+}
+/**
+ * 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.
+ */
+/**
+ * §7's `willDo`, and — since `readArguments` is the first thing it does — the
+ * point where an invalid call is refused.
+ *
+ * Returns a string on every valid call rather than ever returning `undefined`:
+ * `undefined` means "this particular call has nothing to confirm", and there
+ * is no such call here. Every accepted declaration boots or attaches to
+ * something and may write durable R4 facts.
+ *
+ * Reads the *parsed* services rather than the raw object, so the sentence a
+ * developer confirms is built from the same values the run will use — which
+ * is also what makes "spawn" and "attach" here mean exactly what
+ * `readServices` decided they mean, rather than a second, looser guess at the
+ * same distinction.
+ */
+function describeAction(args, ctx) {
+    const { declared } = readArguments(args, ctx.session.repoPath);
+    const spawned = declared.filter((service) => !service.attached).map((service) => service.name);
+    const attached = declared.filter((service) => service.attached).map((service) => service.name);
+    const parts = [];
+    if (spawned.length > 0)
+        parts.push(`start ${String(spawned.length)} service(s) (${spawned.join(", ")})`);
+    if (attached.length > 0) {
+        parts.push(`attach to ${String(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. " +
+        "BEFORE CALLING: this observes an application you can already run — it does not help you get to " +
+        "a runnable state, and that boundary is real rather than apologetic. Its dependencies must be up, " +
+        "its environment set, and its migrations applied, all by you. One trap worth stating because it " +
+        "is invisible: overriding some environment variables does not isolate a run from the " +
+        "application's own configuration file — anything you did not explicitly override is still read " +
+        "from it, including values naming environments you did not intend to touch.",
+    inputSchema: SCHEMA,
+    run,
+    describeAction,
+};
+//# sourceMappingURL=observe-runtime.js.map