@orkestrel/probe 0.0.1

package/dist/src/server/index.d.cts

@@ -0,0 +1,941 @@
+import { Case } from '@orkestrel/probe';
+import { Case as Case_2 } from '@orkestrel/probe';
+import { Check } from '@orkestrel/probe';
+import { Check as Check_2 } from '@orkestrel/probe';
+import { Claim } from '@orkestrel/probe';
+import { EmitterInterface } from '@orkestrel/emitter';
+import { EventEmitter } from 'node:events';
+import { ProbeEventMap } from '@orkestrel/probe';
+import { ProbeInterface } from '@orkestrel/probe';
+import { ProbeOptions } from '@orkestrel/probe';
+import { Project } from '@orkestrel/probe';
+import { Project as Project_2 } from '@orkestrel/probe';
+import { Stage } from '@orkestrel/probe';
+import { Stage as Stage_2 } from '@orkestrel/probe';
+import { Toolchain } from '@orkestrel/probe';
+import type * as TypeScript from 'typescript';
+import { Verdict } from '@orkestrel/probe';
+import type * as VitestNode from 'vitest/node';
+
+/**
+ * Records the listeners one emitter carries for a set of events.
+ *
+ * @param emitter - The emitter to read
+ * @param events - The event names to record
+ * @returns The listeners each named event carries at the moment of the call
+ *
+ * @example
+ * ```ts
+ * const capture = captureListeners(process, ['SIGTERM'])
+ * capture.get('SIGTERM')?.length === process.listenerCount('SIGTERM') // true
+ * ```
+ */
+export declare function captureListeners(emitter: EventEmitter, events: readonly string[]): ListenerCapture;
+
+/**
+ * Computes the canonical digest of one value as it stands in a target workspace.
+ *
+ * @remarks
+ * Digests the normalized value rather than the value itself, so one commit read at two absolute
+ * roots produces one digest and a digest carries no host path. The result is the leading 32 hex
+ * characters of a SHA-256 over the normalized JSON.
+ *
+ * @param workspace - The target workspace root the value's paths are read against
+ * @param value - The value to digest
+ * @returns 32 lowercase hex characters
+ *
+ * @example
+ * ```ts
+ * computeDigest('/srv/checkout', { strict: true }).length // 32
+ * ```
+ */
+export declare function computeDigest(workspace: string, value: unknown): string;
+
+/**
+ * Creates a fresh sibling identity while preserving a test's resolution directory.
+ *
+ * @param workspace - The target workspace root
+ * @param path - The workspace-relative test path
+ * @param revision - The fresh revision identity
+ * @returns An absolute sibling file path
+ *
+ * @example
+ * ```ts
+ * relativeWorkspaceFile(
+ * 	'/srv/checkout',
+ * 	createRevisionFile('/srv/checkout', 'tmp/probe/greeting.test.ts', '4821-9f0c'),
+ * )
+ * // 'tmp/probe/greeting.test.probe-4821-9f0c.ts'
+ * ```
+ */
+export declare function createRevisionFile(workspace: string, path: string, revision: string): string;
+
+/**
+ * Normalizes a caught or foreign error into readable text.
+ *
+ * @param value - The value to describe
+ * @returns Its message when present, or its string representation
+ *
+ * @example
+ * ```ts
+ * describeUnknown(new Error('The lint stage has been destroyed'))
+ * // 'The lint stage has been destroyed'
+ * describeUnknown(17) // '17'
+ * ```
+ */
+export declare function describeUnknown(value: unknown): string;
+
+/**
+ * Names every draft member of a claim-shaped value whose `path` this package's guard refuses.
+ *
+ * @remarks
+ * The published claim schema constrains `Draft.path` to a non-empty string and nothing else, while
+ * `isDraft` also refuses an absolute path and one that escapes the workspace. That one member is
+ * the whole of the difference between the advertised contract and the enforced one, so a caller
+ * refused after satisfying the schema is refused here and nowhere else. The whole input must first
+ * satisfy that schema. Each draft is then tested with `isDraft` itself rather than with a second
+ * copy of its rule. Reports nothing for a value carrying no draft member, including one refused for
+ * a member this contract does not declare.
+ *
+ * This function lives in the server helpers rather than in core: core's leaf pair, `helpers.ts` and
+ * `validators.ts`, may not consume the shapes module this function reads `CLAIM_SHAPE` from, and
+ * `ProbeServer` is the sole consumer of the result it returns.
+ *
+ * @param value - The rejected tool input
+ * @returns The dotted member names, in `case` then `control` order, or an empty list
+ *
+ * @example
+ * ```ts
+ * const test = { path: 'tmp/probe/greeting.test.ts', text: '' }
+ * findRefusedPaths({
+ * 	project: 'tsconfig.json',
+ * 	case: { files: [{ path: '../../etc/hosts', text: '' }], test },
+ * 	control: { files: [], test, stage: 'type', reason: 'must not compile' },
+ * })
+ * // ['case.files.0.path']
+ * ```
+ */
+export declare function findRefusedPaths(value: unknown): readonly string[];
+
+/**
+ * Selects the Language Server Protocol language identifier for a source path.
+ *
+ * @param path - The source path whose extension selects the language
+ * @returns The matching JavaScript or TypeScript language identifier
+ *
+ * @example
+ * ```ts
+ * inferDocumentLanguage('src/core/greeting.ts') // 'typescript'
+ * inferDocumentLanguage('src/browser/Panel.tsx') // 'typescriptreact'
+ * ```
+ */
+export declare function inferDocumentLanguage(path: string): string;
+
+/**
+ * Selects the Vitest project whose environment matches one test path.
+ *
+ * @remarks
+ * There is no root-project fallback. A path no configured project collects returns `undefined`,
+ * and the runtime stage refuses that claimant test with `code: 'missing'` rather than running it
+ * somewhere the workspace never configured.
+ *
+ * @param path - The workspace-relative test path
+ * @returns The matching project's name, or `undefined` when no configured project collects the path
+ *
+ * @example
+ * ```ts
+ * inferTestProject('tmp/probe/greeting.test.ts') // 'probe'
+ * inferTestProject('tests/src/server/helpers.test.ts') // 'src:server'
+ * inferTestProject('tests/config.test.ts') // undefined
+ * ```
+ */
+export declare function inferTestProject(path: string): string | undefined;
+
+/**
+ * Selects the scoped TypeScript project for one candidate draft path.
+ *
+ * @param path - The workspace-relative candidate draft path
+ * @returns The workspace-relative scoped project path
+ * @throws When the path does not name a configured source or application environment
+ *
+ * @example
+ * ```ts
+ * inferTypeProject('src/core/greeting.ts') // 'configs/src/tsconfig.core.json'
+ * inferTypeProject('tests/src/core/greeting.test.ts')
+ * // throws: Cannot infer a scoped TypeScript project for tests/src/core/greeting.test.ts
+ * ```
+ */
+export declare function inferTypeProject(path: string): string;
+
+/**
+ * Carries one queued inspection: the case a stage reads and the claim it belongs to.
+ *
+ * @remarks
+ * The coordinator admits one of these per stage at a time. Every stage reads `subject`; the type
+ * stage also reads `claim.project`, and the runtime stage reports `claim` when its deadline fires.
+ * A coordinator such as `Probe` mints an inspection when it admits a claim to a stage.
+ *
+ * @example
+ * ```ts
+ * const inspection: Inspection = { subject: claim.case, claim }
+ * ```
+ */
+export declare interface Inspection {
+    /** The candidate drafts and test one stage inspects. */
+    readonly subject: Case;
+    /** The claim the subject belongs to. */
+    readonly claim: Claim;
+}
+
+/**
+ * Inspects virtual documents through one resident Oxlint language server.
+ *
+ * @remarks
+ * Construction starts the target workspace's Oxlint binary with its Language Server Protocol
+ * mode. Each inspection opens the supplied text by URI, waits for published diagnostics, and
+ * closes the document without writing it to disk.
+ *
+ * Teardown is bounded at both ends. Warming waits for the server's `initialize` response and the
+ * ending waits for its `shutdown` reply, and the protocol leaves both answers to the server, so
+ * `destroy` bounds each exchange and takes the ending back with a signal when the bound passes.
+ *
+ * The URI is the path the candidate declared, so the candidate receives exactly the rule set the
+ * workspace's own lint gate applies to that path, including an override anchored to one directory,
+ * one file name, or one exact file. A path the workspace's version-control ignore files exclude is
+ * a path that gate never lints, and this stage reports the same nothing for it. Reuse of one
+ * declared path across inspections is what the caller's own serialization protects: the stage
+ * refuses a second inspection of a path it already has open rather than answering either one with
+ * the other's diagnostics.
+ *
+ * @example
+ * ```ts
+ * const stage = new LintStage('/srv/checkout')
+ * const check = await stage.inspect(subject)
+ * await stage.destroy()
+ * ```
+ */
+export declare class LintStage implements StageInterface {
+    #private;
+    /**
+     * Starts warming the target workspace's Oxlint language server.
+     *
+     * @param workspace - The target workspace root. Default: the current working directory
+     */
+    constructor(workspace?: string);
+    get stage(): Stage_2;
+    get progress(): number;
+    inspect(subject: Case_2): Promise<Check_2>;
+    destroy(): Promise<void>;
+}
+
+/**
+ * Holds the listeners one emitter carried for a set of events at the moment it was captured.
+ *
+ * @remarks
+ * A capture is the before half of a listener diff. `captureListeners` takes one, and
+ * `releaseListeners` removes whatever the emitter has gained since. Identity is what the pair
+ * compares, so a listener a capture holds survives the release whatever it is named.
+ *
+ * The pair reads a gain as the callee's own, so it binds its caller to a window nothing else can
+ * attach in. Where a caller cannot promise that window, hold each handler as a field and remove it
+ * by reference instead.
+ *
+ * @example
+ * ```ts
+ * const capture: ListenerCapture = new Map([['SIGTERM', process.listeners('SIGTERM')]])
+ * ```
+ */
+export declare type ListenerCapture = ReadonlyMap<string, readonly Function[]>;
+
+/**
+ * Loads one installed tool module from a target workspace.
+ *
+ * @param workspace - The target workspace root
+ * @param specifier - The module specifier to load
+ * @returns The installed module
+ * @throws When the workspace cannot load the module
+ *
+ * @example
+ * ```ts
+ * const typescript = loadWorkspaceModule(process.cwd(), 'typescript')
+ * console.log(typescript.version)
+ * ```
+ */
+export declare function loadWorkspaceModule(workspace: string, specifier: 'typescript'): typeof TypeScript;
+
+export declare function loadWorkspaceModule(workspace: string, specifier: 'vitest/node'): typeof VitestNode;
+
+/**
+ * Reports whether a path is a workspace module Vitest can cache.
+ *
+ * @param path - The candidate file path
+ * @returns True for script, TypeScript, Vue, and JSON modules; false otherwise
+ *
+ * @example
+ * ```ts
+ * matchesWorkspaceModule('src/core/greeting.ts') // true
+ * matchesWorkspaceModule('src/styles/tokens.css') // false
+ * ```
+ */
+export declare function matchesWorkspaceModule(path: string): boolean;
+
+/**
+ * Rewrites one path into the forward-slash spelling this package compares and reports paths in.
+ *
+ * @remarks
+ * Windows reports a path with backslashes and accepts either separator, so two spellings of one
+ * file compare unequal until they are rewritten. Every path this package keys a map on, matches a
+ * prefix against, or hands a caller passes through here first.
+ *
+ * @param path - The path to rewrite
+ * @returns The same path with every backslash replaced by a forward slash
+ *
+ * @example
+ * ```ts
+ * normalizePath('src\\core\\greeting.ts') // 'src/core/greeting.ts'
+ * normalizePath('src/core/greeting.ts') // 'src/core/greeting.ts'
+ * ```
+ */
+export declare function normalizePath(path: string): string;
+
+/**
+ * Rewrites every workspace-contained absolute path in a value to its workspace-relative form and
+ * sorts every record's keys.
+ *
+ * @remarks
+ * A parsed TypeScript project carries the absolute root it was parsed at, so the same commit
+ * checked out at two paths produces two values that describe one configuration. Rewriting those
+ * members makes the value portable and stops a host path leaking into anything derived from it. A
+ * path that escapes the workspace is left as it stands, because rewriting it would name a file
+ * outside the tree by a relative spelling. Key order is the parser's, not the configuration's, so
+ * sorting removes a difference that means nothing.
+ *
+ * @param workspace - The target workspace root
+ * @param value - The value to rewrite
+ * @returns The value with contained absolute paths made relative and every record key sorted
+ *
+ * @example
+ * ```ts
+ * normalizeValue('/srv/checkout', { rootDir: '/srv/checkout/src/core', strict: true })
+ * // { rootDir: 'src/core', strict: true }
+ * ```
+ */
+export declare function normalizeValue(workspace: string, value: unknown): unknown;
+
+/**
+ * Holds the candidate drafts one inspection substitutes for the files a tool would read from disk.
+ *
+ * @remarks
+ * One overlay belongs to one inspection: the inspection creates it, records every candidate it
+ * carries, and clears it when the inspection ends. Each stage adapts the same set to the host its
+ * own tool expects rather than sharing one filesystem across tools. A fresh identity per instance
+ * is what makes a resident tool re-read a path this overlay holds, so two inspections that supply
+ * different text for one path never share a cached answer.
+ *
+ * @example
+ * ```ts
+ * const overlay = new Overlay()
+ * overlay.set('/srv/checkout/src/core/greeting.ts', "export const GREETING = 'hi'\n")
+ * console.log(overlay.text('/srv/checkout/src/core/greeting.ts'))
+ * overlay.clear()
+ * ```
+ */
+export declare class Overlay implements OverlayInterface {
+    #private;
+    get revision(): string;
+    get paths(): readonly string[];
+    /**
+     * Records one candidate's text against the absolute path it stands in for.
+     *
+     * @param path - The absolute path the candidate replaces
+     * @param text - The candidate's full contents
+     * @returns Nothing
+     */
+    set(path: string, text: string): void;
+    /**
+     * Reads the candidate text recorded for one absolute path.
+     *
+     * @param path - The absolute path to read
+     * @returns The recorded text, or `undefined` when this overlay holds no candidate there
+     */
+    text(path: string): string | undefined;
+    /**
+     * Checks whether a candidate sits beneath one directory.
+     *
+     * @remarks
+     * The answer is derived from the paths the overlay holds rather than stored, so it stops being
+     * true exactly when the inspection that declared those candidates clears them. Both sides pass
+     * through `normalizePath` first, because a tool that normalizes its own paths asks about a
+     * directory in a spelling the recorded path may not share.
+     *
+     * @param directory - The absolute directory path to check
+     * @returns True if a candidate path sits beneath the directory; false otherwise
+     */
+    covers(directory: string): boolean;
+    /**
+     * Releases every candidate.
+     *
+     * @returns Nothing
+     */
+    clear(): void;
+}
+
+/**
+ * Holds the candidate drafts one inspection substitutes for the files a tool would read from disk.
+ *
+ * @remarks
+ * A stage records every candidate the inspection carries before it reads any of them, and clears
+ * the set when the inspection ends, whatever ended it. The entity names no tool: each stage adapts
+ * one overlay to the host its own tool expects, so a language service, a document protocol, and a
+ * module resolver read one candidate set through their own adapters rather than through one shared
+ * filesystem. Paths are absolute and the stage resolves them, because only the stage knows the
+ * workspace a candidate's declared path is relative to. `revision` identifies the set, so a
+ * resident tool that caches by version reads fresh text for a path this overlay holds and reads
+ * disk again after `clear`.
+ *
+ * Mint one overlay per inspection and release it when that inspection ends. An instance shared
+ * across inspections keeps the identity a resident tool caches against, so the second inspection
+ * reads the first one's answer as a fresh one. `Overlay` implements this contract.
+ *
+ * @example
+ * ```ts
+ * const overlay: OverlayInterface = new Overlay()
+ * overlay.set('/srv/checkout/src/core/greeting.ts', "export const GREETING = 'hi'\n")
+ * overlay.covers('/srv/checkout/src/core') // true
+ * overlay.clear()
+ * ```
+ */
+export declare interface OverlayInterface {
+    /** Identity of the candidate set this overlay holds. */
+    readonly revision: string;
+    /** Absolute path of every candidate this overlay holds. */
+    readonly paths: readonly string[];
+    /**
+     * Records one candidate's text against the absolute path it stands in for.
+     *
+     * @param path - The absolute path the candidate replaces
+     * @param text - The candidate's full contents
+     * @returns Nothing
+     */
+    set(path: string, text: string): void;
+    /**
+     * Reads the candidate text recorded for one absolute path.
+     *
+     * @param path - The absolute path to read
+     * @returns The recorded text, or `undefined` when this overlay holds no candidate there
+     */
+    text(path: string): string | undefined;
+    /**
+     * Checks whether a candidate sits beneath one directory.
+     *
+     * @remarks
+     * A tool asking whether a directory exists is answered from disk first, so this reports only
+     * the directories the candidate set adds. A directory listing is a separate question and stays
+     * on disk: a candidate that entered one would outlive the inspection that declared it.
+     *
+     * @param directory - The absolute directory path to check
+     * @returns True if a candidate path sits beneath the directory; false otherwise
+     */
+    covers(directory: string): boolean;
+    /**
+     * Releases every candidate.
+     *
+     * @returns Nothing
+     */
+    clear(): void;
+}
+
+/**
+ * Reads a JSON-RPC frame's declared byte length.
+ *
+ * @param header - The frame header text without its terminating empty line
+ * @returns The non-negative content length, or `undefined` for an invalid header
+ *
+ * @example
+ * ```ts
+ * parseContentLength('Content-Length: 128') // 128
+ * parseContentLength('Content-Type: application/json') // undefined
+ * ```
+ */
+export declare function parseContentLength(header: string): number | undefined;
+
+/**
+ * Answers claims through resident TypeScript, Oxlint, and Vitest stages.
+ *
+ * @remarks
+ * Construction resolves the target workspace's toolchain and begins warming every stage. The boot
+ * controls mutate imported dependencies and refuse service unless the type and runtime stages
+ * report their respective changes. One queue per stage admits inspections in arrival order, one at
+ * a time, so a stage never serves two claims at once and the deadline covers active work rather
+ * than queue wait. Each active stage inspection has a coordinator-owned deadline. An expiry at any
+ * stage abandons that stage and replaces it before the next queued inspection begins, so one slow
+ * claim costs that claim rather than the process. A failed boot is replaced the same way: the next
+ * claim runs the controls again rather than inheriting a refusal.
+ *
+ * @example
+ * ```ts
+ * const probe = new Probe({ workspace: '/srv/checkout' })
+ * const verdict = await probe.prove(claim)
+ * await probe.destroy()
+ * ```
+ */
+export declare class Probe implements ProbeInterface {
+    #private;
+    /**
+     * Resolves the target toolchain and starts warming the resident stages.
+     *
+     * @param options - Workspace, deadline, and initial observation hooks
+     */
+    constructor(options?: ProbeOptions);
+    get emitter(): EmitterInterface<ProbeEventMap>;
+    get toolchain(): Toolchain;
+    prove(claim: Claim): Promise<Verdict>;
+    destroy(): Promise<void>;
+}
+
+/**
+ * Serves one probe over this process's Model Context Protocol stdio transport.
+ *
+ * @remarks
+ * Construction creates the probe, publishes the `prove` tool, and binds the dual-era dispatcher to
+ * the stdio transport. The probe begins warming there, so a harness that spawns the entry pays
+ * arming while its client is still handshaking.
+ *
+ * `start` seizes standard input and registers the signals a harness ends a child with, and records
+ * whether standard input was already flowing. Every listener it attaches is held as a field, and
+ * `destroy` removes exactly those by reference, so a listener a host registers while this server is
+ * serving is still attached and still fires afterwards. The transport reads a stream this server
+ * owns rather than this process's standard input, which is what makes that possible: the
+ * transport's own listeners land on that stream, and the only listeners this server ever puts on
+ * `process.stdin` are the `data`, `close`, and `error` forwarders into it. `destroy` pauses the
+ * stream only when this server is what set it flowing and nothing else is reading it, so a process
+ * that outlives this server reads its own standard input again and receives its own signals.
+ * Teardown removes the signal handlers first: it takes seconds when a boot is in flight, and a
+ * harness that signals again means to kill rather than to queue.
+ *
+ * @example
+ * ```ts
+ * const server = new ProbeServer({ workspace: process.cwd() })
+ * server.start()
+ * await server.destroy()
+ * ```
+ */
+export declare class ProbeServer implements ProbeServerInterface {
+    #private;
+    /**
+     * Creates the probe this server publishes and binds it to this process's stdio transport.
+     *
+     * @param options - Workspace, deadline, and initial observation hooks for the probe it creates
+     */
+    constructor(options?: ProbeOptions);
+    start(): void;
+    destroy(): Promise<void>;
+}
+
+/**
+ * Serves one probe over this process's Model Context Protocol stdio transport.
+ *
+ * @remarks
+ * The server owns the process it runs in. `start` seizes standard input and standard output for
+ * the transport and registers the termination handlers a harness signals, so a host that starts one
+ * has already given the process to it. `destroy` reverses all of that and tears the probe down with
+ * it, which is why there is no verb that stops serving and leaves the resident engines running: a
+ * probe nothing is reading from holds its resident tools for nobody.
+ *
+ * @example
+ * ```ts
+ * const server = new ProbeServer({ workspace: process.cwd() })
+ * server.start()
+ * await server.destroy()
+ * ```
+ */
+export declare interface ProbeServerInterface {
+    /**
+     * Serves the probe over this process's standard input and output.
+     *
+     * @remarks
+     * Reads newline-delimited JSON requests from standard input, and answers a `SIGINT` or a
+     * `SIGTERM` by destroying the server. Calling this on a server already serving does nothing.
+     * Calling it after teardown begins throws a claimant-owned `destroyed` failure.
+     *
+     * @returns Nothing
+     * @throws When this call comes after teardown begins
+     */
+    start(): void;
+    /**
+     * Releases the transport, the process listeners, and the probe behind them.
+     *
+     * @remarks
+     * Settling is idempotent: a call made while teardown is running joins it and returns the same
+     * promise, and a call made afterwards returns that settled promise. The server removes exactly the
+     * listeners it attached, holding each one as a field rather than choosing by absence from a
+     * capture, so a host that keeps running after this call reads its own standard input again and
+     * receives its own signals, and a listener the host registered while
+     * the server was serving is still attached and still fires. That covers the stream's flow as
+     * well as its listeners: standard input is left flowing when it was already flowing before
+     * `start` and when something else is reading it at release, and a stream nothing had read yet
+     * and nothing else reads is paused.
+     *
+     * @returns A promise that settles after the probe releases its resident engines
+     */
+    destroy(): Promise<void>;
+}
+
+/**
+ * Reads one installed package manifest from the target workspace.
+ *
+ * @param workspace - The target workspace root
+ * @param name - The installed package name
+ * @returns The manifest's absolute path and parsed record
+ * @throws When the package cannot be resolved, read, parsed, or does not publish a record manifest
+ *
+ * @example
+ * ```ts
+ * const manifest = readWorkspaceManifest(process.cwd(), 'typescript')
+ * console.log(manifest.contents.version)
+ * ```
+ */
+export declare function readWorkspaceManifest(workspace: string, name: string): WorkspaceManifest;
+
+/**
+ * Projects an absolute tool path into the workspace-relative form issues expose.
+ *
+ * @param workspace - The target workspace root
+ * @param file - The path a tool reported
+ * @returns A forward-slash workspace-relative path
+ *
+ * @example
+ * ```ts
+ * relativeWorkspaceFile('/srv/checkout', '/srv/checkout/src/core/greeting.ts')
+ * // 'src/core/greeting.ts'
+ * ```
+ */
+export declare function relativeWorkspaceFile(workspace: string, file: string): string;
+
+/**
+ * Removes every listener one emitter gained for the captured events since its capture.
+ *
+ * @remarks
+ * Compares identity rather than name, so a listener whose name a dependency changes between
+ * releases is still recognized and a listener that merely shares a name is still left alone. A
+ * listener the capture already held survives, and a listener the capture held that has since been
+ * removed is not restored.
+ *
+ * A gain is not evidence of who caused it, so this reads every gain as the callee's. Call it only
+ * across a window nothing else can attach in — a synchronous call, or a call whose handlers land
+ * before its first await and that is released as it returns — because a listener anyone else
+ * attaches inside that window is removed with the rest. Where a caller cannot promise that window,
+ * hold each handler as a field and remove it by reference instead of capturing at all.
+ *
+ * @param emitter - The emitter to release
+ * @param capture - The listeners the emitter carried at capture time
+ * @returns Nothing
+ *
+ * @example
+ * ```ts
+ * const capture = captureListeners(process, ['SIGTERM'])
+ * process.on('SIGTERM', () => {})
+ * releaseListeners(process, capture)
+ * process.listenerCount('SIGTERM') === capture.get('SIGTERM')?.length // true
+ * ```
+ */
+export declare function releaseListeners(emitter: EventEmitter, capture: ListenerCapture): void;
+
+/**
+ * Resolves a package's portable JavaScript binary from the target workspace.
+ *
+ * @param workspace - The target workspace root
+ * @param name - The installed package name and binary key
+ * @returns The absolute JavaScript entry named by the package's `bin` field
+ * @throws When the package does not publish a binary under the requested name
+ *
+ * @example
+ * ```ts
+ * relativeWorkspaceFile(process.cwd(), resolveWorkspaceBinary(process.cwd(), 'oxlint'))
+ * // 'node_modules/oxlint/bin/oxlint'
+ * resolveWorkspaceBinary(process.cwd(), 'typescript')
+ * // throws: typescript does not publish the typescript binary
+ * ```
+ */
+export declare function resolveWorkspaceBinary(workspace: string, name: string): string;
+
+/**
+ * Resolves a path inside a target workspace and rejects traversal outside it.
+ *
+ * @remarks
+ * A native `ENAMETOOLONG` or NUL-byte `ERR_INVALID_ARG_VALUE` fault is a claimant refusal. This
+ * classifies the fault, not the author: a workspace nested deeply enough that this package's short
+ * generated names overflow the host limit also reads as a claimant refusal.
+ *
+ * @param workspace - The target workspace root
+ * @param target - A workspace-relative path
+ * @param mutate - If `true`, refuses a symbolic link in an existing descendant; if `false`,
+ * resolves lexically. Default: `false`
+ * @returns The absolute contained path
+ * @throws When the path resolves outside the workspace, mutation would cross a symbolic link, or
+ * the target tree cannot be inspected
+ *
+ * @example
+ * ```ts
+ * resolveWorkspaceFile('/srv/checkout', 'src/core/greeting.ts')
+ * // '/srv/checkout/src/core/greeting.ts'
+ * resolveWorkspaceFile('/srv/checkout', '../secrets.env')
+ * // throws: Path escapes the workspace: ../secrets.env
+ * ```
+ */
+export declare function resolveWorkspaceFile(workspace: string, target: string, mutate?: boolean): string;
+
+/**
+ * Resolves one installed module from the target workspace.
+ *
+ * @param workspace - The target workspace root
+ * @param specifier - The module specifier to resolve
+ * @returns The installed module entry path
+ * @throws When the workspace does not install the module
+ *
+ * @example
+ * ```ts
+ * resolveWorkspaceModule(process.cwd(), 'typescript/package.json') ===
+ * 	readWorkspaceManifest(process.cwd(), 'typescript').path // true
+ * ```
+ */
+export declare function resolveWorkspaceModule(workspace: string, specifier: string): string;
+
+/**
+ * Inspects tests through one resident Vitest service from the target workspace.
+ *
+ * @remarks
+ * Construction starts Vitest with the threads pool and instruments each inline or function-declared
+ * project with a Vite plugin that reads the active inspection's candidate overlay. A selected
+ * string-declared project reports a workspace issue because its configuration carries no runtime
+ * overlay plugin. Every inspection writes one fresh sibling specification, invalidates each
+ * workspace module whose disk content or candidate revision changed, runs that specification,
+ * evicts its result, and deletes the file. Clearing the overlay makes the next snapshot differ from
+ * the candidate revision, so the next inspection invalidates that module and reads disk again.
+ *
+ * Vite retains one unresolved URL for every specification path, so the stage replaces its whole
+ * Vitest service after 64 specifications rather than deleting from each map that service owns. Any
+ * bound holds the retention flat, because the replacement releases everything the instance held,
+ * and 64 is the value chosen. The inspection that crosses the bound pays the replacement
+ * synchronously: it closes the resident service and warms a new one before it runs. On 2026-08-20,
+ * over this package's own workspace on the host `guides/probe.md` § Cost names, two runs of 66
+ * inspections put that one at 480 ms and 269 ms against median inspections of 156 ms and 155 ms, so
+ * budget one call in 64 at 110 ms to 330 ms above the rest.
+ *
+ * Every issue this stage emits names its party, and the stage emits an issue for every party
+ * `Party` declares. An `origin: 'claimant'` issue is a failure Vitest reported about the candidate.
+ * An `origin: 'workspace'` issue names the target tree: a project the root configuration declares
+ * as a path string, into which the stage can install no overlay, and a specification path that
+ * crosses a symbolic link, whose existing components this host cannot inspect, or whose directory
+ * the target tree blocks probe from creating. An `origin: 'instrument'` issue names this package's
+ * own machinery: a specification it could not write after its directory exists, or one it could
+ * not run, evict, or delete, in each case for a reason the target tree does not own, and a run
+ * that reported no test. An unmapped caller test and a test whose named project is absent are claimant failures with
+ * `code: 'missing'`, thrown rather than reported, because a test that never ran is no evidence
+ * about the candidate.
+ *
+ * The write path's physical-containment guarantee covers the claim inputs and the target tree as
+ * inspected. A concurrent process that mutates a path component between the final inspection and
+ * the write is outside that guarantee.
+ *
+ * @example
+ * ```ts
+ * const stage = new RuntimeStage('/srv/checkout')
+ * const check = await stage.inspect(subject)
+ * await stage.destroy()
+ * ```
+ */
+export declare class RuntimeStage implements StageInterface {
+    #private;
+    /**
+     * Starts warming the target workspace's Vitest service.
+     *
+     * @param workspace - The target workspace root. Default: the current working directory
+     */
+    constructor(workspace?: string);
+    get stage(): Stage_2;
+    get progress(): number;
+    inspect(subject: Case_2): Promise<Check_2>;
+    destroy(): Promise<void>;
+}
+
+/**
+ * Inspects one case with a resident workspace tool.
+ *
+ * @remarks
+ * Warming begins at construction. The `inspect` method awaits that one warm operation and reuses
+ * the resulting tool across calls. A stage serves one inspection at a time and admits none itself.
+ * Await an inspection before starting the next one, or admit through one queue per stage the way
+ * `Probe` does: a second concurrent call reaches the same resident tool and the same overlay,
+ * document, and specification state the first is still using. A stage never holds a later
+ * inspection behind an earlier one, so a caller that abandons an inspection at its own deadline
+ * can still use the stage. The `destroy` method permanently tears the stage down and releases
+ * every resource it owns.
+ *
+ * @example
+ * ```ts
+ * const check = await stage.inspect(subject)
+ * console.log(check.stage)
+ * await stage.destroy()
+ * ```
+ */
+export declare interface StageInterface {
+    /** The inspection this resident stage performs. */
+    readonly stage: Stage;
+    /**
+     * Claimant-owned progress the coordinator compares with its inspection snapshot.
+     *
+     * @remarks
+     * When claimant-owned work is admitted, raise `progress` before awaiting its result. When this
+     * stage later performs stage-owned awaited work, return `progress` to its pre-inspection reading
+     * before that work starts. `RuntimeStage` does this before eviction and cleanup, so an expiry
+     * during that work reads level with the coordinator's snapshot and is attributed to the
+     * instrument rather than to the claimant.
+     */
+    readonly progress: number;
+    /**
+     * Inspects one case.
+     *
+     * @param subject - The candidate drafts and test to inspect
+     * @returns One outcome for this stage
+     * @throws When the resident tool cannot start or has already been destroyed
+     */
+    inspect(subject: Case): Promise<Check>;
+    /**
+     * Tears down the resident tool and releases its resources.
+     *
+     * @remarks
+     * A stage abandons every inspection it holds rather than waiting behind one, so teardown never
+     * waits for an inspection to return. An abandoned inspection rejects, either at the stage's own
+     * guard or as the owned tool closes. Teardown is bounded whatever the resident tool does: a tool
+     * that answers neither its warming exchange nor its ending is signalled and released at the
+     * stage's own deadline. A coordinator replaces a stage whose worker no longer returns because
+     * teardown neither waits for an inspection nor waits past that deadline.
+     *
+     * @returns A promise that settles after the resident tool releases its resources
+     */
+    destroy(): Promise<void>;
+}
+
+/**
+ * Inspects TypeScript source through resident language services from the target workspace.
+ *
+ * @remarks
+ * Construction starts loading the workspace's compiler and warming one service per project the
+ * workspace declares. A candidate draft is checked against the project a call names, or
+ * against its own scoped environment project when a call names none, while the test uses the root
+ * project. Disk snapshots use their modification time as the service version so dependency edits
+ * cannot leave a warm answer stale. Candidate text lives in an overlay the inspection owns, and
+ * the language-service host answers existence, reads, and versions from it, so a candidate that
+ * exists only as text is importable and a candidate that shadows a disk file is checked as the
+ * text the case supplied. A project outside the declared set holds one recycled slot, so a caller
+ * varying the project cannot grow the resident set. A language service checks one candidate
+ * synchronously, so the stage hands the host's event loop back at each candidate boundary: a
+ * caller's deadline is answered within one candidate's check rather than after the whole
+ * inspection, and an inspection abandoned at that deadline stops at the next boundary.
+ *
+ * @example
+ * ```ts
+ * const stage = new TypeStage('/srv/checkout')
+ * const check = await stage.inspect(subject, 'configs/src/tsconfig.core.json')
+ * await stage.destroy()
+ * ```
+ */
+export declare class TypeStage implements TypeStageInterface {
+    #private;
+    /**
+     * Starts warming the target workspace's TypeScript service.
+     *
+     * @param workspace - The target workspace root. Default: the current working directory
+     */
+    constructor(workspace?: string);
+    get stage(): Stage_2;
+    get progress(): number;
+    /**
+     * Inspects one case, against a caller-named project where the caller names one.
+     *
+     * @remarks
+     * The `project` parameter is this stage's own, not the stage contract's: the lint and runtime
+     * stages read no project, so `StageInterface` declares one parameter and every caller that
+     * needs this one holds a `TypeStage`.
+     *
+     * @param subject - The candidate drafts and test to inspect
+     * @param project - The workspace-relative TypeScript project the candidate drafts are checked
+     * against. Default: the scoped project each candidate path infers
+     * @returns One outcome for this stage
+     * @throws When the resident compiler cannot start or the stage has already been destroyed
+     */
+    inspect(subject: Case_2, project?: string): Promise<Check_2>;
+    /**
+     * Resolves one project to the path and digest this stage applies for it.
+     *
+     * @remarks
+     * Reads the parse this stage itself applies, filling its cache when the project is not already
+     * resident, so the reported digest is the configuration the inspection is judged under rather
+     * than a second parse a caller ran. The returned record is a value copy, so a later eviction
+     * does not move it.
+     *
+     * @param project - The workspace-relative TypeScript project to resolve
+     * @returns The resolved workspace-relative path and the digest of its compiler options
+     * @throws When the project escapes the workspace, cannot be parsed, or the stage has already
+     * been destroyed
+     */
+    resolve(project: string): Promise<Project_2>;
+    destroy(): Promise<void>;
+}
+
+/**
+ * Inspects TypeScript source against a caller-named project and reports what that project is.
+ *
+ * @remarks
+ * The type stage carries members the shared stage contract cannot: the lint and runtime stages
+ * read no project, so a project parameter and a project lookup belong here rather than on
+ * `StageInterface`.
+ *
+ * @example
+ * ```ts
+ * const project = await stage.resolve('configs/src/tsconfig.core.json')
+ * const check = await stage.inspect(subject, project.path)
+ * ```
+ */
+export declare interface TypeStageInterface extends StageInterface {
+    /**
+     * Inspects one case, against a caller-named project where the caller names one.
+     *
+     * @param subject - The candidate drafts and test to inspect
+     * @param project - The workspace-relative TypeScript project the candidate drafts are checked
+     * against. Default: the scoped project each candidate path infers
+     * @returns One outcome for this stage
+     * @throws When the resident compiler cannot start or the stage has already been destroyed
+     */
+    inspect(subject: Case, project?: string): Promise<Check>;
+    /**
+     * Resolves one project to the path and digest the stage applies for it.
+     *
+     * @param project - The workspace-relative TypeScript project to resolve
+     * @returns The resolved workspace-relative path and the digest of its compiler options
+     * @throws When the project escapes the workspace, cannot be parsed, or the stage has already
+     * been destroyed
+     */
+    resolve(project: string): Promise<Project>;
+}
+
+/**
+ * Carries one parsed package manifest and the path it came from.
+ *
+ * @example
+ * ```ts
+ * const manifest: WorkspaceManifest = {
+ * 	path: '/srv/checkout/node_modules/typescript/package.json',
+ * 	contents: { version: '6.0.3' },
+ * }
+ * ```
+ */
+export declare interface WorkspaceManifest {
+    /** Absolute path of the package manifest. */
+    readonly path: string;
+    /** Parsed manifest record. */
+    readonly contents: Readonly<Record<string, unknown>>;
+}
+
+export { }