@orkestrel/probe 0.0.12 → 0.0.14

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

@@ -1,10 +1,10 @@
 import { ArrayShape } from '@orkestrel/contract';
-import { EmitterErrorHandler } from '@orkestrel/emitter';
-import { EmitterHooks } from '@orkestrel/emitter';
-import { EmitterInterface } from '@orkestrel/emitter';
-import { Guard } from '@orkestrel/contract';
+import type { EmitterErrorHandler } from '@orkestrel/emitter';
+import type { EmitterHooks } from '@orkestrel/emitter';
+import type { EmitterInterface } from '@orkestrel/emitter';
+import type { Guard } from '@orkestrel/contract';
 import { LiteralShape } from '@orkestrel/contract';
-import { LSPRange } from '@orkestrel/lsp';
+import type { LSPRange } from '@orkestrel/lsp';
 import { ObjectShape } from '@orkestrel/contract';
 import { StringShape } from '@orkestrel/contract';
 
@@ -20,10 +20,15 @@ import { StringShape } from '@orkestrel/contract';
  * @example
  * ```ts
  * const subject: Case = {
- * 	files: [{ path: 'src/core/greeting.ts', text: "export const GREETING = 'hi'\n" }],
+ * 	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 { GREETING } from '../../src/core/greeting.js'\ntest('greets', () => expect(GREETING).toBe('hi'))\n",
+ * 		text: "import { expect, test } from 'vitest'\nimport { createGreeting } from '../../src/core/factories.js'\ntest('greets', () => expect(createGreeting()).toBe('hi'))\n",
  * 	},
  * }
  * ```
@@ -44,15 +49,15 @@ export declare interface Case {
  * compileGuard(CASE_SHAPE)({ files: [], test }) // true
  * ```
  */
-export declare const CASE_SHAPE: ObjectShape<{
-    files: ArrayShape<ObjectShape<{
-        path: StringShape;
-        text: StringShape;
-    }, false>>;
-    test: ObjectShape<{
-        path: StringShape;
-        text: StringShape;
-    }, false>;
+export declare const CASE_SHAPE: ObjectShape<    {
+files: ArrayShape<ObjectShape<    {
+path: StringShape;
+text: StringShape;
+}, false>>;
+test: ObjectShape<    {
+path: StringShape;
+text: StringShape;
+}, false>;
 }, false>;
 
 /**
@@ -95,20 +100,30 @@ export declare interface Check {
  * const claim: Claim = {
  * 	project: 'configs/src/tsconfig.core.json',
  * 	case: {
- * 		files: [{ path: 'src/core/greeting.ts', text: "export const GREETING = 'hi'\n" }],
+ * 		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 { GREETING } from '../../src/core/greeting.js'\ntest('greets', () => expect(GREETING).toBe('hi'))\n",
+ * 			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/greeting.ts', text: "export const GREETING: number = 'hi'\n" }],
+ * 		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 { GREETING } from '../../src/core/greeting.js'\ntest('greets', () => expect(GREETING).toBe('hi'))\n",
+ * 			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 literal assigned to a number must not compile',
+ * 		reason: 'a string returned as a number must not compile',
  * 	},
  * }
  * ```
@@ -144,30 +159,30 @@ export declare interface Claim {
  * admits({ project: 'tsconfig.json' }) // false
  * ```
  */
-export declare const CLAIM_SHAPE: ObjectShape<{
-    project: StringShape;
-    case: ObjectShape<{
-        files: ArrayShape<ObjectShape<{
-            path: StringShape;
-            text: StringShape;
-        }, false>>;
-        test: ObjectShape<{
-            path: StringShape;
-            text: StringShape;
-        }, false>;
-    }, false>;
-    control: ObjectShape<{
-        stage: LiteralShape<readonly ["type", "lint", "runtime"]>;
-        reason: StringShape;
-        files: ArrayShape<ObjectShape<{
-            path: StringShape;
-            text: StringShape;
-        }, false>>;
-        test: ObjectShape<{
-            path: StringShape;
-            text: StringShape;
-        }, false>;
-    }, false>;
+export declare const CLAIM_SHAPE: ObjectShape<    {
+project: StringShape;
+case: ObjectShape<    {
+files: ArrayShape<ObjectShape<    {
+path: StringShape;
+text: StringShape;
+}, false>>;
+test: ObjectShape<    {
+path: StringShape;
+text: StringShape;
+}, false>;
+}, false>;
+control: ObjectShape<    {
+stage: LiteralShape<readonly ["type", "lint", "runtime"]>;
+reason: StringShape;
+files: ArrayShape<ObjectShape<    {
+path: StringShape;
+text: StringShape;
+}, false>>;
+test: ObjectShape<    {
+path: StringShape;
+text: StringShape;
+}, false>;
+}, false>;
 }, false>;
 
 /**
@@ -208,7 +223,7 @@ export declare const CLAIM_SHAPE: ObjectShape<{
  * @example
  * ```ts
  * computeReceipt(proven, 'type')
- * // 'probe:6ca20c3bff623031d3955b9d1a76d71d:type:typescript@6.0.3:oxlint@1.79.0:vitest@4.1.11:configs/src/tsconfig.core.json@3b674fdf121c85efb9ed1bab25ceeec8'
+ * // 'probe:6ca20c3bff623031d3955b9d1a76d71d:type:typescript@6.0.3:oxlint@1.79.0:vitest@4.1.11:configs/src/tsconfig.core.json@d61f11b52460b1c6707cfac2c6078d59'
  * computeReceipt(proven, 'lint') // undefined
  * ```
  */
@@ -225,13 +240,18 @@ export declare function computeReceipt(verdict: Verdict, stage: Stage): string |
  * @example
  * ```ts
  * const control: Control = {
- * 	files: [{ path: 'src/core/greeting.ts', text: "export const GREETING: number = 'hi'\n" }],
+ * 	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 { GREETING } from '../../src/core/greeting.js'\ntest('greets', () => expect(GREETING).toBe('hi'))\n",
+ * 		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 literal assigned to a number must not compile',
+ * 	reason: 'a string returned as a number must not compile',
  * }
  * ```
  */
@@ -255,17 +275,17 @@ export declare interface Control extends Case {
  * compileGuard(CONTROL_SHAPE)({ files: [], test, stage: 'type', reason: 'must not compile' }) // true
  * ```
  */
-export declare const CONTROL_SHAPE: ObjectShape<{
-    stage: LiteralShape<readonly ["type", "lint", "runtime"]>;
-    reason: StringShape;
-    files: ArrayShape<ObjectShape<{
-        path: StringShape;
-        text: StringShape;
-    }, false>>;
-    test: ObjectShape<{
-        path: StringShape;
-        text: StringShape;
-    }, false>;
+export declare const CONTROL_SHAPE: ObjectShape<    {
+stage: LiteralShape<readonly ["type", "lint", "runtime"]>;
+reason: StringShape;
+files: ArrayShape<ObjectShape<    {
+path: StringShape;
+text: StringShape;
+}, false>>;
+test: ObjectShape<    {
+path: StringShape;
+text: StringShape;
+}, false>;
 }, false>;
 
 /**
@@ -297,7 +317,10 @@ export declare function createDestroyedError(subject: string): ProbeError;
  *
  * @example
  * ```ts
- * const draft: Draft = { path: 'src/core/greeting.ts', text: "export const GREETING = 'hi'\n" }
+ * const draft: Draft = {
+ * 	path: 'src/core/factories.ts',
+ * 	text: "export function createGreeting(): string {\n\treturn 'hi'\n}\n",
+ * }
  * ```
  */
 export declare interface Draft {
@@ -323,9 +346,9 @@ export declare interface Draft {
  * compileGuard(DRAFT_SHAPE)({ path: 'src/core/greeting.ts', text: '' }) // true
  * ```
  */
-export declare const DRAFT_SHAPE: ObjectShape<{
-    path: StringShape;
-    text: StringShape;
+export declare const DRAFT_SHAPE: ObjectShape<    {
+path: StringShape;
+text: StringShape;
 }, false>;
 
 /**
@@ -390,7 +413,7 @@ export declare function formatIssue(issue: Issue): string;
  * @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'
+ * // 'receipt probe:6ca20c3bff623031d3955b9d1a76d71d:type:typescript@6.0.3:oxlint@1.79.0:vitest@4.1.11:configs/src/tsconfig.core.json@d61f11b52460b1c6707cfac2c6078d59'
  * formatProof(disproven) // 'no receipt'
  * ```
  */
@@ -547,9 +570,10 @@ export declare const isControl: Guard<Control>;
  *
  * @example
  * ```ts
- * isDraft({ path: 'src/core/greeting.ts', text: 'export const GREETING = "hi"\n' }) // true
+ * const text = "export function createGreeting(): string {\n\treturn 'hi'\n}\n"
+ * isDraft({ path: 'src/core/factories.ts', text }) // true
  * isDraft({ path: '../../etc/hosts', text: '' }) // false
- * isDraft({ path: 'src/core/greeting.ts' }) // false
+ * isDraft({ path: 'src/core/factories.ts' }) // false
  * ```
  */
 export declare const isDraft: Guard<Draft>;
@@ -665,10 +689,11 @@ export declare const isStage: Guard<Stage>;
  * reported no location, which happens for a whole-file diagnostic. A runtime failure is not one of
  * those: a failure Vitest reported at a stack frame carries that frame's position.
  *
- * Each stage supplies the extent its own tool gives it. The type stage spans the diagnostic's
- * reported length, and the lint stage carries the span the language server published. A tool that
- * reports a point rather than a span, as a stack frame does, produces a zero-width range at that
- * point, which is the same value a span of no width would carry.
+ * Each stage supplies the extent its own tool gives it. The lint stage carries the span the language
+ * server published. A tool that reports a point rather than a span produces a zero-width range at
+ * that point, which is the same value a span of no width would carry, and the type stage and the
+ * runtime stage both report one: the compiler's plain-text output names a start position and no
+ * extent, and a stack frame names a position.
  *
  * `formatIssue` renders `start.line` one-based, because that is the numbering an editor shows.
  *
@@ -676,9 +701,9 @@ export declare const isStage: Guard<Stage>;
  * ```ts
  * const issue: Issue = {
  * 	origin: 'claimant',
- * 	path: 'src/core/greeting.ts',
+ * 	path: 'src/core/factories.ts',
  * 	message: "Type 'string' is not assignable to type 'number'.",
- * 	range: { start: { line: 0, character: 6 }, end: { line: 0, character: 13 } },
+ * 	range: { start: { line: 0, character: 6 }, end: { line: 0, character: 6 } },
  * }
  * ```
  */
@@ -730,8 +755,8 @@ 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.
+ * Names the 2,000 ms 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.
@@ -782,7 +807,8 @@ 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.
+ * Names the default inspection deadline a `Probe` applies when its construction omits one,
+ * 30,000 ms.
  *
  * @remarks
  * `ProbeOptions.deadline` overrides this value per instance.
@@ -795,7 +821,8 @@ export declare type Party = (typeof PROBE_PARTIES)[number];
 export declare const PROBE_DEADLINE = 30000;
 
 /**
- * Lists the conditions that can end a probe operation.
+ * Lists the conditions that can end a probe operation:
+ * `['refused', 'missing', 'malformed', 'destroyed', 'deadline']`.
  *
  * @remarks
  * One list feeds the code union and the error guard, so a condition cannot be constructed by one
@@ -811,7 +838,7 @@ export declare const PROBE_ERROR_CODES: readonly ["refused", "missing", "malform
 
 /**
  * Names the total enumerable key bound `ProbeServer` applies to inbound metadata and to produced
- * tool content alike.
+ * tool content alike, 4096.
  *
  * @remarks
  * `@orkestrel/mcp`'s default leaf is sized for metadata: a verdict costs 38 keys empty and 11 more
@@ -829,7 +856,8 @@ export declare const PROBE_ERROR_CODES: readonly ["refused", "missing", "malform
 export declare const PROBE_KEYS = 4096;
 
 /**
- * Lists the parties that can own action on an issue or probe failure.
+ * Lists the parties that can own action on an issue or probe failure:
+ * `['claimant', 'workspace', 'instrument']`.
  *
  * @remarks
  * One list feeds the `Party` type and its guard, so a party cannot be admitted by one and refused
@@ -843,7 +871,8 @@ export declare const PROBE_KEYS = 4096;
 export declare const PROBE_PARTIES: readonly ["claimant", "workspace", "instrument"];
 
 /**
- * Names the specification lifetime the runtime stage replaces its resident Vitest service at.
+ * Names the specification lifetime the runtime stage replaces its resident Vitest service at,
+ * 64 specifications.
  *
  * @remarks
  * Vite retains one unresolved URL for every fresh specification path, so an inspection that writes
@@ -863,7 +892,8 @@ export declare const PROBE_PARTIES: readonly ["claimant", "workspace", "instrume
 export declare const PROBE_SPECIFICATIONS = 64;
 
 /**
- * Lists the stages a claim passes through, in the order a verdict reports them.
+ * Lists the stages a claim passes through, in the order a verdict reports them:
+ * `['type', 'lint', 'runtime']`.
  *
  * @remarks
  * One list feeds the `Stage` type, the wire shape, the stage guard, and the receipt computation, so
@@ -1028,9 +1058,9 @@ export declare type ProbeEventMap = {
  * the process and a restart is a new process rather than a second lifecycle.
  *
  * `prove` re-reads the target workspace before it answers, so a file edited since the last call is
- * judged as it stands on disk rather than as a warm service remembers it. The resident readers key
- * that sweep differently: the runtime stage compares each workspace module's contents, and the type
- * stage versions a disk file by its modification time.
+ * judged as it stands on disk rather than as a warm service remembers it. Each stage keys that
+ * sweep by content: the runtime stage compares each workspace module's contents, and the type stage
+ * refreshes its mirror of the workspace by content digest.
  *
  * @example
  * ```ts
@@ -1050,7 +1080,7 @@ export declare interface ProbeInterface {
      * @remarks
      * A control carrying the case's files and the case's test byte for byte is refused at admission,
      * with `origin: 'claimant'` and `code: 'refused'`. No stage inspects such a claim: the refusal
-     * answers before the resident stages are awaited, so it reads the same in every workspace state.
+     * answers before any stage is awaited, so it reads the same in every workspace state.
      * Such a control can only break by nondeterminism, so the receipt it would earn attests a
      * falsification that never happened, and a flake-earned receipt is the worst answer this package
      * can return. The refusal compares the bytes of each side's files and test rather than the digest
@@ -1066,9 +1096,9 @@ export declare interface ProbeInterface {
      */
     prove(claim: Claim): Promise<Verdict>;
     /**
-     * Tears down the resident engines and releases the processes they hold.
+     * Tears down every stage and releases the processes and the mirror they hold.
      *
-     * @returns A promise that settles when every engine has released its resources
+     * @returns A promise that settles after every stage has released its resources
      */
     destroy(): Promise<void>;
 }
@@ -1113,13 +1143,15 @@ export declare interface ProbeOptions {
  * under one project and fails under another, so a verdict that omits the project states less than
  * it appears to. `path` names which project file, in the resolved workspace-relative spelling
  * rather than the caller's. `digest` names what that project contained, because a receipt travels
- * away from the workspace that minted it and a path alone is a claim about a name.
+ * away from the workspace that minted it and a path alone is a claim about a name. The digest reads
+ * the compiler's own printed configuration for the workspace's copy of that project, so a claim's
+ * drafts cannot move it.
  *
  * @example
  * ```ts
  * const project: Project = {
  * 	path: 'configs/src/tsconfig.core.json',
- * 	digest: '3b674fdf121c85efb9ed1bab25ceeec8',
+ * 	digest: 'd61f11b52460b1c6707cfac2c6078d59',
  * }
  * ```
  */
@@ -1134,7 +1166,7 @@ export declare interface Project {
 }
 
 /**
- * Names the leading token every receipt carries.
+ * Names the leading token every receipt carries, `'probe'`.
  *
  * @remarks
  * A receipt travels away from the verdict that minted it — an agent pastes it into the promotion
@@ -1143,14 +1175,14 @@ export declare interface Project {
  * @example
  * ```ts
  * const receipt =
- * 	'probe:6ca20c3bff623031d3955b9d1a76d71d:type:typescript@6.0.3:oxlint@1.79.0:vitest@4.1.11:configs/src/tsconfig.core.json@3b674fdf121c85efb9ed1bab25ceeec8'
+ * 	'probe:6ca20c3bff623031d3955b9d1a76d71d:type:typescript@6.0.3:oxlint@1.79.0:vitest@4.1.11:configs/src/tsconfig.core.json@d61f11b52460b1c6707cfac2c6078d59'
  * receipt.startsWith(RECEIPT_PREFIX) // true
  * ```
  */
 export declare const RECEIPT_PREFIX = "probe";
 
 /**
- * Names the character joining a receipt's tokens.
+ * Names the character joining a receipt's tokens, `':'`.
  *
  * @remarks
  * A project path can contain this character, so the project field goes last and a reader rejoins
@@ -1159,14 +1191,15 @@ export declare const RECEIPT_PREFIX = "probe";
  * @example
  * ```ts
  * const receipt =
- * 	'probe:6ca20c3bff623031d3955b9d1a76d71d:type:typescript@6.0.3:oxlint@1.79.0:vitest@4.1.11:configs/src/tsconfig.core.json@3b674fdf121c85efb9ed1bab25ceeec8'
+ * 	'probe:6ca20c3bff623031d3955b9d1a76d71d:type:typescript@6.0.3:oxlint@1.79.0:vitest@4.1.11:configs/src/tsconfig.core.json@d61f11b52460b1c6707cfac2c6078d59'
  * receipt.split(RECEIPT_SEPARATOR).length // 7
  * ```
  */
 export declare const RECEIPT_SEPARATOR = ":";
 
 /**
- * Names the Vite plugin the runtime stage installs into a target workspace's Vitest configuration.
+ * Names the Vite plugin the runtime stage installs into a target workspace's Vitest
+ * configuration, `'orkestrel-runtime-overlay'`.
  *
  * @remarks
  * The stage declares the plugin under this name and reads a configured project's plugin list for
@@ -1216,6 +1249,25 @@ export declare interface Toolchain {
     readonly vitest: string;
 }
 
+/**
+ * Names the workspace-relative directory the type stage keeps its workspace mirror under,
+ * `'tmp/type'`.
+ *
+ * @remarks
+ * Each stage owns one directory beneath this one, named for the writing host's process id and a
+ * fresh UUID, and deletes it at teardown. The directory sits under `tmp/` so nothing the stage
+ * writes reaches a version-controlled path, and beside `tmp/probe/` rather than inside it because
+ * the workbench Vitest project collects `tmp/probe/**` and would otherwise collect a mirrored test.
+ * A target that runs its own `check`, `lint:check`, or `format:check` while a probe is resident
+ * reads whatever it does not exclude, so exclude this directory there.
+ *
+ * @example
+ * ```ts
+ * TYPE_MIRROR // 'tmp/type'
+ * ```
+ */
+export declare const TYPE_MIRROR = "tmp/type";
+
 /**
  * Carries the full result of one claim: every stage, for both the case and its control.
  *
@@ -1257,7 +1309,7 @@ export declare interface Toolchain {
  * 	toolchain: { typescript: '6.0.3', oxlint: '1.79.0', vitest: '4.1.11' },
  * 	project: {
  * 		path: 'configs/src/tsconfig.core.json',
- * 		digest: '3b674fdf121c85efb9ed1bab25ceeec8',
+ * 		digest: 'd61f11b52460b1c6707cfac2c6078d59',
  * 	},
  * 	reason: 'a number annotation must reject the string literal beside it',
  * 	case: [
@@ -1272,7 +1324,7 @@ export declare interface Toolchain {
  * 	],
  * 	elapsed: 549,
  * 	receipt:
- * 		'probe:6ca20c3bff623031d3955b9d1a76d71d:type:typescript@6.0.3:oxlint@1.79.0:vitest@4.1.11:configs/src/tsconfig.core.json@3b674fdf121c85efb9ed1bab25ceeec8',
+ * 		'probe:6ca20c3bff623031d3955b9d1a76d71d:type:typescript@6.0.3:oxlint@1.79.0:vitest@4.1.11:configs/src/tsconfig.core.json@d61f11b52460b1c6707cfac2c6078d59',
  * }
  * ```
  */