@orkestrel/probe 0.0.6 → 0.0.9

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

@@ -202,6 +202,29 @@ export declare interface Inspection {
     readonly claim: Claim;
 }
 
+/**
+ * Carries the bound a caller holds over one stage inspection.
+ *
+ * @remarks
+ * `LintStageInterface.inspect` is the only inspection in this package that reads the signal. Its
+ * wait is a foreign language server's silence, and abandoning that wait would leave the client
+ * holding a pending diagnostics request. The type and runtime stages accept no options and honor no
+ * cancellation: a coordinator abandons an overrunning one and replaces it, which is what `Probe`
+ * does when its own deadline expires.
+ *
+ * Supply the signal a coordinator already armed rather than minting a second bound here. A bound
+ * minted beside the coordinator's races it, and which one answers then depends on scheduling.
+ *
+ * @example
+ * ```ts
+ * const options: InspectionOptions = { signal: AbortSignal.timeout(30_000) }
+ * ```
+ */
+export declare interface InspectionOptions {
+    /** Aborts the inspection's wait for the resident tool's answer. */
+    readonly signal: AbortSignal;
+}
+
 /**
  * Reports whether a fault means the host refuses the name a caller supplied for a file to create.
  *
@@ -243,13 +266,22 @@ export declare function isRefusedName(file: string, error: unknown): boolean;
  * 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.
+ * Construction starts the target workspace's Oxlint binary with its Language Server Protocol mode
+ * and hands the conversation to `@orkestrel/lsp`: `createStdioTransport` owns the child process and
+ * its bytes, and `createLSPClient` owns the framing, the request correlation, the capabilities this
+ * stage advertises, and the choice between pulled and pushed diagnostics. This stage owns the
+ * workspace, the candidate identity, and the projection from a diagnostic to an `Issue`.
+ *
+ * Each inspection opens the supplied text by URI, waits for the client's diagnostics, and closes the
+ * document without writing it to disk. The caller's own signal is what bounds that wait, so a server
+ * that admits a document and publishes nothing refuses the inspection when the caller's bound
+ * expires rather than holding it for the life of the process. This stage mints no bound of its own
+ * for the wait: a second one would race the caller's, and the answer would depend on scheduling.
  *
  * 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.
+ * ending waits for its `shutdown` reply, and the protocol leaves both answers to the server, so the
+ * client's deadline bounds each exchange and the transport's cooperative window takes the ending
+ * back with a signal when that window 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,
@@ -262,11 +294,11 @@ export declare function isRefusedName(file: string, error: unknown): boolean;
  * @example
  * ```ts
  * const stage = new LintStage('/srv/checkout')
- * const check = await stage.inspect(subject)
+ * const check = await stage.inspect(subject, { signal: AbortSignal.timeout(30_000) })
  * await stage.destroy()
  * ```
  */
-export declare class LintStage implements StageInterface {
+export declare class LintStage implements LintStageInterface {
     #private;
     /**
      * Starts warming the target workspace's Oxlint language server.
@@ -276,10 +308,42 @@ export declare class LintStage implements StageInterface {
     constructor(workspace?: string);
     get stage(): Stage_2;
     get progress(): number;
-    inspect(subject: Case_2): Promise<Check_2>;
+    inspect(subject: Case_2, options?: InspectionOptions): Promise<Check_2>;
     destroy(): Promise<void>;
 }
 
+/**
+ * Inspects one case under a bound the caller supplies.
+ *
+ * @remarks
+ * The lint stage carries a member the shared stage contract cannot. Its inspection waits for a
+ * foreign language server to publish, and only the caller knows how long that wait may run, so the
+ * bound belongs here rather than on `StageInterface`. The type and runtime stages read no signal
+ * and keep the shared one-argument `inspect`.
+ *
+ * `options` is optional because `StageInterface.inspect` accepts one argument and this contract
+ * extends it. An inspection that omits `options` is refused rather than served: a bound this stage
+ * minted for itself would race the coordinator's, and the client's own `timeout` covers the
+ * lifecycle exchanges alone.
+ *
+ * @example
+ * ```ts
+ * const check = await stage.inspect(subject, { signal: AbortSignal.timeout(30_000) })
+ * ```
+ */
+export declare interface LintStageInterface extends StageInterface {
+    /**
+     * Inspects one case, under the bound the caller supplies.
+     *
+     * @param subject - The candidate drafts and test to inspect
+     * @param options - The bound this inspection waits under
+     * @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
+     */
+    inspect(subject: Case, options?: InspectionOptions): Promise<Check>;
+}
+
 /**
  * Holds the listeners one emitter carried for a set of events at the moment it was captured.
  *
@@ -384,6 +448,15 @@ 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.
+ *
  * @example
  * ```ts
  * const overlay = new Overlay()
@@ -394,11 +467,21 @@ export declare function normalizeValue(workspace: string, value: unknown): unkno
  */
 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.
+     *
      * @param path - The absolute path the candidate replaces
      * @param text - The candidate's full contents
      * @returns Nothing
@@ -418,7 +501,9 @@ 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.
+     * 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.
      *
      * @param directory - The absolute directory path to check
      * @returns True if a candidate path sits beneath the directory; false otherwise
@@ -497,6 +582,22 @@ export declare interface OverlayInterface {
     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.
@@ -505,12 +606,18 @@ export declare interface OverlayInterface {
  * A containment walk and the write that follows it are separate calls, so a process that swaps the
  * final component between them decides where the bytes land. `writeFileSync` opens with the default
  * `w` flag, which follows a symbolic link at that component and creates the file when it is absent,
- * so the walk's reading does not bind the write. Opening `O_WRONLY | O_TRUNC | O_NOFOLLOW` moves
- * that decision into the call that writes: a link at the final component refuses the open, and the
+ * so the walk's reading does not bind the write. Opening `O_WRONLY | O_NOFOLLOW` moves that
+ * decision into the call that writes: a link at the final component refuses the open, and the
  * omitted `O_CREAT` fails `ENOENT` for a target that has gone since the walk saw it. This is the
  * mutating counterpart of the `wx` flag every create in this package uses. Which code the refusal
  * carries is the host's; Linux with Node v22.22.2 reported `ELOOP` on 2026-08-24.
  *
+ * Truncation runs through the held descriptor rather than through an `O_TRUNC` flag, so it reaches
+ * the file the open bound. A Windows host refuses the numeric `O_TRUNC` without `O_CREAT` outright:
+ * measured on 2026-08-26 on Windows 11 with Node v24.19.0 over NTFS, `openSync` reported `EINVAL`
+ * for `O_WRONLY | O_TRUNC` and for `O_RDWR | O_TRUNC` while `O_WRONLY` alone opened, and adding
+ * `O_CREAT` would trade that refusal for the create this function must never perform.
+ *
  * A directory component stays open, because Node exposes no descriptor-relative call to walk and
  * write through one set of descriptors. Where a host's Node build defines no `O_NOFOLLOW`, that flag
  * contributes nothing to the flag set and the final component is open on that host too.
@@ -531,20 +638,6 @@ export declare interface OverlayInterface {
  */
 export declare function overwriteFile(file: string, text: string): 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.
  *

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

@@ -202,6 +202,29 @@ export declare interface Inspection {
     readonly claim: Claim;
 }
 
+/**
+ * Carries the bound a caller holds over one stage inspection.
+ *
+ * @remarks
+ * `LintStageInterface.inspect` is the only inspection in this package that reads the signal. Its
+ * wait is a foreign language server's silence, and abandoning that wait would leave the client
+ * holding a pending diagnostics request. The type and runtime stages accept no options and honor no
+ * cancellation: a coordinator abandons an overrunning one and replaces it, which is what `Probe`
+ * does when its own deadline expires.
+ *
+ * Supply the signal a coordinator already armed rather than minting a second bound here. A bound
+ * minted beside the coordinator's races it, and which one answers then depends on scheduling.
+ *
+ * @example
+ * ```ts
+ * const options: InspectionOptions = { signal: AbortSignal.timeout(30_000) }
+ * ```
+ */
+export declare interface InspectionOptions {
+    /** Aborts the inspection's wait for the resident tool's answer. */
+    readonly signal: AbortSignal;
+}
+
 /**
  * Reports whether a fault means the host refuses the name a caller supplied for a file to create.
  *
@@ -243,13 +266,22 @@ export declare function isRefusedName(file: string, error: unknown): boolean;
  * 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.
+ * Construction starts the target workspace's Oxlint binary with its Language Server Protocol mode
+ * and hands the conversation to `@orkestrel/lsp`: `createStdioTransport` owns the child process and
+ * its bytes, and `createLSPClient` owns the framing, the request correlation, the capabilities this
+ * stage advertises, and the choice between pulled and pushed diagnostics. This stage owns the
+ * workspace, the candidate identity, and the projection from a diagnostic to an `Issue`.
+ *
+ * Each inspection opens the supplied text by URI, waits for the client's diagnostics, and closes the
+ * document without writing it to disk. The caller's own signal is what bounds that wait, so a server
+ * that admits a document and publishes nothing refuses the inspection when the caller's bound
+ * expires rather than holding it for the life of the process. This stage mints no bound of its own
+ * for the wait: a second one would race the caller's, and the answer would depend on scheduling.
  *
  * 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.
+ * ending waits for its `shutdown` reply, and the protocol leaves both answers to the server, so the
+ * client's deadline bounds each exchange and the transport's cooperative window takes the ending
+ * back with a signal when that window 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,
@@ -262,11 +294,11 @@ export declare function isRefusedName(file: string, error: unknown): boolean;
  * @example
  * ```ts
  * const stage = new LintStage('/srv/checkout')
- * const check = await stage.inspect(subject)
+ * const check = await stage.inspect(subject, { signal: AbortSignal.timeout(30_000) })
  * await stage.destroy()
  * ```
  */
-export declare class LintStage implements StageInterface {
+export declare class LintStage implements LintStageInterface {
     #private;
     /**
      * Starts warming the target workspace's Oxlint language server.
@@ -276,10 +308,42 @@ export declare class LintStage implements StageInterface {
     constructor(workspace?: string);
     get stage(): Stage_2;
     get progress(): number;
-    inspect(subject: Case_2): Promise<Check_2>;
+    inspect(subject: Case_2, options?: InspectionOptions): Promise<Check_2>;
     destroy(): Promise<void>;
 }
 
+/**
+ * Inspects one case under a bound the caller supplies.
+ *
+ * @remarks
+ * The lint stage carries a member the shared stage contract cannot. Its inspection waits for a
+ * foreign language server to publish, and only the caller knows how long that wait may run, so the
+ * bound belongs here rather than on `StageInterface`. The type and runtime stages read no signal
+ * and keep the shared one-argument `inspect`.
+ *
+ * `options` is optional because `StageInterface.inspect` accepts one argument and this contract
+ * extends it. An inspection that omits `options` is refused rather than served: a bound this stage
+ * minted for itself would race the coordinator's, and the client's own `timeout` covers the
+ * lifecycle exchanges alone.
+ *
+ * @example
+ * ```ts
+ * const check = await stage.inspect(subject, { signal: AbortSignal.timeout(30_000) })
+ * ```
+ */
+export declare interface LintStageInterface extends StageInterface {
+    /**
+     * Inspects one case, under the bound the caller supplies.
+     *
+     * @param subject - The candidate drafts and test to inspect
+     * @param options - The bound this inspection waits under
+     * @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
+     */
+    inspect(subject: Case, options?: InspectionOptions): Promise<Check>;
+}
+
 /**
  * Holds the listeners one emitter carried for a set of events at the moment it was captured.
  *
@@ -384,6 +448,15 @@ 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.
+ *
  * @example
  * ```ts
  * const overlay = new Overlay()
@@ -394,11 +467,21 @@ export declare function normalizeValue(workspace: string, value: unknown): unkno
  */
 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.
+     *
      * @param path - The absolute path the candidate replaces
      * @param text - The candidate's full contents
      * @returns Nothing
@@ -418,7 +501,9 @@ 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.
+     * 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.
      *
      * @param directory - The absolute directory path to check
      * @returns True if a candidate path sits beneath the directory; false otherwise
@@ -497,6 +582,22 @@ export declare interface OverlayInterface {
     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.
@@ -505,12 +606,18 @@ export declare interface OverlayInterface {
  * A containment walk and the write that follows it are separate calls, so a process that swaps the
  * final component between them decides where the bytes land. `writeFileSync` opens with the default
  * `w` flag, which follows a symbolic link at that component and creates the file when it is absent,
- * so the walk's reading does not bind the write. Opening `O_WRONLY | O_TRUNC | O_NOFOLLOW` moves
- * that decision into the call that writes: a link at the final component refuses the open, and the
+ * so the walk's reading does not bind the write. Opening `O_WRONLY | O_NOFOLLOW` moves that
+ * decision into the call that writes: a link at the final component refuses the open, and the
  * omitted `O_CREAT` fails `ENOENT` for a target that has gone since the walk saw it. This is the
  * mutating counterpart of the `wx` flag every create in this package uses. Which code the refusal
  * carries is the host's; Linux with Node v22.22.2 reported `ELOOP` on 2026-08-24.
  *
+ * Truncation runs through the held descriptor rather than through an `O_TRUNC` flag, so it reaches
+ * the file the open bound. A Windows host refuses the numeric `O_TRUNC` without `O_CREAT` outright:
+ * measured on 2026-08-26 on Windows 11 with Node v24.19.0 over NTFS, `openSync` reported `EINVAL`
+ * for `O_WRONLY | O_TRUNC` and for `O_RDWR | O_TRUNC` while `O_WRONLY` alone opened, and adding
+ * `O_CREAT` would trade that refusal for the create this function must never perform.
+ *
  * A directory component stays open, because Node exposes no descriptor-relative call to walk and
  * write through one set of descriptors. Where a host's Node build defines no `O_NOFOLLOW`, that flag
  * contributes nothing to the flag set and the final component is open on that host too.
@@ -531,20 +638,6 @@ export declare interface OverlayInterface {
  */
 export declare function overwriteFile(file: string, text: string): 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.
  *