carrick 0.3.53

package/sidecar/dist/src/capture/check-classify.js

@@ -0,0 +1,189 @@
+/**
+ * Diagnostic parsing + four-bucket classification for the v2 check phase.
+ *
+ * The judge is the vendored `tsc` CLI with `--pretty false`, run from the
+ * workspace root so file locations print workspace-relative (no temp path in
+ * the location prefix). This module turns that text into per-pair verdicts,
+ * classifying by diagnostic code + file + line (never by line position alone):
+ *
+ *   poison (stub-file diagnostic)         -> unverifiable   [highest precedence]
+ *   surface import error (probe lines 1-2)-> unverifiable
+ *   IsAny gate fired (TS2344)             -> gate_caught_baked_any
+ *   IsUnknown/IsNever gate fired (TS2344) -> unverifiable
+ *   assignment-class error                -> incompatible
+ *   no diagnostics                        -> compatible     [lowest precedence]
+ *
+ * Gate precedence over the assignment line is load-bearing: an `unknown` side
+ * produces BOTH a gate TS2344 and an assignment TS2322, and reading the latter
+ * would mislabel an unverifiable pair as incompatible.
+ *
+ * Seam: node builtins + this bundle only.
+ */
+import { scrubDiagnostic } from './check-scrub.js';
+const PRIMARY_RE = /^(?<file>(?:[a-zA-Z]:)?[^(]*?)\((?<line>\d+),(?<col>\d+)\): error TS(?<code>\d+): (?<msg>.*)$/;
+/** Parse `tsc --pretty false` output into structured diagnostics. */
+export function parseTscOutput(stdout) {
+    const diags = [];
+    let current = null;
+    for (const rawLine of stdout.split('\n')) {
+        const line = rawLine.replace(/\r$/, '');
+        const m = line.match(PRIMARY_RE);
+        if (m && m.groups) {
+            current = {
+                file: m.groups.file.split('\\').join('/'),
+                line: Number(m.groups.line),
+                col: Number(m.groups.col),
+                code: Number(m.groups.code),
+                message: m.groups.msg,
+            };
+            diags.push(current);
+            continue;
+        }
+        // Indented continuation lines belong to the preceding primary diagnostic.
+        if (current && /^\s+\S/.test(line)) {
+            current.message += '\n' + line;
+            continue;
+        }
+        // Blank line or summary ("Found N errors.") ends the current run.
+        current = null;
+    }
+    return diags;
+}
+/** Assignment-class codes: a real structural mismatch on the value assignment. */
+const ASSIGNMENT_CODES = new Set([2322, 2559, 2739, 2740, 2741, 2769, 2345]);
+function sideForGate(name, plan) {
+    const [which, kind] = name.split(':');
+    const side = which === 'sent' ? plan.direction.sent : plan.direction.expected;
+    return { side, kind };
+}
+function endpointAliasFor(side, plan) {
+    return side === plan.direction.sent
+        ? plan.sentEndpoint.alias
+        : plan.expectedEndpoint.alias;
+}
+/** Classify one pair into exactly one bucket, honouring the precedence order. */
+export function classifyPair(input) {
+    const { plan, probeDiags, poisonReason, scrubCtx } = input;
+    const codes = [...new Set(probeDiags.map((d) => d.code))].sort((a, b) => a - b);
+    const base = { pair_id: plan.pairId, pair_key: plan.spec.pair_key, codes };
+    // Every branch below this point except the last two returns a verdict about
+    // a type nobody could read; each states that in one place rather than
+    // repeating the reasoning.
+    const notAFact = (reason) => ({ resolved: false, unresolved_reason: reason });
+    // 1. Poison: a diagnostic in this pair's own alias closure (either side)
+    //    makes the pair unverifiable, never "no probe error -> compatible". A
+    //    sibling alias's poison in the same service no longer reaches here.
+    for (const side of ['producer', 'consumer']) {
+        const endpoint = plan.spec[side];
+        const reason = poisonReason(endpoint.service_name, endpoint.alias);
+        if (reason) {
+            return {
+                ...base,
+                bucket: 'unverifiable',
+                gate: `poison:${side}`,
+                diagnostic: `the type stub for service '${endpoint.service_name}' does not typecheck (its own declarations carry diagnostics); compatibility cannot be verified.`,
+                ...notAFact(`the ${side} stub does not typecheck`),
+            };
+        }
+    }
+    // 2. Surface import error (missing/renamed export): probe import lines.
+    const importDiag = probeDiags.find((d) => plan.importLines.includes(d.line));
+    if (importDiag) {
+        const side = plan.importLines[0] === importDiag.line ? plan.direction.sent : plan.direction.expected;
+        const alias = endpointAliasFor(side, plan);
+        return {
+            ...base,
+            bucket: 'unverifiable',
+            gate: `import:${side}`,
+            diagnostic: `surface export '${alias}' for the ${side} is missing or renamed; compatibility cannot be verified.`,
+            ...notAFact(`the ${side} surface export is missing or renamed`),
+        };
+    }
+    // 3/4. Probe gates (TS2344). IsAny outranks IsUnknown/IsNever.
+    const gateDiags = probeDiags.filter((d) => d.code === 2344 && plan.gateLines.has(d.line));
+    const anyGate = gateDiags
+        .map((d) => plan.gateLines.get(d.line))
+        .find((name) => name.endsWith(':any'));
+    if (anyGate) {
+        const { side } = sideForGate(anyGate, plan);
+        return {
+            ...base,
+            bucket: 'gate_caught_baked_any',
+            gate: `${side}:any`,
+            diagnostic: `the ${side} type resolved to 'any' at check time; compatibility cannot be verified (a type inferred through a missing library bakes to any).`,
+            ...notAFact(`the ${side} type is 'any'`),
+        };
+    }
+    const decayGate = gateDiags
+        .map((d) => plan.gateLines.get(d.line))
+        .find((name) => name.endsWith(':unknown') || name.endsWith(':never'));
+    if (decayGate) {
+        const { side, kind } = sideForGate(decayGate, plan);
+        return {
+            ...base,
+            bucket: 'unverifiable',
+            gate: `${side}:${kind}`,
+            diagnostic: `the ${side} type resolved to '${kind}' at check time; compatibility cannot be verified.`,
+            ...notAFact(`the ${side} type is '${kind}'`),
+        };
+    }
+    // 5. Assignment-class error on the value assignment line -> incompatible.
+    const assignDiag = probeDiags.find((d) => d.line === plan.assignmentLine && ASSIGNMENT_CODES.has(d.code));
+    if (assignDiag) {
+        return {
+            ...base,
+            bucket: 'incompatible',
+            diagnostic: scrubDiagnostic(assignDiag.message, scrubCtx, plan.sentEndpoint.alias, plan.expectedEndpoint.alias),
+            ...factness(input),
+        };
+    }
+    // Any other diagnostic on the assignment line that is not a known assignment
+    // code still means the pair could not be cleanly verified.
+    const otherAssign = probeDiags.find((d) => d.line === plan.assignmentLine);
+    if (otherAssign) {
+        return {
+            ...base,
+            bucket: 'unverifiable',
+            gate: 'assignment:other',
+            diagnostic: scrubDiagnostic(otherAssign.message, scrubCtx, plan.sentEndpoint.alias, plan.expectedEndpoint.alias),
+            ...notAFact('the probe raised a diagnostic that is not an assignment mismatch'),
+        };
+    }
+    // 6. No diagnostics -> compatible.
+    return { ...base, bucket: 'compatible', ...factness(input) };
+}
+/**
+ * Whether a compared pair is a FACT about two known types (carrick#707, R1d).
+ *
+ * The probe gates only rule out a WHOLLY top-typed side. A pair whose producer
+ * declares `{ id: string; meta: any }` clears every gate and then reads
+ * compatible against literally any counterparty `meta`, because `any` is
+ * bidirectionally assignable. That is not a compatibility result, and a reader
+ * who acts on it acts on nothing. So `resolved` additionally requires the deep
+ * walk to have RUN over both sides in the assembled workspace and come back
+ * empty. A walk that could not run leaves the verdict not-a-fact: absence of
+ * findings is not evidence.
+ */
+function factness(input) {
+    const findings = input.deepFindings;
+    if (!findings) {
+        return {
+            resolved: false,
+            unresolved_reason: 'the type could not be walked for member-level any/unknown after install, so the comparison is not established as a fact',
+        };
+    }
+    for (const side of ['sent', 'expected']) {
+        const first = findings[side][0];
+        if (!first)
+            continue;
+        const label = side === 'sent' ? input.plan.direction.sent : input.plan.direction.expected;
+        const where = first.path === '' ? 'its root' : `'${first.path}'`;
+        return {
+            resolved: false,
+            unresolved_reason: first.kind === 'budget_exhausted'
+                ? `the ${label} type is too deep or wide to verify at ${where}`
+                : `the ${label} type carries '${first.kind}' at ${where}, which every counterparty shape satisfies`,
+        };
+    }
+    return { resolved: true };
+}

package/sidecar/dist/src/capture/check-deep.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Check-time fact-ness walk (carrick#707, R1d).
+ *
+ * The probe gates prove the two sides are not WHOLLY `any`/`unknown`/`never`.
+ * They cannot see a member three levels down, and a member-level `any` accepts
+ * every counterparty shape — so "no diagnostic" there is not a compatibility
+ * result, it is the absence of one. The capture-time walk catches most of it,
+ * but only what the capture could resolve: a member that decayed through a
+ * pinned external is TypeScript's `error` placeholder at capture time and is
+ * deliberately excluded there, because it heals once the check installs the
+ * pin (carrick#450). This walk runs after that install, over the assembled
+ * probe workspace, so it sees what the capture could not.
+ *
+ * It is used for exactly one thing: setting `CheckVerdict.resolved`. No bucket
+ * changes because of it, so a scan's verdicts are identical with and without
+ * it — what changes is whether a reader is told the verdict is a fact.
+ */
+import type { TypeProvenance } from './api.js';
+import type { ProbePlan } from './check-probe.js';
+/** Deep findings for one pair, per probe side. */
+export interface PairDeepFindings {
+    sent: TypeProvenance[];
+    expected: TypeProvenance[];
+}
+/**
+ * Walk both sides of every probe in the assembled workspace.
+ *
+ * Returns an empty map when the program cannot be built — absence of findings
+ * must never be read as "clean", so the caller treats a missing entry as
+ * unresolved rather than resolved.
+ */
+export declare function probeDeepFindings(probesDir: string, plans: ProbePlan[]): Map<string, PairDeepFindings>;

package/sidecar/dist/src/capture/check-deep.js

@@ -0,0 +1,91 @@
+/**
+ * Check-time fact-ness walk (carrick#707, R1d).
+ *
+ * The probe gates prove the two sides are not WHOLLY `any`/`unknown`/`never`.
+ * They cannot see a member three levels down, and a member-level `any` accepts
+ * every counterparty shape — so "no diagnostic" there is not a compatibility
+ * result, it is the absence of one. The capture-time walk catches most of it,
+ * but only what the capture could resolve: a member that decayed through a
+ * pinned external is TypeScript's `error` placeholder at capture time and is
+ * deliberately excluded there, because it heals once the check installs the
+ * pin (carrick#450). This walk runs after that install, over the assembled
+ * probe workspace, so it sees what the capture could not.
+ *
+ * It is used for exactly one thing: setting `CheckVerdict.resolved`. No bucket
+ * changes because of it, so a scan's verdicts are identical with and without
+ * it — what changes is whether a reader is told the verdict is a fact.
+ */
+import ts from 'typescript';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { findDisqualifyingTopTypes, provenanceOf } from './deep-walk.js';
+/**
+ * Walk both sides of every probe in the assembled workspace.
+ *
+ * Returns an empty map when the program cannot be built — absence of findings
+ * must never be read as "clean", so the caller treats a missing entry as
+ * unresolved rather than resolved.
+ */
+export function probeDeepFindings(probesDir, plans) {
+    const results = new Map();
+    if (plans.length === 0)
+        return results;
+    const configPath = path.join(probesDir, 'tsconfig.json');
+    if (!fs.existsSync(configPath))
+        return results;
+    let program;
+    try {
+        const raw = ts.readConfigFile(configPath, (f) => fs.readFileSync(f, 'utf8'));
+        if (raw.error)
+            return results;
+        const parsed = ts.parseJsonConfigFileContent(raw.config, ts.sys, probesDir);
+        const fileNames = plans
+            .map((plan) => path.join(probesDir, 'probes', plan.fileName))
+            .filter((f) => fs.existsSync(f));
+        if (fileNames.length === 0)
+            return results;
+        program = ts.createProgram(fileNames, { ...parsed.options, noEmit: true });
+    }
+    catch {
+        return results;
+    }
+    const checker = program.getTypeChecker();
+    for (const plan of plans) {
+        const file = program.getSourceFile(path.join(probesDir, 'probes', plan.fileName));
+        if (!file)
+            continue;
+        const sent = walkImportedAlias(file, 'Sent', program, checker);
+        const expected = walkImportedAlias(file, 'Expected', program, checker);
+        if (sent === undefined || expected === undefined)
+            continue;
+        results.set(plan.pairId, { sent, expected });
+    }
+    return results;
+}
+/**
+ * Findings for one of the probe's two imported surface aliases, or `undefined`
+ * when the alias cannot be resolved at all (the import-error path, which the
+ * classifier already reports; there is nothing to add here).
+ */
+function walkImportedAlias(file, localName, program, checker) {
+    for (const statement of file.statements) {
+        if (!ts.isImportDeclaration(statement))
+            continue;
+        const bindings = statement.importClause?.namedBindings;
+        if (!bindings || !ts.isNamedImports(bindings))
+            continue;
+        for (const element of bindings.elements) {
+            if (element.name.text !== localName)
+                continue;
+            const local = checker.getSymbolAtLocation(element.name);
+            if (!local)
+                return undefined;
+            const target = local.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(local) : local;
+            const type = checker.getDeclaredTypeOfSymbol(target);
+            if (!type)
+                return undefined;
+            return findDisqualifyingTopTypes(type, program, checker, element.name).map(provenanceOf);
+        }
+    }
+    return undefined;
+}

package/sidecar/dist/src/capture/check-poison.d.ts

@@ -0,0 +1,40 @@
+/**
+ * #438 part 2: stub-tree poison containment.
+ *
+ * A diagnostic in a service's own stub tree (a broken surface line, a nested
+ * declaration file that fails to typecheck) used to poison the WHOLE service —
+ * every pair with that service as producer/consumer read `unverifiable`
+ * (gate=poison:*), masking every clean pair behind one bad alias. This module
+ * contains poison to the aliases actually reachable from the poisoned file:
+ *
+ *  - a diagnostic on the surface entry is attributed to the alias whose
+ *    `export type` statement SPAN covers the diagnostic's line (a multi-line
+ *    alias reports on an interior line);
+ *  - a diagnostic in a nested tree file is attributed to every alias whose
+ *    import closure (surface import-type seeds, then BFS over relative
+ *    imports — the same closure the capture self-check computes) includes that
+ *    file.
+ *
+ * A stub-tree diagnostic reachable from NO alias (e.g. a cross-stub
+ * `declare global` TS2717 collision in an augmentation file, which
+ * `skipLibCheck:false` exists to surface — see check-workspace.ts) has no
+ * closure to contain it and genuinely can affect any alias's comparison, so it
+ * falls back to service-wide poison. Soundness (never falsely compatible) wins
+ * over precision in that one case; every attributable diagnostic is contained.
+ *
+ * Seam: node builtins + `typescript` + this bundle only.
+ */
+import type { AssembledWorkspace } from './check-workspace.js';
+export interface StubPoisonIndex {
+    serviceName: string;
+    /** Workspace-relative surface key: `packages/<dir>/types/surface.d.ts`. */
+    surfaceFile: string;
+    /** Every alias declared in the surface. */
+    allAliases: Set<string>;
+    /** Alias whose `export type` statement span covers the given surface line. */
+    aliasAtSurfaceLine(line: number): string | undefined;
+    /** Aliases whose import closure includes the given workspace-relative file. */
+    aliasesForFile(fileKey: string): string[];
+}
+/** One index per assembled stub, keyed by service name. */
+export declare function buildPoisonIndexes(ws: AssembledWorkspace): Map<string, StubPoisonIndex>;

package/sidecar/dist/src/capture/check-poison.js

@@ -0,0 +1,155 @@
+/**
+ * #438 part 2: stub-tree poison containment.
+ *
+ * A diagnostic in a service's own stub tree (a broken surface line, a nested
+ * declaration file that fails to typecheck) used to poison the WHOLE service —
+ * every pair with that service as producer/consumer read `unverifiable`
+ * (gate=poison:*), masking every clean pair behind one bad alias. This module
+ * contains poison to the aliases actually reachable from the poisoned file:
+ *
+ *  - a diagnostic on the surface entry is attributed to the alias whose
+ *    `export type` statement SPAN covers the diagnostic's line (a multi-line
+ *    alias reports on an interior line);
+ *  - a diagnostic in a nested tree file is attributed to every alias whose
+ *    import closure (surface import-type seeds, then BFS over relative
+ *    imports — the same closure the capture self-check computes) includes that
+ *    file.
+ *
+ * A stub-tree diagnostic reachable from NO alias (e.g. a cross-stub
+ * `declare global` TS2717 collision in an augmentation file, which
+ * `skipLibCheck:false` exists to surface — see check-workspace.ts) has no
+ * closure to contain it and genuinely can affect any alias's comparison, so it
+ * falls back to service-wide poison. Soundness (never falsely compatible) wins
+ * over precision in that one case; every attributable diagnostic is contained.
+ *
+ * Seam: node builtins + `typescript` + this bundle only.
+ */
+import ts from 'typescript';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { collectSpecifiers, isRelative } from './specifiers.js';
+/** One index per assembled stub, keyed by service name. */
+export function buildPoisonIndexes(ws) {
+    const indexes = new Map();
+    for (const stub of ws.stubs) {
+        const index = buildOne(ws, stub.serviceName, stub.packageDir);
+        if (index)
+            indexes.set(stub.serviceName, index);
+    }
+    return indexes;
+}
+function buildOne(ws, serviceName, packageDir) {
+    const typesDirAbs = path.join(ws.workspaceDir, 'packages', packageDir, 'types');
+    const surfaceAbs = path.join(typesDirAbs, 'surface.d.ts');
+    if (!fs.existsSync(surfaceAbs))
+        return undefined;
+    const keyPrefix = `packages/${packageDir}/types`;
+    const surfaceFile = `${keyPrefix}/surface.d.ts`;
+    // Collect the whole `.d.ts` tree, keyed as `packages/<dir>/types/<rel>`.
+    const treeAbs = [];
+    const walk = (dir) => {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const p = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                walk(p);
+            else if (entry.name.endsWith('.d.ts'))
+                treeAbs.push(p);
+        }
+    };
+    walk(typesDirAbs);
+    const treeAbsSet = new Set(treeAbs.map((f) => path.resolve(f)));
+    const keyOf = (abs) => `${keyPrefix}/${path.relative(typesDirAbs, abs).split(path.sep).join('/')}`;
+    const resolveRel = (fromAbs, spec) => {
+        if (!isRelative(spec))
+            return undefined;
+        const base = path.resolve(path.dirname(fromAbs), spec);
+        const candidates = [
+            `${base}.d.ts`,
+            path.join(base, 'index.d.ts'),
+            base.endsWith('.js') ? `${base.slice(0, -3)}.d.ts` : undefined,
+            base, // already `.d.ts`
+        ].filter((c) => c !== undefined);
+        for (const c of candidates) {
+            if (treeAbsSet.has(path.resolve(c)))
+                return c;
+        }
+        return undefined;
+    };
+    // Per-file relative-import adjacency, over the fileKey namespace.
+    const adjacency = new Map();
+    for (const abs of treeAbs) {
+        const text = fs.readFileSync(abs, 'utf8');
+        const neighbors = [];
+        for (const spec of collectSpecifiers(text)) {
+            const target = resolveRel(abs, spec);
+            if (target)
+                neighbors.push(keyOf(target));
+        }
+        adjacency.set(keyOf(abs), neighbors);
+    }
+    // Surface alias statement spans + each alias's import-type seed files.
+    const surfaceText = fs.readFileSync(surfaceAbs, 'utf8');
+    const sf = ts.createSourceFile('surface.d.ts', surfaceText, ts.ScriptTarget.Latest, true);
+    const allAliases = new Set();
+    const spans = [];
+    const seedsByAlias = new Map();
+    for (const stmt of sf.statements) {
+        if (!ts.isTypeAliasDeclaration(stmt))
+            continue;
+        const alias = stmt.name.text;
+        allAliases.add(alias);
+        spans.push({
+            alias,
+            startLine: sf.getLineAndCharacterOfPosition(stmt.getStart(sf)).line + 1,
+            endLine: sf.getLineAndCharacterOfPosition(stmt.getEnd()).line + 1,
+        });
+        const seeds = [];
+        const visit = (n) => {
+            if (ts.isImportTypeNode(n) &&
+                ts.isLiteralTypeNode(n.argument) &&
+                ts.isStringLiteral(n.argument.literal) &&
+                isRelative(n.argument.literal.text)) {
+                const target = resolveRel(surfaceAbs, n.argument.literal.text);
+                if (target)
+                    seeds.push(keyOf(target));
+            }
+            n.forEachChild(visit);
+        };
+        visit(stmt);
+        seedsByAlias.set(alias, seeds);
+    }
+    // Invert per-alias closures into fileKey -> aliases.
+    const fileToAliases = new Map();
+    for (const [alias, seeds] of seedsByAlias) {
+        const closure = new Set();
+        const queue = [...seeds];
+        while (queue.length > 0) {
+            const file = queue.pop();
+            if (closure.has(file))
+                continue;
+            closure.add(file);
+            for (const next of adjacency.get(file) ?? [])
+                queue.push(next);
+        }
+        for (const file of closure) {
+            if (!fileToAliases.has(file))
+                fileToAliases.set(file, new Set());
+            fileToAliases.get(file).add(alias);
+        }
+    }
+    return {
+        serviceName,
+        surfaceFile,
+        allAliases,
+        aliasAtSurfaceLine(line) {
+            for (const span of spans) {
+                if (line >= span.startLine && line <= span.endLine)
+                    return span.alias;
+            }
+            return undefined;
+        },
+        aliasesForFile(fileKey) {
+            return [...(fileToAliases.get(fileKey) ?? [])];
+        },
+    };
+}

package/sidecar/dist/src/capture/check-probe.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Probe generation for the v2 check phase ("tsc as the judge").
+ *
+ * One probe file per matched pair. The probe is a value-level assignment in
+ * the data-flow direction, guarded by six top/bottom-type gates on BOTH sides
+ * (IsAny/IsUnknown/IsNever). Value-level (not `[X] extends [Y]`) because the
+ * conditional-type relation diverges around `any`, and because the compiler's
+ * elaborated assignment error is the user-facing mismatch report.
+ *
+ * GraphQL pairs additionally unwrap the producer's resolver-return ENVELOPE
+ * before the assignment (see the `graphql` branch in `buildProbe`): a GraphQL
+ * producer's captured type is the resolver function's return type with
+ * transport layers (Promise / async-iterator) already peeled at inference
+ * time, which for wrapper-returning resolvers is a single-payload envelope
+ * (`{ data: Order; errors: string[] }`) — not the SDL field payload the
+ * consumer's selection set reads. The v1 checker unwrapped this structurally
+ * at compare time (ts_check type-checker `unwrapGraphqlPayload`, deleted in
+ * WP8); the type-level port here is its v2-native equivalent.
+ *
+ * Seam: node builtins + `typescript` + this bundle only. No imports needed here.
+ */
+import type { CheckPairEndpoint, CheckPairSpec, ProbeProtocol, ProbeTypeKind } from './api.js';
+/** Which pair endpoint supplies the `sent` value / the `expected` binding. */
+export type Side = 'producer' | 'consumer';
+export interface Direction {
+    sent: Side;
+    expected: Side;
+}
+/**
+ * The direction table, keyed on (protocol, type_kind) — one place. Structurally
+ * fixes the confirmed HTTP request-body inversion (data flows consumer ->
+ * producer for request bodies, so the check is consumer <= producer).
+ *
+ *  | protocol       | type_kind | sent     | expected |
+ *  | http, graphql  | response  | producer | consumer |
+ *  | http           | request   | consumer | producer |
+ *  | socket, pubsub | both      | consumer | producer |
+ */
+export declare function directionFor(protocol: ProbeProtocol, typeKind: ProbeTypeKind): Direction;
+/** Deterministic FNV-1a (32-bit) over the pair's stable key. Never a path. */
+export declare function fnv1a(input: string): string;
+/** The pair ID is derived from the pair's semantic identity, not the workspace
+ * path, so it is byte-stable across runs. */
+export declare function pairId(spec: CheckPairSpec): string;
+/** Names each gate line so a TS2344 can be attributed to a specific side+kind. */
+export type GateName = 'sent:any' | 'sent:unknown' | 'sent:never' | 'expected:any' | 'expected:unknown' | 'expected:never';
+export interface ProbePlan {
+    pairId: string;
+    spec: CheckPairSpec;
+    /** Probe file basename, e.g. pair_1a2b3c4d.ts */
+    fileName: string;
+    /** Which endpoint is sent vs expected (resolved via the direction table). */
+    direction: Direction;
+    sentEndpoint: CheckPairEndpoint;
+    expectedEndpoint: CheckPairEndpoint;
+    /** Generated probe source. */
+    source: string;
+    /** Lines the surface imports sit on (1-based). Errors here => unverifiable. */
+    importLines: number[];
+    /** 1-based line -> gate name. TS2344 here => baked-any / unverifiable. */
+    gateLines: Map<number, GateName>;
+    /** 1-based line of the value-level assignment. Errors here => incompatible. */
+    assignmentLine: number;
+}
+/**
+ * Build one probe, recording the exact line of every gate and the assignment so
+ * the classifier never depends on hard-coded offsets. `packageOf` maps a
+ * service name to its workspace package specifier (e.g. `@carrick/orders`).
+ */
+export declare function buildProbe(spec: CheckPairSpec, packageOf: (serviceName: string) => string): ProbePlan;