vieval 0.0.5 → 0.0.7

package/dist/{expect-extensions-QLXESWjn.mjs.map → expect-extensions-DCSqlneN.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"expect-extensions-QLXESWjn.mjs","names":[],"sources":["../src/testing/runtime-expect.ts","../src/testing/expect-extensions.ts"],"sourcesContent":["import type { ExpectStatic, MatchersObject, MatcherState, Tester } from '@vitest/expect'\n\nimport {\n  addCustomEqualityTesters,\n  ASYMMETRIC_MATCHERS_OBJECT,\n  chai,\n  ChaiStyleAssertions,\n  customMatchers,\n  getState,\n  GLOBAL_EXPECT,\n  JestAsymmetricMatchers,\n  JestChaiExpect,\n  JestExtend,\n  setState,\n} from '@vitest/expect'\n\nlet isPluginInstalled = false\nlet runtimeExpectInstance: ExpectStatic | undefined\n\n/**\n * Installs Vitest expect plugins once for process-local runtime assertions.\n *\n * Use when:\n * - running eval tasks outside Vitest worker runtime\n * - building an `expect` instance that does not rely on Vitest internal state\n *\n * Expects:\n * - `@vitest/expect` is available in runtime dependencies\n *\n * Returns:\n * - nothing; side-effects are applied to `chai`\n */\nfunction ensureRuntimeExpectPluginsInstalled(): void {\n  if (isPluginInstalled) {\n    return\n  }\n\n  chai.use(JestExtend)\n  chai.use(JestChaiExpect)\n  chai.use(ChaiStyleAssertions)\n  chai.use(JestAsymmetricMatchers)\n  isPluginInstalled = true\n}\n\n/**\n * Creates a Vitest-compatible `expect` instance without worker-state coupling.\n *\n * Use when:\n * - CLI runtime needs assertion helpers from `vieval/expect`\n * - code is executed outside `vitest run`\n *\n * Expects:\n * - plugins from {@link ensureRuntimeExpectPluginsInstalled} are installed\n * - callers do not depend on Vitest worker-only features (snapshot/poll internals)\n *\n * Returns:\n * - standalone expect instance with core matcher APIs and `extend`\n */\nfunction createRuntimeExpect(): ExpectStatic {\n  ensureRuntimeExpectPluginsInstalled()\n\n  const runtimeExpect = ((value: unknown, message?: string) => {\n    const currentState = getState(runtimeExpect)\n    setState({ assertionCalls: currentState.assertionCalls + 1 }, runtimeExpect)\n    return chai.expect(value, message)\n  }) as unknown as ExpectStatic\n\n  Object.assign(runtimeExpect, chai.expect)\n  Object.assign(runtimeExpect, (globalThis as Record<PropertyKey, unknown>)[ASYMMETRIC_MATCHERS_OBJECT] as object)\n\n  runtimeExpect.getState = () => getState(runtimeExpect)\n  runtimeExpect.setState = (state: Partial<MatcherState>) => setState(state, runtimeExpect)\n  runtimeExpect.assert = chai.assert\n  // NOTICE:\n  // Chai's public `ExpectStatic` type does not expose Vitest's plugin-added `extend`.\n  // Runtime `chai.expect.extend` exists after `JestExtend` plugin installation.\n  // Source/context: `@vitest/expect` plugin pipeline in `dist/index.js`.\n  // Removal condition: remove this cast if upstream exposes `extend` on Chai expect types.\n  const chaiExpectWithExtend = chai.expect as unknown as {\n    extend: (expect: ExpectStatic, matchers: MatchersObject) => void\n  }\n  runtimeExpect.extend = (matchers: MatchersObject) => chaiExpectWithExtend.extend(runtimeExpect, matchers)\n  runtimeExpect.addEqualityTesters = (customTesters: Tester[]) => addCustomEqualityTesters(customTesters)\n  runtimeExpect.unreachable = (message?: string) => {\n    chai.assert.fail(`expected${message ? ` \"${message}\" ` : ' '}not to be reached`)\n  }\n\n  runtimeExpect.setState({\n    assertionCalls: 0,\n    currentTestName: '',\n    expectedAssertionsNumber: null,\n    expectedAssertionsNumberErrorGen: null,\n    isExpectingAssertions: false,\n    isExpectingAssertionsError: null,\n  })\n\n  runtimeExpect.extend(customMatchers)\n\n  return runtimeExpect\n}\n\n/**\n * Returns process-local runtime `expect` instance used by Vieval.\n *\n * Use when:\n * - you need matcher assertions in eval files and CLI runtime\n * - importing from `vitest` would crash outside Vitest worker contexts\n *\n * Expects:\n * - single-process usage (instance is memoized per process)\n *\n * Returns:\n * - memoized runtime `expect` instance\n */\nexport function getRuntimeExpect(): ExpectStatic {\n  if (runtimeExpectInstance != null) {\n    return runtimeExpectInstance\n  }\n\n  runtimeExpectInstance = createRuntimeExpect()\n  Object.defineProperty(globalThis, GLOBAL_EXPECT, {\n    configurable: true,\n    value: runtimeExpectInstance,\n    writable: true,\n  })\n\n  return runtimeExpectInstance\n}\n","import type { RubricJudgeResult, ToolCall } from '../core/assertions'\n\nimport { normalizeMatchText } from '../core/assertions'\nimport { getRuntimeExpect } from './runtime-expect'\n\n/**\n * Options for keyword-based matcher behavior.\n */\nexport interface KeywordMatcherOptions {\n  /**\n   * Case-sensitive matching toggle.\n   *\n   * @default false\n   */\n  caseSensitive?: boolean\n  /**\n   * Match mode.\n   *\n   * @default 'all'\n   */\n  mode?: 'all' | 'any'\n}\n\n/**\n * Shape used by tool-call matchers.\n */\nexport interface ToolCallContainer {\n  /**\n   * Tool calls to inspect.\n   */\n  toolCalls?: readonly ToolCall[]\n}\n\nfunction toKeywordArray(keywords: string | readonly string[]): readonly string[] {\n  if (typeof keywords === 'string') {\n    return [keywords]\n  }\n\n  return keywords\n}\n\n/**\n * Registers vieval custom matchers on Vitest `expect`.\n *\n * Call stack:\n *\n * {@link installVievalExpectMatchers}\n *   -> `expect.extend(...)`\n *     -> `expect(received).toMustInclude(...)`\n *     -> `expect(received).toScoreRubricGreaterThan(...)`\n *\n * Use when:\n * - eval suites need domain assertions while preserving native Vitest ergonomics\n * - callers want native `.not` chaining with the same matchers\n */\nexport function installVievalExpectMatchers(): void {\n  const expect = getRuntimeExpect()\n\n  expect.extend({\n    toMustExclude(received: unknown, keywords: string | readonly string[], options: KeywordMatcherOptions = {}) {\n      const keywordList = toKeywordArray(keywords)\n\n      if (typeof received !== 'string') {\n        return {\n          message: () => 'Expected received value to be a string.',\n          pass: false,\n        }\n      }\n\n      const normalizedText = normalizeMatchText(received, options.caseSensitive ?? false)\n      const forbiddenMatches = keywordList.filter((keyword) => {\n        return normalizedText.includes(normalizeMatchText(keyword, options.caseSensitive ?? false))\n      })\n\n      const pass = forbiddenMatches.length === 0\n\n      return {\n        message: () => {\n          if (pass) {\n            return `Expected text to include forbidden keywords: ${keywordList.join(', ')}`\n          }\n\n          return `Expected text not to include forbidden keywords, but matched: ${forbiddenMatches.join(', ')}`\n        },\n        pass,\n      }\n    },\n\n    toMustInclude(received: unknown, keywords: string | readonly string[], options: KeywordMatcherOptions = {}) {\n      const keywordList = toKeywordArray(keywords)\n\n      if (typeof received !== 'string') {\n        return {\n          message: () => 'Expected received value to be a string.',\n          pass: false,\n        }\n      }\n\n      const normalizedText = normalizeMatchText(received, options.caseSensitive ?? false)\n      const matches = keywordList.filter((keyword) => {\n        return normalizedText.includes(normalizeMatchText(keyword, options.caseSensitive ?? false))\n      })\n\n      const mode = options.mode ?? 'all'\n      const pass = mode === 'all' ? matches.length === keywordList.length : matches.length > 0\n\n      return {\n        message: () => {\n          if (pass) {\n            return `Expected text not to match required keywords, but matched: ${matches.join(', ')}`\n          }\n\n          return `Expected text to match required keywords (${mode}), but matched ${matches.length}/${keywordList.length}.`\n        },\n        pass,\n      }\n    },\n\n    toScoreRubricGreaterThan(received: unknown, threshold: number) {\n      const score = typeof received === 'number'\n        ? received\n        : (received as RubricJudgeResult | null)?.score\n\n      if (typeof score !== 'number') {\n        return {\n          message: () => 'Expected received value to be a number or RubricJudgeResult.',\n          pass: false,\n        }\n      }\n\n      const pass = score > threshold\n\n      return {\n        message: () => {\n          if (pass) {\n            return `Expected rubric score ${score} to be less than or equal to ${threshold}.`\n          }\n\n          return `Expected rubric score ${score} to be greater than ${threshold}.`\n        },\n        pass,\n      }\n    },\n\n    toSatisfyStructuredOutput<T>(received: unknown, validator: (value: unknown) => value is T) {\n      const pass = validator(received)\n\n      return {\n        message: () => pass\n          ? 'Expected structured output validator to fail.'\n          : 'Expected structured output validator to pass.',\n        pass,\n      }\n    },\n\n    toSatisfyToolCallArgs(\n      received: unknown,\n      toolName: string,\n      validator: (args: unknown) => boolean,\n    ) {\n      const toolCalls = (received as ToolCallContainer | null)?.toolCalls\n\n      if (toolCalls == null) {\n        return {\n          message: () => 'Expected received value to provide toolCalls array.',\n          pass: false,\n        }\n      }\n\n      const targetCall = toolCalls.find(call => call.name === toolName)\n      if (targetCall == null) {\n        return {\n          message: () => `Expected tool call ${toolName} to exist.`,\n          pass: false,\n        }\n      }\n\n      const pass = validator(targetCall.args)\n\n      return {\n        message: () => pass\n          ? `Expected tool call args for ${toolName} to fail validation.`\n          : `Expected tool call args for ${toolName} to pass validation.`,\n        pass,\n      }\n    },\n  })\n}\n\ninterface VievalCustomMatchers {\n  /**\n   * Asserts that text includes required keywords.\n   *\n   * Example:\n   * `expect('calm answer').toMustInclude(['calm'])`\n   */\n  toMustInclude: (keywords: string | readonly string[], options?: KeywordMatcherOptions) => void\n  /**\n   * Asserts that text excludes forbidden keywords.\n   *\n   * Example:\n   * `expect('calm answer').toMustExclude(['bestmove'])`\n   */\n  toMustExclude: (keywords: string | readonly string[], options?: KeywordMatcherOptions) => void\n  /**\n   * Asserts rubric score is greater than a threshold.\n   *\n   * Example:\n   * `expect({ score: 0.91 }).toScoreRubricGreaterThan(0.8)`\n   */\n  toScoreRubricGreaterThan: (threshold: number) => void\n  /**\n   * Asserts structured output satisfies a validator.\n   *\n   * Example:\n   * `expect(value).toSatisfyStructuredOutput(isMyShape)`\n   */\n  toSatisfyStructuredOutput: <TValue>(validator: (value: unknown) => value is TValue) => void\n  /**\n   * Asserts selected tool-call args satisfy validator.\n   *\n   * Example:\n   * `expect({ toolCalls }).toSatisfyToolCallArgs('builtIn_sparkCommand', isSparkArgs)`\n   */\n  toSatisfyToolCallArgs: (toolName: string, validator: (args: unknown) => boolean) => void\n}\n\n/* eslint-disable unused-imports/no-unused-vars */\ndeclare module '@vitest/expect' {\n  interface Matchers<T = any> extends VievalCustomMatchers {}\n  interface Assertion<T = any> extends VievalCustomMatchers {}\n}\n\ndeclare module 'vitest' {\n  interface Assertion extends VievalCustomMatchers {}\n  interface Matchers<T = any> extends VievalCustomMatchers {}\n}\n/* eslint-enable unused-imports/no-unused-vars */\n"],"mappings":"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"}
+{"version":3,"file":"expect-extensions-DCSqlneN.mjs","names":[],"sources":["../src/testing/runtime-expect.ts","../src/testing/expect-extensions.ts"],"sourcesContent":["import type { ExpectStatic, MatchersObject, MatcherState, Tester } from '@vitest/expect'\n\nimport {\n  addCustomEqualityTesters,\n  ASYMMETRIC_MATCHERS_OBJECT,\n  chai,\n  ChaiStyleAssertions,\n  customMatchers,\n  getState,\n  GLOBAL_EXPECT,\n  JestAsymmetricMatchers,\n  JestChaiExpect,\n  JestExtend,\n  setState,\n} from '@vitest/expect'\n\nlet isPluginInstalled = false\nlet runtimeExpectInstance: ExpectStatic | undefined\n\n/**\n * Installs Vitest expect plugins once for process-local runtime assertions.\n *\n * Use when:\n * - running eval tasks outside Vitest worker runtime\n * - building an `expect` instance that does not rely on Vitest internal state\n *\n * Expects:\n * - `@vitest/expect` is available in runtime dependencies\n *\n * Returns:\n * - nothing; side-effects are applied to `chai`\n */\nfunction ensureRuntimeExpectPluginsInstalled(): void {\n  if (isPluginInstalled) {\n    return\n  }\n\n  chai.use(JestExtend)\n  chai.use(JestChaiExpect)\n  chai.use(ChaiStyleAssertions)\n  chai.use(JestAsymmetricMatchers)\n  isPluginInstalled = true\n}\n\n/**\n * Creates a Vitest-compatible `expect` instance without worker-state coupling.\n *\n * Use when:\n * - CLI runtime needs assertion helpers from `vieval/expect`\n * - code is executed outside `vitest run`\n *\n * Expects:\n * - plugins from {@link ensureRuntimeExpectPluginsInstalled} are installed\n * - callers do not depend on Vitest worker-only features (snapshot/poll internals)\n *\n * Returns:\n * - standalone expect instance with core matcher APIs and `extend`\n */\nfunction createRuntimeExpect(): ExpectStatic {\n  ensureRuntimeExpectPluginsInstalled()\n\n  const runtimeExpect = ((value: unknown, message?: string) => {\n    const currentState = getState(runtimeExpect)\n    setState({ assertionCalls: currentState.assertionCalls + 1 }, runtimeExpect)\n    return chai.expect(value, message)\n  }) as unknown as ExpectStatic\n\n  Object.assign(runtimeExpect, chai.expect)\n  Object.assign(runtimeExpect, (globalThis as Record<PropertyKey, unknown>)[ASYMMETRIC_MATCHERS_OBJECT] as object)\n\n  runtimeExpect.getState = () => getState(runtimeExpect)\n  runtimeExpect.setState = (state: Partial<MatcherState>) => setState(state, runtimeExpect)\n  runtimeExpect.assert = chai.assert\n  // NOTICE:\n  // Chai's public `ExpectStatic` type does not expose Vitest's plugin-added `extend`.\n  // Runtime `chai.expect.extend` exists after `JestExtend` plugin installation.\n  // Source/context: `@vitest/expect` plugin pipeline in `dist/index.js`.\n  // Removal condition: remove this cast if upstream exposes `extend` on Chai expect types.\n  const chaiExpectWithExtend = chai.expect as unknown as {\n    extend: (expect: ExpectStatic, matchers: MatchersObject) => void\n  }\n  runtimeExpect.extend = (matchers: MatchersObject) => chaiExpectWithExtend.extend(runtimeExpect, matchers)\n  runtimeExpect.addEqualityTesters = (customTesters: Tester[]) => addCustomEqualityTesters(customTesters)\n  runtimeExpect.unreachable = (message?: string) => {\n    chai.assert.fail(`expected${message ? ` \"${message}\" ` : ' '}not to be reached`)\n  }\n\n  runtimeExpect.setState({\n    assertionCalls: 0,\n    currentTestName: '',\n    expectedAssertionsNumber: null,\n    expectedAssertionsNumberErrorGen: null,\n    isExpectingAssertions: false,\n    isExpectingAssertionsError: null,\n  })\n\n  runtimeExpect.extend(customMatchers)\n\n  return runtimeExpect\n}\n\n/**\n * Returns process-local runtime `expect` instance used by Vieval.\n *\n * Use when:\n * - you need matcher assertions in eval files and CLI runtime\n * - importing from `vitest` would crash outside Vitest worker contexts\n *\n * Expects:\n * - single-process usage (instance is memoized per process)\n *\n * Returns:\n * - memoized runtime `expect` instance\n */\nexport function getRuntimeExpect(): ExpectStatic {\n  if (runtimeExpectInstance != null) {\n    return runtimeExpectInstance\n  }\n\n  runtimeExpectInstance = createRuntimeExpect()\n  Object.defineProperty(globalThis, GLOBAL_EXPECT, {\n    configurable: true,\n    value: runtimeExpectInstance,\n    writable: true,\n  })\n\n  return runtimeExpectInstance\n}\n","import type { RubricJudgeResult, ToolCall } from '../core/assertions'\n\nimport { normalizeMatchText } from '../core/assertions'\nimport { getRuntimeExpect } from './runtime-expect'\n\n/**\n * Options for keyword-based matcher behavior.\n */\nexport interface KeywordMatcherOptions {\n  /**\n   * Case-sensitive matching toggle.\n   *\n   * @default false\n   */\n  caseSensitive?: boolean\n  /**\n   * Match mode.\n   *\n   * @default 'all'\n   */\n  mode?: 'all' | 'any'\n}\n\n/**\n * Shape used by tool-call matchers.\n */\nexport interface ToolCallContainer {\n  /**\n   * Tool calls to inspect.\n   */\n  toolCalls?: readonly ToolCall[]\n}\n\nfunction toKeywordArray(keywords: string | readonly string[]): readonly string[] {\n  if (typeof keywords === 'string') {\n    return [keywords]\n  }\n\n  return keywords\n}\n\n/**\n * Registers vieval custom matchers on Vitest `expect`.\n *\n * Call stack:\n *\n * {@link installVievalExpectMatchers}\n *   -> `expect.extend(...)`\n *     -> `expect(received).toMustInclude(...)`\n *     -> `expect(received).toScoreRubricGreaterThan(...)`\n *\n * Use when:\n * - eval suites need domain assertions while preserving native Vitest ergonomics\n * - callers want native `.not` chaining with the same matchers\n */\nexport function installVievalExpectMatchers(): void {\n  const expect = getRuntimeExpect()\n\n  expect.extend({\n    toMustExclude(received: unknown, keywords: string | readonly string[], options: KeywordMatcherOptions = {}) {\n      const keywordList = toKeywordArray(keywords)\n\n      if (typeof received !== 'string') {\n        return {\n          message: () => 'Expected received value to be a string.',\n          pass: false,\n        }\n      }\n\n      const normalizedText = normalizeMatchText(received, options.caseSensitive ?? false)\n      const forbiddenMatches = keywordList.filter((keyword) => {\n        return normalizedText.includes(normalizeMatchText(keyword, options.caseSensitive ?? false))\n      })\n\n      const pass = forbiddenMatches.length === 0\n\n      return {\n        message: () => {\n          if (pass) {\n            return `Expected text to include forbidden keywords: ${keywordList.join(', ')}`\n          }\n\n          return `Expected text not to include forbidden keywords, but matched: ${forbiddenMatches.join(', ')}`\n        },\n        pass,\n      }\n    },\n\n    toMustInclude(received: unknown, keywords: string | readonly string[], options: KeywordMatcherOptions = {}) {\n      const keywordList = toKeywordArray(keywords)\n\n      if (typeof received !== 'string') {\n        return {\n          message: () => 'Expected received value to be a string.',\n          pass: false,\n        }\n      }\n\n      const normalizedText = normalizeMatchText(received, options.caseSensitive ?? false)\n      const matches = keywordList.filter((keyword) => {\n        return normalizedText.includes(normalizeMatchText(keyword, options.caseSensitive ?? false))\n      })\n\n      const mode = options.mode ?? 'all'\n      const pass = mode === 'all' ? matches.length === keywordList.length : matches.length > 0\n\n      return {\n        message: () => {\n          if (pass) {\n            return `Expected text not to match required keywords, but matched: ${matches.join(', ')}`\n          }\n\n          return `Expected text to match required keywords (${mode}), but matched ${matches.length}/${keywordList.length}.`\n        },\n        pass,\n      }\n    },\n\n    toScoreRubricGreaterThan(received: unknown, threshold: number) {\n      const score = typeof received === 'number'\n        ? received\n        : (received as RubricJudgeResult | null)?.score\n\n      if (typeof score !== 'number') {\n        return {\n          message: () => 'Expected received value to be a number or RubricJudgeResult.',\n          pass: false,\n        }\n      }\n\n      const pass = score > threshold\n\n      return {\n        message: () => {\n          if (pass) {\n            return `Expected rubric score ${score} to be less than or equal to ${threshold}.`\n          }\n\n          return `Expected rubric score ${score} to be greater than ${threshold}.`\n        },\n        pass,\n      }\n    },\n\n    toSatisfyStructuredOutput<T>(received: unknown, validator: (value: unknown) => value is T) {\n      const pass = validator(received)\n\n      return {\n        message: () => pass\n          ? 'Expected structured output validator to fail.'\n          : 'Expected structured output validator to pass.',\n        pass,\n      }\n    },\n\n    toSatisfyToolCallArgs(\n      received: unknown,\n      toolName: string,\n      validator: (args: unknown) => boolean,\n    ) {\n      const toolCalls = (received as ToolCallContainer | null)?.toolCalls\n\n      if (toolCalls == null) {\n        return {\n          message: () => 'Expected received value to provide toolCalls array.',\n          pass: false,\n        }\n      }\n\n      const targetCall = toolCalls.find(call => call.name === toolName)\n      if (targetCall == null) {\n        return {\n          message: () => `Expected tool call ${toolName} to exist.`,\n          pass: false,\n        }\n      }\n\n      const pass = validator(targetCall.args)\n\n      return {\n        message: () => pass\n          ? `Expected tool call args for ${toolName} to fail validation.`\n          : `Expected tool call args for ${toolName} to pass validation.`,\n        pass,\n      }\n    },\n  })\n}\n\ninterface VievalCustomMatchers {\n  /**\n   * Asserts that text includes required keywords.\n   *\n   * Example:\n   * `expect('calm answer').toMustInclude(['calm'])`\n   */\n  toMustInclude: (keywords: string | readonly string[], options?: KeywordMatcherOptions) => void\n  /**\n   * Asserts that text excludes forbidden keywords.\n   *\n   * Example:\n   * `expect('calm answer').toMustExclude(['bestmove'])`\n   */\n  toMustExclude: (keywords: string | readonly string[], options?: KeywordMatcherOptions) => void\n  /**\n   * Asserts rubric score is greater than a threshold.\n   *\n   * Example:\n   * `expect({ score: 0.91 }).toScoreRubricGreaterThan(0.8)`\n   */\n  toScoreRubricGreaterThan: (threshold: number) => void\n  /**\n   * Asserts structured output satisfies a validator.\n   *\n   * Example:\n   * `expect(value).toSatisfyStructuredOutput(isMyShape)`\n   */\n  toSatisfyStructuredOutput: <TValue>(validator: (value: unknown) => value is TValue) => void\n  /**\n   * Asserts selected tool-call args satisfy validator.\n   *\n   * Example:\n   * `expect({ toolCalls }).toSatisfyToolCallArgs('builtIn_sparkCommand', isSparkArgs)`\n   */\n  toSatisfyToolCallArgs: (toolName: string, validator: (args: unknown) => boolean) => void\n}\n\n/* eslint-disable unused-imports/no-unused-vars */\ndeclare module '@vitest/expect' {\n  interface Matchers<T = any> extends VievalCustomMatchers {}\n  interface Assertion<T = any> extends VievalCustomMatchers {}\n}\n\ndeclare module 'vitest' {\n  interface Assertion extends VievalCustomMatchers {}\n  interface Matchers<T = any> extends VievalCustomMatchers {}\n}\n/* eslint-enable unused-imports/no-unused-vars */\n"],"mappings":"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"}

package/dist/expect.mjs

@@ -1,4 +1,4 @@
-import { n as getRuntimeExpect, t as installVievalExpectMatchers } from "./expect-extensions-QLXESWjn.mjs";
+import { n as getRuntimeExpect, t as installVievalExpectMatchers } from "./expect-extensions-DCSqlneN.mjs";
 //#region src/expect.ts
 let isInstalled = false;
 function ensureExpectMatchersInstalled() {

package/dist/{index-OEdqjQSe.d.mts → index-5R1_k2nv.d.mts}

@@ -477,6 +477,10 @@ interface ModelDefinition {
    * Alias names that can resolve this model.
    */
   aliases: string[];
+  /**
+   * Optional execution policy hints attached to this model.
+   */
+  executionPolicy?: TaskExecutionPolicy;
   /**
    * Optional model-level call parameters.
    */
@@ -642,7 +646,39 @@ declare class RunnerExecutionError extends Error {
  */
 declare function runScheduledTasks(tasks: readonly ScheduledTask[], executor: ScheduledTaskExecutor, options?: RunScheduledTasksOptions): Promise<AggregatedRunResults>;
 //#endregion
+//#region src/core/telemetry/types.d.ts
+/** JSON-compatible scalar values accepted as telemetry attributes. */
+type TelemetryAttributeValue = boolean | number | string | null | readonly TelemetryAttributeValue[];
+/** Attribute map shared by local report projection and OpenTelemetry span calls. */
+type TelemetryAttributes = Record<string, TelemetryAttributeValue | undefined>;
+/**
+ * Internal Vieval telemetry runtime.
+ *
+ * Use when:
+ * - runner code needs one execution path for disabled and enabled telemetry
+ * - case code should run inside an active OpenTelemetry span when configured
+ *
+ * Expects:
+ * - attributes are JSON-compatible and stable enough for report filtering
+ * - callbacks are awaited by the caller
+ *
+ * Returns:
+ * - callback result, preserving thrown errors after telemetry records them
+ */
+interface TelemetryRuntime {
+  withSpan: <T>(name: string, attributes: TelemetryAttributes, callback: () => Promise<T>) => Promise<T>;
+  addEvent: (name: string, attributes?: TelemetryAttributes) => void;
+  setAttributes: (attributes: TelemetryAttributes) => void;
+  recordException: (error: unknown) => void;
+}
+//#endregion
 //#region src/config/types.d.ts
+/**
+ * Value that can be returned directly or through a promise.
+ *
+ * @param T - Resolved value type.
+ */
+type Awaitable<T> = Promise<T> | T;
 /**
  * Primitive value allowed in one matrix cell.
  *
@@ -858,6 +894,100 @@ interface TaskRunOutput {
    */
   scores: readonly RunScore[];
 }
+/**
+ * Delay policy for retries within one task case attempt.
+ *
+ * @param retryIndex Retry number where `1` is the first retry after the initial failure.
+ */
+type TaskAutoRetryDelay = number | ((retryIndex: number) => number);
+/**
+ * Execution policy applied to task and case callbacks.
+ *
+ * Use when:
+ * - one task or case should time out after a bounded duration
+ * - failures should retry within the current attempt or trigger a later full task attempt
+ *
+ * Expects:
+ * - `timeout` to be a positive integer when provided
+ * - `autoRetry` and `autoAttempt` to be non-negative integers when provided
+ *
+ * Returns:
+ * - one partial execution policy descriptor
+ */
+interface TaskExecutionPolicy {
+  /**
+   * Additional retries allowed within the current attempt.
+   *
+   * @default 0
+   */
+  autoRetry?: number;
+  /**
+   * Delay in milliseconds before a case auto retry starts.
+   *
+   * A number applies the same delay to every retry. A function receives the
+   * retry index where `1` is the first retry after the initial failure.
+   *
+   * @default retryIndex => 500 * 2 ** (retryIndex - 1)
+   */
+  autoRetryDelay?: TaskAutoRetryDelay;
+  /**
+   * Additional full task attempts allowed after the current attempt settles.
+   *
+   * @default 0
+   */
+  autoAttempt?: number;
+  /**
+   * Timeout in milliseconds for one case execution.
+   */
+  timeout?: number;
+}
+/**
+ * Task-local concurrency metadata.
+ *
+ * Use when:
+ * - task declarations need to preserve attempt and case caps for later runtime coordination
+ * - DSL execution needs to resolve the default task-level case concurrency for registered cases
+ *
+ * Expects:
+ * - each provided value to be a positive integer chosen by the caller
+ *
+ * Returns:
+ * - one partial task-local concurrency descriptor
+ */
+interface TaskConcurrencyConfig {
+  /**
+   * Attempt-level concurrency cap for this task.
+   */
+  attempt?: number;
+  /**
+   * Case-level concurrency cap for this task.
+   */
+  case?: number;
+}
+/**
+ * Reporting configuration for local artifacts and optional OpenTelemetry integration.
+ */
+interface CliReportingConfig {
+  /**
+   * Optional OpenTelemetry API integration.
+   */
+  openTelemetry?: CliOpenTelemetryReportingConfig;
+}
+/**
+ * OpenTelemetry reporting configuration managed by user config setup.
+ */
+interface CliOpenTelemetryReportingConfig {
+  /**
+   * Enables Vieval active span wrapping through `@opentelemetry/api`.
+   *
+   * @default false
+   */
+  enabled?: boolean;
+  /**
+   * Called after all telemetry events and local report artifacts have been emitted.
+   */
+  onRunEnd?: () => Awaitable<void>;
+}
 /**
  * Runtime context passed into eval task `run`.
  */
@@ -933,6 +1063,34 @@ interface TaskRunContext {
    * - hooks are best-effort observers and should not affect task scoring
    */
   reporterHooks?: TaskReporterHooks;
+  /**
+   * Optional telemetry runtime shared by runner, DSL, and reporter integrations.
+   *
+   * Use when:
+   * - task execution should emit events to the currently active telemetry runtime
+   * - enabled and disabled telemetry should keep the same execution path
+   *
+   * Expects:
+   * - callers inject a no-op runtime when telemetry is disabled
+   */
+  telemetry?: TelemetryRuntime;
+  /**
+   * Optional runtime scheduling overrides supplied by CLI or host execution.
+   *
+   * Use when:
+   * - run operators need to override task/case concurrency without editing eval code
+   * - DSL task runners need to distinguish runtime flags from code defaults
+   *
+   * Expects:
+   * - values are positive integers when provided
+   *
+   * @default undefined
+   */
+  runtimeConcurrency?: TaskConcurrencyConfig;
+  /**
+   * Cooperative abort signal for the current execution.
+   */
+  signal?: AbortSignal;
 }
 /**
  * Allowed terminal outcomes for one task case.
@@ -943,7 +1101,7 @@ interface TaskRunContext {
  * Expects:
  * - consumers treat the value as the final state for the case
  */
-type TaskCaseState = 'passed' | 'failed';
+type TaskCaseState = 'passed' | 'failed' | 'timeout';
 /**
  * Payload emitted when a task case starts.
  *
@@ -956,10 +1114,22 @@ type TaskCaseState = 'passed' | 'failed';
  * - `total` is the total number of registered cases
  */
 interface TaskCaseReporterPayload {
+  /**
+   * Maximum retry count configured for this case.
+   */
+  autoRetry?: number;
+  /**
+   * Optional case input payload registered by the task DSL.
+   */
+  input?: unknown;
   /**
    * Declared case label.
    */
   name: string;
+  /**
+   * Current retry attempt index, where `0` is the first try.
+   */
+  retryIndex?: number;
   /**
    * Zero-based case position within the task.
    */
@@ -982,6 +1152,10 @@ interface TaskCaseReporterPayload {
  * - `state` describes the final case result
  */
 interface TaskCaseReporterEndPayload extends TaskCaseReporterPayload {
+  /**
+   * Optional case output returned by the task case callback.
+   */
+  output?: unknown;
   /**
    * Final case state.
    */
@@ -1052,6 +1226,24 @@ interface TaskDefinition {
    * Stable task id for diagnostics.
    */
   id: string;
+  /**
+   * Optional task-local concurrency metadata.
+   *
+   * Use when:
+   * - task declarations need to preserve task-scoped attempt/case caps for later scheduler wiring
+   * - higher-level orchestration wants to inspect task-local concurrency without executing the task
+   *
+   * Expects:
+   * - each provided value to be a positive integer chosen by the caller
+   *
+   * Returns:
+   * - one partial task-local concurrency descriptor
+   */
+  concurrency?: TaskConcurrencyConfig;
+  /**
+   * Optional task-local execution policy.
+   */
+  executionPolicy?: TaskExecutionPolicy;
   /**
    * Optional matrix layering for this task definition.
    *
@@ -1186,5 +1378,5 @@ interface ConfigHookPlugin<TConfig> {
   configVievalResolved?: (config: TConfig) => void | Promise<void>;
 }
 //#endregion
-export { ScheduledTaskMatrixMeta as $, TaskModelSelectionOptions as A, AggregatedRunResults as B, RunScheduledTasksOptions as C, runScheduledTasks as D, ScheduledTaskExecutor as E, collectEvalEntries as F, aggregateRunResults as G, RunResult as H, CreateVievalRunnerRuntimeContextOptions as I, RunnerMatrixDefinition as J, CreateRunnerScheduleOptions as K, RunnerRuntimeContext as L, ModelDefinition as M, resolveModelByName as N, CreateTaskExecutionContextOptions as O, asProjectRelativePath as P, ScheduledTaskMatrix as Q, createRunnerRuntimeContext as R, TaskRunOutput as S, RunnerTaskState as T, RunScore as U, AggregatedRunSummary as V, RunScoreKind as W, RunnerMatrixSelection as X, RunnerMatrixInput as Y, ScheduledTask as Z, TaskCaseState as _, EvalDefinition as a, CacheFileOptions as at, TaskReporterHooks as b, MatrixAxisValues as c, MatrixPrimitive as d, createRunnerSchedule as et, MatrixRow as f, TaskCaseReporterPayload as g, TaskCaseReporterEndPayload as h, CollectedEvalEntry as i, CacheFileHandle as it, createTaskExecutionContext as j, TaskExecutionContext as k, MatrixDefinition as l, ScopedMatrices as m, defineEval as n, createFilesystemTaskCacheRuntime as nt, EvalModule as o, CacheNamespace as ot, MatrixValue as p, InferenceExecutor as q, defineTask as r, normalizeCacheFilePathSegments as rt, EvalModuleMap as s, TaskCacheRuntime as st, ConfigHookPlugin as t, CreateFilesystemTaskCacheRuntimeOptions as tt, MatrixLayer as u, TaskDefinition as v, RunnerExecutionError as w, TaskRunContext as x, TaskReporterEventPayload as y, AggregatedProviderSummary as z };
-//# sourceMappingURL=index-OEdqjQSe.d.mts.map
+export { CreateRunnerScheduleOptions as $, RunScheduledTasksOptions as A, resolveModelByName as B, TaskDefinition as C, TaskRunContext as D, TaskReporterHooks as E, CreateTaskExecutionContextOptions as F, createRunnerRuntimeContext as G, collectEvalEntries as H, TaskExecutionContext as I, AggregatedRunSummary as J, AggregatedProviderSummary as K, TaskModelSelectionOptions as L, RunnerTaskState as M, ScheduledTaskExecutor as N, TaskRunOutput as O, runScheduledTasks as P, aggregateRunResults as Q, createTaskExecutionContext as R, TaskConcurrencyConfig as S, TaskReporterEventPayload as T, CreateVievalRunnerRuntimeContextOptions as U, asProjectRelativePath as V, RunnerRuntimeContext as W, RunScore as X, RunResult as Y, RunScoreKind as Z, ScopedMatrices as _, CliOpenTelemetryReportingConfig as a, ScheduledTaskMatrix as at, TaskCaseReporterPayload as b, EvalDefinition as c, CreateFilesystemTaskCacheRuntimeOptions as ct, MatrixAxisValues as d, CacheFileHandle as dt, InferenceExecutor as et, MatrixDefinition as f, CacheFileOptions as ft, MatrixValue as g, MatrixRow as h, Awaitable as i, ScheduledTask as it, RunnerExecutionError as j, TelemetryAttributeValue as k, EvalModule as l, createFilesystemTaskCacheRuntime as lt, MatrixPrimitive as m, TaskCacheRuntime as mt, defineEval as n, RunnerMatrixInput as nt, CliReportingConfig as o, ScheduledTaskMatrixMeta as ot, MatrixLayer as p, CacheNamespace as pt, AggregatedRunResults as q, defineTask as r, RunnerMatrixSelection as rt, CollectedEvalEntry as s, createRunnerSchedule as st, ConfigHookPlugin as t, RunnerMatrixDefinition as tt, EvalModuleMap as u, normalizeCacheFilePathSegments as ut, TaskAutoRetryDelay as v, TaskExecutionPolicy as w, TaskCaseState as x, TaskCaseReporterEndPayload as y, ModelDefinition as z };
+//# sourceMappingURL=index-5R1_k2nv.d.mts.map

package/dist/index-fakXoZEe.d.mts

@@ -0,0 +1,147 @@
+//#region src/core/scheduler/types.d.ts
+/**
+ * Hierarchical scheduler scopes used by the queue runtime.
+ *
+ * Use when:
+ * - selecting which concurrency cap applies to a unit of work
+ * - ordering middleware acquisition and release hooks
+ *
+ * Expects:
+ * - values move from broad to narrow scope in this order:
+ *   `workspace -> project -> task -> attempt -> case`
+ *
+ * Returns:
+ * - a string literal scope identifier
+ */
+type SchedulerScope = 'workspace' | 'project' | 'task' | 'attempt' | 'case';
+/**
+ * Context carried through queue acquisition, execution, and release.
+ *
+ * Use when:
+ * - middleware needs stable identifiers for logging or instrumentation
+ * - runtime helpers need to know which hierarchical scope is being executed
+ *
+ * Expects:
+ * - `workspaceId` and `experimentId` are always present
+ * - narrower ids are only provided when the selected scope requires them
+ *
+ * Returns:
+ * - a serializable scope context object
+ */
+interface SchedulerScopeContext {
+  scope: SchedulerScope;
+  workspaceId: string;
+  experimentId: string;
+  projectName?: string;
+  taskId?: string;
+  attemptIndex?: number;
+  caseId?: string;
+}
+/**
+ * Middleware hooks wrapped around scheduler execution.
+ *
+ * Use when:
+ * - recording queue lifecycle telemetry
+ * - attaching tracing or temporary resources around queued work
+ *
+ * Expects:
+ * - implementations call `next()` exactly once to continue the pipeline
+ *
+ * Returns:
+ * - optional async acquire and release hooks
+ */
+interface SchedulerMiddleware {
+  onAcquire?: (context: SchedulerScopeContext, next: () => Promise<void>) => Promise<void> | void;
+  onRelease?: (context: SchedulerScopeContext, next: () => Promise<void>) => Promise<void> | void;
+}
+/**
+ * Per-scope concurrency limits used by the scheduler runtime.
+ *
+ * Use when:
+ * - bounding parallel work for a specific scope
+ * - disabling a scope cap by omitting its entry
+ *
+ * Expects:
+ * - values are positive integers when provided
+ *
+ * Returns:
+ * - a partial map of scheduler scope to concurrency cap
+ */
+interface SchedulerConcurrencyConfig {
+  workspace?: number;
+  project?: number;
+  task?: number;
+  attempt?: number;
+  case?: number;
+}
+/**
+ * Options accepted by {@link createSchedulerRuntime}.
+ *
+ * Use when:
+ * - constructing a scheduler runtime with queue limits or middleware
+ *
+ * Expects:
+ * - omitted configuration falls back to unbounded execution for that concern
+ *
+ * Returns:
+ * - queue and middleware configuration for the runtime
+ */
+interface CreateSchedulerRuntimeOptions {
+  concurrency?: SchedulerConcurrencyConfig;
+  middleware?: SchedulerMiddleware[];
+}
+/**
+ * Runtime API used to execute case-level work through scheduler policies.
+ *
+ * Use when:
+ * - the runner needs to enqueue case execution under middleware and queue caps
+ *
+ * Expects:
+ * - `runCase` receives a case context and a callback that performs the work
+ *
+ * Returns:
+ * - a promise that resolves with the callback result once all guards release
+ */
+interface SchedulerRuntime {
+  runCase: <T>(context: SchedulerScopeContext, execute: () => Promise<T>) => Promise<T>;
+}
+//#endregion
+//#region src/core/scheduler/runtime.d.ts
+/**
+ * Creates the core scheduler runtime used to serialize work by scope.
+ *
+ * Call stack:
+ *
+ * {@link createSchedulerRuntime}
+ *   -> `createRuntimeQueues`
+ *     -> `runtime.runCase(context, execute)`
+ *       -> `runWithQueues`
+ *         -> `runAcquireMiddleware`
+ *           -> `execute`
+ *         -> `runReleaseMiddleware`
+ *
+ * Use when:
+ * - runner code needs concurrency caps for queued case execution
+ * - middleware should wrap work with acquire/release lifecycle hooks
+ *
+ * Expects:
+ * - middleware is ordered from outermost to innermost concern
+ * - concurrency caps are positive integers when provided
+ *
+ * Returns:
+ * - a scheduler runtime with case execution support
+ */
+declare function createSchedulerRuntime(options?: CreateSchedulerRuntimeOptions): SchedulerRuntime;
+/**
+ * Resolves the scheduler scopes that apply to a context.
+ *
+ * Before:
+ * - `{ scope: 'case', workspaceId: 'ws', experimentId: 'exp', caseId: 'case-1' }`
+ *
+ * After:
+ * - `['workspace', 'project', 'task', 'attempt', 'case']` up to the requested scope
+ */
+declare function getActiveScopes(context: SchedulerScopeContext): SchedulerScope[];
+//#endregion
+export { SchedulerMiddleware as a, SchedulerScopeContext as c, SchedulerConcurrencyConfig as i, getActiveScopes as n, SchedulerRuntime as o, CreateSchedulerRuntimeOptions as r, SchedulerScope as s, createSchedulerRuntime as t };
+//# sourceMappingURL=index-fakXoZEe.d.mts.map