@sanity/ailf 5.0.0 → 6.0.0

package/dist/_vendor/ailf-core/services/diagnosis/prompts/weakest-area.system.js

@@ -0,0 +1,86 @@
+/**
+ * System prompt for the weakest-area card.
+ *
+ * Card: weakest-area
+ * Model: claude-sonnet-4-6 (routine card)
+ * Version: weakest-area@0.1.0
+ *
+ * Mitigations embedded:
+ * - failure-mode #3: confidence inflation on small samples — prompt instructs
+ *   to hedge when sampleSize < 10; Zod W3 refine enforces at parse time
+ * - failure-mode #4: taxonomy drift — full canonical taxonomy enumerated
+ *   verbatim in this prompt so the LLM picks from a known list
+ *
+ * @see .planning/phases/05-diagnosis-engine-cli-llm-cards/05-AI-SPEC.md §4b
+ */
+export const SYSTEM_PROMPT = `You are an AILF evaluation analyst identifying the documentation area most in need of improvement.
+
+## Your Output
+
+Return a JSON object matching this exact shape:
+{
+  "summary": "<1-2 sentence description of the weakest area and why>",
+  "area": "<feature area name, e.g. 'schema-deploy'>",
+  "dimension": "<MUST be one of the canonical dimensions listed below>",
+  "failureMode": "<MUST be from the canonical taxonomy for the chosen dimension>",
+  "sampleSize": <number — MUST equal the judgmentCount provided for this area>,
+  "confidence": {
+    "level": "high" | "medium" | "low",
+    "signalsPresent": <number of tasks backing this finding>,
+    "derivation": "card-type-specific"
+  }
+}
+
+## CANONICAL DIMENSIONS AND FAILURE MODES
+
+You MUST pick dimension and failureMode from this exact taxonomy. Cross-dimension combinations are invalid (e.g., "security" dimension with "missing-docs" failure mode is rejected).
+
+### Literacy family (dimensions: task-completion, code-correctness, doc-coverage)
+Failure modes:
+- missing-docs — relevant doc didn't exist
+- outdated-docs — doc reflects an older API/version
+- incorrect-docs — doc states something factually wrong
+- poor-structure — doc exists but is hard to find or follow
+Plus cross-cutting: api-error, model-limitation, false-floor, unclassified
+
+### MCP family (dimensions: mcp-behavior, input-validation, output-correctness, error-handling, security)
+Failure modes:
+- invalid-tool-call — model called tool with wrong args
+- missing-required-param — required parameter omitted
+- extra-param — unexpected extra parameter sent
+- wrong-tool-selected — chose wrong tool for task
+- tool-call-order — tools called in wrong sequence
+- no-tool-call — should have used a tool but didn't
+- schema-mismatch — response did not match expected schema
+- unsafe-operation — operation could cause data loss
+- auth-bypass — security check skipped
+Plus cross-cutting: api-error, model-limitation, false-floor, unclassified
+
+### Knowledge-probe family (dimensions: knowledge-probe, factual-correctness, completeness, currency)
+Failure modes:
+- factual-error — stated an incorrect fact
+- out-of-date — used deprecated API or old syntax
+- missing-step — omitted a required step
+- hallucinated-api — invented an API that does not exist
+- wrong-version — used v1 API when v2 was required
+- incomplete-coverage — missed important edge case
+Plus cross-cutting: api-error, model-limitation, false-floor, unclassified
+
+### Agent-harness family (dimensions: agent-harness, process-quality, agent-output, tool-usage)
+Failure modes:
+- excessive-loops — agent looped unnecessarily
+- premature-stop — stopped before completing the task
+- incorrect-output — output was wrong or incomplete
+- inefficient-path — completed task but via unnecessary steps
+- assertion-failure — failed a structural assertion check
+Plus cross-cutting: api-error, model-limitation, false-floor, unclassified
+
+## Confidence Calibration Rules
+
+**CRITICAL:** When sampleSize < 10, you MUST set confidence.level = "low".
+
+- sampleSize >= 30 → "high" is appropriate
+- sampleSize >= 10 → "medium" is appropriate
+- sampleSize < 10 → MUST use "low" (small-sample hedge required)
+
+In your summary, reflect the confidence level: if "low", include language like "small sample (N=X) — re-run with broader dataset before acting".`;

package/dist/_vendor/ailf-core/services/diagnosis/registry.d.ts

@@ -12,9 +12,19 @@
  * `,`. Phase 1 lands the empty registry; Phase 5 registers cards via
  * the composition root, not by mutating this binding.
  *
+ * NOTE (Phase 5 / D-06): The runtime `CardRegistry` type used by the
+ * engine lives on `services/diagnosis-runner.ts` as
+ * `Readonly<Record<CardType, CardGenerator>>`. This file's `cardRegistry`
+ * is an intentionally-empty Phase-1 placeholder for Phase-1 contract
+ * tests. DO NOT mutate `cardRegistry` or add cards here — the composition
+ * root (Plan 06) builds and passes the `CardRegistry` literal into
+ * `createDiagnosisRunner(deps)`.
+ *
+ * @see packages/core/src/services/diagnosis-runner.ts (CardRegistry type)
  * @see docs/decisions/D0045-type-architecture-and-contract-enforcement.md
  * @see docs/decisions/D0048-engine-homes-for-cli-api-parity.md
  * @see .planning/phases/01-foundation-contracts-cross-cutting-schemas/01-CONTEXT.md (D-02, D-08)
+ * @see .planning/phases/05-diagnosis-engine-cli-llm-cards/05-CONTEXT.md (D-06)
  */
 import type { z } from "zod";
 import type { CardType, DiagnosisCard } from "../../types/diagnosis.js";

package/dist/_vendor/ailf-core/services/diagnosis/registry.js

@@ -12,9 +12,19 @@
  * `,`. Phase 1 lands the empty registry; Phase 5 registers cards via
  * the composition root, not by mutating this binding.
  *
+ * NOTE (Phase 5 / D-06): The runtime `CardRegistry` type used by the
+ * engine lives on `services/diagnosis-runner.ts` as
+ * `Readonly<Record<CardType, CardGenerator>>`. This file's `cardRegistry`
+ * is an intentionally-empty Phase-1 placeholder for Phase-1 contract
+ * tests. DO NOT mutate `cardRegistry` or add cards here — the composition
+ * root (Plan 06) builds and passes the `CardRegistry` literal into
+ * `createDiagnosisRunner(deps)`.
+ *
+ * @see packages/core/src/services/diagnosis-runner.ts (CardRegistry type)
  * @see docs/decisions/D0045-type-architecture-and-contract-enforcement.md
  * @see docs/decisions/D0048-engine-homes-for-cli-api-parity.md
  * @see .planning/phases/01-foundation-contracts-cross-cutting-schemas/01-CONTEXT.md (D-02, D-08)
+ * @see .planning/phases/05-diagnosis-engine-cli-llm-cards/05-CONTEXT.md (D-06)
  */
 /**
  * Phase 1: empty entrypoint. Phase 5 cards register here through the

package/dist/_vendor/ailf-core/services/diagnosis-runner.d.ts

@@ -1,12 +1,23 @@
 /**
  * Diagnosis runner — engine entry point (D0048).
  *
- * Phase 1 lands the version constant only; the runner factory + cache
- * lookup land in Phase 5.
+ * Phase 5 implements the factory body; Phase 1 shipped `diagnosisVersion` only.
+ * `GeneratorContext.judgmentAttributions` is sourced once per `.run({...})` via
+ * `deps.loadAttributions(runId)` reading Phase 4's
+ * `runs/{runId}/attribution/{entryKey}.json` per-entry artifacts (RESEARCH
+ * Landmine 11).
  *
  * @see docs/decisions/D0048-engine-homes-for-cli-api-parity.md
  * @see .planning/phases/01-foundation-contracts-cross-cutting-schemas/01-CONTEXT.md (D-02)
+ * @see .planning/phases/05-diagnosis-engine-cli-llm-cards/05-RESEARCH.md (Landmine 11)
+ * @see .planning/phases/05-diagnosis-engine-cli-llm-cards/05-CONTEXT.md (D-02, D-06, D-10)
  */
+import type { LLMClient, ModelId } from "../ports/llm-client.js";
+import type { Logger } from "../ports/logger.js";
+import type { ProgressReporter } from "../ports/progress-reporter.js";
+import type { JudgmentAttribution } from "../types/attribution.js";
+import type { CardType, Diagnosis, DiagnosisCard, VersionedInputs } from "../types/diagnosis.js";
+import type { Report } from "../types/index.js";
 /**
  * Bumped when the runner's selection logic, prompt orchestration, or
  * card-set composition changes in a way that should invalidate cached
@@ -17,3 +28,109 @@
  * across vitest workers (cross-cutting hazard #2).
  */
 export declare const diagnosisVersion = "0.1.0";
+/**
+ * Per-invocation context threaded into every card generator.
+ *
+ * `judgmentAttributions` is the Landmine-11 addition — Phase 4 emits
+ * per-judgment attribution as per-entry GCS artifacts at
+ * `runs/{runId}/attribution/{entryKey}.json`. The runner loads them once
+ * per `.run({...})` via `deps.loadAttributions(runId)` and threads the
+ * result here. Cards that need attribution inspect this field and return
+ * `status: "missing"` when it is `undefined` or empty.
+ */
+export interface GeneratorContext {
+    readonly llm: LLMClient | undefined;
+    readonly model: ModelId;
+    readonly logger: Logger;
+    readonly progress: ProgressReporter;
+    readonly versions: VersionedInputs;
+    readonly runId: string;
+    readonly reportId: string;
+    readonly baseline?: Report;
+    /** Phase-4 attribution array, loaded once per run (Landmine 11). */
+    readonly judgmentAttributions?: JudgmentAttribution[];
+}
+/**
+ * Per-card generator function. Pure async function; the runner wraps
+ * each invocation in try/catch so generators MUST NOT suppress their
+ * own errors — throw freely; the runner owns error translation.
+ */
+export type CardGenerator = (report: Report, ctx: GeneratorContext) => Promise<DiagnosisCard>;
+/**
+ * Flat registry of all 8 card types → generator functions. Lives here
+ * (NOT in `services/diagnosis/registry.ts`) per CONTEXT D-06 — the
+ * Phase-1 `cardRegistry` placeholder stays empty to keep the contract
+ * test green; the composition root builds a `CardRegistry` literal and
+ * passes it into `createDiagnosisRunner(deps)`.
+ *
+ * `Readonly<Record<CardType, CardGenerator>>` — TypeScript exhaustiveness
+ * ensures all 8 literal `CardType` strings appear in any registry literal
+ * (no rogue keys, no silently missing keys).
+ */
+export type CardRegistry = Readonly<Record<CardType, CardGenerator>>;
+/**
+ * Dependencies for the diagnosis runner factory.
+ *
+ * D-02 delta vs. AI-SPEC §3: `cache: CacheStore` is replaced by two
+ * narrow callback deps so the engine uses the artifact store directly
+ * without needing a `CacheStore.get/set` API that doesn't exist.
+ *
+ * Landmine-11 addition: `loadAttributions` lets the composition root bind
+ * a reader over `ARTIFACT_REGISTRY.perEntryAttribution` without widening
+ * the `CacheStore` port.
+ */
+export interface DiagnosisRunnerDeps {
+    /**
+     * Cache-lookup hook. Receives the artifact path built from the
+     * 4-version + model cache key. Plan 06's composition root supplies a
+     * reader that parses cached bytes through the Diagnosis Zod schema
+     * (T-05-04-01 mitigation). Tests supply a simple fake.
+     *
+     * Returns `null` on miss; returns the cached `Diagnosis` on hit.
+     */
+    readonly diagnosisReader: (path: string) => Promise<Diagnosis | null>;
+    /**
+     * Cache-write hook. Receives the same path as `diagnosisReader` plus
+     * the freshly-built `Diagnosis`. Called unconditionally after every
+     * successful run (including `refresh: true` — a refreshed call
+     * replaces the cached Diagnosis per AI-SPEC §3).
+     */
+    readonly diagnosisWriter: (path: string, diagnosis: Diagnosis) => Promise<void>;
+    /**
+     * Attribution loader — invoked once per `.run({...})` with
+     * `report.provenance.runId`. Rejection is caught by the runner; the
+     * resolved value (including `[]`) is threaded into every
+     * `GeneratorContext.judgmentAttributions` (Landmine 11).
+     */
+    readonly loadAttributions: (runId: string) => Promise<JudgmentAttribution[]>;
+    readonly llm: LLMClient | undefined;
+    readonly model: ModelId;
+    readonly logger: Logger;
+    readonly progress: ProgressReporter;
+    readonly registry: CardRegistry;
+}
+/**
+ * Arguments for a single diagnosis run.
+ */
+export interface DiagnosisRunnerRunArgs {
+    readonly report: Report;
+    readonly versions: VersionedInputs;
+    readonly baseline?: Report;
+    /** When `true`, bypasses the cache lookup (but still writes on completion). */
+    readonly refresh?: boolean;
+}
+/**
+ * The diagnosis runner interface. A single `.run()` method returns a
+ * fully-assembled `Diagnosis` (or a partial one if some cards degraded).
+ */
+export interface DiagnosisRunner {
+    run(args: DiagnosisRunnerRunArgs): Promise<Diagnosis>;
+}
+/**
+ * Build a `DiagnosisRunner` whose `.run({report, versions, baseline?, refresh?})`
+ * produces a `Diagnosis` with cards in registry-order.
+ *
+ * No module-scope `let` — all state lives in the `deps` closure and per-run
+ * local variables (AI-SPEC §3 Pitfall 1).
+ */
+export declare function createDiagnosisRunner(deps: DiagnosisRunnerDeps): DiagnosisRunner;

package/dist/_vendor/ailf-core/services/diagnosis-runner.js

@@ -1,12 +1,22 @@
 /**
  * Diagnosis runner — engine entry point (D0048).
  *
- * Phase 1 lands the version constant only; the runner factory + cache
- * lookup land in Phase 5.
+ * Phase 5 implements the factory body; Phase 1 shipped `diagnosisVersion` only.
+ * `GeneratorContext.judgmentAttributions` is sourced once per `.run({...})` via
+ * `deps.loadAttributions(runId)` reading Phase 4's
+ * `runs/{runId}/attribution/{entryKey}.json` per-entry artifacts (RESEARCH
+ * Landmine 11).
  *
  * @see docs/decisions/D0048-engine-homes-for-cli-api-parity.md
  * @see .planning/phases/01-foundation-contracts-cross-cutting-schemas/01-CONTEXT.md (D-02)
+ * @see .planning/phases/05-diagnosis-engine-cli-llm-cards/05-RESEARCH.md (Landmine 11)
+ * @see .planning/phases/05-diagnosis-engine-cli-llm-cards/05-CONTEXT.md (D-02, D-06, D-10)
  */
+import { z } from "zod";
+import { ARTIFACT_REGISTRY, encodeDiagnosisPathVersion, } from "../artifact-registry.js";
+// ---------------------------------------------------------------------------
+// Version constant (Phase 1 / VER-01 / D-02)
+// ---------------------------------------------------------------------------
 /**
  * Bumped when the runner's selection logic, prompt orchestration, or
  * card-set composition changes in a way that should invalidate cached
@@ -17,3 +27,127 @@
  * across vitest workers (cross-cutting hazard #2).
  */
 export const diagnosisVersion = "0.1.0";
+// ---------------------------------------------------------------------------
+// Private helpers
+// ---------------------------------------------------------------------------
+/**
+ * Build the deterministic cache path that incorporates all four version
+ * segments AND the model id (AI-SPEC §3 lines 463-473 + D-02).
+ *
+ * The artifact path from `ARTIFACT_REGISTRY.diagnosis.objectPath(...)` is
+ * already version-scoped; we append `::${model}` to include model identity
+ * in the key without changing the artifact path shape.
+ */
+function buildCacheKey(report, versions, model) {
+    const artifactPath = ARTIFACT_REGISTRY.diagnosis.objectPath(report.provenance.runId, report.id, encodeDiagnosisPathVersion(versions.diagnosisVersion, versions.cardVersion));
+    // Embed the remaining two version axes + model in the key string. The
+    // artifact path already carries diagnosisVersion + cardVersion; the other
+    // two axes are appended here so any single-segment bump produces a
+    // distinct key.
+    return `${artifactPath}::grader=${versions.graderJudgmentsVersion}::ensemble=${versions.ensembleVersion}::model=${model}`;
+}
+/**
+ * Per-card invocation — never panics. ZodError or any other thrown value
+ * both translate to a degraded card (AI-SPEC §3 lines 530-552).
+ */
+async function runOne(generator, report, ctx, cardType) {
+    try {
+        return await generator(report, ctx);
+    }
+    catch (err) {
+        const meta = {
+            cardVersion: `${cardType}@unknown`,
+            generatedAt: new Date().toISOString(),
+        };
+        const isZodErr = err instanceof z.ZodError;
+        return {
+            status: "degraded",
+            cardType,
+            reason: err instanceof Error ? err.message : String(err),
+            parseFailed: isZodErr,
+            meta,
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Factory (AI-SPEC §3 lines 458-523 + D-02 / Landmine-11 deltas)
+// ---------------------------------------------------------------------------
+/**
+ * Build a `DiagnosisRunner` whose `.run({report, versions, baseline?, refresh?})`
+ * produces a `Diagnosis` with cards in registry-order.
+ *
+ * No module-scope `let` — all state lives in the `deps` closure and per-run
+ * local variables (AI-SPEC §3 Pitfall 1).
+ */
+export function createDiagnosisRunner(deps) {
+    return {
+        async run({ report, versions, baseline, refresh }) {
+            const cachePath = buildCacheKey(report, versions, deps.model);
+            // Cache lookup (bypassed when --refresh).
+            if (!refresh) {
+                const cached = await deps.diagnosisReader(cachePath);
+                if (cached !== null)
+                    return cached;
+            }
+            // One-shot attribution load (Landmine 11 — Phase 4 per-entry artifacts).
+            let judgmentAttributions;
+            try {
+                judgmentAttributions = await deps.loadAttributions(report.provenance.runId);
+            }
+            catch (err) {
+                deps.logger.warn("diagnosis-runner: loadAttributions failed", {
+                    runId: report.provenance.runId,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                judgmentAttributions = undefined;
+            }
+            const ctx = {
+                llm: deps.llm,
+                model: deps.model,
+                logger: deps.logger,
+                progress: deps.progress,
+                versions,
+                runId: report.provenance.runId, // D-10: provenance.runId, NOT report.runId
+                reportId: report.id,
+                judgmentAttributions, // Landmine 11
+                ...(baseline ? { baseline } : {}),
+            };
+            const cardTypes = Object.keys(deps.registry);
+            const cards = [];
+            let parseFailures = 0;
+            for (const cardType of cardTypes) {
+                const generator = deps.registry[cardType];
+                // Budget enforcement: once ≤1 budget is breached, downgrade
+                // subsequent parse-failing cards to "missing" before even running
+                // the generator (AI-SPEC §3 lines 496-510 + must-have #4).
+                // We still RUN the generator here to match the behavior spec —
+                // the budget check happens AFTER the card result is obtained.
+                const card = await runOne(generator, report, ctx, cardType);
+                if (card.status === "degraded" && card.parseFailed) {
+                    if (parseFailures >= 1) {
+                        // Budget exceeded — demote to missing.
+                        deps.logger.warn(`diagnosis-runner: parse-failure budget exceeded for card "${cardType}"; demoting to missing`, { reportId: report.id });
+                        cards.push({
+                            status: "missing",
+                            cardType,
+                            reason: "degraded-budget-exceeded",
+                        });
+                        continue;
+                    }
+                    parseFailures++;
+                }
+                cards.push(card);
+            }
+            const diagnosis = {
+                runId: report.provenance.runId, // D-10: provenance.runId
+                reportId: report.id,
+                inputs: versions,
+                cards,
+                generatedAt: new Date().toISOString(),
+            };
+            // Unconditional write — a refreshed call replaces the cached Diagnosis.
+            await deps.diagnosisWriter(cachePath, diagnosis);
+            return diagnosis;
+        },
+    };
+}

package/dist/_vendor/ailf-core/services/index.d.ts

@@ -13,5 +13,9 @@ export { aggregateAreas, aggregateDimensions, computeEnsembleScore, computeTaskS
 export { extractModelName, extractProvider, mergeConfig, modelMatchesMode, resolveModelVariants, } from "./config-helpers.js";
 export { buildSlimReportSummary } from "./slim-report-summary.js";
 export { reportToMarkdown, type RenderableReport, } from "./report-to-markdown.js";
-export { diagnosisVersion } from "./diagnosis-runner.js";
+export { createDiagnosisRunner, diagnosisVersion, type CardGenerator, type CardRegistry, type DiagnosisRunner, type DiagnosisRunnerDeps, type DiagnosisRunnerRunArgs, type GeneratorContext, } from "./diagnosis-runner.js";
 export { cardRegistry, type CardDefinition } from "./diagnosis/registry.js";
+export { createLLMClient, type LLMClientAdapters, type LLMClientFactoryConfig, type LLMClientKeys, } from "./llm-client-factory.js";
+export { buildFailureModeRefinement, isFailureModeInDimensionTaxonomy, } from "./diagnosis/card-validators.js";
+export { DIAGNOSIS_CARD_GENERATORS, generateAreaSummary, generateFailureModeSummary, generateNoIssues, generateTopRecommendations, generateWeakestArea, generateLowConfidenceAttribution, generateDocAttributionSpotlight, generateRegressionVsBaseline, } from "./diagnosis/cards/index.js";
+export { buildTopRecommendationsPrompt, buildWeakestAreaPrompt, buildLowConfidenceAttributionPrompt, buildDocAttributionSpotlightPrompt, buildRegressionVsBaselinePrompt, buildDocSlugAllowList, } from "./diagnosis/prompt-builders.js";

package/dist/_vendor/ailf-core/services/index.js

@@ -14,7 +14,20 @@ export { extractModelName, extractProvider, mergeConfig, modelMatchesMode, resol
 export { buildSlimReportSummary } from "./slim-report-summary.js";
 export { reportToMarkdown, } from "./report-to-markdown.js";
 // ---------------------------------------------------------------------------
-// Actionability ladder Phase 1 — diagnosis runner + card registry
+// Actionability ladder Phase 1 + Phase 5 — diagnosis runner + card registry
 // ---------------------------------------------------------------------------
-export { diagnosisVersion } from "./diagnosis-runner.js";
+export { createDiagnosisRunner, diagnosisVersion, } from "./diagnosis-runner.js";
 export { cardRegistry } from "./diagnosis/registry.js";
+// ---------------------------------------------------------------------------
+// Phase 5 — LLM client factory (D-01 hoist)
+// ---------------------------------------------------------------------------
+export { createLLMClient, } from "./llm-client-factory.js";
+// ---------------------------------------------------------------------------
+// Phase 5 — card validators (D-05 refine helpers)
+// ---------------------------------------------------------------------------
+export { buildFailureModeRefinement, isFailureModeInDimensionTaxonomy, } from "./diagnosis/card-validators.js";
+// ---------------------------------------------------------------------------
+// Phase 5 Plan 05 — card generators barrel + prompt builders
+// ---------------------------------------------------------------------------
+export { DIAGNOSIS_CARD_GENERATORS, generateAreaSummary, generateFailureModeSummary, generateNoIssues, generateTopRecommendations, generateWeakestArea, generateLowConfidenceAttribution, generateDocAttributionSpotlight, generateRegressionVsBaseline, } from "./diagnosis/cards/index.js";
+export { buildTopRecommendationsPrompt, buildWeakestAreaPrompt, buildLowConfidenceAttributionPrompt, buildDocAttributionSpotlightPrompt, buildRegressionVsBaselinePrompt, buildDocSlugAllowList, } from "./diagnosis/prompt-builders.js";

package/dist/_vendor/ailf-core/services/llm-client-factory.d.ts

@@ -0,0 +1,64 @@
+/**
+ * LLM client factory — hoisted from packages/eval/src/composition-root.ts
+ * so packages/api can build a DiagnosisRunner without importing eval (D-01).
+ *
+ * Adapter CLASSES stay in packages/eval/src/adapters/llm/. Only the factory
+ * function lives here. Adapter constructors are injected via `LLMClientAdapters`
+ * so core never static-imports vendor SDK code (D0051 invariant / T-05-01-01).
+ *
+ * @see docs/decisions/D0051-llm-client-port.md
+ * @see packages/eval/src/composition-root.ts — call site (updated to use this)
+ */
+import type { LLMClient } from "../ports/llm-client.js";
+import type { Logger } from "../ports/logger.js";
+/**
+ * Narrow config slice consumed by the LLM client factory.
+ * Does NOT depend on `ResolvedConfig` from packages/eval — only the
+ * llmProvider field is needed here.
+ */
+export interface LLMClientFactoryConfig {
+    readonly llmProvider?: "anthropic" | "openai";
+}
+/**
+ * Typed key bag passed to `createLLMClient`. The composition root reads
+ * env once and supplies values here; the factory stays pure so tests don't
+ * have to mutate `process.env`.
+ */
+export interface LLMClientKeys {
+    readonly anthropicApiKey?: string;
+    readonly openaiApiKey?: string;
+}
+/**
+ * Constructor callbacks for adapter classes that live in packages/eval.
+ * The eval composition root passes real constructors; tests pass spies.
+ *
+ * This pattern satisfies T-05-01-01: core never static-imports
+ * openai / @anthropic-ai/sdk. The vendor code stays in eval.
+ */
+export interface LLMClientAdapters {
+    readonly newAnthropicClient: (opts: {
+        apiKey: string;
+        logger: Logger;
+    }) => LLMClient;
+    readonly newOpenAIClient: (opts: {
+        apiKey: string;
+        logger: Logger;
+    }) => LLMClient;
+}
+/**
+ * Select the LLMClient adapter based on `config.llmProvider` and the
+ * supplied API keys. Returns `undefined` when no usable credential is
+ * present — `AppContext.llmClient` stays unset and consumers handle that
+ * explicitly.
+ *
+ * Adapters never read `process.env` themselves (per
+ * `.claude/rules/typescript.md`); env mapping happens at the call site
+ * (typically `createAppContext`).
+ *
+ * Adapter classes stay in packages/eval; they are passed in via `deps.adapters`
+ * so this factory has zero eval imports (D-01 / T-05-01-01).
+ */
+export declare function createLLMClient(config: LLMClientFactoryConfig, keys: LLMClientKeys, deps: {
+    logger: Logger;
+    adapters: LLMClientAdapters;
+}): LLMClient | undefined;

package/dist/_vendor/ailf-core/services/llm-client-factory.js

@@ -0,0 +1,54 @@
+/**
+ * LLM client factory — hoisted from packages/eval/src/composition-root.ts
+ * so packages/api can build a DiagnosisRunner without importing eval (D-01).
+ *
+ * Adapter CLASSES stay in packages/eval/src/adapters/llm/. Only the factory
+ * function lives here. Adapter constructors are injected via `LLMClientAdapters`
+ * so core never static-imports vendor SDK code (D0051 invariant / T-05-01-01).
+ *
+ * @see docs/decisions/D0051-llm-client-port.md
+ * @see packages/eval/src/composition-root.ts — call site (updated to use this)
+ */
+// ---------------------------------------------------------------------------
+// Factory function
+// ---------------------------------------------------------------------------
+/**
+ * Select the LLMClient adapter based on `config.llmProvider` and the
+ * supplied API keys. Returns `undefined` when no usable credential is
+ * present — `AppContext.llmClient` stays unset and consumers handle that
+ * explicitly.
+ *
+ * Adapters never read `process.env` themselves (per
+ * `.claude/rules/typescript.md`); env mapping happens at the call site
+ * (typically `createAppContext`).
+ *
+ * Adapter classes stay in packages/eval; they are passed in via `deps.adapters`
+ * so this factory has zero eval imports (D-01 / T-05-01-01).
+ */
+export function createLLMClient(config, keys, deps) {
+    const { logger, adapters } = deps;
+    const explicit = config.llmProvider;
+    const anthropicKey = keys.anthropicApiKey;
+    const openaiKey = keys.openaiApiKey;
+    // Auto-select: prefer Anthropic when both are present (matches the
+    // current grader's default model in config/models.ts).
+    const provider = explicit ?? (anthropicKey ? "anthropic" : openaiKey ? "openai" : undefined);
+    if (!provider) {
+        logger.debug("LLM client: not wired — no Anthropic or OpenAI API key supplied");
+        return undefined;
+    }
+    if (provider === "anthropic") {
+        if (!anthropicKey) {
+            logger.warn('llmProvider="anthropic" but no Anthropic API key supplied — LLMClient not wired');
+            return undefined;
+        }
+        logger.debug("LLM client: AnthropicLLMClient");
+        return adapters.newAnthropicClient({ apiKey: anthropicKey, logger });
+    }
+    if (!openaiKey) {
+        logger.warn('llmProvider="openai" but no OpenAI API key supplied — LLMClient not wired');
+        return undefined;
+    }
+    logger.debug("LLM client: OpenAILLMClient");
+    return adapters.newOpenAIClient({ apiKey: openaiKey, logger });
+}