@orkestrel/probe 0.0.12 → 0.0.13

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

@@ -1,20 +1,17 @@
-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 { Case } from '@orkestrel/probe';
+import type { Check } from '@orkestrel/probe';
+import type { Claim } from '@orkestrel/probe';
+import type { EmitterInterface } from '@orkestrel/emitter';
+import type { EventEmitter } from 'node:events';
+import type { Issue } from '@orkestrel/probe';
+import type { LSPRange } from '@orkestrel/lsp';
+import type { ProbeEventMap } from '@orkestrel/probe';
+import type { ProbeInterface } from '@orkestrel/probe';
+import type { ProbeOptions } from '@orkestrel/probe';
+import type { Project } from '@orkestrel/probe';
+import type { Stage } from '@orkestrel/probe';
+import type { Toolchain } from '@orkestrel/probe';
+import type { Verdict } from '@orkestrel/probe';
 import type * as VitestNode from 'vitest/node';
 
 /**
@@ -52,6 +49,27 @@ export declare function buildRevisionPath(workspace: string, path: string, revis
  */
 export declare function captureListeners(emitter: EventEmitter, events: readonly string[]): ListenerCapture;
 
+/**
+ * Collects every regular file a target workspace holds, skipping the trees no inspection reads.
+ *
+ * @remarks
+ * Skips a directory named `.git`, `dist`, or `node_modules` at any depth, and the directory
+ * {@link TYPE_MIRROR} names, which would otherwise carry this package's own mirror into the walk. A
+ * directory this host cannot list is skipped rather than raised, so one unreadable directory in a
+ * consumer's tree is not a reason to refuse the whole walk. A symbolic link is not carried, whether
+ * it names a file or a directory, so a file reached only through one is absent from the result; a
+ * `Dirent` that is neither a directory nor a regular file is skipped the same way.
+ *
+ * @param workspace - The target workspace root
+ * @returns The absolute path of every regular file the walk found
+ *
+ * @example
+ * ```ts
+ * collectWorkspaceFiles(process.cwd()).some((path) => path.endsWith('package.json')) // true
+ * ```
+ */
+export declare function collectWorkspaceFiles(workspace: string): readonly string[];
+
 /**
  * Computes the canonical digest of one value as it stands in a target workspace.
  *
@@ -86,6 +104,34 @@ export declare function computeDigest(workspace: string, value: unknown): string
  */
 export declare function describeUnknown(value: unknown): string;
 
+/**
+ * Carries one diagnostic line a compiler run reported, in this package's own coordinates.
+ *
+ * @remarks
+ * `path` and `range` are absent together, because a diagnostic the compiler reports about a
+ * project rather than about a file carries no location. `path` is spelled as the compiler printed
+ * it, relative to the directory the run started in. `range` holds the zero-based UTF-16 point the
+ * compiler reported: the plain-text output carries a start position and no extent, so `end` equals
+ * `start`. `message` is the diagnostic text, elaboration lines joined by newlines.
+ *
+ * @example
+ * ```ts
+ * const diagnostic: Diagnostic = {
+ * 	path: 'src/core/greeting.ts',
+ * 	range: { start: { line: 0, character: 13 }, end: { line: 0, character: 13 } },
+ * 	message: "Type 'string' is not assignable to type 'number'.",
+ * }
+ * ```
+ */
+export declare interface Diagnostic {
+    /** Names the file the compiler reported against, or is absent for a project diagnostic. */
+    readonly path?: string;
+    /** Holds the zero-based UTF-16 point the compiler reported, or is absent with `path`. */
+    readonly range?: LSPRange;
+    /** Holds the diagnostic text, with every elaboration line joined by a newline. */
+    readonly message: string;
+}
+
 /**
  * Reports whether one path resolves outside the root it is read against.
  *
@@ -112,6 +158,48 @@ export declare function describeUnknown(value: unknown): string;
  */
 export declare function escapesRoot(root: string, target: string): boolean;
 
+/**
+ * Carries what one spawned workspace command reported when it closed.
+ *
+ * @remarks
+ * `stdout` and `stderr` mirror the POSIX stream names the child wrote to. `status` is the exit
+ * code, and it is absent when a signal ended the child, which is what teardown does to a run it
+ * abandons. A compiler's exit code is not its verdict — the majors this package supports disagree
+ * on it — so read the diagnostics the streams carry rather than this number.
+ *
+ * @example
+ * ```ts
+ * const execution: Execution = { status: 0, stdout: '{}\n', stderr: '' }
+ * ```
+ */
+export declare interface Execution {
+    /** Holds the exit code, or is absent when a signal ended the child. */
+    readonly status?: number;
+    /** Holds everything the child wrote to its standard output. */
+    readonly stdout: string;
+    /** Holds everything the child wrote to its standard error. */
+    readonly stderr: string;
+}
+
+/**
+ * Filters one issue list to the distinct issues it carries, in the order they arrived.
+ *
+ * @remarks
+ * A stage that reads one candidate through more than one tool run reports that candidate's
+ * diagnostic once per run. Two issues are the same issue when their party, path, message, and range
+ * all agree, because those are every value an issue carries.
+ *
+ * @param issues - The issues to filter
+ * @returns The distinct issues, in the order the list carried them
+ *
+ * @example
+ * ```ts
+ * const issue: Issue = { origin: 'claimant', path: 'src/core/greeting.ts', message: 'not assignable' }
+ * filterUniqueIssues([issue, { ...issue }]).length // 1
+ * ```
+ */
+export declare function filterUniqueIssues(issues: readonly Issue[]): readonly Issue[];
+
 /**
  * Names every draft member of a claim-shaped value whose `path` this package's guard refuses.
  *
@@ -145,9 +233,9 @@ export declare function escapesRoot(root: string, target: string): boolean;
 export declare function findRefusedPaths(value: unknown): readonly string[];
 
 /**
- * Guards one resident-stage operation with the stage failure contract.
+ * Guards one stage operation with the stage failure contract.
  *
- * @param stage - The resident stage serving the operation
+ * @param stage - The stage serving the operation
  * @param operation - The operation to settle
  * @returns The operation's fulfilled value
  * @throws The original `ProbeError`, or an instrument-owned malformed failure retaining the cause
@@ -334,9 +422,9 @@ export declare class LintStage implements LintStageInterface {
      * @param workspace - The target workspace root. Default: the current working directory
      */
     constructor(workspace?: string);
-    get stage(): Stage_2;
+    get stage(): Stage;
     get progress(): number;
-    inspect(subject: Case_2, options?: InspectionOptions): Promise<Check_2>;
+    inspect(subject: Case, options?: InspectionOptions): Promise<Check>;
     destroy(): Promise<void>;
 }
 
@@ -368,6 +456,11 @@ export declare interface LintStageInterface extends StageInterface {
      * @returns One outcome for this stage
      * @throws When the caller supplies no bound, when the resident language server cannot start, or
      * when the stage has already been destroyed
+     *
+     * @example
+     * ```ts
+     * const check = await stage.inspect(subject, { signal: AbortSignal.timeout(30_000) })
+     * ```
      */
     inspect(subject: Case, options?: InspectionOptions): Promise<Check>;
 }
@@ -392,22 +485,44 @@ export declare interface LintStageInterface extends StageInterface {
 export declare type ListenerCapture = ReadonlyMap<string, readonly Function[]>;
 
 /**
- * Loads one installed tool module from a target workspace.
+ * Loads the installed `vitest/node` module from a target workspace.
+ *
+ * @remarks
+ * The only tool this package drives in process. The compiler is a process this package spawns
+ * rather than a module it loads, so `typescript` is resolved through {@link resolveWorkspaceBinary}
+ * instead.
  *
  * @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
+ * @returns The installed `vitest/node` module
+ * @throws When the workspace cannot load `vitest/node`
  *
  * @example
  * ```ts
- * const typescript = loadWorkspaceModule(process.cwd(), 'typescript')
- * console.log(typescript.version)
+ * const vitest = loadWorkspaceVitest(process.cwd())
+ * typeof vitest.createVitest === 'function' // true
  * ```
  */
-export declare function loadWorkspaceModule(workspace: string, specifier: 'typescript'): typeof TypeScript;
+export declare function loadWorkspaceVitest(workspace: string): typeof VitestNode;
 
-export declare function loadWorkspaceModule(workspace: string, specifier: 'vitest/node'): typeof VitestNode;
+/**
+ * Reports whether the host that wrote one file is still running.
+ *
+ * @remarks
+ * Signal 0 delivers nothing and reports reachability alone. A process this one may not signal
+ * reports `EPERM` and reads as running, and a non-positive identity names a process group rather
+ * than a process, so both answer true: the safe direction is to keep a file this package cannot
+ * account for.
+ *
+ * @param id - The process id a file's own revision names
+ * @returns True if that process is running or cannot be judged; false otherwise
+ *
+ * @example
+ * ```ts
+ * matchesLiveProcess(process.pid) // true
+ * matchesLiveProcess(0) // true
+ * ```
+ */
+export declare function matchesLiveProcess(id: number): boolean;
 
 /**
  * Reports whether a path is a workspace module Vitest can cache.
@@ -447,12 +562,12 @@ export declare function normalizePath(path: string): string;
  * 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.
+ * `tsc --showConfig` spells a path relative to the project file, so a printed record carries an
+ * absolute path only where a project itself declares one. Rewriting a contained absolute path to
+ * its relative form keeps one commit checked out at two roots reading to one digest. 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 compiler's own and it differs between the supported
+ * majors, so sorting removes a difference that means nothing.
  *
  * @param workspace - The target workspace root
  * @param value - The value to rewrite
@@ -467,7 +582,8 @@ export declare function normalizePath(path: string): string;
 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.
+ * Implements `OverlayInterface` over a private map from normalized absolute path to candidate text,
+ * minting at construction the `revision` a resident tool caches its answers against.
  *
  * @remarks
  * One overlay belongs to one inspection: the inspection creates it, records every candidate it
@@ -476,39 +592,32 @@ export declare function normalizeValue(workspace: string, value: unknown): unkno
  * 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.
  *
- * This overlay matches a lookup key the way the host its stage declares to its tool matches file
- * names. A host that resolves two spellings of one file name to one file leaves the tool holding
- * whichever spelling it met first — the disk one, where the file is on disk — and the tool asks
- * under that, so an overlay matching keys exactly answers nothing and the tool reads the committed
- * file instead. Mint the overlay with the sensitivity the stage declares, and one reading decides
- * both. The recorded spelling is what `paths` reports and what `covers` matches a directory
- * against, so a folded key never reaches the paths a tool is handed and containment stays an exact
- * comparison.
+ * A lookup key matches a recorded path exactly, after both pass through `normalizePath`, so a tool
+ * that reports its own paths with backslashes still reaches a candidate recorded with forward
+ * slashes. Case is never folded: the recorded spelling is what `paths` reports, what `covers`
+ * compares a directory against, and what `text` answers under. A stage whose tool resolves two
+ * spellings of one file name to one file therefore reports the path its tool served rather than
+ * matching the two spellings here.
  *
  * @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'))
+ * const path = '/srv/checkout/src/core/factories.ts'
+ * overlay.set(path, "export function createGreeting(): string {\n\treturn 'hi'\n}\n")
+ * console.log(overlay.text(path))
  * overlay.clear()
  * ```
  */
 export declare class Overlay implements OverlayInterface {
     #private;
-    /**
-     * Creates an empty candidate set under a fresh identity.
-     *
-     * @param options - Construction options
-     */
-    constructor(options?: OverlayOptions);
     get revision(): string;
     get paths(): readonly string[];
     /**
      * Records one candidate's text against the absolute path it stands in for.
      *
      * @remarks
-     * Recording a candidate under a path this overlay's own matching reads as one already recorded
-     * replaces that candidate, the way one file holds one text.
+     * Recording a candidate under a path this overlay already holds replaces that candidate, the way
+     * one file holds one text.
      *
      * @param path - The absolute path the candidate replaces
      * @param text - The candidate's full contents
@@ -529,9 +638,7 @@ export declare class Overlay implements OverlayInterface {
      * 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. Case is never folded here: this is a
-     * containment comparison, and it reads the recorded spelling whatever an overlay minted for a
-     * case-folding host matches its lookup keys by.
+     * 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
@@ -550,10 +657,10 @@ export declare class Overlay implements OverlayInterface {
  *
  * @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
+ * the set when the inspection ends, whatever ended it. The runtime stage's module resolver reads
+ * one candidate set through its adapter and is the stage that holds an overlay; the type stage
+ * writes each draft into its mirror and the lint stage opens each draft as a document, so neither
+ * holds one. 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`.
@@ -565,7 +672,8 @@ export declare class Overlay implements OverlayInterface {
  * @example
  * ```ts
  * const overlay: OverlayInterface = new Overlay()
- * overlay.set('/srv/checkout/src/core/greeting.ts', "export const GREETING = 'hi'\n")
+ * const path = '/srv/checkout/src/core/factories.ts'
+ * overlay.set(path, "export function createGreeting(): string {\n\treturn 'hi'\n}\n")
  * overlay.covers('/srv/checkout/src/core') // true
  * overlay.clear()
  * ```
@@ -581,6 +689,12 @@ export declare interface OverlayInterface {
      * @param path - The absolute path the candidate replaces
      * @param text - The candidate's full contents
      * @returns Nothing
+     *
+     * @example
+     * ```ts
+     * const path = '/srv/checkout/src/core/factories.ts'
+     * overlay.set(path, "export function createGreeting(): string {\n\treturn 'hi'\n}\n")
+     * ```
      */
     set(path: string, text: string): void;
     /**
@@ -600,32 +714,29 @@ export declare interface OverlayInterface {
      *
      * @param directory - The absolute directory path to check
      * @returns True if a candidate path sits beneath the directory; false otherwise
+     *
+     * @example
+     * ```ts
+     * const path = '/srv/checkout/src/core/factories.ts'
+     * overlay.set(path, "export function createGreeting(): string {\n\treturn 'hi'\n}\n")
+     * overlay.covers('/srv/checkout/src/core') // true
+     * ```
      */
     covers(directory: string): boolean;
     /**
      * Releases every candidate.
      *
      * @returns Nothing
+     *
+     * @example
+     * ```ts
+     * overlay.clear()
+     * overlay.paths // []
+     * ```
      */
     clear(): void;
 }
 
-/**
- * Carries the construction options `Overlay` accepts.
- *
- * @example
- * ```ts
- * const options: OverlayOptions = { sensitive: false }
- * ```
- */
-export declare interface OverlayOptions {
-    /**
-     * If `true`, a lookup key matches a recorded path exactly; if `false`, it matches with file-name
-     * case folded. Default: `true`
-     */
-    readonly sensitive?: boolean;
-}
-
 /**
  * Overwrites a file that already exists, through a descriptor that refuses a symbolic link at the
  * final component.
@@ -667,7 +778,50 @@ export declare interface OverlayOptions {
 export declare function overwriteFile(file: string, text: string): void;
 
 /**
- * Answers claims through resident TypeScript, Oxlint, and Vitest stages.
+ * Parses the configuration one compiler run printed for a TypeScript project.
+ *
+ * @remarks
+ * Reads what `tsc --showConfig` writes: a JSON record carrying the resolved `compilerOptions`
+ * beside the project's own file selection. `compilerOptions` is carried unvalidated, because a
+ * caller digests it rather than reading a member out of it. `files` and `include` are read only
+ * where the printed record carries one whose entries are all strings, so a member the compiler
+ * printed in another shape reads as absent rather than as an empty selection. Text that is not a
+ * JSON record, including the diagnostic the compiler prints for a project it refuses, yields
+ * `undefined`.
+ *
+ * @param text - The compiler's printed configuration
+ * @returns The project's resolved configuration, or `undefined` when the text carries no record
+ *
+ * @example
+ * ```ts
+ * parseProjectConfig('{"compilerOptions":{"strict":true}}')?.compilerOptions // { strict: true }
+ * parseProjectConfig("error TS5058: The specified path does not exist.") // undefined
+ * ```
+ */
+export declare function parseProjectConfig(text: string): ProjectConfig | undefined;
+
+/**
+ * Parses the process id one revision identity names.
+ *
+ * @remarks
+ * Every file and directory this package writes into a target carries the writing host's process id
+ * and a fresh UUID, joined by `-`. A sweep reads that id to decide whether the host that wrote the
+ * name is gone. The whole identity must match, so a name carrying anything else yields `undefined`
+ * and the sweep leaves what it found alone.
+ *
+ * @param revision - The revision identity a name carries
+ * @returns The process id it names, or `undefined` when the text is not a revision identity
+ *
+ * @example
+ * ```ts
+ * parseRevisionOwner('4821-1b4e28ba-2fa1-11d2-883f-0016d3cca427') // 4821
+ * parseRevisionOwner('4821-9f0c') // undefined
+ * ```
+ */
+export declare function parseRevisionOwner(revision: string): number | undefined;
+
+/**
+ * Answers claims through its type, lint, and runtime stages.
  *
  * @remarks
  * Construction resolves the target workspace's toolchain and begins warming every stage. The boot
@@ -679,17 +833,52 @@ export declare function overwriteFile(file: string, text: string): void;
  * 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
+ * @example The claim that earns a receipt
  * ```ts
- * const probe = new Probe({ workspace: '/srv/checkout' })
+ * import type { Claim } from '@orkestrel/probe'
+ * import { Probe } from '@orkestrel/probe/server'
+ *
+ * const claim: Claim = {
+ * 	project: 'configs/src/tsconfig.core.json',
+ * 	case: {
+ * 		files: [
+ * 			{
+ * 				path: 'src/core/factories.ts',
+ * 				text: "export function createGreeting(): string {\n\treturn 'hi'\n}\n",
+ * 			},
+ * 		],
+ * 		test: {
+ * 			path: 'tmp/probe/greeting.test.ts',
+ * 			text: "import { expect, test } from 'vitest'\nimport { createGreeting } from '../../src/core/factories.js'\ntest('greets', () => expect(createGreeting()).toBe('hi'))\n",
+ * 		},
+ * 	},
+ * 	control: {
+ * 		files: [
+ * 			{
+ * 				path: 'src/core/factories.ts',
+ * 				text: "export function createGreeting(): number {\n\treturn 'hi'\n}\n",
+ * 			},
+ * 		],
+ * 		test: {
+ * 			path: 'tmp/probe/greeting.test.ts',
+ * 			text: "import { expect, test } from 'vitest'\nimport { createGreeting } from '../../src/core/factories.js'\ntest('greets', () => expect(createGreeting()).toBe('hi'))\n",
+ * 		},
+ * 		stage: 'type',
+ * 		reason: 'a string returned as a number must not compile',
+ * 	},
+ * }
+ *
+ * const probe = new Probe({ workspace: process.cwd() })
  * const verdict = await probe.prove(claim)
+ * verdict.digest // 'fcb88a2dee987b8673c1fc7107979470'
+ * verdict.receipt // 'probe:fcb88a2dee987b8673c1fc7107979470:type:typescript@6.0.3:oxlint@1.82.0:vitest@4.1.11:configs/src/tsconfig.core.json@434f59254d58cf2683d453a26bd0d837'
  * await probe.destroy()
  * ```
  */
 export declare class Probe implements ProbeInterface {
     #private;
     /**
-     * Resolves the target toolchain and starts warming the resident stages.
+     * Resolves the target toolchain and starts warming every stage.
      *
      * @param options - Workspace, deadline, and initial observation hooks
      */
@@ -701,7 +890,9 @@ export declare class Probe implements ProbeInterface {
 }
 
 /**
- * Serves one probe over this process's Model Context Protocol stdio transport.
+ * Implements `ProbeServerInterface` over a `PassThrough` stream this server owns, binding the
+ * published `prove` tool and the dual-era dispatcher to this process's Model Context Protocol
+ * stdio transport.
  *
  * @remarks
  * Construction creates the probe, publishes the `prove` tool, and binds the dual-era dispatcher to
@@ -746,8 +937,8 @@ export declare class ProbeServer implements ProbeServerInterface {
  * 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.
+ * it, which is why there is no verb that stops serving and leaves the stages standing: a probe
+ * nothing is reading from holds its tools and its mirror for nobody.
  *
  * @example
  * ```ts
@@ -767,6 +958,12 @@ export declare interface ProbeServerInterface {
      *
      * @returns Nothing
      * @throws When this call comes after teardown begins
+     *
+     * @example
+     * ```ts
+     * const server = new ProbeServer({ workspace: process.cwd() })
+     * server.start()
+     * ```
      */
     start(): void;
     /**
@@ -783,11 +980,40 @@ export declare interface ProbeServerInterface {
      * `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
+     * @returns A promise that settles after the probe releases every stage's tool and mirror
      */
     destroy(): Promise<void>;
 }
 
+/**
+ * Carries what one TypeScript project resolved to, as the compiler itself printed it.
+ *
+ * @remarks
+ * The type stage reads this from `tsc --showConfig`, which prints the resolved options beside the
+ * project's own file selection. `compilerOptions` is the compiler's record and is carried
+ * unvalidated, because this package digests it rather than reading a member out of it. `files` is
+ * the selection the project resolved to, spelled relative to the project file, and `include` is
+ * present only where the project or a project it extends declares one. Every path is the
+ * compiler's own spelling, so a copy of the project file placed beside the original reads them
+ * unchanged.
+ *
+ * @example
+ * ```ts
+ * const config: ProjectConfig = {
+ * 	compilerOptions: { strict: true, rootDir: '../../src/core' },
+ * 	files: ['../../src/core/index.ts'],
+ * }
+ * ```
+ */
+export declare interface ProjectConfig {
+    /** Holds the compiler options the project resolved to, unvalidated. */
+    readonly compilerOptions: unknown;
+    /** Holds the files the project resolved to, or is absent when the compiler printed none. */
+    readonly files?: readonly string[];
+    /** Holds the file patterns the project declares, or is absent when it declares none. */
+    readonly include?: readonly string[];
+}
+
 /**
  * Reads the condition code a native fault carries.
  *
@@ -919,20 +1145,26 @@ export declare function releaseListeners(emitter: EventEmitter, capture: Listene
 /**
  * Resolves a package's portable JavaScript binary from the target workspace.
  *
+ * @remarks
+ * A package publishes its binaries under keys of its own choosing, and that key is often not the
+ * package name: `typescript` publishes `tsc`. Name the key as `command` wherever the two differ.
+ * Default: the package name.
+ *
  * @param workspace - The target workspace root
- * @param name - The installed package name and binary key
+ * @param name - The installed package name
+ * @param command - The `bin` key to read. Default: `name`
  * @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
+ * @throws When the package does not publish a binary under the requested key
  *
  * @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
+ * relativeWorkspaceFile(process.cwd(), resolveWorkspaceBinary(process.cwd(), 'typescript', 'tsc'))
+ * // 'node_modules/typescript/bin/tsc'
  * ```
  */
-export declare function resolveWorkspaceBinary(workspace: string, name: string): string;
+export declare function resolveWorkspaceBinary(workspace: string, name: string, command?: string): string;
 
 /**
  * Resolves a path inside a target workspace and rejects traversal outside it.
@@ -1044,24 +1276,72 @@ export declare class RuntimeStage implements StageInterface {
      * @param workspace - The target workspace root. Default: the current working directory
      */
     constructor(workspace?: string);
-    get stage(): Stage_2;
+    get stage(): Stage;
     get progress(): number;
-    inspect(subject: Case_2): Promise<Check_2>;
+    /**
+     * Inspects one case.
+     *
+     * @param subject - The candidate drafts and test to inspect
+     * @returns One outcome for this stage
+     * @throws When the workspace's own tool cannot start or has already been destroyed
+     */
+    inspect(subject: Case): Promise<Check>;
+    /**
+     * Tears down the resident tool or the mirror 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 stage's own 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 or the mirror releases its resources
+     */
     destroy(): Promise<void>;
 }
 
 /**
- * Inspects one case with a resident workspace tool.
+ * Scans the plain-text output of one compiler run into the diagnostics it reported.
  *
  * @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.
+ * Reads the shape `tsc --pretty false` prints: `path(line,column): error TSnnnn: message` for a
+ * diagnostic about a file, and `error TSnnnn: message` for one about a project. A line that carries
+ * neither prefix and begins with whitespace is an elaboration of the diagnostic above it and joins
+ * that message with a newline; any other line is skipped, so a runtime's own failure text yields no
+ * diagnostic and a caller reads that as the fault it is. The compiler counts lines and columns from
+ * one and columns in UTF-16 code units, so each location is lowered to the zero-based UTF-16 point
+ * `Diagnostic.range` fixes and `end` resolves to `start`, which is the extent this output carries.
+ * A warning reads as a diagnostic, because the workspace's own gate reports it the same way. The
+ * `TS\d+` token that follows `error` or `warning` is what recognizes the line; nothing is captured
+ * from it, because `Diagnostic` carries no field for it.
+ *
+ * @param text - The compiler's output
+ * @returns One record per reported diagnostic, in the compiler's own order
+ *
+ * @example
+ * ```ts
+ * scanDiagnostics("src/a.ts(1,14): error TS2322: Type 'string' is not assignable to type 'number'.")
+ * // [{ path: 'src/a.ts', range: { start: { line: 0, character: 13 }, end: { line: 0, character: 13 } }, message: "Type 'string' is not assignable to type 'number'." }]
+ * scanDiagnostics('error TS5058: The specified path does not exist.')
+ * // [{ message: 'The specified path does not exist.' }]
+ * ```
+ */
+export declare function scanDiagnostics(text: string): readonly Diagnostic[];
+
+/**
+ * Inspects one case with the workspace's own tool.
+ *
+ * @remarks
+ * Warming begins at construction. The `inspect` method awaits that one warm operation, which
+ * builds the resident tool or the mirror it reuses 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 or mirror 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
@@ -1071,7 +1351,7 @@ export declare class RuntimeStage implements StageInterface {
  * ```
  */
 export declare interface StageInterface {
-    /** Names the inspection this resident stage performs. */
+    /** Names the inspection this stage performs. */
     readonly stage: Stage;
     /**
      * Reports claimant-owned progress the coordinator compares with its inspection snapshot.
@@ -1089,41 +1369,58 @@ export declare interface StageInterface {
      *
      * @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
+     * @throws When the workspace's own tool cannot start or has already been destroyed
+     *
+     * @example
+     * ```ts
+     * const check = await stage.inspect(subject)
+     * console.log(check.stage, check.elapsed, check.issues.length)
+     * ```
      */
     inspect(subject: Case): Promise<Check>;
     /**
-     * Tears down the resident tool and releases its resources.
+     * Tears down the resident tool or the mirror 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
+     * guard or as the owned tool closes. Teardown is bounded whatever the stage's own 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
+     * @returns A promise that settles after the resident tool or the mirror releases its resources
      */
     destroy(): Promise<void>;
 }
 
 /**
- * Inspects TypeScript source through resident language services from the target workspace.
+ * Inspects TypeScript source by running the target workspace's own compiler over a mirror of it.
  *
  * @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.
+ * The compiler is a process this stage spawns rather than a module it loads, so nothing here holds
+ * a resident program and the host's event loop is free for the whole check. Construction sweeps a
+ * mirror an earlier host left behind, copies the workspace into a fresh one under
+ * {@link TYPE_MIRROR}, and builds each declared project's incremental state there, so the first
+ * inspection is warm.
+ *
+ * Every inspection refreshes the mirror by content digest, writes each candidate draft and the test
+ * at its mirrored declared path, and runs `tsc --noEmit --pretty false` once per distinct selected
+ * project. A draft therefore shadows the file it replaces: a consumer of that path is checked
+ * against the draft's text, and a draft importing a sibling draft resolves to the sibling draft.
+ * Nothing is written outside `tmp/`, and the workspace's own copy of a drafted file never moves.
+ *
+ * Each run reads a scratch project this stage writes beside the mirrored project it extends, so
+ * every relative path the project declares — its own `rootDir`, `include`, `paths`, and the
+ * projects it extends — resolves inside the mirror without being rewritten. The scratch adds the
+ * drafts as `files`, which the project's own `exclude` does not reach, and its incremental state
+ * lives in the mirror so reuse survives the refresh.
+ *
+ * The diagnostics decide the outcome, never the exit code, which the supported compiler majors
+ * disagree on. A diagnostic naming a project file, and one naming no file at all, is the target
+ * tree's own configuration fault and raises rather than reporting, unless the `.json` file is one
+ * the claim itself drafted; every other diagnostic is a claimant issue at the point the compiler
+ * reported, which is the extent the plain-text output carries.
  *
  * @example
  * ```ts
@@ -1135,12 +1432,12 @@ export declare interface StageInterface {
 export declare class TypeStage implements TypeStageInterface {
     #private;
     /**
-     * Starts warming the target workspace's TypeScript service.
+     * Resolves the target workspace's compiler and starts warming its mirror.
      *
      * @param workspace - The target workspace root. Default: the current working directory
      */
     constructor(workspace?: string);
-    get stage(): Stage_2;
+    get stage(): Stage;
     get progress(): number;
     /**
      * Inspects one case, against a caller-named project where the caller names one.
@@ -1154,24 +1451,25 @@ export declare class TypeStage implements TypeStageInterface {
      * @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
+     * @throws When the workspace refuses the mirror, when a project the run reads is malformed, or
+     * when the stage has already been destroyed
      */
-    inspect(subject: Case_2, project?: string): Promise<Check_2>;
+    inspect(subject: Case, project?: string): Promise<Check>;
     /**
      * 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.
+     * Reads the configuration the compiler itself prints for the project as the mirror holds it,
+     * refreshed from the workspace first on a cache miss, so the digest names the configuration the
+     * check applies. The reading is cached per project for the life of the stage, so a draft written
+     * afterward cannot 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
+     * @throws When the project escapes the workspace, when the compiler refuses it, or when the
+     * stage has already been destroyed
      */
-    resolve(project: string): Promise<Project_2>;
+    resolve(project: string): Promise<Project>;
     destroy(): Promise<void>;
 }
 
@@ -1181,7 +1479,8 @@ export declare class TypeStage implements TypeStageInterface {
  * @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`.
+ * `StageInterface`. `resolve` reads the compiler's own printed configuration for the workspace's
+ * copy of the project, so a claim's drafts never move the digest it reports.
  *
  * @example
  * ```ts
@@ -1197,7 +1496,13 @@ export declare interface TypeStageInterface extends StageInterface {
      * @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
+     * @throws When the workspace refuses the mirror, when a project the run reads is malformed, or
+     * when the stage has already been destroyed
+     *
+     * @example
+     * ```ts
+     * const check = await stage.inspect(subject, 'configs/src/tsconfig.core.json')
+     * ```
      */
     inspect(subject: Case, project?: string): Promise<Check>;
     /**
@@ -1205,8 +1510,14 @@ export declare interface TypeStageInterface extends StageInterface {
      *
      * @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
+     * @throws When the project escapes the workspace, when the compiler refuses it, or when the
+     * stage has already been destroyed
+     *
+     * @example
+     * ```ts
+     * const project = await stage.resolve('configs/src/tsconfig.core.json')
+     * console.log(project.path, project.digest)
+     * ```
      */
     resolve(project: string): Promise<Project>;
 }