@wix/pathgrade 1.0.30 → 1.0.32

package/dist/internal/direct-mcp-v2/json.d.ts

@@ -1,8 +1,6 @@
 import type { JsonValue } from './types.js';
-export declare function assertJsonValue(value: unknown, path?: string, ancestors?: Set<object>): asserts value is JsonValue;
 export declare function canonicalJson(value: unknown): string;
 export declare function sha256Canonical(value: unknown): string;
-export declare function escapePointerToken(token: string): string;
 export declare function parsePointer(pointer: string): string[];
 export declare const MISSING: unique symbol;
 export declare function resolvePointer(value: JsonValue, pointer: string): JsonValue | typeof MISSING;

package/dist/internal/direct-mcp-v2/json.js

@@ -13,7 +13,7 @@ function assertValidString(value, path) {
         }
     }
 }
-export function assertJsonValue(value, path = '$', ancestors = new Set()) {
+function assertJsonValue(value, path = '$', ancestors = new Set()) {
     if (value === null || typeof value === 'boolean')
         return;
     if (typeof value === 'string')
@@ -69,7 +69,7 @@ export function canonicalJson(value) {
 export function sha256Canonical(value) {
     return createHash('sha256').update(canonicalJson(value)).digest('hex');
 }
-export function escapePointerToken(token) {
+function escapePointerToken(token) {
     return token.replaceAll('~', '~0').replaceAll('/', '~1');
 }
 export function parsePointer(pointer) {

package/dist/internal/direct-mcp-v2/runtime-lock.d.ts

@@ -32,7 +32,7 @@ export type RuntimeLockAdmissionContext<TControlPlane extends RuntimeLockControl
     commandVersion?: (commandPath: string, args: readonly string[]) => Promise<string>;
     initializeControlPlane(commandPath: string, args: readonly string[]): Promise<TControlPlane>;
 };
-export type RuntimeLockIdentity = {
+type RuntimeLockIdentity = {
     provider: RuntimeLock['provider'];
     platform: string;
     architecture: string;
@@ -49,3 +49,4 @@ export type RuntimeLockAdmission<TControlPlane extends RuntimeLockControlPlane =
     controlPlane: TControlPlane;
 };
 export declare function admitRuntimeLock<TControlPlane extends RuntimeLockControlPlane>(rawLock: RuntimeLock, context: RuntimeLockAdmissionContext<TControlPlane>): Promise<RuntimeLockAdmission<TControlPlane>>;
+export {};

package/dist/internal/direct-mcp-v2/runtime-profile.d.ts

@@ -24,5 +24,4 @@ export type RuntimeAdmissionResult = {
 };
 export declare function profileFingerprint(profile: Omit<RuntimeCapabilityProfile, 'profileFingerprint' | 'runtimeCapabilityFingerprint'>): string;
 export declare function runtimeCapabilityFingerprint(normalizedHandshake: JsonObject): string;
-export declare function parseRuntimeProfile(input: string | unknown): RuntimeCapabilityProfile;
 export declare function admitRuntimeProfile(rawProfile: string | unknown, context: RuntimeAdmissionContext): Promise<RuntimeAdmissionResult>;

package/dist/internal/direct-mcp-v2/runtime-profile.js

@@ -28,7 +28,7 @@ export function profileFingerprint(profile) {
 export function runtimeCapabilityFingerprint(normalizedHandshake) {
     return sha256Canonical(normalizedHandshake);
 }
-export function parseRuntimeProfile(input) {
+function parseRuntimeProfile(input) {
     const value = typeof input === 'string' ? parseStrictJson(input) : input;
     canonicalJson(value);
     if (!object(value))

package/dist/internal/direct-mcp-v2/types.d.ts

@@ -3,8 +3,8 @@ export type JsonValue = JsonPrimitive | JsonValue[] | JsonObject;
 export type JsonObject = {
     [key: string]: JsonValue;
 };
-export type Sha256 = string;
-export type HmacSha256 = string;
+type Sha256 = string;
+type HmacSha256 = string;
 export type ProviderId = 'claude' | 'codex' | 'cursor' | 'opencode';
 export type MatchPredicate = {
     pointer: string;
@@ -72,7 +72,7 @@ export type ScenarioDiagnostic = {
     path: string;
     message: string;
 };
-export type CompiledTool = {
+type CompiledTool = {
     qualifiedToolId: string;
     serverId: string;
     toolId: string;
@@ -80,7 +80,7 @@ export type CompiledTool = {
     otherwise: ScenarioRejection;
     effectful: boolean;
 };
-export type ScenarioIR = {
+type ScenarioIR = {
     version: 2;
     scenarioId: string;
     initialState: string;
@@ -231,3 +231,4 @@ export type ProviderCorroboration = {
     phase: string;
     order: number;
 };
+export {};

package/dist/providers/mcp-config.d.ts

@@ -29,9 +29,7 @@ export type McpDeclaration = {
 } | {
     mock: MockMcpServerDescriptor | MockMcpServerDescriptor[];
 };
-export declare const MCP_CONFIG_FILENAME = ".pathgrade-mcp.json";
 export declare function readStagedMcpServers(workspacePath: string, mcpConfigPath?: string): Promise<Record<string, McpConfigFileEntry> | undefined>;
-export declare function missingMcpSecretReferences(mcpServers: Record<string, McpConfigFileEntry> | undefined, env: Record<string, string | undefined>): string[];
 export declare function assertMcpSecretReferencesReady(opts: {
     workspacePath: string;
     mcpConfigPath?: string;

package/dist/providers/mcp-config.js

@@ -1,6 +1,6 @@
 import fs from 'fs-extra';
 import * as path from 'path';
-export const MCP_CONFIG_FILENAME = '.pathgrade-mcp.json';
+const MCP_CONFIG_FILENAME = '.pathgrade-mcp.json';
 const GENERATED_MOCK_SERVER_FILENAME = '.pathgrade-mcp-mock-server.cjs';
 function isRecord(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
@@ -76,7 +76,7 @@ export async function readStagedMcpServers(workspacePath, mcpConfigPath = MCP_CO
         return undefined;
     return readMcpServers(await fs.readJson(configPath));
 }
-export function missingMcpSecretReferences(mcpServers, env) {
+function missingMcpSecretReferences(mcpServers, env) {
     if (!mcpServers)
         return [];
     const missing = [];

package/dist/providers/mcp-runtime-mounting.d.ts

@@ -1,20 +1,12 @@
 import type { McpStdioEntry } from './mcp-config.js';
 import type { McpSafetyOptions } from '../sdk/mcp-safety.js';
-export type ClaudeSdkMcpServerEntry = McpStdioEntry | {
+type ClaudeSdkMcpServerEntry = McpStdioEntry | {
     type: 'http';
     url: string;
     headers?: Record<string, string>;
 };
 /** Object form of MCP server entries the SDK driver passes to `Options.mcpServers`. */
 export type McpServersObject = Record<string, ClaudeSdkMcpServerEntry>;
-export type CodexMcpServerEntry = McpStdioEntry | {
-    url: string;
-    http_headers?: Record<string, string>;
-    env_http_headers?: Record<string, string>;
-    bearer_token_env_var?: string;
-    startup_timeout_sec?: number;
-    tool_timeout_sec?: number;
-};
 export interface CodexAppServerMcpConfig extends Record<string, unknown> {
     mcp_servers: Record<string, unknown>;
 }

package/dist/providers/sandbox-lifecycle.d.ts

@@ -1,6 +1,4 @@
-export declare const SANDBOX_PREFIX = "pathgrade-";
 export declare const SANDBOX_MARKER = ".pathgrade-sandbox.json";
-export declare const STALE_SANDBOX_AGE_MS: number;
 interface RemoveSandboxRootOptions {
     remove?: (target: string) => Promise<void>;
     sleep?: (ms: number) => Promise<void>;

package/dist/providers/sandbox-lifecycle.js

@@ -1,9 +1,9 @@
 import fs from 'fs-extra';
 import * as os from 'os';
 import * as path from 'path';
-export const SANDBOX_PREFIX = 'pathgrade-';
+const SANDBOX_PREFIX = 'pathgrade-';
 export const SANDBOX_MARKER = '.pathgrade-sandbox.json';
-export const STALE_SANDBOX_AGE_MS = 24 * 60 * 60 * 1_000;
+const STALE_SANDBOX_AGE_MS = 24 * 60 * 60 * 1_000;
 let startupCleanup;
 const SANDBOX_REMOVE_RETRY_DELAYS_MS = [
     50,

package/dist/providers/scripted-mcp-mock-host.d.ts

@@ -1,6 +1,6 @@
 import type { ToolEvent } from '../tool-events.js';
 import { type CompiledMcpMockSession } from '../sdk/mcp-mock-approvals.js';
-export interface ScriptedMcpDecision {
+interface ScriptedMcpDecision {
     decision: 'approve' | 'deny';
     outcome: 'matched' | 'unmatched' | 'protocol_error';
     reason: 'rule_match' | 'no_matching_rule' | 'protocol_error';

package/dist/providers/workspace.d.ts

@@ -1,6 +1,5 @@
 import { type SandboxConfig } from './sandbox.js';
 import type { CommandResult, McpConfigOrigin } from '../types.js';
-export type { McpDeclaration } from './mcp-config.js';
 export interface Workspace {
     readonly path: string;
     readonly mcpConfigPath: string | undefined;

package/dist/reporters/github-comment.d.ts

@@ -26,17 +26,6 @@ export declare function commentMarker(commentId: string): string;
  * posted as a GitHub issue comment body.
  */
 export declare function formatReportMarkdown(report: PathgradeReport, opts: FormatOptions): string;
-/**
- * Render the `### Selection` section for the PR comment. Pure: no fs,
- * no network, no reporter side effects. Three variants:
- *
- *   - `global_match` set → "global trigger fired" one-liner, no collapsible.
- *   - `skipped` empty + `selected` non-empty → "every eval had a matching
- *     change" one-liner.
- *   - otherwise → "Ran **X of Y**" line + `<details>` block listing
- *     skipped eval paths as inline code.
- */
-export declare function formatSelectionSection(selection: PathgradeSelectionReport): string;
 export interface PrContext {
     owner: string;
     repo: string;

package/dist/reporters/github-comment.js

@@ -114,7 +114,7 @@ export function formatReportMarkdown(report, opts) {
  *   - otherwise → "Ran **X of Y**" line + `<details>` block listing
  *     skipped eval paths as inline code.
  */
-export function formatSelectionSection(selection) {
+function formatSelectionSection(selection) {
     const out = [];
     out.push('### Selection');
     const total = selection.selected.length + selection.skipped.length;

package/dist/reporters/verbose-emitter.d.ts

@@ -1,11 +1,3 @@
-/** Maximum characters retained in a prompt/reply preview before truncation. */
-export declare const PREVIEW_MAX_CHARS = 80;
-/** Maximum characters retained in a retry error message before truncation. */
-export declare const RETRY_ERROR_MAX_CHARS = 120;
-/** Ellipsis appended to truncated strings. */
-export declare const TRUNCATION_SUFFIX = "\u2026";
-/** Newline replacement in single-line previews. */
-export declare const NEWLINE_REPLACEMENT = "\u23CE";
 export interface VerboseSink {
     write(line: string): void;
 }
@@ -19,33 +11,33 @@ export interface VerboseEmitterOptions {
      */
     testName?: string;
 }
-export interface TurnStartArgs {
+interface TurnStartArgs {
     turn: number;
     kind: 'agent_start' | 'user_reply';
     message: string;
 }
-export interface ToolEventArgs {
+interface ToolEventArgs {
     action: string;
     summary: string;
 }
-export interface TurnEndArgs {
+interface TurnEndArgs {
     turn: number;
     durationMs: number;
     outputLines: number;
     messagePreview: string;
 }
-export interface RetryArgs {
+interface RetryArgs {
     attempt: number;
     maxAttempts: number;
     errorMessage: string;
 }
-export interface ReactionFiredArgs {
+interface ReactionFiredArgs {
     turn: number;
     reactionIndex: number;
     pattern: string;
     reply: string;
 }
-export interface ConversationEndArgs {
+interface ConversationEndArgs {
     reason: string;
     turns: number;
     durationMs: number;
@@ -61,9 +53,5 @@ export interface VerboseEmitter {
     reactionFired(args: ReactionFiredArgs): void;
     conversationEnd(args: ConversationEndArgs): void;
 }
-/**
- * Build a preview string: strip newlines, truncate to a max length.
- * `null` / `undefined` becomes an empty string so formatting never throws.
- */
-export declare function preview(text: string | null | undefined, max?: number): string;
 export declare function createVerboseEmitter(opts: VerboseEmitterOptions): VerboseEmitter;
+export {};

package/dist/reporters/verbose-emitter.js

@@ -10,18 +10,18 @@
  */
 import { fmt } from '../utils/cli.js';
 /** Maximum characters retained in a prompt/reply preview before truncation. */
-export const PREVIEW_MAX_CHARS = 80;
+const PREVIEW_MAX_CHARS = 80;
 /** Maximum characters retained in a retry error message before truncation. */
-export const RETRY_ERROR_MAX_CHARS = 120;
+const RETRY_ERROR_MAX_CHARS = 120;
 /** Ellipsis appended to truncated strings. */
-export const TRUNCATION_SUFFIX = '…';
+const TRUNCATION_SUFFIX = '…';
 /** Newline replacement in single-line previews. */
-export const NEWLINE_REPLACEMENT = '⏎';
+const NEWLINE_REPLACEMENT = '⏎';
 /**
  * Build a preview string: strip newlines, truncate to a max length.
  * `null` / `undefined` becomes an empty string so formatting never throws.
  */
-export function preview(text, max = PREVIEW_MAX_CHARS) {
+function preview(text, max = PREVIEW_MAX_CHARS) {
     const normalized = (text ?? '').replace(/\r?\n/g, NEWLINE_REPLACEMENT);
     if (normalized.length <= max)
         return normalized;

package/dist/reporting/comparison-contract.d.ts

@@ -0,0 +1,10 @@
+import type { ComparisonContract, EvalReport } from '../types.js';
+import type { Scorer } from '../sdk/types.js';
+import type { ReportGroupInput } from './types.js';
+export declare function buildComparisonContract(input: {
+    group: ReportGroupInput;
+    report: EvalReport;
+    attemptsRequested: number;
+    attemptsCompleted: number;
+}): ComparisonContract;
+export declare function createScorerRevision(scorers: readonly Scorer[]): string | undefined;

package/dist/reporting/comparison-contract.js

@@ -0,0 +1,127 @@
+import { createHash } from 'node:crypto';
+import { canonicalizeJson } from '../core/canonical-json.js';
+export function buildComparisonContract(input) {
+    const unavailable = new Set();
+    const evaluations = input.group.cases.flatMap(testCase => {
+        const caseIdentity = testCase.repeatKey ?? testCase.caseId ?? testCase.name;
+        return (testCase.attempts?.flatMap(attempt => attempt.evaluations ?? [])
+            ?? testCase.evaluations
+            ?? [])
+            .filter(evaluation => evaluation.resultKind !== 'synthetic_no_evaluation')
+            .map((evaluation, index) => ({
+            case: caseIdentity,
+            definition: evaluation.evaluationDefinitionKey ?? `position:${index}`,
+            scorer: evaluation.scorerRevision,
+            runtime: runtimeIdentity(evaluation.agent ?? evaluation.trial?.agent),
+        }));
+    });
+    const definitionRevision = input.group.sourceRevision
+        ? revision('definition', {
+            source: input.group.sourceRevision,
+            evaluations: uniqueSorted(evaluations.map(evaluation => ({
+                case: evaluation.case, definition: evaluation.definition,
+            }))),
+        })
+        : undefined;
+    if (!definitionRevision)
+        unavailable.add('definition_metadata_missing');
+    const scorerRevision = evaluations.length > 0 && evaluations.every(evaluation => evaluation.scorer)
+        ? revision('scorers', uniqueSorted(evaluations.map(evaluation => ({
+            case: evaluation.case,
+            definition: evaluation.definition,
+            scorer: evaluation.scorer,
+        }))))
+        : undefined;
+    if (!scorerRevision)
+        unavailable.add('scorer_metadata_missing');
+    const runtimeComplete = evaluations.length > 0
+        && evaluations.every(evaluation => Object.values(evaluation.runtime)
+            .every(value => value !== undefined));
+    const runtimeRevision = runtimeComplete
+        ? revision('runtime', uniqueSorted(evaluations.map(evaluation => ({
+            case: evaluation.case,
+            definition: evaluation.definition,
+            runtime: evaluation.runtime,
+        }))))
+        : undefined;
+    if (!runtimeRevision)
+        unavailable.add('runtime_metadata_missing');
+    const reportableCases = input.group.cases.filter(testCase => testCase.reportable !== false
+        && testCase.state !== 'skipped' && testCase.state !== 'pending');
+    const samplingComplete = input.attemptsCompleted === input.attemptsRequested
+        && reportableCases.every(testCase => (testCase.attempts?.length ?? (testCase.evaluations === undefined ? 0 : 1)) === input.attemptsRequested)
+        && reportableCases.every(testCase => testCase.attempts
+            ? testCase.attempts.every(attempt => hasTerminalEvaluation(attempt.evaluations))
+            : hasTerminalEvaluation(testCase.evaluations));
+    const samplingRevision = samplingComplete
+        ? revision('sampling', {
+            attempts: input.attemptsRequested,
+            cases: reportableCases.map(testCase => testCase.repeatKey ?? testCase.caseId ?? testCase.name).toSorted(),
+        })
+        : undefined;
+    if (!samplingRevision)
+        unavailable.add('sampling_incomplete');
+    return {
+        version: 1,
+        ...(definitionRevision ? { definition_revision: definitionRevision } : {}),
+        ...(scorerRevision ? { scorer_revision: scorerRevision } : {}),
+        ...(runtimeRevision ? { runtime_revision: runtimeRevision } : {}),
+        ...(samplingRevision ? { sampling_revision: samplingRevision } : {}),
+        report_schema_revision: 'pathgrade-results-v2',
+        ...(unavailable.size > 0 ? { unavailable_reasons: [...unavailable].sort() } : {}),
+    };
+}
+function hasTerminalEvaluation(evaluations) {
+    return evaluations?.some(evaluation => evaluation.resultKind !== 'synthetic_no_evaluation') === true;
+}
+export function createScorerRevision(scorers) {
+    try {
+        return revision('scorer-declaration', scorers
+            .map(scorer => canonicalizeJson(scorerDeclaration(scorer))).toSorted());
+    }
+    catch {
+        return undefined;
+    }
+}
+function runtimeIdentity(agent) {
+    return {
+        name: agent?.name,
+        model: agent?.resolvedModel,
+        transport: agent?.transport,
+        interaction: agent?.interactionMode,
+    };
+}
+function scorerDeclaration(scorer) {
+    const common = { type: scorer.type, name: scorer.name.normalize('NFC'), weight: scorer.weight };
+    if (scorer.type === 'check' || scorer.type === 'score') {
+        return { ...common, function: scorer.fn.toString() };
+    }
+    if (scorer.type === 'tool_usage') {
+        return {
+            ...common,
+            expectations: scorer.expectations
+                .toSorted((left, right) => canonicalizeJson(left).localeCompare(canonicalizeJson(right))),
+        };
+    }
+    return {
+        ...common,
+        rubric: scorer.rubric,
+        model: scorer.model ?? null,
+        retry: scorer.retry ?? null,
+        includeToolEvents: scorer.includeToolEvents ?? null,
+        input: typeof scorer.input === 'function' ? scorer.input.toString() : scorer.input ?? null,
+        tools: scorer.tools?.toSorted() ?? null,
+        maxRounds: scorer.maxRounds ?? null,
+        cacheControl: scorer.cacheControl ?? null,
+    };
+}
+function revision(namespace, value) {
+    return `sha256:${createHash('sha256')
+        .update(canonicalizeJson(['pathgrade-comparison', 1, namespace, value]))
+        .digest('hex')}`;
+}
+function uniqueSorted(values) {
+    return [...new Map(values.map(value => [canonicalizeJson(value), value])).entries()]
+        .toSorted(([left], [right]) => left.localeCompare(right))
+        .map(([, value]) => value);
+}

package/dist/reporting/core.js

@@ -1,5 +1,6 @@
 import { buildDiagnosticsReport } from '../sdk/diagnostics.js';
 import { extractSkillsFromLog } from '../tool-events.js';
+import { buildComparisonContract } from './comparison-contract.js';
 export function buildPathgradeReport(input) {
     const warnings = [];
     const consolidatedGroups = [];
@@ -8,6 +9,7 @@ export function buildPathgradeReport(input) {
     const attemptsRequested = input.attemptsRequested ?? 1;
     const attemptsCompleted = input.attemptsCompleted ?? attemptsRequested;
     const builtGroups = input.groups.map(group => ({
+        input: group,
         groupName: group.groupName,
         cases: group.cases.map(toBuiltCase),
     }));
@@ -32,7 +34,18 @@ export function buildPathgradeReport(input) {
             return rest;
         });
         const { trials: _trials, ...rest } = report;
-        consolidatedGroups.push({ ...rest, trials: strippedTrials, trace_file: traceFile });
+        consolidatedGroups.push({
+            ...rest,
+            trials: strippedTrials,
+            trace_file: traceFile,
+            ...(group.input.sourceFile ? { source_file: group.input.sourceFile } : {}),
+            comparison_contract: buildComparisonContract({
+                group: group.input,
+                report,
+                attemptsRequested,
+                attemptsCompleted,
+            }),
+        });
     }
     const scores = reportableGroups.flatMap(group => group.cases.flatMap(testCase => (testCase.attempts
         .filter(attempt => attempt.resultKind !== 'synthetic_no_evaluation')

package/dist/reporting/report-parser.d.ts

@@ -0,0 +1,2 @@
+import type { PathgradeReport } from '../types.js';
+export declare function parsePathgradeReport(value: unknown): PathgradeReport;

package/dist/reporting/report-parser.js

@@ -0,0 +1,112 @@
+export function parsePathgradeReport(value) {
+    if (!isRecord(value)
+        || (value.version !== 1 && value.version !== 2)
+        || typeof value.timestamp !== 'string'
+        || typeof value.overall_pass_rate !== 'number'
+        || (value.version === 2 && (typeof value.overall_mean_reward !== 'number' || !validAttemptCounts(value)))
+        || !optionalNumber(value.threshold)
+        || (value.status !== 'pass' && value.status !== 'fail')
+        || (value.run_kind !== undefined && value.run_kind !== 'evaluation' && value.run_kind !== 'no-affected')
+        || !Array.isArray(value.groups)
+        || !value.groups.every(group => isReportGroup(group, value.version))
+        || !isSelection(value.selection)) {
+        throw new Error('PathGrade results.json is missing or has an unsupported schema');
+    }
+    return value;
+}
+function isReportGroup(value, version) {
+    return isRecord(value)
+        && typeof value.task === 'string'
+        && (version === 1 ? legacyMetrics(value) : schemaV2Metrics(value))
+        && optionalString(value.source_file)
+        && typeof value.trace_file === 'string'
+        && Array.isArray(value.skills_used)
+        && value.skills_used.every(item => typeof item === 'string')
+        && Array.isArray(value.trials)
+        && value.trials.every(isTrial)
+        && (value.comparison_contract === undefined || isComparisonContract(value.comparison_contract));
+}
+function isTrial(value) {
+    return isRecord(value)
+        && typeof value.trial_id === 'number'
+        && typeof value.duration_ms === 'number'
+        && typeof value.input_tokens === 'number'
+        && typeof value.output_tokens === 'number'
+        && optionalNumber(value.reward)
+        && optionalNumber(value.conversation_input_tokens)
+        && optionalNumber(value.conversation_output_tokens)
+        && optionalNumber(value.conversation_cost_usd)
+        && Array.isArray(value.scorer_results)
+        && value.scorer_results.every(scorer => isRecord(scorer)
+            && typeof scorer.scorer_type === 'string'
+            && typeof scorer.score === 'number'
+            && typeof scorer.weight === 'number');
+}
+function legacyMetrics(value) {
+    return typeof value.pass_rate === 'number'
+        && typeof value.pass_at_k === 'number'
+        && typeof value.pass_pow_k === 'number';
+}
+function schemaV2Metrics(value) {
+    return (value.status === 'pass' || value.status === 'fail')
+        && typeof value.mean_reward === 'number'
+        && optionalNumber(value.success_rate)
+        && (value.pass_at_k === undefined || (isRecord(value.pass_at_k)
+            && Object.values(value.pass_at_k).every(item => typeof item === 'number')))
+        && (value.pass_at_k_method === undefined || value.pass_at_k_method === 'finite_sample_unbiased')
+        && (value.pass_at_k_unavailable_reason === undefined
+            || value.pass_at_k_unavailable_reason === 'non_binary_reward'
+            || value.pass_at_k_unavailable_reason === 'incomplete_attempts'
+            || value.pass_at_k_unavailable_reason === 'case_identity_mismatch')
+        && optionalNonNegativeInteger(value.eligible_case_count)
+        && optionalPositiveInteger(value.attempts_per_case);
+}
+function validAttemptCounts(value) {
+    return typeof value.attempts_requested === 'number'
+        && Number.isSafeInteger(value.attempts_requested)
+        && value.attempts_requested >= 1
+        && typeof value.attempts_completed === 'number'
+        && Number.isSafeInteger(value.attempts_completed)
+        && value.attempts_completed >= 0
+        && value.attempts_completed <= value.attempts_requested;
+}
+function isSelection(value) {
+    return value === undefined || (isRecord(value)
+        && typeof value.base_ref === 'string'
+        && typeof value.changed_files_count === 'number'
+        && Array.isArray(value.selected)
+        && value.selected.every(item => typeof item === 'string')
+        && Array.isArray(value.skipped)
+        && value.skipped.every(item => isRecord(item)
+            && typeof item.file === 'string'
+            && item.reason === 'no-matching-deps'));
+}
+function isComparisonContract(value) {
+    return isRecord(value)
+        && value.version === 1
+        && optionalString(value.definition_revision)
+        && optionalString(value.scorer_revision)
+        && optionalString(value.runtime_revision)
+        && optionalString(value.sampling_revision)
+        && value.report_schema_revision === 'pathgrade-results-v2'
+        && (value.unavailable_reasons === undefined || (Array.isArray(value.unavailable_reasons)
+            && value.unavailable_reasons.every(reason => reason === 'definition_metadata_missing'
+                || reason === 'scorer_metadata_missing'
+                || reason === 'runtime_metadata_missing'
+                || reason === 'sampling_incomplete')));
+}
+function optionalString(value) {
+    return value === undefined || typeof value === 'string';
+}
+function optionalNumber(value) {
+    return value === undefined || typeof value === 'number';
+}
+function optionalNonNegativeInteger(value) {
+    return value === undefined || (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0);
+}
+function optionalPositiveInteger(value) {
+    return value === undefined || (typeof value === 'number' && Number.isSafeInteger(value) && value >= 1);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/reporting/source-metadata.d.ts

@@ -0,0 +1,5 @@
+export interface SourceMetadata {
+    sourceFile?: string;
+    sourceRevision?: string;
+}
+export declare function resolveSourceMetadata(filePath: string | undefined, cwd: string): SourceMetadata;

package/dist/reporting/source-metadata.js

@@ -0,0 +1,20 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import * as path from 'node:path';
+export function resolveSourceMetadata(filePath, cwd) {
+    if (!filePath)
+        return {};
+    const absolute = path.resolve(cwd, filePath);
+    const relative = path.relative(cwd, absolute).replaceAll(path.sep, '/');
+    if (!relative || relative === '..' || relative.startsWith('../'))
+        return {};
+    try {
+        return {
+            sourceFile: relative,
+            sourceRevision: `sha256:${createHash('sha256').update(readFileSync(absolute)).digest('hex')}`,
+        };
+    }
+    catch {
+        return { sourceFile: relative };
+    }
+}

package/dist/reporting/types.d.ts

@@ -12,6 +12,8 @@ export interface ReportRunInput {
 }
 export interface ReportGroupInput {
     groupName: string;
+    sourceFile?: string;
+    sourceRevision?: string;
     cases: ReportCaseInput[];
 }
 export interface ReportCaseInput {
@@ -45,6 +47,8 @@ export interface ReportEvaluationInput {
     scoringDurationMs?: number;
     recordedAt?: string;
     agent?: AgentExecutionMetadata;
+    evaluationDefinitionKey?: string;
+    scorerRevision?: string;
 }
 export interface PathgradeReportBuildResult {
     report: PathgradeReport;
@@ -71,9 +75,10 @@ export interface ReportSummaryGroup {
     trial_count: number;
     diagnostics: ReportSummaryDiagnostics[];
 }
-export interface ReportSummaryDiagnostics {
+interface ReportSummaryDiagnostics {
     caseName: string;
     state: ReportCaseState;
     resultKind?: EvaluationResultKind;
     report: DiagnosticsReport;
 }
+export {};