@orkestrel/probe 0.0.1

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

@@ -0,0 +1,1134 @@
+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 { LiteralShape } from '@orkestrel/contract';
+import { ObjectShape } from '@orkestrel/contract';
+import { StringShape } from '@orkestrel/contract';
+
+/**
+ * Carries the candidate drafts a claim asserts about and the test that exercises them.
+ *
+ * @remarks
+ * `files` and `test` belong to different TypeScript projects. Each draft in `files` is checked
+ * against the project its claim names, and `test` is checked against the root project, because a
+ * test needs the Vitest and Node globals the scoped projects remove. A direct type-stage call that
+ * supplies no project infers one from each candidate path.
+ *
+ * @example
+ * ```ts
+ * const subject: Case = {
+ * 	files: [{ path: 'src/core/greeting.ts', text: "export const GREETING = 'hi'\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",
+ * 	},
+ * }
+ * ```
+ */
+export declare interface Case {
+    /** The candidate drafts the test imports, in the order the claim supplies them. */
+    readonly files: readonly Draft[];
+    /** The test that exercises those drafts. */
+    readonly test: Draft;
+}
+
+/**
+ * Describes the drafts a claim asserts about and the test that exercises them.
+ *
+ * @example
+ * ```ts
+ * const test = { path: 'tests/src/core/greeting.test.ts', text: '' }
+ * 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>;
+}, false>;
+
+/**
+ * Carries one stage's outcome: what it cost and what it reported.
+ *
+ * @remarks
+ * An empty `issues` list is the clean result. There is no separate pass flag, because passing is
+ * exactly the absence of issues and a stored flag could disagree with the list beside it.
+ *
+ * @example
+ * ```ts
+ * const check: Check = { stage: 'lint', elapsed: 17, issues: [] }
+ * ```
+ */
+export declare interface Check {
+    /** The stage that produced this outcome. */
+    readonly stage: Stage;
+    /** Milliseconds the stage took. */
+    readonly elapsed: number;
+    /** Every message the stage's tool reported, in the tool's own order. */
+    readonly issues: readonly Issue[];
+}
+
+/**
+ * Carries everything the service needs to produce one verdict.
+ *
+ * @remarks
+ * `project` names the TypeScript project the candidate drafts in both cases are checked against,
+ * because the root project admits host globals the scoped projects remove and would report green
+ * where the gate reports red. The test drafts remain on the root project for Vitest and Node globals.
+ *
+ * The control's candidate drafts must differ from the case's. A control byte-identical to its case
+ * cannot break, so it never produces the `origin: 'claimant'` issue a receipt requires, and the
+ * claim is unprovable however correct the case is.
+ *
+ * @example
+ * ```ts
+ * const claim: Claim = {
+ * 	project: 'configs/src/tsconfig.core.json',
+ * 	case: {
+ * 		files: [{ path: 'src/core/greeting.ts', text: "export const GREETING = 'hi'\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",
+ * 		},
+ * 	},
+ * 	control: {
+ * 		files: [{ path: 'src/core/greeting.ts', text: "export const GREETING: number = 'hi'\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",
+ * 		},
+ * 		stage: 'type',
+ * 		reason: 'a string literal assigned to a number must not compile',
+ * 	},
+ * }
+ * ```
+ */
+export declare interface Claim {
+    /** Workspace-relative path of the TypeScript project the candidate drafts are checked against. */
+    readonly project: string;
+    /** The drafts and test the claim asserts about. */
+    readonly case: Case;
+    /** The negative control that must break, and where. */
+    readonly control: Control;
+}
+
+/**
+ * Describes one claim and is the sole source of both the published tool schema and the guard
+ * applied to an arriving claim.
+ *
+ * @remarks
+ * The Model Context Protocol tool publishes `compileSchema(CLAIM_SHAPE)` and admits a call with
+ * `isClaim`. Deriving the advertised schema from this one value is what stops the two from drifting
+ * apart across a release on any member either can express. `isClaim` is narrower on the one member
+ * neither a schema keyword nor this shape can carry — the containment rule on `Draft.path` — and
+ * `validators.ts` names where.
+ *
+ * @example
+ * ```ts
+ * const schema = compileSchema(CLAIM_SHAPE)
+ * const admits = compileGuard(CLAIM_SHAPE)
+ * schema.type // 'object'
+ * 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>;
+}, false>;
+
+/**
+ * Computes the proof token a verdict carries, or returns nothing when the claim was not proven.
+ *
+ * @remarks
+ * A receipt is minted on these conditions together: both phases report one check per stage, the
+ * case carries no issue, the control carries at least one `origin: 'claimant'` issue
+ * at the stage it declared, and every other control stage carries no claimant issue. A control
+ * that fails somewhere else has falsified the instrument rather than the claim, so no receipt is
+ * minted for it.
+ *
+ * Both phases owe every stage, not the case alone. `stayed` reads the control entries a verdict
+ * carries, so a control that omits a stage entirely would otherwise read as a stage that stayed
+ * clean, and the receipt would certify an inspection that never ran. `prove` records every stage
+ * for both phases, so this condition refuses only a verdict a caller assembled by hand.
+ *
+ * The token names every condition the verdict was reached under, so a receipt read away from its
+ * verdict still says what was judged and what judged it: the claim's digest, the stage the control
+ * broke at, the tool versions, and the project the candidate drafts were checked against.
+ * The call's identity is deliberately absent. It carries no integrity and it is the only value
+ * stopping two honest runs of one claim from producing one comparable string, so leaving it out is
+ * what makes "re-run `prove` and compare tokens" a verification a reader can perform.
+ *
+ * The project goes last, and its own path and digest are joined by `@`. Split the token on
+ * `RECEIPT_SEPARATOR`, take fields 0 through 5, and rejoin the remainder with that separator to
+ * read the project field; inside it the digest is everything after the final `@`. That rule stays
+ * total for a workspace-relative project path containing either character.
+ *
+ * An `origin: 'instrument'` issue in either phase means the inspection did not complete and
+ * refuses the receipt. A workspace issue in the control does not decide whether the claimant's
+ * candidate broke, while one in the case still means that the case did not run clean.
+ *
+ * @param verdict - The verdict whose case and control checks decide the outcome
+ * @param stage - The stage the claim's control declared it must fail at
+ * @returns The receipt token, or `undefined` when any condition fails
+ *
+ * @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'
+ * computeReceipt(proven, 'lint') // undefined
+ * ```
+ */
+export declare function computeReceipt(verdict: Verdict, stage: Stage): string | undefined;
+
+/**
+ * Extends a case with the stage it must fail at and the reason it must fail there.
+ *
+ * @remarks
+ * A claim that cannot state what would falsify it cannot be proven, so the control is required
+ * rather than optional. `stage` is the axis the control varies: a control that fails at a stage
+ * other than the one it names has falsified the instrument, not the claim.
+ *
+ * @example
+ * ```ts
+ * const control: Control = {
+ * 	files: [{ path: 'src/core/greeting.ts', text: "export const GREETING: number = 'hi'\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",
+ * 	},
+ * 	stage: 'type',
+ * 	reason: 'a string literal assigned to a number must not compile',
+ * }
+ * ```
+ */
+export declare interface Control extends Case {
+    /** The stage this control must report issues at. */
+    readonly stage: Stage;
+    /** Why the control fails there, in the claimant's own words. */
+    readonly reason: string;
+}
+
+/**
+ * Describes the negative control, which is a case plus where and why it must break.
+ *
+ * @remarks
+ * Built from `CASE_SHAPE`'s own properties rather than a second copy of them, so the control and
+ * the case cannot describe a draft differently.
+ *
+ * @example
+ * ```ts
+ * const test = { path: 'tests/src/core/greeting.test.ts', text: '' }
+ * 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>;
+}, false>;
+
+/**
+ * Creates the failure raised when an instrument is used after it was torn down.
+ *
+ * @remarks
+ * Every resident entity in this package refuses this way, so the subject names which one in the
+ * message and the condition is the same for all of them. A caller that meets this builds a
+ * replacement rather than retrying: teardown is permanent.
+ *
+ * @param subject - The torn-down entity, named as the message names it, such as `type stage`
+ * @returns A typed teardown failure
+ *
+ * @example
+ * ```ts
+ * createDestroyedError('type stage').message // 'The type stage has been destroyed'
+ * createDestroyedError('probe').code // 'destroyed'
+ * ```
+ */
+export declare function createDestroyedError(subject: string): ProbeError;
+
+/**
+ * Carries one proposed file's location and its contents.
+ *
+ * @remarks
+ * A draft is a file as the claimant proposes it rather than as the workspace holds it. `path` is
+ * contained within the workspace, relative to its root, and need not exist on disk. The type and
+ * lint stages read the text from memory; only the runtime stage writes a file.
+ *
+ * @example
+ * ```ts
+ * const draft: Draft = { path: 'src/core/greeting.ts', text: "export const GREETING = 'hi'\n" }
+ * ```
+ */
+export declare interface Draft {
+    /** Workspace-relative path the stages resolve the text against. */
+    readonly path: string;
+    /** The file's full contents. */
+    readonly text: string;
+}
+
+/**
+ * Describes one proposed file a claim carries.
+ *
+ * @remarks
+ * `path` is constrained to a non-empty string because every stage resolves a file by it, so an
+ * empty path names no file. That minimum is the whole of the constraint here, and it is the one
+ * place the wire contract is wider than what this package admits: `isDraft` enforces the same
+ * minimum and also refuses an absolute path and one that traverses out of the workspace, which no
+ * JSON Schema keyword can express. A caller that satisfies this shape can still be refused, and
+ * `ProbeServer` names the member when it is.
+ *
+ * @example
+ * ```ts
+ * compileGuard(DRAFT_SHAPE)({ path: 'src/core/greeting.ts', text: '' }) // true
+ * ```
+ */
+export declare const DRAFT_SHAPE: ObjectShape<{
+    path: StringShape;
+    text: StringShape;
+}, false>;
+
+/**
+ * Renders one stage's outcome as its summary line followed by every message it reported.
+ *
+ * @remarks
+ * A clean stage renders one line. The count appears even when it is zero, because that line is
+ * what shows a reader the stage ran; a silent stage and a skipped stage read the same.
+ *
+ * @param check - The stage outcome to render
+ * @returns The summary line, then one indented line per issue
+ *
+ * @example
+ * ```ts
+ * formatCheck({ stage: 'lint', elapsed: 17, issues: [] })
+ * // 'lint: 0 issues (17 ms)'
+ * ```
+ */
+export declare function formatCheck(check: Check): string;
+
+/**
+ * Renders one tool message as a single line an agent can classify and locate.
+ *
+ * @param issue - The message and location a stage reported
+ * @returns The bracketed origin, location, and message, separated by spaces
+ *
+ * @example
+ * ```ts
+ * const located: Issue = {
+ * 	origin: 'claimant',
+ * 	path: 'src/core/greeting.ts',
+ * 	message: 'not assignable',
+ * 	line: 1,
+ * }
+ * const whole: Issue = {
+ * 	origin: 'claimant',
+ * 	path: 'src/core/greeting.ts',
+ * 	message: 'not assignable',
+ * }
+ * formatIssue(located) // '[claimant] src/core/greeting.ts:1 not assignable'
+ * formatIssue(whole) // '[claimant] src/core/greeting.ts not assignable'
+ * ```
+ */
+export declare function formatIssue(issue: Issue): string;
+
+/**
+ * Renders one generated specification: the caller's own test text, then the marker naming the
+ * revision that wrote it.
+ *
+ * @remarks
+ * The marker is what makes a file in a target workspace attributable to this package. A generated
+ * specification carries text the caller supplied, so its name alone cannot separate it from a
+ * developer's own file, and a sweep reading the name alone deletes that file. The marker goes last
+ * so every line of the caller's text keeps the number a reported stack frame gives it, and the text
+ * gains a terminating newline first so the marker is never appended to a line of the test.
+ *
+ * @param text - The caller's own test text
+ * @param revision - The writing host's process id and a fresh UUID, joined by `-`
+ * @returns The bytes the runtime stage writes for that revision
+ *
+ * @example
+ * ```ts
+ * formatSpecification("test('greets', () => {})\n", '4821-9f0c')
+ * // "test('greets', () => {})\n// @orkestrel/probe generated specification 4821-9f0c\n"
+ * ```
+ */
+export declare function formatSpecification(text: string, revision: string): string;
+
+/**
+ * Renders a whole verdict as the text an agent reads.
+ *
+ * @remarks
+ * Every stage appears for both the case and the control, so no failing stage can be masked by an
+ * earlier one. The closing line always states the receipt or its absence, so a reader never has to
+ * infer from silence whether the claim was proven.
+ *
+ * The heading lines carry everything the receipt binds, each in the name-then-value form the
+ * toolchain line established: the call's identity, the claim it answered, the tools that ran, and
+ * the project that judged the candidates. A verdict carrying the control's reason renders it next,
+ * before either phase's checks. A reader comparing two verdicts therefore reads what differed
+ * without recomputing anything.
+ *
+ * @param verdict - The verdict to render
+ * @returns The identity, claim, toolchain, project, and reason when present, then every case and
+ * control stage, then the receipt line
+ *
+ * @example
+ * ```ts
+ * formatVerdict(verdict).split('\n')[1] // 'claim 6ca20c3bff623031d3955b9d1a76d71d'
+ * ```
+ */
+export declare function formatVerdict(verdict: Verdict): string;
+
+/**
+ * Checks whether a value carries a claim's candidate drafts and its test.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a case; false otherwise
+ *
+ * @example
+ * ```ts
+ * const test = { path: 'tests/src/core/greeting.test.ts', text: 'test("greets", () => {})\n' }
+ * isCase({ files: [], test }) // true
+ * ```
+ */
+export declare const isCase: Guard<Case>;
+
+/**
+ * Checks whether a value carries one stage's outcome.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a check; false otherwise
+ *
+ * @example
+ * ```ts
+ * isCheck({ stage: 'lint', elapsed: 17, issues: [] }) // true
+ * ```
+ */
+export declare const isCheck: Guard<Check>;
+
+/**
+ * Checks whether a value carries a project, a case, and a control.
+ *
+ * @remarks
+ * Exact rather than open: a claim is this package's own record, so an unknown member is a caller
+ * sending a contract this service does not implement rather than a wider caller it must tolerate.
+ *
+ * `CLAIM_SHAPE` is the wire contract's shape and this is the admission rule the tool enforces, and
+ * the rule is strictly narrower than the shape. They agree on every member but `Draft.path`: the
+ * shape constrains it to a non-empty string, while `isDraft` also refuses an absolute path
+ * and one that traverses out of the workspace, so `../../etc/hosts` satisfies
+ * `compileGuard(CLAIM_SHAPE)` and is refused here. `ProbeServer` advertises the shape and enforces
+ * this rule, so it names the refused member rather than reporting only that the claim was invalid.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a claim; false otherwise
+ *
+ * @example
+ * ```ts
+ * isClaim({ project: 'tsconfig.json', case: subject, control }) // true
+ * isClaim({ project: 'tsconfig.json', case: subject }) // false
+ * ```
+ */
+export declare const isClaim: Guard<Claim>;
+
+/**
+ * Checks whether a value carries a case plus the stage and reason it must fail for.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a control; false otherwise
+ *
+ * @example
+ * ```ts
+ * const test = { path: 'tests/src/core/greeting.test.ts', text: 'test("greets", () => {})\n' }
+ * isControl({ files: [], test, stage: 'type', reason: 'must not compile' }) // true
+ * isControl({ files: [], test }) // false
+ * ```
+ */
+export declare const isControl: Guard<Control>;
+
+/**
+ * Checks whether a value carries a proposed file's path and text.
+ *
+ * @remarks
+ * Rejects an empty, absolute, or workspace-escaping path. A contained relative path may contain
+ * `.` or may traverse to a parent that remains inside the workspace. Every stage resolves a file
+ * by that path, so admitting an escape here would defer the refusal until a stage had already
+ * accepted the draft. An `Issue` carries no such minimum because this package produces issues
+ * rather than admits them.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a draft; false otherwise
+ *
+ * @example
+ * ```ts
+ * isDraft({ path: 'src/core/greeting.ts', text: 'export const GREETING = "hi"\n' }) // true
+ * isDraft({ path: '../../etc/hosts', text: '' }) // false
+ * isDraft({ path: 'src/core/greeting.ts' }) // false
+ * ```
+ */
+export declare const isDraft: Guard<Draft>;
+
+/**
+ * Checks whether a value carries one message, its location, and the origin of the fault it names.
+ *
+ * @remarks
+ * `origin` is required rather than optional. Every issue this package produces sets it, and a
+ * receipt turns on it: a control's issue disproves the claim only when its origin names the
+ * claimant.
+ *
+ * @param value - The value to check
+ * @returns True if the value is an issue; false otherwise
+ *
+ * @example
+ * ```ts
+ * isIssue({ origin: 'claimant', path: 'src/core/greeting.ts', message: 'not assignable' }) // true
+ * isIssue({ path: 'src/core/greeting.ts', message: 'not assignable' }) // false
+ * ```
+ */
+export declare const isIssue: Guard<Issue>;
+
+/**
+ * Checks whether a value names a party an issue carries.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a party; false otherwise
+ *
+ * @example
+ * ```ts
+ * isParty('claimant') // true
+ * isParty('workspace') // true
+ * isParty('instrument') // true
+ * isParty('stage') // false
+ * ```
+ */
+export declare const isParty: Guard<Party>;
+
+/**
+ * Checks whether an unknown value is a {@link ProbeError}.
+ *
+ * @remarks
+ * Recognition combines the global own-property brand with the native `Error` base, the subclass
+ * prototype, the fixed name, a party {@link PROBE_PARTIES} declares, and a condition
+ * {@link PROBE_ERROR_CODES} declares. The brand carries recognition across duplicate installations
+ * and across an ESM and a CommonJS copy of this package, where the two classes are different values.
+ * A plain `Error`, a property-only lookalike, and a branded value carrying an undeclared origin or
+ * condition all stay outside the type.
+ *
+ * @param value - The value to inspect
+ * @returns True only for a `ProbeError` instance; false otherwise
+ *
+ * @example
+ * ```ts
+ * isProbeError(createDestroyedError('probe')) // true
+ * isProbeError(new Error('The probe has been destroyed')) // false
+ * ```
+ */
+export declare function isProbeError(value: unknown): value is ProbeError;
+
+/**
+ * Checks whether a value names one resolved TypeScript project and what it contained.
+ *
+ * @remarks
+ * Rejects an empty path and an empty digest. A verdict names the project that judged it, so a
+ * blank member here would report a project the type stage never applied.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a project; false otherwise
+ *
+ * @example
+ * ```ts
+ * isProject({ path: 'configs/src/tsconfig.core.json', digest: '3b674fdf121c85ef' }) // true
+ * isProject({ path: 'configs/src/tsconfig.core.json', digest: '' }) // false
+ * ```
+ */
+export declare const isProject: Guard<Project>;
+
+/**
+ * Checks whether a value names a stage.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a stage name; false otherwise
+ *
+ * @example
+ * ```ts
+ * isStage('lint') // true
+ * isStage('typecheck') // false
+ * ```
+ */
+export declare const isStage: Guard<Stage>;
+
+/**
+ * Carries one message a stage reported, where it reported it, and whose fault it names.
+ *
+ * @remarks
+ * The stage is not repeated here. An issue always arrives inside the `Check` that names its
+ * stage, so a second copy could only drift from the first.
+ *
+ * A `claimant` issue is a tool's diagnostic about a candidate draft, and nothing else. Every
+ * other claimant fault is thrown. Without this invariant, a bad test path could satisfy the
+ * receipt condition even though the test never ran.
+ *
+ * `path` is the workspace-relative path a reader can open, which is not always the path the tool
+ * named. Each stage maps its tool's own spelling back: the type stage from the compiler's absolute
+ * path, the lint stage from the document URI it opened, and the runtime stage from the generated
+ * specification it wrote to the test path the case declared.
+ *
+ * `line` is absent when the stage's tool reported no line, 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 line.
+ *
+ * @example
+ * ```ts
+ * const issue: Issue = {
+ * 	origin: 'claimant',
+ * 	path: 'src/core/greeting.ts',
+ * 	message: "Type 'string' is not assignable to type 'number'.",
+ * 	line: 1,
+ * }
+ * ```
+ */
+export declare interface Issue {
+    /** The party that must act on this message. */
+    readonly origin: Party;
+    /** Workspace-relative path this message is reported against. */
+    readonly path: string;
+    /** The diagnostic or failure message. */
+    readonly message: string;
+    /** One-based line the tool reported, or absent when it reported none. */
+    readonly line?: number;
+}
+
+/**
+ * Checks whether a value names every resolved tool version.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a toolchain; false otherwise
+ *
+ * @example
+ * ```ts
+ * isToolchain({ typescript: '6.0.3', oxlint: '1.79.0', vitest: '4.1.11' }) // true
+ * isToolchain({ typescript: '6.0.3' }) // false
+ * ```
+ */
+export declare const isToolchain: Guard<Toolchain>;
+
+/**
+ * Checks whether a value carries a complete verdict.
+ *
+ * @remarks
+ * Accepts any check count, because arity is the coordinator's obligation rather than this guard's:
+ * a stage that could not start throws before a verdict is built, so a short list can only arrive
+ * from a caller that assembled one by hand.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a verdict; false otherwise
+ *
+ * @example
+ * ```ts
+ * const basis = { id: '01J8Z0', digest: '6ca20c3b', toolchain, project, elapsed: 337 }
+ * isVerdict({ ...basis, case: [], control: [] }) // true
+ * isVerdict({ ...basis, case: [] }) // false
+ * ```
+ */
+export declare const isVerdict: Guard<Verdict>;
+
+/**
+ * Checks whether one file's text is the generated specification written for one revision.
+ *
+ * @remarks
+ * Reads the marker `formatSpecification` writes, taken from that function rather than restated, so
+ * the writer and the reader cannot drift apart. An empty body renders the marker alone, which is
+ * why the comparison is built from a call rather than from a second copy of the text.
+ *
+ * @param text - The file's full contents
+ * @param revision - The revision the file's name declares
+ * @returns True if the text ends with this package's marker for that revision; false otherwise
+ *
+ * @example
+ * ```ts
+ * matchesSpecification(formatSpecification('', '4821-9f0c'), '4821-9f0c') // true
+ * matchesSpecification('export const NOTE = 1\n', '4821-9f0c') // false
+ * ```
+ */
+export declare function matchesSpecification(text: string, revision: string): boolean;
+
+/**
+ * Names who must act on an issue or probe failure.
+ *
+ * @remarks
+ * `claimant` is the caller who wrote the claim: its input, selections, candidate draft, and
+ * lifecycle. `workspace` is the target tree probe borrows. `instrument` is this package.
+ *
+ * @example
+ * ```ts
+ * const party: Party = 'claimant'
+ * ```
+ */
+export declare type Party = (typeof PROBE_PARTIES)[number];
+
+/**
+ * Lists the conditions that can end a probe operation.
+ *
+ * @remarks
+ * One list feeds the code union and the error guard, so a condition cannot be constructed by one
+ * and refused by the other. The guard reads this list rather than the class, which is what lets it
+ * refuse a lookalike carrying a condition this package never declared.
+ *
+ * @example
+ * ```ts
+ * PROBE_ERROR_CODES // ['refused', 'missing', 'malformed', 'destroyed', 'deadline']
+ * ```
+ */
+export declare const PROBE_ERROR_CODES: readonly ["refused", "missing", "malformed", "destroyed", "deadline"];
+
+/**
+ * Lists the parties that can own action on an issue or probe failure.
+ *
+ * @remarks
+ * One list feeds the `Party` type and its guard, so a party cannot be admitted by one and refused
+ * by another.
+ *
+ * @example
+ * ```ts
+ * PROBE_PARTIES // ['claimant', 'workspace', 'instrument']
+ * ```
+ */
+export declare const PROBE_PARTIES: readonly ["claimant", "workspace", "instrument"];
+
+/**
+ * Lists the stages a claim passes through, in the order a verdict reports them.
+ *
+ * @remarks
+ * One list feeds the `Stage` type, the wire shape, the stage guard, and the receipt computation, so
+ * a stage cannot be admitted by one and refused by another. The type derives from this list rather
+ * than standing beside it, so a stage the list omits is a stage no member of the union names.
+ *
+ * @example
+ * ```ts
+ * PROBE_STAGES // ['type', 'lint', 'runtime']
+ * ```
+ */
+export declare const PROBE_STAGES: readonly ["type", "lint", "runtime"];
+
+/**
+ * Reports one probe failure under stable ownership and condition axes.
+ *
+ * @remarks
+ * Every failure raised while serving a claim arrives as one of these, so a consumer catching from
+ * `prove`, from a stage, or from a workspace leaf branches on {@link Party} and
+ * {@link ProbeErrorCode} rather than on message text. Narrow a caught value with
+ * {@link isProbeError} before reading either member. A pure leaf called directly with a value
+ * `isClaim` would refuse raises the host's own fault unchanged, because those leaves are written to
+ * be total over a validated claim rather than over every value.
+ *
+ * @example
+ * ```ts
+ * const error = new ProbeError('Path escapes the workspace: ../secrets.env', {
+ * 	origin: 'claimant',
+ * 	code: 'refused',
+ * 	context: { path: '../secrets.env' },
+ * })
+ * error.origin // 'claimant'
+ * error.code // 'refused'
+ * error.context?.path // '../secrets.env'
+ * ```
+ */
+export declare class ProbeError extends Error {
+    readonly name = "ProbeError";
+    readonly origin: Party;
+    readonly code: ProbeErrorCode;
+    readonly context?: ProbeErrorContext;
+    /**
+     * Creates one classified probe failure.
+     *
+     * @param message - Human-readable description of what failed
+     * @param options - The ownership, condition, optional structured context, and optional cause
+     */
+    constructor(message: string, options: ProbeErrorOptions);
+}
+
+/**
+ * Names the condition that ended a probe operation, derived from {@link PROBE_ERROR_CODES}.
+ *
+ * @remarks
+ * Each condition names a different repair. `refused` changes the rejected value. `missing` creates
+ * or installs the named thing. `malformed` repairs the value read against a contract. `destroyed`
+ * builds a replacement. `deadline` changes the budget or the work it bounds according to the
+ * failure's {@link Party}.
+ *
+ * @example
+ * ```ts
+ * const code: ProbeErrorCode = 'missing'
+ * ```
+ */
+export declare type ProbeErrorCode = (typeof PROBE_ERROR_CODES)[number];
+
+/**
+ * Carries the structured detail one probe failure reports beside its message.
+ *
+ * @remarks
+ * Every member is absent unless the failure has that value to report, so a reader branches on
+ * presence rather than on a sentinel. `value` is the rejected input itself, carried unchanged, so
+ * treat it as untrusted when rendering it.
+ *
+ * @example
+ * ```ts
+ * const context: ProbeErrorContext = { stage: 'runtime', deadline: 30_000 }
+ * ```
+ */
+export declare interface ProbeErrorContext {
+    /** 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
+     * input a caller supplied, absolute for a file this package resolved.
+     */
+    readonly path?: string;
+    /** The workspace-relative TypeScript project involved, for a project failure. */
+    readonly project?: string;
+    /** The installed package name involved, for a workspace toolchain failure. */
+    readonly name?: string;
+    /** Milliseconds the expired budget allowed, for a deadline failure. */
+    readonly deadline?: number;
+    /** The rejected value, for an input the guards refused. */
+    readonly value?: unknown;
+}
+
+/**
+ * Configures one probe failure at construction.
+ *
+ * @remarks
+ * `origin` and `code` are required, because a failure a consumer cannot branch on is the failure
+ * this type exists to replace. `cause` carries the underlying fault where one ended the operation,
+ * and reaches the native `Error` option of the same name.
+ *
+ * @example
+ * ```ts
+ * const options: ProbeErrorOptions = {
+ * 	origin: 'claimant',
+ * 	code: 'refused',
+ * 	context: { path: '../secrets.env' },
+ * }
+ * ```
+ */
+export declare interface ProbeErrorOptions {
+    /** The party that must act on this failure. */
+    readonly origin: Party;
+    /** The condition that ended the operation. */
+    readonly code: ProbeErrorCode;
+    /** Structured detail about the failure. */
+    readonly context?: ProbeErrorContext;
+    /** The underlying fault, when one ended the operation. */
+    readonly cause?: unknown;
+}
+
+/**
+ * Reports what a probe observes while it serves.
+ *
+ * @remarks
+ * `arm` fires when the boot control has reported red and the service will answer calls; a probe
+ * arriving before it awaits that step rather than starting a second one. `expire` fires when the
+ * coordinator's own deadline destroyed a stage and a replacement took its place, which is the only
+ * way a synchronous infinite loop is ever reported.
+ *
+ * @example
+ * ```ts
+ * const hooks: EmitterHooks<ProbeEventMap> = { prove: (verdict) => console.log(verdict.id) }
+ * ```
+ */
+export declare type ProbeEventMap = {
+    /** The boot control reported red and the instrument has begun answering calls. */
+    readonly arm: readonly [toolchain: Toolchain];
+    /** A claim was answered. */
+    readonly prove: readonly [verdict: Verdict];
+    /** The coordinator's deadline fired at one stage and that stage was replaced before this event. */
+    readonly expire: readonly [claim: Claim];
+    /** A fault surfaced for observation. */
+    readonly error: readonly [error: unknown];
+};
+
+/**
+ * Answers a claim with type, lint, and runtime evidence in one call.
+ *
+ * @remarks
+ * Warming begins at construction and `prove` awaits it, so there is no `start`: the harness owns
+ * 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.
+ *
+ * @example
+ * ```ts
+ * const verdict = await probe.prove(claim)
+ * console.log(formatVerdict(verdict))
+ * await probe.destroy()
+ * ```
+ */
+export declare interface ProbeInterface {
+    /** Observation surface for arming, answers, deadline expiry, and faults. */
+    readonly emitter: EmitterInterface<ProbeEventMap>;
+    /** The tool versions resolved from the workspace at construction. */
+    readonly toolchain: Toolchain;
+    /**
+     * Answers one claim with every stage's evidence.
+     *
+     * @param claim - The case, its control, and the project the candidate drafts in both cases
+     * are checked against
+     * @returns The verdict, carrying one check per stage for both the case and the control
+     * @throws When a stage cannot start, so no verdict ever reports a stage that did not run
+     */
+    prove(claim: Claim): Promise<Verdict>;
+    /**
+     * Tears down the resident engines and releases the processes they hold.
+     *
+     * @returns A promise that settles when every engine has released its resources
+     */
+    destroy(): Promise<void>;
+}
+
+/**
+ * Configures a probe.
+ *
+ * @remarks
+ * `workspace` is the target root whose installed `typescript`, `oxlint`, and `vitest` the stages
+ * resolve, and whose files each stage re-reads before it answers. Default: the current working
+ * directory. `deadline` is the coordinator's milliseconds budget for one active stage inspection.
+ * Queue wait is not charged to that inspection; the inspections and runtime recoveries ahead of it
+ * carry their own bounds. The runtime deadline lives outside the worker because a test timeout
+ * expressed in worker configuration cannot fire while that worker spins. One runtime inspection in
+ * every 64 also pays the resident runner's replacement, so budget `deadline` against that
+ * inspection rather than the common one.
+ *
+ * @example
+ * ```ts
+ * const options: ProbeOptions = { workspace: '/srv/checkout', deadline: 30_000 }
+ * ```
+ */
+export declare interface ProbeOptions {
+    /** Initial listeners, wired at construction. */
+    readonly on?: EmitterHooks<ProbeEventMap>;
+    /** Handler for a listener throw. */
+    readonly error?: EmitterErrorHandler;
+    /** 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.
+     */
+    readonly deadline?: number;
+}
+
+/**
+ * Names the TypeScript project that judged a verdict's candidate drafts.
+ *
+ * @remarks
+ * A verdict is an assertion about code under one compiler configuration, and the same code passes
+ * 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.
+ *
+ * @example
+ * ```ts
+ * const project: Project = {
+ * 	path: 'configs/src/tsconfig.core.json',
+ * 	digest: '3b674fdf121c85efb9ed1bab25ceeec8',
+ * }
+ * ```
+ */
+export declare interface Project {
+    /** 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. */
+    readonly digest: string;
+}
+
+/**
+ * Names the leading token every receipt carries.
+ *
+ * @remarks
+ * A receipt travels away from the verdict that minted it — an agent pastes it into the promotion
+ * action — so it names itself rather than relying on where it was found.
+ *
+ * @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'
+ * receipt.startsWith(RECEIPT_PREFIX) // true
+ * ```
+ */
+export declare const RECEIPT_PREFIX = "probe";
+
+/**
+ * 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
+ * every field from index 6 onward with this separator rather than expecting a fixed count.
+ *
+ * @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'
+ * receipt.split(RECEIPT_SEPARATOR).length // 7
+ * ```
+ */
+export declare const RECEIPT_SEPARATOR = ":";
+
+/**
+ * Names an inspection a claim passes through, derived from {@link PROBE_STAGES}.
+ *
+ * @remarks
+ * They are irreducible modes rather than labels: each reads a different tool, and a verdict that
+ * omits one hides a defect the agent would then believe it had fixed.
+ *
+ * @example
+ * ```ts
+ * const stage: Stage = 'lint'
+ * ```
+ */
+export declare type Stage = (typeof PROBE_STAGES)[number];
+
+/**
+ * Names the tool versions a verdict was produced with.
+ *
+ * @remarks
+ * A probe is worth running only when its verdict predicts the gate's verdict, which holds only
+ * when the probe and the gate read one installed copy of each tool. Carrying the resolved versions
+ * on the verdict makes that claim checkable rather than assumed.
+ *
+ * @example
+ * ```ts
+ * const toolchain: Toolchain = { typescript: '6.0.3', oxlint: '1.79.0', vitest: '4.1.11' }
+ * ```
+ */
+export declare interface Toolchain {
+    /** Resolved `typescript` version the type stage ran. */
+    readonly typescript: string;
+    /** Resolved `oxlint` version the lint stage ran. */
+    readonly oxlint: string;
+    /** Resolved `vitest` version the runtime stage ran. */
+    readonly vitest: string;
+}
+
+/**
+ * Carries the full result of one claim: every stage, for both the case and its control.
+ *
+ * @remarks
+ * A verdict exists only when every stage ran on both the case and the control, so `case`
+ * and `control` each hold one entry per stage. A stage that cannot start throws instead, which is
+ * why no member here models a missing stage. `receipt` is present only when the case reported no
+ * issue, the control reported an `origin: 'claimant'` issue at the stage it declared,
+ * every other control stage reported no claimant issue, and neither phase reported an
+ * `origin: 'instrument'` issue.
+ *
+ * `id` identifies this call and `digest` identifies the claim it answered, so two calls over one
+ * claim share a digest and differ in their identity. `digest` and `project` are required, because
+ * the type stage always runs and a claim always names a project, so no verdict exists without
+ * either value. A verdict returned by `Probe` also carries the control's claimant-authored
+ * `reason` unchanged. A hand-built verdict may omit it because the receipt helper needs only the
+ * recorded checks and declared stage.
+ *
+ * `digest` covers these things: the case bytes, the control bytes including this `reason`, and the
+ * workspace they were read against. The reason is part of the control, so two claims differing only
+ * in its prose are two claims and digest differently — a claimant who restates the falsifier has
+ * answered a different question, and a digest that excluded it would describe less than the claim.
+ * The workspace enters because every absolute string in a claim is rewritten relative to it before
+ * hashing, so a claim carrying no absolute string digests the same in every workspace and one that
+ * carries any digests per workspace. `receipt` carries this digest as a field, so the same inputs
+ * reach the token.
+ *
+ * @example
+ * ```ts
+ * const broke: Issue = {
+ * 	origin: 'claimant',
+ * 	path: 'src/core/farewell.ts',
+ * 	message: 'not assignable',
+ * 	line: 1,
+ * }
+ * const verdict: Verdict = {
+ * 	id: '88a5addc-7d33-40dc-9a5a-104b71f8787d',
+ * 	digest: '6ca20c3bff623031d3955b9d1a76d71d',
+ * 	toolchain: { typescript: '6.0.3', oxlint: '1.79.0', vitest: '4.1.11' },
+ * 	project: {
+ * 		path: 'configs/src/tsconfig.core.json',
+ * 		digest: '3b674fdf121c85efb9ed1bab25ceeec8',
+ * 	},
+ * 	reason: 'a number annotation must reject the string literal beside it',
+ * 	case: [
+ * 		{ stage: 'type', elapsed: 61, issues: [] },
+ * 		{ stage: 'lint', elapsed: 17, issues: [] },
+ * 		{ stage: 'runtime', elapsed: 259, issues: [] },
+ * 	],
+ * 	control: [
+ * 		{ stage: 'type', elapsed: 58, issues: [broke] },
+ * 		{ stage: 'lint', elapsed: 16, issues: [] },
+ * 		{ stage: 'runtime', elapsed: 254, issues: [] },
+ * 	],
+ * 	elapsed: 549,
+ * 	receipt:
+ * 		'probe:6ca20c3bff623031d3955b9d1a76d71d:type:typescript@6.0.3:oxlint@1.79.0:vitest@4.1.11:configs/src/tsconfig.core.json@3b674fdf121c85efb9ed1bab25ceeec8',
+ * }
+ * ```
+ */
+export declare interface Verdict {
+    /** The revision identity this verdict was produced for, fresh per call. */
+    readonly id: string;
+    /** Digest of the case and control this verdict answers. */
+    readonly digest: string;
+    /** The tool versions that produced it. */
+    readonly toolchain: Toolchain;
+    /** 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.
+     */
+    readonly reason?: string;
+    /** One outcome per stage for the claim's case. */
+    readonly case: readonly Check[];
+    /** 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. */
+    readonly elapsed: number;
+    /** The proof token, absent when either phase reports an instrument failure. */
+    readonly receipt?: string;
+}
+
+export { }