carrick 0.3.53

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

@@ -0,0 +1,147 @@
+/**
+ * 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.
+ */
+/**
+ * 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 function directionFor(protocol, typeKind) {
+    if (protocol === 'socket' || protocol === 'pubsub') {
+        return { sent: 'consumer', expected: 'producer' };
+    }
+    if (protocol === 'http' && typeKind === 'request') {
+        return { sent: 'consumer', expected: 'producer' };
+    }
+    // http/graphql response, and any other (http, graphql) shape.
+    return { sent: 'producer', expected: 'consumer' };
+}
+/** Deterministic FNV-1a (32-bit) over the pair's stable key. Never a path. */
+export function fnv1a(input) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < input.length; i++) {
+        hash ^= input.charCodeAt(i);
+        // hash *= 16777619, kept in 32-bit unsigned range.
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash.toString(16).padStart(8, '0');
+}
+/** The pair ID is derived from the pair's semantic identity, not the workspace
+ * path, so it is byte-stable across runs. */
+export function pairId(spec) {
+    const key = [
+        spec.protocol,
+        spec.type_kind,
+        spec.producer.service_name,
+        spec.producer.alias,
+        spec.consumer.service_name,
+        spec.consumer.alias,
+        spec.pair_key,
+    ].join('|');
+    return fnv1a(key);
+}
+/**
+ * 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 function buildProbe(spec, packageOf) {
+    const id = pairId(spec);
+    const direction = directionFor(spec.protocol, spec.type_kind);
+    const sentEndpoint = direction.sent === 'producer' ? spec.producer : spec.consumer;
+    const expectedEndpoint = direction.expected === 'producer' ? spec.producer : spec.consumer;
+    const sentPkg = packageOf(sentEndpoint.service_name);
+    const expectedPkg = packageOf(expectedEndpoint.service_name);
+    const lines = [];
+    const importLines = [];
+    const gateLines = new Map();
+    const push = (text) => {
+        lines.push(text);
+        return lines.length; // 1-based line number just written
+    };
+    importLines.push(push(`import type { ${sentEndpoint.alias} as Sent } from '${sentPkg}';`));
+    importLines.push(push(`import type { ${expectedEndpoint.alias} as Expected } from '${expectedPkg}';`));
+    push(`type IsAny<T> = 0 extends 1 & T ? true : false;`);
+    push(`type IsUnknown<T> = unknown extends T ? (0 extends 1 & T ? false : true) : false;`);
+    push(`type IsNever<T> = [T] extends [never] ? true : false;`);
+    push(`type Not<T extends boolean> = T extends true ? false : true;`);
+    push(`type Assert<T extends true> = T;`);
+    gateLines.set(push(`type _G_sent_any = Assert<Not<IsAny<Sent>>>;`), 'sent:any');
+    gateLines.set(push(`type _G_sent_unknown = Assert<Not<IsUnknown<Sent>>>;`), 'sent:unknown');
+    gateLines.set(push(`type _G_sent_never = Assert<Not<IsNever<Sent>>>;`), 'sent:never');
+    gateLines.set(push(`type _G_expected_any = Assert<Not<IsAny<Expected>>>;`), 'expected:any');
+    gateLines.set(push(`type _G_expected_unknown = Assert<Not<IsUnknown<Expected>>>;`), 'expected:unknown');
+    gateLines.set(push(`type _G_expected_never = Assert<Not<IsNever<Expected>>>;`), 'expected:never');
+    push(`declare const sent: Sent;`);
+    let assignmentLine;
+    if (spec.protocol === 'graphql') {
+        // GraphQL selection-set semantics (v1 `unwrapGraphqlPayload` parity): the
+        // producer side (always `sent` for graphql — see the direction table) is
+        // the resolver's return type. When that return is a single-payload
+        // ENVELOPE — exactly one property whose type is payload-shaped (an
+        // object, an array of objects, or a union of objects), every sibling a
+        // scalar or scalar array (`errors: string[]`) — the consumer's selection
+        // reads the payload, not the envelope, so the payload is the comparand.
+        //
+        // Fail-closed by construction:
+        //   - `Sent` already assignable to `Expected` short-circuits to `Sent`
+        //     (plain structural subset selection stays exactly as before);
+        //   - zero payload-shaped properties (already-bare payloads of scalars)
+        //     or several (ambiguous envelope, or a bare payload whose own fields
+        //     include more than one object-shaped property) keep the whole type —
+        //     the unwrap never fires on anything but an unambiguous envelope;
+        //   - `GqlObjLike` can never select `any`/`unknown`/`never` (top/bottom
+        //     types fail both its array and its object arm), and the comparand is
+        //     re-gated below anyway — the v2 port of v1's comparand re-guard, so
+        //     a payload decayed to a top type can never read compatible.
+        push(`type GqlObjLike<V> = [V] extends [readonly unknown[]] ? ([V] extends [readonly (infer E)[]] ? ([E] extends [readonly unknown[]] ? false : ([E] extends [object] ? true : false)) : false) : ([V] extends [object] ? true : false);`);
+        push(`type GqlIsUnion<T, U = T> = [T extends unknown ? ([U] extends [T] ? false : true) : never] extends [false] ? false : true;`);
+        push(`type GqlPayloadKeys<T> = { [K in keyof T]-?: [GqlObjLike<T[K]>] extends [true] ? K : never }[keyof T];`);
+        push(`type GqlSingleKey<K> = [K] extends [never] ? never : ([GqlIsUnion<K>] extends [false] ? K : never);`);
+        push(`type GqlPayloadOf<S> = [S] extends [readonly unknown[]] ? never : [GqlIsUnion<S>] extends [true] ? never : [S] extends [object] ? ([GqlSingleKey<GqlPayloadKeys<S>>] extends [never] ? never : S[GqlSingleKey<GqlPayloadKeys<S>> & keyof S]) : never;`);
+        push(`type GqlComparand = [Sent] extends [Expected] ? Sent : ([GqlPayloadOf<Sent>] extends [never] ? Sent : GqlPayloadOf<Sent>);`);
+        gateLines.set(push(`type _G_comparand_any = Assert<Not<IsAny<GqlComparand>>>;`), 'sent:any');
+        gateLines.set(push(`type _G_comparand_unknown = Assert<Not<IsUnknown<GqlComparand>>>;`), 'sent:unknown');
+        gateLines.set(push(`type _G_comparand_never = Assert<Not<IsNever<GqlComparand>>>;`), 'sent:never');
+        push(`declare const sentComparand: GqlComparand;`);
+        assignmentLine = push(`const expected: Expected = sentComparand;`);
+    }
+    else {
+        assignmentLine = push(`const expected: Expected = sent;`);
+    }
+    return {
+        pairId: id,
+        spec,
+        fileName: `pair_${id}.ts`,
+        direction,
+        sentEndpoint,
+        expectedEndpoint,
+        source: lines.join('\n') + '\n',
+        importLines,
+        gateLines,
+        assignmentLine,
+    };
+}

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

@@ -0,0 +1,31 @@
+/**
+ * Diagnostic scrub for the v2 check phase.
+ *
+ * Raw tsc diagnostics leak two run-varying / internal things into the most
+ * interesting error class (cross-stub conflicts): stub-absolute
+ * `import("/tmp/xxxx/packages/orders/types/surface")` paths inside elaboration
+ * text, and the probe's `Sent`/`Expected` import aliases in the headline. This
+ * pass maps every workspace-absolute path to a stable `@carrick/<service>` (or
+ * `pkg@version`) label and rewrites the aliases to the real surface names, so
+ * the message is user-facing AND byte-stable across runs with different temp
+ * dirs. Real TS text (e.g. TS2741 "... missing in type 'StockLevel'") is
+ * preserved intact.
+ *
+ * Seam: node builtins only; no imports needed.
+ */
+export interface ScrubContext {
+    /** Absolute path of the scratch workspace root (fully removed from output). */
+    workspaceRoot: string;
+    /** Workspace package dir (== sanitized service) -> the @carrick/<dir> label. */
+    packageLabelOf: (packageDir: string) => string | undefined;
+}
+/** Replace stub-absolute import paths and any lingering workspace root. */
+export declare function scrubPaths(text: string, ctx: ScrubContext): string;
+/**
+ * Rewrite the probe's `Sent`/`Expected` import aliases (which the compiler
+ * prints in the headline) to the real surface alias names. Only quoted forms
+ * are touched, so real type names in nested elaboration lines are preserved.
+ */
+export declare function rewriteAliases(text: string, sentAlias: string, expectedAlias: string): string;
+/** Full scrub applied to an incompatible pair's diagnostic message. */
+export declare function scrubDiagnostic(text: string, ctx: ScrubContext, sentAlias: string, expectedAlias: string): string;

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

@@ -0,0 +1,71 @@
+/**
+ * Diagnostic scrub for the v2 check phase.
+ *
+ * Raw tsc diagnostics leak two run-varying / internal things into the most
+ * interesting error class (cross-stub conflicts): stub-absolute
+ * `import("/tmp/xxxx/packages/orders/types/surface")` paths inside elaboration
+ * text, and the probe's `Sent`/`Expected` import aliases in the headline. This
+ * pass maps every workspace-absolute path to a stable `@carrick/<service>` (or
+ * `pkg@version`) label and rewrites the aliases to the real surface names, so
+ * the message is user-facing AND byte-stable across runs with different temp
+ * dirs. Real TS text (e.g. TS2741 "... missing in type 'StockLevel'") is
+ * preserved intact.
+ *
+ * Seam: node builtins only; no imports needed.
+ */
+const IMPORT_PATH_RE = /import\("([^"]+)"\)/g;
+const PNPM_SEGMENT_RE = /\/\.pnpm\/([^/]+)\/node_modules\//;
+const NODE_MODULES_TAIL_RE = /\/node_modules\/((?:@[^/]+\/)?[^/]+)(?:\/|$)/;
+const PACKAGES_SEGMENT_RE = /\/packages\/([^/]+)\//;
+/** Map one absolute import specifier to a stable, path-free label. */
+function labelForImportPath(absPath, ctx) {
+    const normalized = absPath.split('\\').join('/');
+    // pnpm isolated store: .../.pnpm/<name>@<ver>/node_modules/<name>/...
+    const pnpm = normalized.match(PNPM_SEGMENT_RE);
+    if (pnpm)
+        return pnpm[1];
+    // A stub tree file: .../packages/<dir>/types/surface -> @carrick/<service>
+    const pkg = normalized.match(PACKAGES_SEGMENT_RE);
+    if (pkg) {
+        const label = ctx.packageLabelOf(pkg[1]);
+        if (label)
+            return label;
+    }
+    // Any other node_modules path (defensive; isolated linker should not hit).
+    const nm = normalized.match(NODE_MODULES_TAIL_RE);
+    if (nm)
+        return nm[1];
+    // Fall back to just stripping the workspace root prefix.
+    if (normalized.startsWith(ctx.workspaceRoot.split('\\').join('/'))) {
+        return normalized.slice(ctx.workspaceRoot.length).replace(/^\/+/, '');
+    }
+    return normalized;
+}
+/** Replace stub-absolute import paths and any lingering workspace root. */
+export function scrubPaths(text, ctx) {
+    let out = text.replace(IMPORT_PATH_RE, (_m, p1) => {
+        return `import("${labelForImportPath(p1, ctx)}")`;
+    });
+    // Defensive: no raw temp path may survive anywhere in the message.
+    if (ctx.workspaceRoot) {
+        out = out.split(ctx.workspaceRoot).join('');
+        out = out.split(ctx.workspaceRoot.split('/').join('\\')).join('');
+    }
+    return out;
+}
+/**
+ * Rewrite the probe's `Sent`/`Expected` import aliases (which the compiler
+ * prints in the headline) to the real surface alias names. Only quoted forms
+ * are touched, so real type names in nested elaboration lines are preserved.
+ */
+export function rewriteAliases(text, sentAlias, expectedAlias) {
+    return text
+        .split(`'Sent'`)
+        .join(`'${sentAlias}'`)
+        .split(`'Expected'`)
+        .join(`'${expectedAlias}'`);
+}
+/** Full scrub applied to an incompatible pair's diagnostic message. */
+export function scrubDiagnostic(text, ctx, sentAlias, expectedAlias) {
+    return rewriteAliases(scrubPaths(text, ctx), sentAlias, expectedAlias);
+}

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

@@ -0,0 +1,52 @@
+/**
+ * Scratch synthetic-monorepo assembly for the v2 check phase.
+ *
+ * Copies each capture stub package into a temp pnpm workspace
+ * (node-linker=isolated, so every stub keeps its OWN node_modules and two
+ * versions of one dependency genuinely coexist), adds a `carrick-probes`
+ * package that depends on every stub via `workspace:*`, writes the checker
+ * tsconfig, and computes semver-dedupe overrides so patch/minor drift on a
+ * private-member class does not manufacture a nominal false-incompatible
+ * (design Check step 6) while genuinely conflicting majors stay physically
+ * duplicated (and thus verdict incompatible, correctly).
+ *
+ * Seam: node builtins + this bundle only.
+ */
+import type { CheckStubInput } from './api.js';
+import type { ProbePlan } from './check-probe.js';
+export interface AssembledStub {
+    serviceName: string;
+    /** Workspace package dir under packages/ (== the @carrick/<dir> suffix). */
+    packageDir: string;
+    /** Full package specifier, e.g. @carrick/orders-engine. */
+    packageName: string;
+}
+export interface AssembledWorkspace {
+    workspaceDir: string;
+    probesDir: string;
+    /** Relative (forward-slash) probes dir, e.g. packages/carrick-probes. */
+    probesRel: string;
+    stubs: AssembledStub[];
+    /** service name -> package specifier (for probe imports). */
+    packageOf: (serviceName: string) => string;
+    /** package dir -> package specifier (for scrub labels). */
+    packageLabelOf: (packageDir: string) => string | undefined;
+    /** package dir -> service name (for poison attribution). */
+    serviceOfPackageDir: (packageDir: string) => string | undefined;
+}
+/**
+ * Build pnpm exact-selector overrides that collapse semver-compatible drift to
+ * the max version in each compat group, leaving conflicting majors untouched.
+ * Returns a deterministically key-sorted map, e.g. { "bson@6.8.0": "6.10.1" }.
+ */
+export declare function computeDedupeOverrides(stubs: {
+    dependencies: Record<string, string>;
+}[]): Record<string, string>;
+export interface AssembleOptions {
+    stubs: CheckStubInput[];
+    workspaceRoot?: string;
+}
+/** Create the scratch workspace and copy in the stub packages. */
+export declare function assembleWorkspace(opts: AssembleOptions): AssembledWorkspace;
+/** Write the generated probe files into the assembled probes package. */
+export declare function writeProbes(ws: AssembledWorkspace, plans: ProbePlan[]): void;

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

@@ -0,0 +1,218 @@
+/**
+ * Scratch synthetic-monorepo assembly for the v2 check phase.
+ *
+ * Copies each capture stub package into a temp pnpm workspace
+ * (node-linker=isolated, so every stub keeps its OWN node_modules and two
+ * versions of one dependency genuinely coexist), adds a `carrick-probes`
+ * package that depends on every stub via `workspace:*`, writes the checker
+ * tsconfig, and computes semver-dedupe overrides so patch/minor drift on a
+ * private-member class does not manufacture a nominal false-incompatible
+ * (design Check step 6) while genuinely conflicting majors stay physically
+ * duplicated (and thus verdict incompatible, correctly).
+ *
+ * Seam: node builtins + this bundle only.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+const PROBES_PACKAGE = 'carrick-probes';
+function parseVersion(v) {
+    const core = v.replace(/^[^\d]*/, '').split('-')[0].split('+')[0];
+    const [maj = '0', min = '0', pat = '0'] = core.split('.');
+    return {
+        major: Number(maj) || 0,
+        minor: Number(min) || 0,
+        patch: Number(pat) || 0,
+        raw: v,
+    };
+}
+/**
+ * Semver compat key: same key => dedupe candidates. 0.x is minor-scoped, and
+ * 0.0.x is patch-scoped: semver treats every 0.0.x release as its own
+ * breaking boundary, so 0.0.3 and 0.0.5 must never collapse onto one
+ * physical copy (that would manufacture a false-compatible for by-reference
+ * library types).
+ */
+function compatKey(v) {
+    if (v.major > 0)
+        return `${v.major}`;
+    if (v.minor > 0)
+        return `0.${v.minor}`;
+    return `0.0.${v.patch}`;
+}
+function versionGreater(a, b) {
+    if (a.major !== b.major)
+        return a.major > b.major;
+    if (a.minor !== b.minor)
+        return a.minor > b.minor;
+    return a.patch > b.patch;
+}
+/**
+ * Build pnpm exact-selector overrides that collapse semver-compatible drift to
+ * the max version in each compat group, leaving conflicting majors untouched.
+ * Returns a deterministically key-sorted map, e.g. { "bson@6.8.0": "6.10.1" }.
+ */
+export function computeDedupeOverrides(stubs) {
+    const byName = new Map();
+    for (const stub of stubs) {
+        for (const [name, version] of Object.entries(stub.dependencies ?? {})) {
+            if (!byName.has(name))
+                byName.set(name, new Set());
+            byName.get(name).add(version);
+        }
+    }
+    const overrides = {};
+    for (const [name, versions] of byName) {
+        if (versions.size < 2)
+            continue;
+        const groups = new Map();
+        for (const raw of versions) {
+            const parsed = parseVersion(raw);
+            const key = compatKey(parsed);
+            if (!groups.has(key))
+                groups.set(key, []);
+            groups.get(key).push(parsed);
+        }
+        for (const members of groups.values()) {
+            if (members.length < 2)
+                continue;
+            let max = members[0];
+            for (const m of members)
+                if (versionGreater(m, max))
+                    max = m;
+            for (const m of members) {
+                if (m.raw !== max.raw)
+                    overrides[`${name}@${m.raw}`] = max.raw;
+            }
+        }
+    }
+    return Object.fromEntries(Object.keys(overrides)
+        .sort()
+        .map((k) => [k, overrides[k]]));
+}
+function readStubPackageName(stubDir) {
+    const pkgPath = path.join(stubDir, 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    if (!pkg.name)
+        throw new Error(`stub package.json missing 'name': ${pkgPath}`);
+    return pkg.name;
+}
+function readStubDependencies(stubDir) {
+    const pkg = JSON.parse(fs.readFileSync(path.join(stubDir, 'package.json'), 'utf8'));
+    return pkg.dependencies ?? {};
+}
+/** Package dir under packages/ == the sanitized suffix of @carrick/<suffix>. */
+function packageDirOf(packageName) {
+    const slash = packageName.lastIndexOf('/');
+    return slash >= 0 ? packageName.slice(slash + 1) : packageName;
+}
+/** Create the scratch workspace and copy in the stub packages. */
+export function assembleWorkspace(opts) {
+    const root = opts.workspaceRoot ?? os.tmpdir();
+    fs.mkdirSync(root, { recursive: true });
+    const workspaceDir = fs.mkdtempSync(path.join(root, 'carrick-check-v2-'));
+    const packagesDir = path.join(workspaceDir, 'packages');
+    fs.mkdirSync(packagesDir, { recursive: true });
+    fs.writeFileSync(path.join(workspaceDir, '.npmrc'), NPMRC);
+    fs.writeFileSync(path.join(workspaceDir, 'pnpm-workspace.yaml'), 'packages:\n  - "packages/*"\n');
+    const assembled = [];
+    const dependencySets = [];
+    const svcToPkg = new Map();
+    const dirToPkg = new Map();
+    const dirToSvc = new Map();
+    for (const stub of opts.stubs) {
+        const packageName = readStubPackageName(stub.stub_dir);
+        const packageDir = packageDirOf(packageName);
+        const dest = path.join(packagesDir, packageDir);
+        fs.cpSync(stub.stub_dir, dest, {
+            recursive: true,
+            filter: (src) => !src.split(path.sep).includes('node_modules'),
+        });
+        assembled.push({ serviceName: stub.service_name, packageDir, packageName });
+        dependencySets.push({ dependencies: readStubDependencies(stub.stub_dir) });
+        svcToPkg.set(stub.service_name, packageName);
+        dirToPkg.set(packageDir, packageName);
+        dirToSvc.set(packageDir, stub.service_name);
+    }
+    // Root manifest carries the semver-dedupe overrides.
+    const overrides = computeDedupeOverrides(dependencySets);
+    fs.writeFileSync(path.join(workspaceDir, 'package.json'), JSON.stringify({
+        name: 'carrick-check-workspace',
+        version: '0.0.0',
+        private: true,
+        ...(Object.keys(overrides).length > 0 ? { pnpm: { overrides } } : {}),
+    }, null, 2) + '\n');
+    const probesDir = path.join(packagesDir, PROBES_PACKAGE);
+    fs.mkdirSync(path.join(probesDir, 'probes'), { recursive: true });
+    const probeDeps = {};
+    for (const stub of assembled)
+        probeDeps[stub.packageName] = 'workspace:*';
+    fs.writeFileSync(path.join(probesDir, 'package.json'), JSON.stringify({
+        name: PROBES_PACKAGE,
+        version: '0.0.0',
+        private: true,
+        dependencies: probeDeps,
+    }, null, 2) + '\n');
+    fs.writeFileSync(path.join(probesDir, 'tsconfig.json'), CHECKER_TSCONFIG);
+    return {
+        workspaceDir,
+        probesDir,
+        probesRel: `packages/${PROBES_PACKAGE}`,
+        stubs: assembled,
+        packageOf: (s) => {
+            const pkg = svcToPkg.get(s);
+            if (!pkg)
+                throw new Error(`no stub for service '${s}'`);
+            return pkg;
+        },
+        packageLabelOf: (dir) => dirToPkg.get(dir),
+        serviceOfPackageDir: (dir) => dirToSvc.get(dir),
+    };
+}
+/** Write the generated probe files into the assembled probes package. */
+export function writeProbes(ws, plans) {
+    for (const plan of plans) {
+        fs.writeFileSync(path.join(ws.probesDir, 'probes', plan.fileName), plan.source);
+    }
+}
+const NPMRC = [
+    // Every stub gets its own node_modules: two versions of one dep coexist and
+    // tsc resolves each stub's ref to its own copy (the isolation guarantee).
+    'node-linker=isolated',
+    // Stubs pin arbitrary library majors; peer conflicts must degrade to
+    // unverifiable via the probe gates, never abort the whole install.
+    'strict-peer-dependencies=false',
+    // Determinism: install exactly the pinned closure, no implicit peer pull-in.
+    'auto-install-peers=false',
+    // Determinism: the scratch workspace has no committed lockfile, so the
+    // transitive closure would otherwise be a pure function of live registry
+    // state. prefer-offline resolves from the local store/metadata cache
+    // whenever possible (byte-stable across runs on a host), and the explicit
+    // resolution-mode pins pnpm's resolver behavior across pnpm versions.
+    // Direct deps are exact-pinned by the stubs; only transitives resolve.
+    'prefer-offline=true',
+    'resolution-mode=highest',
+    '',
+].join('\n');
+// skipLibCheck:false is load-bearing (surfaces cross-stub declare-global
+// TS2717 collisions so the poison rule can convert them to honest
+// unverifiables). noUnusedLocals/Parameters:false keep TS6133/6196 off the
+// gate/assignment lines. moduleResolution bundler accepts both node16
+// `.js`-suffixed and extensionless specifiers in one program.
+const CHECKER_TSCONFIG = JSON.stringify({
+    compilerOptions: {
+        strict: true,
+        exactOptionalPropertyTypes: false,
+        skipLibCheck: false,
+        noUnusedLocals: false,
+        noUnusedParameters: false,
+        moduleResolution: 'bundler',
+        module: 'esnext',
+        target: 'es2022',
+        lib: ['es2022', 'dom', 'dom.iterable'],
+        types: [],
+        noEmit: true,
+        forceConsistentCasingInFileNames: true,
+    },
+    include: ['probes/**/*.ts'],
+}, null, 2) + '\n';

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

@@ -0,0 +1,39 @@
+/**
+ * v2 check core: "tsc as the judge"
+ * (docs/reference/type-compat-synthetic-monorepo.md, Check phase).
+ *
+ * Consumes two or more capture stub packages, assembles a scratch synthetic
+ * monorepo, installs pinned deps with the vendored pnpm (isolated linker),
+ * generates one probe per matched pair, runs the vendored `tsc` CLI, and
+ * classifies diagnostics into the four buckets. Deterministic given the stubs
+ * and pairs: verdicts are byte-stable across runs (the scrub pass removes the
+ * per-run temp path, and the pair IDs / ordering derive from the pair specs).
+ *
+ * Seam: this file imports only node builtins, `typescript` (for the version
+ * string), and the rest of this bundle. The sidecar reaches it only through
+ * ./index.js. The judge is the `tsc` CLI (no compiler API), which keeps the
+ * check phase TS7-ready by construction.
+ */
+import type { CheckOptions, CheckProgressPhase, CheckResult } from './api.js';
+export type CheckProgress = (phase: CheckProgressPhase, message: string) => void;
+/**
+ * Locate a vendored executable the way node locates a package: walk up from
+ * the bundle and take the first `node_modules/.bin/<name>` that exists.
+ *
+ * Where the bins sit depends on how the sidecar arrived. A checkout and the
+ * release tarball both keep them in the sidecar's own `node_modules`, so the
+ * first candidate hits and nothing changes. An npm install never can: npm
+ * strips nested `node_modules` from a published tarball, so the sidecar ships
+ * as a plain directory inside the package and its dependencies are installed
+ * by the package that carries it — hoisted to the install root, or nested one
+ * level up when a version conflict forces it. Assuming one shape is what made
+ * an installed `carrick` degrade every pair to unverifiable (carrick#833).
+ *
+ * `from` is injectable so the layouts can be pinned by test; production always
+ * starts at the bundle. Returns the sidecar-local path when nothing exists,
+ * which is the caller's "not found" signal and the most useful thing to name.
+ */
+export declare function resolveVendoredBin(name: string, from?: string): string;
+/** Run the deterministic check phase. Async: install + tsc run off the event
+ * loop so the sidecar stays responsive and can emit keepalive frames. */
+export declare function runCheck(opts: CheckOptions, onProgress?: CheckProgress): Promise<CheckResult>;