@descryy/mcp 0.1.2 → 0.3.0

package/dist/browser/scenario-runner.js

@@ -0,0 +1,315 @@
+/**
+ * Replaying a stored scenario — §7's runner half.
+ *
+ * ## What this composes, and the four things it must not get wrong
+ *
+ * Everything below is composition: the port drives, `scenarios/` is the
+ * artifact, `scenario-resolve.ts` re-resolves a descriptor, `tool-support.ts`
+ * drains and correlates. What the runner adds is *order*, and four ordering
+ * mistakes each fail as flakiness or as a false pass rather than as an error,
+ * which is why each is named here rather than left to be rediscovered.
+ *
+ * 1. **`registry.use()` is called once per step.** It is not a lookup: it is
+ *    asynchronous, it is the crash detector, and it touches the idle clock. A
+ *    runner that resolved the session once and held the entry across N steps
+ *    would be reaped mid-scenario at the five-minute idle timeout, and would
+ *    read as a flaky test rather than as a design error.
+ * 2. **`drainEvidence()` drains, it does not peek.** Once per step, aggregated
+ *    into the summary. A single read at the end loses every earlier step's
+ *    observations — and would silently pass an assertion anchored at step 0,
+ *    which is the false green this whole feature exists to prevent.
+ * 3. **A stored step carries no `ref`.** Every step re-resolves against a
+ *    fresh snapshot, exact-or-refuse, with no fallback chain. See
+ *    `scenario-resolve.ts`.
+ * 4. **Assertions evaluate here, at replay.** An empty assertion list replays
+ *    as `unverified`, never `passed`.
+ *
+ * ## The outcome rule
+ *
+ * `DEC-384`, implemented rather than restated. A
+ * failed assertion is the scenario's own claim about the application, written
+ * down by a person, and it blocks. A console error or a failed request is
+ * reported and does not block — frequently true of a working page, and a check
+ * people disable protects nothing. No assertions is `unverified`. An
+ * unresolvable step is **neither pass nor fail**: Descry cannot tell a
+ * deliberate rename from a vanished button, and both produce a byte-identical
+ * unresolvable step, so it claims neither while still stopping the run.
+ *
+ * Three counts, **never summed** — `failed`, `unresolved`, `unverified` — and
+ * only failed assertions join `blockingTotal`, because folding `unresolved`
+ * into it would re-assert through arithmetic the defect claim the ruling
+ * refused to make in prose.
+ */
+import { NO_GRAPH_WRITE } from "./graph-write.js";
+import { resolveTarget } from "./scenario-resolve.js";
+import { observeAndCorrelate, useSession, withinConsent } from "./tool-support.js";
+const MUTATING = ["click", "type", "fill"];
+/** True when replaying this scenario would change the running application. A navigate-only scenario would not. */
+export function mutates(scenario) {
+    return scenario.steps.some((step) => MUTATING.includes(step.action));
+}
+function mergeGraph(into, next) {
+    const reached = [...into.reached];
+    for (const node of next.reached)
+        if (!reached.some((seen) => seen.nodeId === node.nodeId))
+            reached.push(node);
+    return {
+        reached,
+        promoted: [...new Set([...into.promoted, ...next.promoted])],
+        created: [...new Set([...into.created, ...next.created])],
+        refused: [...new Set([...into.refused, ...next.refused])],
+        contradictions: [...new Set([...into.contradictions, ...next.contradictions])],
+    };
+}
+export async function replayScenario(ctx, registry, sessionId, scenario) {
+    const steps = scenario.steps.map((step, index) => ({
+        index,
+        action: step.action,
+        status: "skipped",
+        url: "",
+        resolution: null,
+    }));
+    const assertionResults = scenario.assertions.map(() => null);
+    const acc = { consoleErrors: [], failedRequests: [], actions: [], totalRequests: 0 };
+    let graph = NO_GRAPH_WRITE;
+    const notes = [];
+    let sessionEnded = null;
+    let stopped = false;
+    function absorb(evidence) {
+        acc.consoleErrors.push(...evidence.consoleErrors);
+        acc.failedRequests.push(...evidence.failedRequests);
+        acc.actions.push(...evidence.actions);
+        acc.totalRequests += evidence.totalRequests;
+    }
+    function cumulative() {
+        return {
+            consoleErrors: [...acc.consoleErrors],
+            failedRequests: [...acc.failedRequests],
+            actions: [...acc.actions],
+            totalRequests: acc.totalRequests,
+        };
+    }
+    function anchoredAt(anchor) {
+        return scenario.assertions.some((assertion, index) => assertion.afterStep === anchor && assertionResults[index] === null);
+    }
+    /**
+     * A snapshot is taken only when something is anchored here.
+     *
+     * Not a micro-optimisation: a snapshot is a real round trip to a real page,
+     * and taking one after every step of a twenty-step scenario that asserts
+     * once at the end would triple the cost of the common case.
+     */
+    async function evaluateAnchored(anchor, entry) {
+        if (!anchoredAt(anchor))
+            return;
+        const snapshot = await entry.page.snapshot();
+        scenario.assertions.forEach((assertion, index) => {
+            if (assertion.afterStep !== anchor || assertionResults[index] !== null)
+                return;
+            assertionResults[index] = evaluateAssertion(assertion, index, entry, snapshot, cumulative());
+        });
+    }
+    for (const [index, step] of scenario.steps.entries()) {
+        // Trap 1. Per step, always: `use` is the crash detector and the idle
+        // clock, and a five-minute scenario that resolved the session once would
+        // be reaped out from under itself halfway through.
+        const found = await useSession(registry, sessionId);
+        if (!found.ok) {
+            sessionEnded = found.dead;
+            absorb(found.dead.evidence);
+            stopped = true;
+            break;
+        }
+        const { entry } = found;
+        ctx.progress(`Replaying step ${index + 1} of ${scenario.steps.length}`, index + 1, scenario.steps.length);
+        if (step.action === "navigate") {
+            const url = step.url ?? "";
+            if (!withinConsent(entry, url)) {
+                steps[index] = {
+                    index,
+                    action: step.action,
+                    status: "unresolved",
+                    url: entry.page.currentUrl(),
+                    resolution: {
+                        kind: "zero",
+                        disagreed: [],
+                        message: `step ${index}: navigating to ${url} would leave ${entry.consentedOrigin}, the origin this ` +
+                            "session was consented for. The step is not run and the replay stops — consent is bound to one " +
+                            "origin, and a stored step cannot widen it.",
+                    },
+                };
+                stopped = true;
+                break;
+            }
+            await entry.page.navigate(url);
+        }
+        else {
+            // Trap 3. A fresh snapshot every time, and exact-or-refuse against it.
+            const snapshot = await entry.page.snapshot();
+            const target = step.target;
+            if (target === null) {
+                steps[index] = {
+                    index,
+                    action: step.action,
+                    status: "unresolved",
+                    url: snapshot.url,
+                    resolution: {
+                        kind: "zero",
+                        disagreed: [],
+                        message: `step ${index}: a ${step.action} step carries no target to resolve. Fix the scenario file and re-save it.`,
+                    },
+                };
+                stopped = true;
+                break;
+            }
+            const resolved = resolveTarget(`step ${index}`, target, snapshot);
+            if (!resolved.resolved) {
+                steps[index] = { index, action: step.action, status: "unresolved", url: snapshot.url, resolution: resolved.failure };
+                // Trap 2 again, on the failure path. Stopping without draining would
+                // discard whatever the page said before the descriptor stopped
+                // matching, which is exactly the evidence a person needs to tell a
+                // rename from a breakage.
+                const observed = await observeAndCorrelate(ctx, entry);
+                absorb(observed.evidence);
+                graph = mergeGraph(graph, observed.graph);
+                notes.push(...observed.notes);
+                stopped = true;
+                break;
+            }
+            const ref = resolved.element.ref;
+            if (step.action === "click")
+                await entry.page.click(ref);
+            else if (step.action === "type")
+                await entry.page.type(ref, step.text ?? "");
+            else
+                await entry.page.fill(ref, step.text ?? "");
+        }
+        // Trap 2. Once per step, aggregated. A final read would lose everything
+        // the earlier steps saw; a peeking read would report each observation
+        // again on the teardown flush.
+        const observed = await observeAndCorrelate(ctx, entry);
+        absorb(observed.evidence);
+        graph = mergeGraph(graph, observed.graph);
+        notes.push(...observed.notes);
+        steps[index] = { index, action: step.action, status: "ran", url: entry.page.currentUrl(), resolution: null };
+        await evaluateAnchored(index, entry);
+    }
+    // End-of-scenario assertions, and only when there are some. A `use` call is
+    // not free — it is the crash detector and it touches the idle clock — so a
+    // scenario with nothing anchored at the end does not make one.
+    if (!stopped && anchoredAt(null)) {
+        const found = await useSession(registry, sessionId);
+        if (found.ok) {
+            await evaluateAnchored(null, found.entry);
+        }
+        else {
+            sessionEnded = found.dead;
+            absorb(found.dead.evidence);
+        }
+    }
+    const assertions = scenario.assertions.map((assertion, index) => assertionResults[index] ?? {
+        index,
+        kind: assertion.kind,
+        afterStep: assertion.afterStep,
+        status: "notReached",
+        detail: `The replay stopped before this assertion's anchor, so it never ran. That is not a pass and not a ` +
+            "failure — it is already accounted for by the step that stopped the run.",
+    });
+    const failed = assertions.filter((a) => a.status === "failed").length;
+    const unevaluable = assertions.filter((a) => a.status === "unevaluable").length;
+    const unresolvedSteps = steps.filter((s) => s.status === "unresolved").length;
+    const unresolved = unresolvedSteps + unevaluable;
+    // A scenario that claimed nothing verified nothing. One scenario, so this is
+    // 1 or 0 — the count is a count so the CLI can add scenarios together, never
+    // so it can add it to the other two.
+    const unverified = scenario.assertions.length === 0 ? 1 : 0;
+    const passed = assertions.filter((a) => a.status === "passed").length;
+    const outcome = failed > 0 ? "failed" : unresolved > 0 || sessionEnded !== null ? "unresolved" : unverified > 0 ? "unverified" : "passed";
+    return {
+        scenario: scenario.name,
+        sessionId,
+        outcome,
+        counts: { passed, failed, unresolved, unverified },
+        // Only failed assertions. See the header.
+        blockingTotal: failed,
+        exitCode: outcome === "failed" ? 1 : outcome === "unresolved" ? 2 : 0,
+        steps,
+        assertions,
+        evidence: cumulative(),
+        graph,
+        sessionEnded,
+        notes,
+    };
+}
+/**
+ * Evaluate one assertion against the page as it stands and the evidence
+ * gathered so far.
+ *
+ * The two evidence assertions read *cumulatively* — everything observed since
+ * the replay began, not only the step just taken. An author anchoring
+ * `noConsoleErrors` after step 3 is claiming the page got that far cleanly,
+ * not that step 3 in isolation was quiet.
+ */
+function evaluateAssertion(assertion, index, entry, snapshot, evidence) {
+    const base = { index, kind: assertion.kind, afterStep: assertion.afterStep };
+    const unevaluable = (detail) => ({ ...base, status: "unevaluable", detail });
+    const passed = (detail) => ({ ...base, status: "passed", detail });
+    const failed = (detail) => ({ ...base, status: "failed", detail });
+    switch (assertion.kind) {
+        case "elementVisible": {
+            if (assertion.target === null) {
+                return unevaluable(`assertion ${index}: elementVisible names no element. Fix the scenario file and re-save it.`);
+            }
+            const found = resolveTarget(`assertion ${index}`, assertion.target, snapshot);
+            if (found.resolved)
+                return passed(`assertion ${index}: the element is on ${snapshot.url}.`);
+            // Ambiguity is the page being unreadable, not the claim being wrong —
+            // "which of these two did you mean" is a question, not a defect. Zero
+            // and partial are the claim failing: the author wrote down that this
+            // element would be here, and it is not.
+            if (found.failure.kind === "ambiguous")
+                return unevaluable(found.failure.message);
+            return failed(found.failure.message);
+        }
+        case "textEquals": {
+            if (assertion.target === null || assertion.expected === null) {
+                return unevaluable(`assertion ${index}: textEquals needs both an element and an expected value, and the scenario file ` +
+                    "stores only one of them. Fix the scenario and re-save it.");
+            }
+            const found = resolveTarget(`assertion ${index}`, assertion.target, snapshot);
+            if (!found.resolved) {
+                return found.failure.kind === "ambiguous" ? unevaluable(found.failure.message) : failed(found.failure.message);
+            }
+            // The snapshot carries an accessible name, which is what the port
+            // exposes; there is no text-content field to compare against and
+            // inventing one would be a promise the format cannot keep.
+            return found.element.name === assertion.expected
+                ? passed(`assertion ${index}: the element's accessible name is "${assertion.expected}".`)
+                : failed(`assertion ${index}: expected the element's accessible name to be "${assertion.expected}", and it ` +
+                    `is "${found.element.name}".`);
+        }
+        case "urlEquals": {
+            if (assertion.expected === null) {
+                return unevaluable(`assertion ${index}: urlEquals stores no expected URL. Fix the scenario file and re-save it.`);
+            }
+            const actual = entry.page.currentUrl();
+            return actual === assertion.expected
+                ? passed(`assertion ${index}: the page is at ${actual}.`)
+                : failed(`assertion ${index}: expected the page to be at ${assertion.expected}, and it is at ${actual}.`);
+        }
+        case "noConsoleErrors":
+            return evidence.consoleErrors.length === 0
+                ? passed(`assertion ${index}: no console errors were observed.`)
+                : failed(`assertion ${index}: ${evidence.consoleErrors.length} console error(s) were observed, the first ` +
+                    `being "${evidence.consoleErrors[0]?.text ?? ""}". An observed console error does not block a ` +
+                    "push on its own; this one does, because the scenario's author claimed there would be none.");
+        case "noFailedRequests":
+            return evidence.failedRequests.length === 0
+                ? passed(`assertion ${index}: no failed requests were observed.`)
+                : failed(`assertion ${index}: ${evidence.failedRequests.length} request(s) failed, the first being ` +
+                    `${evidence.failedRequests[0]?.method ?? ""} ${evidence.failedRequests[0]?.url ?? ""}. A failed ` +
+                    "request does not block a push on its own; this one does, because the author claimed there " +
+                    "would be none.");
+    }
+}
+//# sourceMappingURL=scenario-runner.js.map

package/dist/browser/scenario-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenario-runner.js","sourceRoot":"","sources":["../../src/browser/scenario-runner.ts"],"names":[],"mappings":"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"}

package/dist/browser/stack-parser.d.ts

@@ -0,0 +1,43 @@
+/**
+ * How a browser session reaches a stack-trace parser without naming a
+ * language.
+ *
+ * `runtime-registry.ts`'s argument, applied to the browser lane. A raw
+ * `fetch()` call-site stack is a string in some runtime's own format, and
+ * turning it into resolved frames is per-language work that lives in
+ * `descry-runtime`'s adapters. An `import { createV8StackTraceParser } from
+ * "@descryy/runtime-adapter-typescript"` in a tool file would put the word
+ * "typescript" above the IR boundary in the one process that runs everything
+ * — rule 1, which this repository calls a design bug rather than a style
+ * preference.
+ *
+ * So the parser is **named by the caller as a module specifier** and imported
+ * at run time, exactly as every static source and runtime adapter already is.
+ *
+ * ## Without one, the arrow does not exist, and the reply says so
+ *
+ * This is not a degradation that can be hidden. `confirmObservedFrontendCaller`
+ * takes a parsed `StackTrace`; with no parser, every request is still observed
+ * and every endpoint it reached can still be named, but **no caller edge is
+ * written at all**. That is a real, honest, partial answer — "this route was
+ * hit, we cannot tell you from where" — and it is disclosed rather than
+ * presented as a run that found nothing.
+ */
+import type { StackTraceParser } from "@descryy/runtime-backend-observation";
+/** A stack-trace parser named the way `RuntimeAdapterSpec` names a runtime adapter. */
+export interface StackParserSpec {
+    readonly module: string;
+    /** Named export to call. Defaults to the `create*StackTraceParser` convention. */
+    readonly export?: string;
+}
+/**
+ * Distinct from a generic `Error` so a tool can tell "the parser would not
+ * load" — a refusal it must disclose — from "the run itself broke". Both are
+ * honest; they are not the same statement.
+ */
+export declare class StackParserLoadError extends Error {
+    readonly specifier: string;
+    constructor(specifier: string, reason: string);
+}
+export declare function loadStackParser(spec: StackParserSpec): Promise<StackTraceParser>;
+//# sourceMappingURL=stack-parser.d.ts.map

package/dist/browser/stack-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stack-parser.d.ts","sourceRoot":"","sources":["../../src/browser/stack-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sCAAsC,CAAC;AAE7E,uFAAuF;AACvF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kFAAkF;IAClF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAQ9C;AAKD,wBAAsB,eAAe,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAkDtF"}

package/dist/browser/stack-parser.js

@@ -0,0 +1,112 @@
+/**
+ * How a browser session reaches a stack-trace parser without naming a
+ * language.
+ *
+ * `runtime-registry.ts`'s argument, applied to the browser lane. A raw
+ * `fetch()` call-site stack is a string in some runtime's own format, and
+ * turning it into resolved frames is per-language work that lives in
+ * `descry-runtime`'s adapters. An `import { createV8StackTraceParser } from
+ * "@descryy/runtime-adapter-typescript"` in a tool file would put the word
+ * "typescript" above the IR boundary in the one process that runs everything
+ * — rule 1, which this repository calls a design bug rather than a style
+ * preference.
+ *
+ * So the parser is **named by the caller as a module specifier** and imported
+ * at run time, exactly as every static source and runtime adapter already is.
+ *
+ * ## Without one, the arrow does not exist, and the reply says so
+ *
+ * This is not a degradation that can be hidden. `confirmObservedFrontendCaller`
+ * takes a parsed `StackTrace`; with no parser, every request is still observed
+ * and every endpoint it reached can still be named, but **no caller edge is
+ * written at all**. That is a real, honest, partial answer — "this route was
+ * hit, we cannot tell you from where" — and it is disclosed rather than
+ * presented as a run that found nothing.
+ */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/**
+ * Distinct from a generic `Error` so a tool can tell "the parser would not
+ * load" — a refusal it must disclose — from "the run itself broke". Both are
+ * honest; they are not the same statement.
+ */
+export class StackParserLoadError extends Error {
+    specifier;
+    constructor(specifier, reason) {
+        super(`Could not load a stack-trace parser from "${specifier}": ${reason}. Requests will still be observed ` +
+            "and endpoints still named, but no frontend→backend caller edge can be written without one.");
+        this.name = "StackParserLoadError";
+        this.specifier = specifier;
+    }
+}
+const FACTORY_PATTERN = /^create[A-Za-z0-9]*StackTraceParser$/;
+const RESOLVER_PATTERN = /^create[A-Za-z0-9]*SourceLocationResolver$/;
+export async function loadStackParser(spec) {
+    let module;
+    try {
+        module = (await import(__rewriteRelativeImportExtension(spec.module)));
+    }
+    catch (error) {
+        throw new StackParserLoadError(spec.module, error instanceof Error ? error.message : String(error));
+    }
+    const name = spec.export ?? soleFactory(module, spec.module);
+    const factory = module[name];
+    if (typeof factory !== "function") {
+        throw new StackParserLoadError(spec.module, `"${name}" is not a function`);
+    }
+    // A parser factory that takes an argument takes a `SourceLocationResolver`
+    // — resolving a script URL to a real file on disk is the half of the job
+    // that is filesystem-shaped rather than text-shaped, and every adapter that
+    // needs one exports a `create*SourceLocationResolver` beside its parser.
+    //
+    // This is checked rather than assumed because the failure is silent. Called
+    // with no resolver, `createV8StackTraceParser` returns a parser that throws
+    // nothing and produces `null` for every stack — so a run would observe
+    // every request, write no edge, report no error, and look exactly like an
+    // application with no frontend callers. Measured, not hypothesised: it is
+    // what this loader did before this branch existed.
+    const needsResolver = factory.length >= 1;
+    let resolver;
+    if (needsResolver) {
+        const resolverName = soleMatch(module, RESOLVER_PATTERN);
+        if (resolverName === null) {
+            throw new StackParserLoadError(spec.module, `${name}() expects a source-location resolver and the module exports no create*SourceLocationResolver ` +
+                "to build one from. Without it every stack parses to null and no caller edge could ever be written");
+        }
+        try {
+            resolver = module[resolverName]();
+        }
+        catch (error) {
+            throw new StackParserLoadError(spec.module, `${resolverName}() threw: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    try {
+        return needsResolver
+            ? factory(resolver)
+            : factory();
+    }
+    catch (error) {
+        throw new StackParserLoadError(spec.module, `${name}() threw: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function soleMatch(module, pattern) {
+    const matches = Object.keys(module).filter((key) => pattern.test(key) && typeof module[key] === "function");
+    return matches.length === 1 ? matches[0] : null;
+}
+/** Two matches is an error, not a coin toss — `runtime-registry.ts`'s rule, for the same reason. */
+function soleFactory(module, specifier) {
+    const matches = Object.keys(module).filter((key) => FACTORY_PATTERN.test(key) && typeof module[key] === "function");
+    if (matches.length === 1)
+        return matches[0];
+    if (matches.length === 0) {
+        throw new StackParserLoadError(specifier, "it exports no create*StackTraceParser factory; name one explicitly with \"export\"");
+    }
+    throw new StackParserLoadError(specifier, `it exports ${matches.length} create*StackTraceParser factories (${matches.join(", ")}) — name one explicitly with "export"`);
+}
+//# sourceMappingURL=stack-parser.js.map

package/dist/browser/stack-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stack-parser.js","sourceRoot":"","sources":["../../src/browser/stack-parser.ts"],"names":[],"mappings":"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"}

package/dist/browser/tool-support.d.ts

@@ -0,0 +1,113 @@
+/**
+ * What the seven browser tools share.
+ *
+ * Kept in one place because the parts that repeat are the parts that must not
+ * drift: how a dead session is reported, how consent is checked, and how a
+ * reply is stamped. Seven copies of a refusal is seven chances for one of
+ * them to say something slightly different about the same state.
+ */
+import { type ToolContext } from "../tools/kit.ts";
+import type { ToolAnswer } from "../render.ts";
+import type { BrowserSessionEntry, BrowserSessionRegistry } from "./registry.ts";
+import { type BrowserEvidenceReport } from "./evidence.ts";
+import type { BrowserObservation } from "./driver.ts";
+import { type BrowserGraphWrite } from "./graph-write.ts";
+/**
+ * The staleness stamp for a reply that observed a browser.
+ *
+ * A browser tool does not read the graph, and on a repository that has never
+ * been analysed there is no graph to read. Refusing to open a browser because
+ * of that would be refusing for a reason that has nothing to do with the
+ * request, so the stamp degrades instead — and says it degraded.
+ */
+export interface BrowserStamp {
+    readonly commitSha: string | null;
+    readonly graphBuiltAt: number | null;
+    readonly irSchemaVersion: number;
+    readonly commitSpread: number;
+    readonly note: string | null;
+}
+export declare function browserStamp(ctx: ToolContext): BrowserStamp;
+export interface BrowserReplyOptions<T> {
+    readonly headline: string;
+    readonly data: T;
+    readonly notes: readonly string[];
+    readonly state?: "ok" | "refused" | "failed" | "empty";
+    readonly ctx: ToolContext;
+    readonly fitToBudget?: (budgetBytes: number) => import("../render.ts").ReplyFit<T>;
+}
+/**
+ * Every browser reply, stamped identically.
+ *
+ * `resolutionFloor: 4` on a successful observation, and that is not
+ * generosity: R4 is "observed at runtime", and a page element this call
+ * actually saw is the definition of it. A refusal or a failure observed
+ * nothing, so it stamps R0 — the floor has to describe the evidence behind
+ * *this* reply, not the tool's best case.
+ */
+export declare function browserAnswer<T>(options: BrowserReplyOptions<T>): ToolAnswer<T>;
+export interface DeadSession {
+    readonly state: "refused" | "failed";
+    readonly headline: string;
+    readonly notes: readonly string[];
+    readonly evidence: BrowserEvidenceReport;
+}
+/**
+ * Look a session up, or describe exactly why it cannot be used.
+ *
+ * The three dead states are deliberately not collapsed into one. "You never
+ * had this session", "it timed out five minutes ago, here is what it saw" and
+ * "the browser crashed" are three different things for a caller to do next,
+ * and only the last of them is a `failed`.
+ */
+export declare function useSession(registry: BrowserSessionRegistry, sessionId: string): Promise<{
+    readonly ok: true;
+    readonly entry: BrowserSessionEntry;
+} | {
+    readonly ok: false;
+    readonly dead: DeadSession;
+}>;
+/**
+ * Drain what the page has said, relate it to the graph, and produce both the
+ * payload and the disclosures in one place.
+ *
+ * Every evidence-bearing browser tool goes through this rather than draining
+ * for itself. Two reasons, and the second is the one that matters: a tool
+ * that drained without correlating would be a tool through which the R4 write
+ * silently does not happen, and nothing about its reply would look different.
+ *
+ * A repository with no graph correlates nothing and says so. That is a real
+ * state — a developer can drive a browser against an app they have never
+ * analysed — and it must not look like "we looked and found no connection".
+ */
+export declare function observeAndCorrelate(ctx: ToolContext, entry: BrowserSessionEntry): Promise<{
+    readonly evidence: BrowserEvidenceReport;
+    readonly graph: BrowserGraphWrite;
+    readonly notes: readonly string[];
+}>;
+export declare function emptyEvidence(): BrowserEvidenceReport;
+export declare function reportOf(observation: BrowserObservation): BrowserEvidenceReport;
+/**
+ * Is `url` inside the origin this session was consented for?
+ *
+ * The consent ruling's one hard bound. Checked here rather than in each verb
+ * so that a future eighth tool cannot forget it.
+ */
+/**
+ * Does this session's environment profile permit changing the application?
+ *
+ * Read off the profile the session was opened under — DEC-270's
+ * `safetyLevel`, the same field `observe_runtime` consults. Deliberately not
+ * a per-tool flag: two independent notions of "safe" is how a runtime run and
+ * a browser run end up disagreeing about the same environment.
+ *
+ * A session opened with no profile returns null here, and the session's own
+ * consent is then the only authorization — which is a real authorization,
+ * granted explicitly at `browser_start_session` against a named origin. The
+ * two are independent and both must pass: consent answers *may Descry drive a
+ * browser against this target at all*, the profile answers *may it mutate*,
+ * and neither excuses the other.
+ */
+export declare function mutationRefusal(entry: BrowserSessionEntry): string | null;
+export declare function withinConsent(entry: BrowserSessionEntry, url: string): boolean;
+//# sourceMappingURL=tool-support.d.ts.map

package/dist/browser/tool-support.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-support.d.ts","sourceRoot":"","sources":["../../src/browser/tool-support.ts"],"names":[],"mappings":"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"}