@evomap/evolver-core 2.0.0-beta.0

package/dist/signals/traceSignals.js

@@ -0,0 +1,123 @@
+// Signal extraction from the LLM proxy's per-turn trace records (the `llm-trace-*.jsonl` files written by
+// the proxy's JsonlTraceSink). Trace records are TURN METADATA — models, tier decision, status, latency,
+// usage, stop_reason — never conversation text, so the signals here are the economic/reliability ones the
+// session transcripts can't see: upstream failures, credential breakage, router fallbacks, truncation
+// pressure, sustained latency. This closes the loop opened by the proxy's trace-capture seam: the proxy
+// captures turn metadata, and `evolver ingest` mines it through this extractor.
+//
+// Three-leg mapping: every rule below is a zero-cost structured judgment over counters, so every emitted
+// signal is `strong` with `needsAnalysis: false`. The `agent` and `weak` legs do not apply to metadata —
+// there is no free text for an agent marker or difficulty wording to live in.
+import { ulid as makeUlid } from 'ulid';
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+const str = (v) => (typeof v === 'string' && v.length > 0 ? v : null);
+const strong = (kind, text) => ({ id: makeUlid(), strength: 'strong', kind, text: text.slice(0, 2000), needsAnalysis: false });
+/**
+ * Extract economic/reliability signals from a batch of llm-trace records. Returns the SAME signal shape as
+ * `extractSignals` (one batch-aggregated signal per fired rule, not one per record — a day file holds
+ * thousands of turns and per-record emission would flood every downstream consumer with duplicates).
+ * Records whose `event` is not `'llm_turn'` are ignored, so callers can pass a raw parsed JSONL batch.
+ */
+export function extractTraceSignals(records, cfg = {}) {
+    const min5xx = cfg.min5xx ?? 2;
+    const minRateLimited = cfg.minRateLimited ?? 3;
+    const minAuthFailures = cfg.minAuthFailures ?? 2;
+    const minTruncations = cfg.minTruncations ?? 3;
+    const minPolicyFallbacks = cfg.minPolicyFallbacks ?? 3;
+    const slowTtfbMs = cfg.slowTtfbMs ?? 30_000;
+    const minSlowTurns = cfg.minSlowTurns ?? 5;
+    const minSlowShare = cfg.minSlowShare ?? 0.2;
+    const handlerErrors = new Map(); // normalized error text → count
+    const fallbacks = new Map(); // fallback reason → count
+    const fiveXxStatuses = new Map(); // 5xx status → count
+    let authFailures = 0;
+    let rateLimited = 0;
+    let truncations = 0;
+    let eligibleTurns = 0; // successful turns with a measured TTFB — the latency denominator
+    let slowTurns = 0;
+    for (const r of records) {
+        if (r.event !== 'llm_turn')
+            continue;
+        const status = num(r.status);
+        const error = str(r.error);
+        const fallback = str(r.fallback);
+        const stopReason = str(r.stop_reason);
+        const ttfb = num(r.ttfb_ms);
+        // Handler/transport errors (upstream unreachable, drain failure, …). Auth statuses are carved out into
+        // their own rule below so a 401's "x-api-key required" error text is not double-counted.
+        if (error && status !== 401 && status !== 403) {
+            const key = error.replace(/\s+/g, ' ').trim().slice(0, 200);
+            handlerErrors.set(key, (handlerErrors.get(key) ?? 0) + 1);
+        }
+        if (status === 401 || status === 403)
+            authFailures++;
+        if (status !== null && status >= 500)
+            fiveXxStatuses.set(status, (fiveXxStatuses.get(status) ?? 0) + 1);
+        if (status === 429)
+            rateLimited++;
+        if (fallback)
+            fallbacks.set(fallback, (fallbacks.get(fallback) ?? 0) + 1);
+        if (stopReason === 'max_tokens')
+            truncations++;
+        if (status === 200 && ttfb !== null) {
+            eligibleTurns++;
+            if (ttfb >= slowTtfbMs)
+                slowTurns++;
+        }
+    }
+    const out = [];
+    // RULE: handler error — the proxy could not complete the turn at all (e.g. ECONNREFUSED, drain timeout).
+    // Threshold 1: a hard transport/handler failure is never routine, mirroring how a single tool error is a
+    // strong signal in the session extractor. Grouped by error text so a repeated failure stays one signal.
+    for (const [text, count] of handlerErrors) {
+        out.push(strong('trace_handler_error', `LLM proxy handler error ×${count}: ${text}`));
+    }
+    // RULE: upstream 5xx — server-side failures that survived the route's own retry. Threshold 2: a single
+    // 5xx is normal API weather (overload blips happen and the handler already retries rewritten requests);
+    // two or more in one ingested batch is a reliability pattern worth surfacing.
+    const total5xx = [...fiveXxStatuses.values()].reduce((s, n) => s + n, 0);
+    if (total5xx >= min5xx) {
+        const breakdown = [...fiveXxStatuses.keys()].sort((a, b) => a - b).join('/');
+        out.push(strong('trace_upstream_5xx', `upstream 5xx ×${total5xx} (status ${breakdown}) — upstream reliability degraded`));
+    }
+    // RULE: rate limiting — 429s are the purest economic signal in the trace (quota/budget pressure).
+    // Threshold 3: occasional 429s are expected under bursty load; sustained ones mean the tier/quota
+    // configuration is mismatched with real usage.
+    if (rateLimited >= minRateLimited) {
+        out.push(strong('trace_rate_limited', `upstream 429 rate-limited ×${rateLimited} — quota/tier pressure`));
+    }
+    // RULE: auth failures — 401/403 from the credential path. Threshold 2: a single 401 can be one client's
+    // typo; repeated ones mean the proxy or its clients are misconfigured (broken key, missing env cred).
+    if (authFailures >= minAuthFailures) {
+        out.push(strong('trace_auth_failure', `auth failures (401/403) ×${authFailures} — credential configuration broken`));
+    }
+    // RULE: router fallbacks, split by what the reason MEANS:
+    //   - classifier_error / rewrite_error: the router's own code threw. Threshold 1 — a throwing classifier
+    //     is a bug, never routine operation.
+    //   - downgrade_blocked: the safety guard refused an intra-family downgrade. Threshold 3 — single blocks
+    //     are the guard working as designed; a sustained pattern means the tier config conflicts with what
+    //     clients actually request and routing silently does nothing.
+    //   - anything else (future reasons): threshold 2 — unknown but repeated is worth a look.
+    for (const [reason, count] of fallbacks) {
+        const min = reason === 'classifier_error' || reason === 'rewrite_error' ? 1
+            : reason === 'downgrade_blocked' ? minPolicyFallbacks
+                : 2;
+        if (count >= min) {
+            out.push(strong('trace_router_fallback', `router fallback ${reason} ×${count} — routing degraded to passthrough`));
+        }
+    }
+    // RULE: truncation pressure — turns that stopped at max_tokens. Threshold 3: a single truncation is often
+    // deliberate (caller set a tight cap); repeated ones mean responses are systematically being cut off,
+    // which silently corrupts agent behavior and wastes the tokens already paid for.
+    if (truncations >= minTruncations) {
+        out.push(strong('trace_truncation', `stop_reason=max_tokens ×${truncations} — output truncation pressure`));
+    }
+    // RULE: sustained high TTFB. TTFB (time to upstream response headers), NOT total latency_ms, because total
+    // latency scales with legitimate output length — long generations are normal, slow first bytes are queue/
+    // network/server pressure. Two-part gate so single spikes never fire: an absolute count (>= minSlowTurns)
+    // AND a meaningful share of successful turns (>= minSlowShare) must be slow.
+    if (slowTurns >= minSlowTurns && eligibleTurns > 0 && slowTurns / eligibleTurns >= minSlowShare) {
+        out.push(strong('trace_slow_ttfb', `sustained high TTFB: ${slowTurns}/${eligibleTurns} successful turns ≥ ${slowTtfbMs}ms`));
+    }
+    return out;
+}

package/dist/signatures/classifier.d.ts

@@ -0,0 +1,16 @@
+import type { ProblemSignatureInput } from './signatures.js';
+/** 把工程事件归类成领域问题 (event_sig → problem_sig). 可插拔: 规则/LLM/agent, 实验选 (硬化). */
+export interface ProblemClassifier {
+    readonly name: string;
+    classify(input: ClassifyInput): ProblemSignatureInput | null;
+}
+export interface ClassifyInput {
+    text: string;
+    errorClass?: string;
+    affectedSurface?: string;
+}
+/** MVP 规则分类器 (LLM/agent 分类器是 M4). */
+export declare class RuleProblemClassifier implements ProblemClassifier {
+    readonly name = "rules";
+    classify(input: ClassifyInput): ProblemSignatureInput | null;
+}

package/dist/signatures/classifier.js

@@ -0,0 +1,29 @@
+const KEYWORD_TAGS = [
+    [/(auth|401|403|token|credential|认证|鉴权)/i, 'auth'],
+    [/\bhttp|api|request|fetch|网络|network/i, 'network'],
+    [/\bdb|sql|database|prisma/i, 'db'],
+    [/\btest|测试|vitest|jest/i, 'test'],
+];
+const FAILURE_MODES = [
+    [/\btimeout|timed out|ETIMEDOUT|超时/i, 'timeout'],
+    [/\bECONNRESET|reset|断开|disconnect/i, 'connection_reset'],
+    [/\b401|403|unauthorized|forbidden/i, 'unauthorized'],
+    [/\bENOENT|not found|404|缺失/i, 'not_found'],
+];
+/** MVP 规则分类器 (LLM/agent 分类器是 M4). */
+export class RuleProblemClassifier {
+    name = 'rules';
+    classify(input) {
+        const hay = `${input.text} ${input.errorClass ?? ''}`;
+        const domainTags = KEYWORD_TAGS.filter(([re]) => re.test(hay)).map(([, t]) => t);
+        const fm = FAILURE_MODES.find(([re]) => re.test(hay));
+        if (domainTags.length === 0 && !fm)
+            return null;
+        return {
+            problemKind: domainTags[0] ?? 'general',
+            domainTags,
+            affectedSurface: input.affectedSurface ?? domainTags[0] ?? 'unknown',
+            failureMode: fm?.[1] ?? 'unknown',
+        };
+    }
+}

package/dist/signatures/index.d.ts

@@ -0,0 +1,2 @@
+export * from './signatures.js';
+export * from './classifier.js';

package/dist/signatures/index.js

@@ -0,0 +1,2 @@
+export * from './signatures.js';
+export * from './classifier.js';

package/dist/signatures/signatures.d.ts

@@ -0,0 +1,22 @@
+export declare const SIGNATURE_V = 1;
+/** 文本归一化: 小写+NFKC+去标点+折叠空白 → 同义不同措辞归并. */
+export declare function normalizeText(s: string): string;
+/** 栈帧归一化: 去绝对路径/行列号, 留 fn@basename. */
+export declare function normalizeStackFrame(frame: string): string;
+export declare function exitCodeClass(code?: number): string;
+/** 工程层指纹 (军杰 §4.2): 纯工程特征, 不含领域语义. */
+export interface EventSignatureInput {
+    errorClass: string;
+    stack?: readonly string[];
+    syscall?: string;
+    exitCode?: number;
+}
+export declare function eventSignature(input: EventSignatureInput): string;
+/** 领域层指纹 (军杰 §4.3): 不含 gene_id/capsule_id. */
+export interface ProblemSignatureInput {
+    problemKind: string;
+    domainTags?: readonly string[];
+    affectedSurface?: string;
+    failureMode?: string;
+}
+export declare function problemSignature(input: ProblemSignatureInput): string;

package/dist/signatures/signatures.js

@@ -0,0 +1,42 @@
+import { createHash } from 'node:crypto';
+export const SIGNATURE_V = 1;
+function sha1(...parts) {
+    return createHash('sha1').update(parts.join('\x1f')).digest('hex');
+}
+/** 文本归一化: 小写+NFKC+去标点+折叠空白 → 同义不同措辞归并. */
+export function normalizeText(s) {
+    return s.toLowerCase().normalize('NFKC').replace(/[^\p{L}\p{N}]+/gu, ' ').trim().replace(/\s+/g, ' ');
+}
+/** 栈帧归一化: 去绝对路径/行列号, 留 fn@basename. */
+export function normalizeStackFrame(frame) {
+    const f = frame.trim().replace(/^at\s+/, '');
+    const pathMatch = f.match(/\(?([^()\s]+?):(\d+)(?::(\d+))?\)?$/);
+    const fnMatch = f.match(/^([^(]+?)\s*\(/);
+    const fileWithPath = pathMatch?.[1] ?? f;
+    const base = fileWithPath.split(/[/\\]/).pop() ?? fileWithPath;
+    const fn = fnMatch?.[1]?.trim() ?? '';
+    return fn ? `${fn}@${base}` : base;
+}
+export function exitCodeClass(code) {
+    if (code === undefined)
+        return 'none';
+    if (code === 0)
+        return 'ok';
+    if (code === 1)
+        return 'general';
+    if (code === 2)
+        return 'misuse';
+    if (code === 126 || code === 127)
+        return 'notfound';
+    if (code >= 128)
+        return 'signal';
+    return 'other';
+}
+export function eventSignature(input) {
+    const top3 = (input.stack ?? []).slice(0, 3).map(normalizeStackFrame).join('|');
+    return sha1('ev', normalizeText(input.errorClass), top3, input.syscall ?? '', exitCodeClass(input.exitCode));
+}
+export function problemSignature(input) {
+    const tags = [...(input.domainTags ?? [])].map(normalizeText).sort().join(',');
+    return sha1('pb', normalizeText(input.problemKind), tags, normalizeText(input.affectedSurface ?? ''), normalizeText(input.failureMode ?? ''));
+}

package/dist/strategy/experiment.d.ts

@@ -0,0 +1,48 @@
+import type { Strategy, StrategyContext, StrategyPoint } from './strategyPoint.js';
+/** 策略多指标适应度(算法草案§7). 权重可调, 初值 0.5/0.3/0.2(待实验校准). */
+export interface FitnessWeights {
+    resolved: number;
+    reuse: number;
+    cost: number;
+}
+export declare const DEFAULT_WEIGHTS: FitnessWeights;
+export interface FitnessSample {
+    resolvedByEvidence: boolean;
+    reused: boolean;
+    cost: number;
+}
+export interface FitnessScore {
+    n: number;
+    resolvedRate: number;
+    reuseRate: number;
+    avgCost: number;
+    score: number;
+}
+/** fitness = w1·resolved_by_evidence率 + w2·capsule复用率 − w3·归一成本. */
+export declare function computeFitness(samples: readonly FitnessSample[], w?: FitnessWeights): FitnessScore;
+export interface ShadowResult<O> {
+    active: O;
+    activeName: string;
+    shadows: Array<{
+        name: string;
+        output?: O;
+        error?: string;
+    }>;
+}
+/**
+ * Shadow 评估: active 权威返回; 其余实现旁路跑同输入, 记录产出/异常供离线对比, 不影响主流程.
+ * 实验台打底(算法草案§7): 所有候选先 shadow, 关键的才 A/B.
+ */
+export declare function runShadow<I, O>(sp: StrategyPoint<I, O>, input: I, ctx: StrategyContext): Promise<ShadowResult<O>>;
+/** 确定性 A/B 分桶: 同 key 永远同变体(可复现, 不依赖随机). */
+export declare function assignVariant(key: string, variants: readonly string[]): string;
+/** A/B 路由: 按 ctx.cycleId 确定性选变体并跑. */
+export declare function runAB<I, O>(sp: StrategyPoint<I, O>, variants: readonly string[], input: I, ctx: StrategyContext): Promise<{
+    variant: string;
+    output: O;
+}>;
+/**
+ * 离线回放: 用历史输入集跑某策略, 由打分器产出 fitness 样本, 算总分.
+ * 用途: 新策略上线前先离线对比 active(算法草案§7 offline replay).
+ */
+export declare function offlineReplay<I, O>(impl: Strategy<I, O>, inputs: readonly I[], score: (input: I, output: O) => FitnessSample, ctxOf: (i: number) => StrategyContext, w?: FitnessWeights): Promise<FitnessScore>;

package/dist/strategy/experiment.js

@@ -0,0 +1,63 @@
+import { createHash } from 'node:crypto';
+export const DEFAULT_WEIGHTS = { resolved: 0.5, reuse: 0.3, cost: 0.2 };
+/** fitness = w1·resolved_by_evidence率 + w2·capsule复用率 − w3·归一成本. */
+export function computeFitness(samples, w = DEFAULT_WEIGHTS) {
+    const n = samples.length;
+    if (n === 0)
+        return { n: 0, resolvedRate: 0, reuseRate: 0, avgCost: 0, score: 0 };
+    const resolvedRate = samples.filter((s) => s.resolvedByEvidence).length / n;
+    const reuseRate = samples.filter((s) => s.reused).length / n;
+    const avgCost = samples.reduce((a, s) => a + s.cost, 0) / n;
+    const score = w.resolved * resolvedRate + w.reuse * reuseRate - w.cost * avgCost;
+    return { n, resolvedRate, reuseRate, avgCost, score };
+}
+/**
+ * Shadow 评估: active 权威返回; 其余实现旁路跑同输入, 记录产出/异常供离线对比, 不影响主流程.
+ * 实验台打底(算法草案§7): 所有候选先 shadow, 关键的才 A/B.
+ */
+export async function runShadow(sp, input, ctx) {
+    const active = sp.active();
+    const activeOut = await active.run(input, ctx);
+    const shadows = [];
+    for (const impl of sp.list()) {
+        if (impl.name === active.name)
+            continue;
+        try {
+            shadows.push({ name: impl.name, output: await impl.run(input, ctx) });
+        }
+        catch (e) {
+            shadows.push({ name: impl.name, error: e instanceof Error ? e.message : String(e) });
+        }
+    }
+    return { active: activeOut, activeName: active.name, shadows };
+}
+/** 确定性 A/B 分桶: 同 key 永远同变体(可复现, 不依赖随机). */
+export function assignVariant(key, variants) {
+    if (variants.length === 0)
+        throw new Error('A/B 变体不能为空');
+    const h = createHash('sha256').update(key).digest();
+    const bucket = h.readUInt32BE(0) % variants.length;
+    return variants[bucket];
+}
+/** A/B 路由: 按 ctx.cycleId 确定性选变体并跑. */
+export async function runAB(sp, variants, input, ctx) {
+    const variant = assignVariant(ctx.cycleId, variants);
+    const impl = sp.get(variant);
+    if (!impl)
+        throw new Error(`A/B 变体无实现: ${variant}`);
+    return { variant, output: await impl.run(input, ctx) };
+}
+/**
+ * 离线回放: 用历史输入集跑某策略, 由打分器产出 fitness 样本, 算总分.
+ * 用途: 新策略上线前先离线对比 active(算法草案§7 offline replay).
+ */
+export async function offlineReplay(impl, inputs, score, ctxOf, w = DEFAULT_WEIGHTS) {
+    const samples = [];
+    let i = 0;
+    for (const input of inputs) {
+        const out = await impl.run(input, ctxOf(i));
+        samples.push(score(input, out));
+        i += 1;
+    }
+    return computeFitness(samples, w);
+}

package/dist/strategy/index.d.ts

@@ -0,0 +1,2 @@
+export * from './strategyPoint.js';
+export * from './experiment.js';

package/dist/strategy/index.js

@@ -0,0 +1,2 @@
+export * from './strategyPoint.js';
+export * from './experiment.js';

package/dist/strategy/strategyPoint.d.ts

@@ -0,0 +1,30 @@
+/**
+ * StrategyPoint 框架(M4A-1a). 算法设计内核: 固定 cycle 骨架, 处处可插拔策略点.
+ * 每个 StrategyPoint = 一处可换算法(分类/触发/选 gene/变异/...); 多实现注册, 一个 active, 其余可 shadow/A-B.
+ * 经验主义: 不先验判优劣, 靠实验台(experiment.ts)按 fitness 选优.
+ */
+export interface StrategyContext {
+    now: number;
+    cycleId: string;
+    /** Injected randomness for stochastic strategies (e.g. exploration drift). Defaults to Math.random; inject a seeded rng for deterministic tests. */
+    rng?: () => number;
+}
+export interface Strategy<I, O> {
+    readonly name: string;
+    readonly version: string;
+    run(input: I, ctx: StrategyContext): Promise<O> | O;
+}
+export declare class StrategyPoint<I, O> {
+    readonly id: string;
+    private readonly impls;
+    private activeName;
+    constructor(id: string, primary: Strategy<I, O>);
+    register(s: Strategy<I, O>): this;
+    setActive(name: string): this;
+    active(): Strategy<I, O>;
+    get(name: string): Strategy<I, O> | undefined;
+    list(): Strategy<I, O>[];
+    names(): string[];
+    /** 跑 active, 透传 ctx. */
+    run(input: I, ctx: StrategyContext): Promise<O> | O;
+}

package/dist/strategy/strategyPoint.js

@@ -0,0 +1,23 @@
+export class StrategyPoint {
+    id;
+    impls = new Map();
+    activeName;
+    constructor(id, primary) {
+        this.id = id;
+        this.impls.set(primary.name, primary);
+        this.activeName = primary.name;
+    }
+    register(s) { this.impls.set(s.name, s); return this; }
+    setActive(name) {
+        if (!this.impls.has(name))
+            throw new Error(`StrategyPoint(${this.id}) 无实现: ${name}`);
+        this.activeName = name;
+        return this;
+    }
+    active() { return this.impls.get(this.activeName); }
+    get(name) { return this.impls.get(name); }
+    list() { return [...this.impls.values()]; }
+    names() { return [...this.impls.keys()]; }
+    /** 跑 active, 透传 ctx. */
+    run(input, ctx) { return this.active().run(input, ctx); }
+}

package/dist/trace/index.d.ts

@@ -0,0 +1,2 @@
+export * from './trajectory.js';
+export * from './trajectoryExport.js';

package/dist/trace/index.js

@@ -0,0 +1,2 @@
+export * from './trajectory.js';
+export * from './trajectoryExport.js';

package/dist/trace/trajectory.d.ts

@@ -0,0 +1,82 @@
+export interface NativeTraceUsage {
+    input_tokens?: number;
+    output_tokens?: number;
+    cache_creation_input_tokens?: number;
+    cache_read_input_tokens?: number;
+}
+export interface NativeTraceRecord {
+    event?: unknown;
+    ts?: unknown;
+    id?: unknown;
+    request_id?: unknown;
+    route?: unknown;
+    provider?: unknown;
+    wire_api?: unknown;
+    client?: unknown;
+    session_id?: unknown;
+    response_id?: unknown;
+    previous_response_id?: unknown;
+    original_model?: unknown;
+    chosen_model?: unknown;
+    status?: unknown;
+    stream?: unknown;
+    ttfb_ms?: unknown;
+    latency_ms?: unknown;
+    usage?: unknown;
+    stop_reason?: unknown;
+    error?: unknown;
+    requestBody?: unknown;
+    responseBody?: unknown;
+    request_body?: unknown;
+    response_body?: unknown;
+    redaction?: unknown;
+    body_truncated?: unknown;
+    reasoning?: unknown;
+    tool_calls?: unknown;
+    diff?: unknown;
+    validation?: unknown;
+}
+export type TraceCoverageStatus = 'covered' | 'missing';
+export interface TraceCoverageItem {
+    field: string;
+    status: TraceCoverageStatus;
+    source?: string;
+}
+export interface TraceTurnDraft {
+    trace_id: string | null;
+    ts: string | null;
+    provider: string | null;
+    wire_api: string | null;
+    route: string | null;
+    client: string | null;
+    session_id: string | null;
+    request_id: string | null;
+    response_id: string | null;
+    previous_response_id: string | null;
+    original_model: string | null;
+    chosen_model: string | null;
+    status: number | null;
+    stream: boolean | null;
+    ttfb_ms: number | null;
+    latency_ms: number | null;
+    usage?: NativeTraceUsage;
+    stop_reason?: string | null;
+    error?: string;
+    request_body?: unknown;
+    response_body?: unknown;
+    redaction?: string;
+    body_truncated?: boolean;
+    reasoning?: unknown;
+    tool_calls?: unknown;
+    diff?: unknown;
+    validation?: unknown;
+}
+export interface TraceTrajectoryDraft {
+    schema: 'evolver_trace_trajectory_draft.v1';
+    session_id: string | null;
+    turns: TraceTurnDraft[];
+    coverage: TraceCoverageItem[];
+}
+export declare function traceRecordToTurnDraft(record: NativeTraceRecord): TraceTurnDraft | null;
+export declare function buildTraceTrajectoryDraft(records: readonly NativeTraceRecord[]): TraceTrajectoryDraft;
+export declare function coverageForTurns(turns: readonly TraceTurnDraft[]): TraceCoverageItem[];

package/dist/trace/trajectory.js

@@ -0,0 +1,117 @@
+const REQUIRED_COVERAGE = [
+    { field: 'native_request_body', source: 'request_body' },
+    { field: 'native_response_body', source: 'response_body' },
+    { field: 'provider', source: 'provider' },
+    { field: 'wire_api', source: 'wire_api' },
+    { field: 'session_id', source: 'session_id' },
+    { field: 'usage', source: 'usage' },
+    { field: 'status', source: 'status' },
+    { field: 'reasoning_summary', source: 'reasoning' },
+    { field: 'tool_calls', source: 'tool_calls' },
+    { field: 'diff_or_before_after', source: 'diff' },
+    { field: 'validation_or_test_commands', source: 'validation' },
+];
+function stringOrNull(value) {
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+function numberOrNull(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+function booleanOrNull(value) {
+    return typeof value === 'boolean' ? value : null;
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function parseSerializedBody(value) {
+    if (typeof value !== 'string')
+        return value;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+function usageOrUndefined(value) {
+    if (!isRecord(value))
+        return undefined;
+    const out = {};
+    for (const key of ['input_tokens', 'output_tokens', 'cache_creation_input_tokens', 'cache_read_input_tokens']) {
+        const raw = value[key];
+        if (typeof raw === 'number' && Number.isFinite(raw))
+            out[key] = raw;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+function present(value) {
+    if (value === undefined || value === null)
+        return false;
+    if (typeof value === 'string')
+        return value.length > 0;
+    if (Array.isArray(value))
+        return value.length > 0;
+    if (typeof value === 'object')
+        return Object.keys(value).length > 0;
+    return true;
+}
+export function traceRecordToTurnDraft(record) {
+    if (record.event !== 'llm_turn')
+        return null;
+    const usage = usageOrUndefined(record.usage);
+    const requestBody = parseSerializedBody(record.requestBody !== undefined ? record.requestBody : record.request_body);
+    const responseBody = parseSerializedBody(record.responseBody !== undefined ? record.responseBody : record.response_body);
+    const reasoning = parseSerializedBody(record.reasoning);
+    const toolCalls = parseSerializedBody(record.tool_calls);
+    const diff = parseSerializedBody(record.diff);
+    const validation = parseSerializedBody(record.validation);
+    return {
+        trace_id: stringOrNull(record.id),
+        ts: stringOrNull(record.ts),
+        provider: stringOrNull(record.provider),
+        wire_api: stringOrNull(record.wire_api),
+        route: stringOrNull(record.route),
+        client: stringOrNull(record.client),
+        session_id: stringOrNull(record.session_id),
+        request_id: stringOrNull(record.request_id),
+        response_id: stringOrNull(record.response_id),
+        previous_response_id: stringOrNull(record.previous_response_id),
+        original_model: stringOrNull(record.original_model),
+        chosen_model: stringOrNull(record.chosen_model),
+        status: numberOrNull(record.status),
+        stream: booleanOrNull(record.stream),
+        ttfb_ms: numberOrNull(record.ttfb_ms),
+        latency_ms: numberOrNull(record.latency_ms),
+        ...(usage ? { usage } : {}),
+        ...(record.stop_reason !== undefined ? { stop_reason: stringOrNull(record.stop_reason) } : {}),
+        ...(typeof record.error === 'string' ? { error: record.error } : {}),
+        ...(requestBody !== undefined ? { request_body: requestBody } : {}),
+        ...(responseBody !== undefined ? { response_body: responseBody } : {}),
+        ...(typeof record.redaction === 'string' ? { redaction: record.redaction } : {}),
+        ...(typeof record.body_truncated === 'boolean' ? { body_truncated: record.body_truncated } : {}),
+        ...(reasoning !== undefined ? { reasoning } : {}),
+        ...(toolCalls !== undefined ? { tool_calls: toolCalls } : {}),
+        ...(diff !== undefined ? { diff } : {}),
+        ...(validation !== undefined ? { validation } : {}),
+    };
+}
+export function buildTraceTrajectoryDraft(records) {
+    const turns = records.map(traceRecordToTurnDraft).filter((turn) => turn !== null);
+    const sessionIds = [...new Set(turns.map((turn) => turn.session_id).filter((value) => typeof value === 'string' && value.length > 0))];
+    return {
+        schema: 'evolver_trace_trajectory_draft.v1',
+        session_id: sessionIds.length === 1 ? sessionIds[0] : null,
+        turns,
+        coverage: coverageForTurns(turns),
+    };
+}
+export function coverageForTurns(turns) {
+    return REQUIRED_COVERAGE.map(({ field, source }) => {
+        const hasField = turns.some((turn) => present(turn[source]));
+        return {
+            field,
+            status: hasField ? 'covered' : 'missing',
+            ...(hasField ? { source: 'llm_trace' } : {}),
+        };
+    });
+}