@orkestrel/probe 0.0.10 → 0.0.12

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

@@ -29,9 +29,9 @@ import { StringShape } from '@orkestrel/contract';
  * ```
  */
 export declare interface Case {
-    /** The candidate drafts the test imports, in the order the claim supplies them. */
+    /** Holds the candidate drafts the test imports, in the order the claim supplies them. */
     readonly files: readonly Draft[];
-    /** The test that exercises those drafts. */
+    /** Holds the test that exercises those drafts. */
     readonly test: Draft;
 }
 
@@ -68,11 +68,11 @@ export declare const CASE_SHAPE: ObjectShape<{
  * ```
  */
 export declare interface Check {
-    /** The stage that produced this outcome. */
+    /** Names the stage that produced this outcome. */
     readonly stage: Stage;
-    /** Milliseconds the stage took. */
+    /** Holds the milliseconds the stage took. */
     readonly elapsed: number;
-    /** Every message the stage's tool reported, in the tool's own order. */
+    /** Holds every message the stage's tool reported, in the tool's own order. */
     readonly issues: readonly Issue[];
 }
 
@@ -114,11 +114,14 @@ export declare interface Check {
  * ```
  */
 export declare interface Claim {
-    /** Workspace-relative path of the TypeScript project the candidate drafts are checked against. */
+    /**
+     * Names the workspace-relative path of the TypeScript project the candidate drafts are checked
+     * against.
+     */
     readonly project: string;
-    /** The drafts and test the claim asserts about. */
+    /** Holds the drafts and test the claim asserts about. */
     readonly case: Case;
-    /** The negative control that must break, and where. */
+    /** Holds the negative control that must break, and where. */
     readonly control: Control;
 }
 
@@ -233,9 +236,9 @@ export declare function computeReceipt(verdict: Verdict, stage: Stage): string |
  * ```
  */
 export declare interface Control extends Case {
-    /** The stage this control must report issues at. */
+    /** Names the stage this control must report issues at. */
     readonly stage: Stage;
-    /** Why the control fails there, in the claimant's own words. */
+    /** Explains why the control fails there, in the claimant's own words. */
     readonly reason: string;
 }
 
@@ -298,9 +301,9 @@ export declare function createDestroyedError(subject: string): ProbeError;
  * ```
  */
 export declare interface Draft {
-    /** Workspace-relative path the stages resolve the text against. */
+    /** Names the workspace-relative path the stages resolve the text against. */
     readonly path: string;
-    /** The file's full contents. */
+    /** Holds the file's full contents. */
     readonly text: string;
 }
 
@@ -374,6 +377,46 @@ export declare function formatCheck(check: Check): string;
  */
 export declare function formatIssue(issue: Issue): string;
 
+/**
+ * Renders the closing line a rendered verdict ends with: the receipt it earned, or its absence.
+ *
+ * @remarks
+ * One implementation serves every rendering of that line, so the line a reader quotes off a whole
+ * verdict and the line a bounded reply falls back to cannot drift apart.
+ *
+ * @param verdict - The verdict whose `receipt` decides the line
+ * @returns `receipt <token>` when the verdict carries a receipt, and `no receipt` when it does not
+ *
+ * @example
+ * ```ts
+ * formatProof(proven)
+ * // 'receipt probe:6ca20c3bff623031d3955b9d1a76d71d:type:typescript@6.0.3:oxlint@1.79.0:vitest@4.1.11:configs/src/tsconfig.core.json@3b674fdf121c85efb9ed1bab25ceeec8'
+ * formatProof(disproven) // 'no receipt'
+ * ```
+ */
+export declare function formatProof(verdict: Verdict): string;
+
+/**
+ * Renders the smallest text a verdict can travel as: what it judged, and how it ended.
+ *
+ * @remarks
+ * A reply whose bounds refuse both the record and the whole rendering answers with this text, so it
+ * carries what a reader cannot recompute — the call's identity, the claim's digest, and the
+ * control's reason when the verdict carries one — and closes with the same line `formatVerdict`
+ * closes with. Every line here is a line `formatVerdict` renders at the same position relative to
+ * the ones around it, so a reader meets one shape whichever answer arrived.
+ *
+ * @param verdict - The verdict to render
+ * @returns The identity and claim lines, the reason when present, then the closing receipt line
+ *
+ * @example
+ * ```ts
+ * formatReceipt(disproven).split('\n')
+ * // ['probe 88a5addc-7d33-40dc-9a5a-104b71f8787d (549 ms)', 'claim 6ca20c3bff623031d3955b9d1a76d71d', 'no receipt']
+ * ```
+ */
+export declare function formatReceipt(verdict: Verdict): string;
+
 /**
  * Renders one generated specification: the caller's own test text, then the marker naming the
  * revision that wrote it.
@@ -558,7 +601,7 @@ export declare const isParty: Guard<Party>;
  * condition all stay outside the type.
  *
  * @param value - The value to inspect
- * @returns True only for a `ProbeError` instance; false otherwise
+ * @returns True if the value is a `ProbeError` instance; false otherwise
  *
  * @example
  * ```ts
@@ -640,13 +683,15 @@ export declare const isStage: Guard<Stage>;
  * ```
  */
 export declare interface Issue {
-    /** The party that must act on this message. */
+    /** Names the party that must act on this message. */
     readonly origin: Party;
-    /** Workspace-relative path this message is reported against. */
+    /** Names the workspace-relative path this message is reported against. */
     readonly path: string;
-    /** The diagnostic or failure message. */
+    /** Holds the diagnostic or failure message. */
     readonly message: string;
-    /** Zero-based UTF-16 span the tool reported, or absent when it reported no location. */
+    /**
+     * Holds the zero-based UTF-16 span the tool reported, or is absent when it reported no location.
+     */
     readonly range?: LSPRange;
 }
 
@@ -684,6 +729,24 @@ export declare const isToolchain: Guard<Toolchain>;
  */
 export declare const isVerdict: Guard<Verdict>;
 
+/**
+ * Names the bound the lint stage holds over the lifecycle exchanges the protocol leaves to the
+ * server: the `initialize` reply warming waits for and the `shutdown` reply ending waits for.
+ *
+ * @remarks
+ * It does not reach the diagnostics an inspection waits for, which the caller's own signal bounds.
+ * The transport's cooperative window is half of it, so a child that ignores its ending is
+ * signalled and released inside the same bound rather than outliving the client's own wait for
+ * the close. Measured 2026-08-27: the workspace `oxlint --lsp` answers `initialize` in 155 ms, so
+ * this bound is more than ten times that reply.
+ *
+ * @example
+ * ```ts
+ * LINT_DEADLINE // 2_000
+ * ```
+ */
+export declare const LINT_DEADLINE = 2000;
+
 /**
  * Checks whether one file's text is the generated specification written for one revision.
  *
@@ -718,6 +781,19 @@ export declare function matchesSpecification(text: string, revision: string): bo
  */
 export declare type Party = (typeof PROBE_PARTIES)[number];
 
+/**
+ * Names the default inspection deadline a `Probe` applies when its construction omits one.
+ *
+ * @remarks
+ * `ProbeOptions.deadline` overrides this value per instance.
+ *
+ * @example
+ * ```ts
+ * PROBE_DEADLINE // 30_000
+ * ```
+ */
+export declare const PROBE_DEADLINE = 30000;
+
 /**
  * Lists the conditions that can end a probe operation.
  *
@@ -733,6 +809,25 @@ export declare type Party = (typeof PROBE_PARTIES)[number];
  */
 export declare const PROBE_ERROR_CODES: readonly ["refused", "missing", "malformed", "destroyed", "deadline"];
 
+/**
+ * Names the total enumerable key bound `ProbeServer` applies to inbound metadata and to produced
+ * tool content alike.
+ *
+ * @remarks
+ * `@orkestrel/mcp`'s default leaf is sized for metadata: a verdict costs 38 keys empty and 11 more
+ * for each issue a stage reports, so the default carries a verdict whose control refuses one
+ * declaration and stops carrying the next one. A whole tool-call result carrying the record beside
+ * its rendering costs 44 keys plus 11 for each issue, so this bound carries a record reporting up
+ * to 368 issues. Past that the reply falls back to the rendered text, and past the 4 MiB content
+ * bound to the receipt block.
+ *
+ * @example
+ * ```ts
+ * PROBE_KEYS // 4096
+ * ```
+ */
+export declare const PROBE_KEYS = 4096;
+
 /**
  * Lists the parties that can own action on an issue or probe failure.
  *
@@ -747,6 +842,26 @@ export declare const PROBE_ERROR_CODES: readonly ["refused", "missing", "malform
  */
 export declare const PROBE_PARTIES: readonly ["claimant", "workspace", "instrument"];
 
+/**
+ * Names the specification lifetime the runtime stage replaces its resident Vitest service at.
+ *
+ * @remarks
+ * Vite retains one unresolved URL for every fresh specification path, so an inspection that writes
+ * a specification grows a map the resident service never releases. The stage replaces that service
+ * rather than deleting from each map it owns, and this is the count of specifications one service
+ * carries before the replacement. Any bound holds the retention flat, because the replacement
+ * releases everything the instance held; this value trades the cost of the replacement against how
+ * far the map grows between them. On 2026-08-20, over this package's own workspace on the host
+ * `guides/probe.md` § Cost names, two runs of 66 inspections put the crossing inspection at 480 ms
+ * and 269 ms against median inspections of 156 ms and 155 ms.
+ *
+ * @example
+ * ```ts
+ * PROBE_SPECIFICATIONS // 64
+ * ```
+ */
+export declare const PROBE_SPECIFICATIONS = 64;
+
 /**
  * Lists the stages a claim passes through, in the order a verdict reports them.
  *
@@ -829,20 +944,20 @@ export declare type ProbeErrorCode = (typeof PROBE_ERROR_CODES)[number];
  * ```
  */
 export declare interface ProbeErrorContext {
-    /** The stage the failure belongs to, when one stage owns it. */
+    /** Names the stage the failure belongs to, when one stage owns it. */
     readonly stage?: Stage;
     /**
-     * The path involved, spelled as the refusing operation named it: workspace-relative for an
+     * Names the path involved, spelled as the refusing operation named it: workspace-relative for an
      * input a caller supplied, absolute for a file this package resolved.
      */
     readonly path?: string;
-    /** The workspace-relative TypeScript project involved, for a project failure. */
+    /** Names the workspace-relative TypeScript project involved, for a project failure. */
     readonly project?: string;
-    /** The installed package name involved, for a workspace toolchain failure. */
+    /** Identifies the installed package involved, for a workspace toolchain failure. */
     readonly name?: string;
-    /** Milliseconds the expired budget allowed, for a deadline failure. */
+    /** Holds the milliseconds the expired budget allowed, for a deadline failure. */
     readonly deadline?: number;
-    /** The rejected value, for an input the guards refused. */
+    /** Holds the rejected value, for an input the guards refused. */
     readonly value?: unknown;
 }
 
@@ -864,13 +979,13 @@ export declare interface ProbeErrorContext {
  * ```
  */
 export declare interface ProbeErrorOptions {
-    /** The party that must act on this failure. */
+    /** Names the party that must act on this failure. */
     readonly origin: Party;
-    /** The condition that ended the operation. */
+    /** Names the condition that ended the operation. */
     readonly code: ProbeErrorCode;
-    /** Structured detail about the failure. */
+    /** Holds structured detail about the failure. */
     readonly context?: ProbeErrorContext;
-    /** The underlying fault, when one ended the operation. */
+    /** Holds the underlying fault, when one ended the operation. */
     readonly cause?: unknown;
 }
 
@@ -892,13 +1007,16 @@ export declare interface ProbeErrorOptions {
  * ```
  */
 export declare type ProbeEventMap = {
-    /** The boot control reported red and the instrument has begun answering calls. */
+    /** Fires when the boot control has reported red and the instrument has begun answering calls. */
     readonly arm: readonly [toolchain: Toolchain];
-    /** A claim was answered. */
+    /** Fires when a claim is answered. */
     readonly prove: readonly [verdict: Verdict];
-    /** The coordinator's deadline fired at one stage and that stage was replaced before this event. */
+    /** Fires after the coordinator's deadline fired at one stage and that stage was replaced. */
     readonly expire: readonly [claim: Claim];
-    /** A fault surfaced for observation, once per fault, including a rejected arming attempt. */
+    /**
+     * Fires when a fault surfaces for observation, once per fault, including a rejected arming
+     * attempt.
+     */
     readonly error: readonly [error: unknown];
 };
 
@@ -922,9 +1040,9 @@ export declare type ProbeEventMap = {
  * ```
  */
 export declare interface ProbeInterface {
-    /** Observation surface for arming, answers, deadline expiry, and faults. */
+    /** Publishes arming, answers, deadline expiry, and faults for observation. */
     readonly emitter: EmitterInterface<ProbeEventMap>;
-    /** The tool versions resolved from the workspace at construction. */
+    /** Names the tool versions resolved from the workspace at construction. */
     readonly toolchain: Toolchain;
     /**
      * Answers one claim with every stage's evidence.
@@ -974,15 +1092,15 @@ export declare interface ProbeInterface {
  * ```
  */
 export declare interface ProbeOptions {
-    /** Initial listeners, wired at construction. */
+    /** Declares the initial listeners, wired at construction. */
     readonly on?: EmitterHooks<ProbeEventMap>;
-    /** Handler for a listener throw. */
+    /** Holds the handler for a listener throw. */
     readonly error?: EmitterErrorHandler;
-    /** Target workspace root. Default: the current working directory. */
+    /** Names the target workspace root. Default: the current working directory. */
     readonly workspace?: string;
     /**
-     * Milliseconds one active stage inspection may take; an expired stage is replaced. Default:
-     * 30,000 ms.
+     * Holds the milliseconds one active stage inspection may take; an expired stage is replaced.
+     * Default: 30,000 ms.
      */
     readonly deadline?: number;
 }
@@ -1006,9 +1124,12 @@ export declare interface ProbeOptions {
  * ```
  */
 export declare interface Project {
-    /** Resolved workspace-relative path of the project file the type stage applied. */
+    /** Names the resolved workspace-relative path of the project file the type stage applied. */
     readonly path: string;
-    /** Digest of that project's resolved compiler options, workspace-relative and key-sorted. */
+    /**
+     * Holds the digest of that project's resolved compiler options, workspace-relative and
+     * key-sorted.
+     */
     readonly digest: string;
 }
 
@@ -1044,6 +1165,21 @@ export declare const RECEIPT_PREFIX = "probe";
  */
 export declare const RECEIPT_SEPARATOR = ":";
 
+/**
+ * Names the Vite plugin the runtime stage installs into a target workspace's Vitest configuration.
+ *
+ * @remarks
+ * The stage declares the plugin under this name and reads a configured project's plugin list for
+ * the same name to decide whether that project carries the overlay. One name feeds both, so a
+ * project the stage instrumented is never reported as a workspace project it could not reach.
+ *
+ * @example
+ * ```ts
+ * RUNTIME_PLUGIN // 'orkestrel-runtime-overlay'
+ * ```
+ */
+export declare const RUNTIME_PLUGIN = "orkestrel-runtime-overlay";
+
 /**
  * Names an inspection a claim passes through, derived from {@link PROBE_STAGES}.
  *
@@ -1072,11 +1208,11 @@ export declare type Stage = (typeof PROBE_STAGES)[number];
  * ```
  */
 export declare interface Toolchain {
-    /** Resolved `typescript` version the type stage ran. */
+    /** Names the resolved `typescript` version the type stage ran. */
     readonly typescript: string;
-    /** Resolved `oxlint` version the lint stage ran. */
+    /** Names the resolved `oxlint` version the lint stage ran. */
     readonly oxlint: string;
-    /** Resolved `vitest` version the runtime stage ran. */
+    /** Names the resolved `vitest` version the runtime stage ran. */
     readonly vitest: string;
 }
 
@@ -1141,26 +1277,26 @@ export declare interface Toolchain {
  * ```
  */
 export declare interface Verdict {
-    /** The revision identity this verdict was produced for, fresh per call. */
+    /** Names the revision identity this verdict was produced for, fresh per call. */
     readonly id: string;
-    /** Digest of the case and control this verdict answers. */
+    /** Holds the digest of the case and control this verdict answers. */
     readonly digest: string;
-    /** The tool versions that produced it. */
+    /** Names the tool versions that produced it. */
     readonly toolchain: Toolchain;
-    /** The TypeScript project the candidate drafts were judged against. */
+    /** Names the TypeScript project the candidate drafts were judged against. */
     readonly project: Project;
     /**
-     * The claimant's explanation for the selected control, when the verdict came from a claim. Part
-     * of the control, so it enters `digest` and through it the receipt token.
+     * Holds the claimant's explanation for the selected control, when the verdict came from a claim.
+     * Part of the control, so it enters `digest` and through it the receipt token.
      */
     readonly reason?: string;
-    /** One outcome per stage for the claim's case. */
+    /** Holds one outcome per stage for the claim's case. */
     readonly case: readonly Check[];
-    /** One outcome per stage for the claim's control. */
+    /** Holds one outcome per stage for the claim's control. */
     readonly control: readonly Check[];
-    /** Milliseconds the whole call took, including both the case and the control. */
+    /** Holds the milliseconds the whole call took, including both the case and the control. */
     readonly elapsed: number;
-    /** The proof token, absent when either phase reports an instrument failure. */
+    /** Holds the proof token, absent when either phase reports an instrument failure. */
     readonly receipt?: string;
 }