@kweaver-ai/kweaver-sdk 0.8.1 → 0.8.3

package/dist/trace-ai/scan/index.js

@@ -0,0 +1,390 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import yaml from "js-yaml";
+import { fileURLToPath } from "node:url";
+import { getSpansByConversationId } from "../../api/trace.js";
+import { assembleTraceTree } from "../diagnose/trace-shaper.js";
+import { loadRules } from "../diagnose/rule-loader.js";
+import "../diagnose/builtin-rules/register.js"; // side effect: registers all builtin predicates
+import { runRules, rubricRules } from "../diagnose/signal-probe.js";
+import { templateSynthesize } from "../diagnose/synthesizer-template.js";
+import { assembleReport, reportToYamlObject, symbolicHitsToFindings } from "../diagnose/report-assembler.js";
+import { renderReportMarkdown } from "../diagnose/report-markdown.js";
+import { ReportSchema } from "../diagnose/schemas.js";
+import { defaultRegistry } from "../../agent-providers/registry.js";
+import { defaultPromptRegistry } from "../../agent-providers/prompt-template.js";
+import { resolveRubricInput, renderChangeTemplate } from "../diagnose/agent-binding.js";
+import { validateSingleAgent } from "./single-agent-validator.js";
+import { runPerTracePipeline } from "./runner.js";
+import { runBatchedRubric } from "./batched-rubric.js";
+import { aggregate } from "./aggregator.js";
+import { sample } from "./sampler.js";
+import { runCrossTraceSynthesizer } from "./cross-trace-synthesizer.js";
+import { renderScanSummaryMarkdown } from "./scan-summary-markdown.js";
+import { ArtifactWriter } from "./artifacts/writer.js";
+import { resolveArtifactsBase } from "./artifacts/paths.js";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const BUILTIN_RULES_DIR = path.join(__dirname, "..", "diagnose", "builtin-rules");
+const SHARED_PROMPT_DIR = path.join(__dirname, "..", "..", "agent-providers", "prompts");
+const SCAN_PROMPT_DIR = path.join(__dirname, "prompts", "builtin");
+async function ensurePromptsLoaded(reg) {
+    await reg.loadBuiltinDir(SHARED_PROMPT_DIR).catch(() => undefined);
+    await reg.loadBuiltinDir(SCAN_PROMPT_DIR).catch(() => undefined);
+}
+async function readReportFromDisk(yamlPath) {
+    const text = await fs.readFile(yamlPath, "utf8");
+    const obj = yaml.load(text);
+    const parsed = ReportSchema.parse(obj);
+    return {
+        schemaVersion: "trace-diagnose-report/v1",
+        trace: {
+            traceId: parsed.trace.trace_id,
+            agentId: parsed.trace.agent_id,
+            tenant: parsed.trace.tenant,
+        },
+        run: {
+            diagnosedAt: parsed.run.diagnosed_at,
+            cliVersion: parsed.run.cli_version,
+            mode: parsed.run.mode,
+            rulesApplied: parsed.run.rules_applied,
+            rulesSkipped: parsed.run.rules_skipped.map((s) => ({
+                ruleId: s.rule_id,
+                reason: s.reason,
+            })),
+            synthesizerMode: parsed.run.synthesizer_mode,
+        },
+        summary: {
+            headline: parsed.summary.headline,
+            primaryRootCause: parsed.summary.primary_root_cause === null
+                ? null
+                : {
+                    findingIds: parsed.summary.primary_root_cause.finding_ids,
+                    description: parsed.summary.primary_root_cause.description,
+                    targetForFix: parsed.summary.primary_root_cause.target_for_fix,
+                },
+            fixPriority: parsed.summary.fix_priority.map((p) => ({
+                findingId: p.finding_id,
+                reason: p.reason,
+            })),
+            crossFindingLinks: parsed.summary.cross_finding_links.map((l) => ({
+                findingIds: l.finding_ids,
+                relation: l.relation,
+            })),
+        },
+        findings: parsed.findings.map((f) => ({
+            ruleId: f.rule_id,
+            judgmentKind: f.judgment_kind,
+            severity: f.severity,
+            symptom: f.symptom,
+            likelyCause: f.likely_cause,
+            evidence: { spans: f.evidence.spans, excerpt: f.evidence.excerpt },
+            suggestedFix: { target: f.suggested_fix.target, change: f.suggested_fix.change },
+            confidence: f.confidence,
+            verifyWith: {
+                suggestedEvalCase: {
+                    queryId: f.verify_with.suggested_eval_case.query_id,
+                    query: f.verify_with.suggested_eval_case.query,
+                    assertions: f.verify_with.suggested_eval_case.assertions,
+                },
+            },
+        })),
+    };
+}
+/**
+ * Orchestrator: walks N conv_ids through the batch pipeline.
+ * Single-agent enforced; --no-llm rejected by CLI (not here).
+ */
+export async function runBatch(opts) {
+    const t_start = Date.now();
+    const registry = defaultRegistry;
+    const promptRegistry = defaultPromptRegistry;
+    await ensurePromptsLoaded(promptRegistry);
+    const writeFormats = opts.format ?? "both";
+    const tracesDir = path.join(opts.out, "traces");
+    // 1. Single-agent validation (also caches first batch of getSpansByConversationId results)
+    const cachedSpans = new Map();
+    const validation = await validateSingleAgent(opts.traces, async (convId) => {
+        const fetched = await getSpansByConversationId({
+            baseUrl: opts.baseUrl,
+            token: opts.token,
+            businessDomain: opts.businessDomain,
+            conversationId: convId,
+        });
+        cachedSpans.set(convId, fetched.spans);
+        return {
+            spans: fetched.spans.map((s) => ({ attributes: (s.attributes ?? {}) })),
+            conversation_id: convId,
+        };
+    });
+    const agentId = validation.agentId;
+    // 2. Artifacts writer
+    const artifactsBase = resolveArtifactsBase({ mode: "batch", out: opts.out });
+    const artifacts = new ArtifactWriter({ base: artifactsBase, enabled: !opts.noArtifacts });
+    // 3. Load rules (gates_on metadata available after this)
+    const rules = await loadRules({
+        builtinDir: opts.noBuiltin ? null : BUILTIN_RULES_DIR,
+        cwdRulesDir: opts.rulesDir,
+        extraRulesDir: null,
+        noBuiltin: opts.noBuiltin,
+    });
+    const allRubricWork = [];
+    const t_stage1 = Date.now();
+    const perTrace = [];
+    let cursor = 0;
+    while (cursor < opts.traces.length) {
+        const chunk = opts.traces.slice(cursor, cursor + opts.maxParallel);
+        const results = await Promise.all(chunk.map(async (convId) => {
+            const r = await runPerTracePipeline({
+                convId,
+                outDir: tracesDir,
+                runDiagnose: async (id, partial) => {
+                    const rawSpans = cachedSpans.get(id) ??
+                        (await getSpansByConversationId({
+                            baseUrl: opts.baseUrl,
+                            token: opts.token,
+                            businessDomain: opts.businessDomain,
+                            conversationId: id,
+                        })).spans;
+                    const firstTraceId = rawSpans.find((s) => s.traceId)?.traceId ?? id;
+                    const tree = assembleTraceTree(firstTraceId, rawSpans);
+                    const hitsMap = await runRules(rules, tree);
+                    const symbolicFindings = symbolicHitsToFindings(rules, hitsMap);
+                    // Determine which symbolic rules fired (for paired-gate rubric filtering)
+                    const firedRuleIds = new Set(symbolicFindings.map((f) => f.ruleId));
+                    for (const rule of rubricRules(rules)) {
+                        const gates = rule.rubric?.gatesOn;
+                        if (gates && gates.length > 0 && !gates.some((g) => firedRuleIds.has(g)))
+                            continue;
+                        const resolvedInputs = {};
+                        for (const inp of rule.rubric.inputs) {
+                            resolvedInputs[inp.kind] = resolveRubricInput(inp, tree);
+                        }
+                        allRubricWork.push({
+                            rule,
+                            trace: {
+                                traceId: tree.traceId,
+                                spans: tree.spans.map((s) => s.spanId),
+                                inputs: resolvedInputs,
+                            },
+                        });
+                    }
+                    const summary = templateSynthesize(symbolicFindings);
+                    const report = assembleReport({
+                        traceId: tree.traceId,
+                        agentId,
+                        tenant: null,
+                        cliVersion: "0.7.4",
+                        rules,
+                        hits: hitsMap,
+                        extraFindings: [],
+                        summary,
+                        mode: "hybrid",
+                        synthesizerMode: "template",
+                    });
+                    await fs.writeFile(partial, yaml.dump(reportToYamlObject(report)), "utf8");
+                    if (writeFormats !== "yaml") {
+                        await fs.writeFile(path.join(path.dirname(partial), `${id}.md`), renderReportMarkdown(report, { conversationId: id, businessDomain: opts.businessDomain }), "utf8");
+                    }
+                    return { traceId: tree.traceId, agentId };
+                },
+            });
+            // Re-read the (possibly just-written, possibly reused) report from disk
+            const report = await readReportFromDisk(path.join(tracesDir, `${convId}.yaml`));
+            return { convId, report, reused: r.reused };
+        }));
+        perTrace.push(...results);
+        cursor += opts.maxParallel;
+    }
+    const t_stage1_end = Date.now();
+    // 5. Stage-2 batched rubric (per rule, chunks of 10)
+    const t_stage2_start = Date.now();
+    let stage2Chunks = 0;
+    // Group rubric work by rule_id
+    const workByRule = new Map();
+    for (const w of allRubricWork) {
+        const arr = workByRule.get(w.rule.id) ?? [];
+        arr.push(w);
+        workByRule.set(w.rule.id, arr);
+    }
+    for (const [ruleId, items] of workByRule.entries()) {
+        const rule = items[0].rule;
+        const traces = items.map((i) => i.trace);
+        stage2Chunks += Math.ceil(traces.length / 10);
+        let provider;
+        try {
+            provider = registry.resolve({ preferred: rule.rubric.agentBinding.provider });
+        }
+        catch {
+            // Provider not registered — skip this rule
+            continue;
+        }
+        if (!provider)
+            continue;
+        const batchedRule = {
+            ruleId,
+            judgeQuestion: rule.rubric.judgeQuestion,
+            outputSchema: rule.rubric.outputZodSchema,
+            outputSchemaRaw: rule.rubric.outputSchemaRaw,
+            promptTemplateRef: "builtin:rubric-judge-batch-v1",
+        };
+        const result = await runBatchedRubric({
+            rule: batchedRule,
+            traces,
+            agentId,
+            provider,
+            promptRegistry,
+            chunkSize: 10,
+            lang: opts.lang,
+            artifacts,
+            timeoutMs: opts.timeoutMs,
+        });
+        // Fold verdicts back into per-trace report objects
+        for (const v of result.verdicts) {
+            const pt = perTrace.find((p) => p.report.trace.traceId === v.traceId);
+            if (!pt)
+                continue;
+            // Build bindings for change_template / assertion_templates rendering.
+            // Bindings shape matches what PR-B single-trace agent-binding.ts passes:
+            // the rubric verdict's `out` object (category, severity, reasoning, first_violating_step_id, evidence_span_ids).
+            const bindings = {
+                category: v.category,
+                reasoning: v.reasoning,
+                severity: v.severity,
+                first_violating_step_id: v.firstViolatingStepId,
+                evidence_span_ids: v.evidenceSpanIds,
+            };
+            pt.report.findings.push({
+                ruleId,
+                judgmentKind: "rubric",
+                severity: v.severity,
+                symptom: rule.symptom,
+                likelyCause: v.category,
+                evidence: { spans: v.evidenceSpanIds, excerpt: v.reasoning },
+                suggestedFix: {
+                    target: rule.suggestedFix.target,
+                    change: renderChangeTemplate(rule.suggestedFix.changeTemplate, bindings),
+                },
+                confidence: "medium",
+                verifyWith: {
+                    suggestedEvalCase: {
+                        queryId: null,
+                        query: null,
+                        assertions: rule.verifyWith.assertionTemplates.map((t) => renderChangeTemplate(t, bindings)),
+                    },
+                },
+            });
+            // Re-write yaml + md with updated findings
+            await fs.writeFile(path.join(tracesDir, `${pt.convId}.yaml`), yaml.dump(reportToYamlObject(pt.report)), "utf8");
+            if (writeFormats !== "yaml") {
+                await fs.writeFile(path.join(tracesDir, `${pt.convId}.md`), renderReportMarkdown(pt.report, { conversationId: pt.convId, businessDomain: opts.businessDomain }), "utf8");
+            }
+        }
+        for (const s of result.skipped) {
+            const pt = perTrace.find((p) => p.report.trace.traceId === s.traceId);
+            if (!pt)
+                continue;
+            pt.report.run.rulesSkipped.push({ ruleId, reason: s.reason });
+            await fs.writeFile(path.join(tracesDir, `${pt.convId}.yaml`), yaml.dump(reportToYamlObject(pt.report)), "utf8");
+        }
+    }
+    const t_stage2_end = Date.now();
+    // 6. Aggregator + sampler
+    const allReports = perTrace.map((p) => p.report);
+    const aggregates = aggregate(allReports);
+    const samplerOutput = sample(allReports);
+    // 7. Stage-4: cross-trace synth
+    const t_stage4_start = Date.now();
+    let synthProvider;
+    try {
+        synthProvider = registry.resolve({});
+    }
+    catch {
+        synthProvider = null;
+    }
+    let synthSummary = null;
+    if (synthProvider) {
+        const result = await runCrossTraceSynthesizer({
+            agentId,
+            aggregates,
+            samples: samplerOutput,
+            nTotal: allReports.length,
+            provider: synthProvider,
+            promptRegistry,
+            lang: opts.lang,
+            artifacts,
+            timeoutMs: opts.timeoutMs,
+        });
+        synthSummary = result.summary;
+    }
+    const t_stage4_end = Date.now();
+    // 8. Assemble + write scan-summary
+    const tracesReused = perTrace.filter((p) => p.reused).length;
+    const scanSummary = {
+        schema_version: "scan-summary/v1",
+        scan: {
+            agent_id: agentId,
+            trace_count: allReports.length,
+            traces_with_findings: allReports.filter((r) => r.findings.length > 0).length,
+            traces_reused: tracesReused,
+            traces_freshly_diagnosed: allReports.length - tracesReused,
+            resumed_from_partial: tracesReused > 0,
+            diagnosed_at: new Date().toISOString(),
+            cli_version: "0.7.4",
+            synthesizer_mode: "agent",
+        },
+        summary: synthSummary,
+        aggregates,
+        per_trace_index: perTrace.map((p) => ({
+            trace_id: p.report.trace.traceId,
+            conversation_id: p.convId,
+            report_path: `traces/${p.convId}.yaml`,
+            finding_count: p.report.findings.length,
+        })),
+    };
+    const scanSummaryYamlPath = path.join(opts.out, "scan-summary.yaml");
+    const scanSummaryMdPath = path.join(opts.out, "scan-summary.md");
+    await fs.writeFile(scanSummaryYamlPath, yaml.dump(scanSummary), "utf8");
+    if (writeFormats !== "yaml") {
+        await fs.writeFile(scanSummaryMdPath, renderScanSummaryMarkdown(scanSummary), "utf8");
+    }
+    // 9. Run metadata artifact
+    const t_total = Date.now() - t_start;
+    await artifacts.writeRunMetadata({
+        cli_args: { traces: opts.traces, out: opts.out, lang: opts.lang ?? "en" },
+        agent_id: agentId,
+        rule_load_summary: {
+            rules_applied: rules.map((r) => r.id),
+            rules_skipped_at_load: [],
+            rules_dir: opts.rulesDir ?? "builtin",
+        },
+        single_agent_validation: {
+            checked_conv_ids: validation.checkedConvIds,
+            agent_id_resolved: agentId,
+        },
+        timing: {
+            stage_1_ms: t_stage1_end - t_stage1,
+            stage_2_ms: t_stage2_end - t_stage2_start,
+            stage_3_ms: 0,
+            stage_4_ms: t_stage4_end - t_stage4_start,
+            total_ms: t_total,
+        },
+        llm_calls: {
+            stage_2_chunks: stage2Chunks,
+            stage_3: 0,
+            stage_4: synthSummary ? 1 : 0,
+            total: stage2Chunks + (synthSummary ? 1 : 0),
+        },
+        cost_estimate_usd: {
+            stage_2: stage2Chunks * 0.005,
+            stage_4: (synthSummary ? 1 : 0) * 0.05,
+            total: stage2Chunks * 0.005 + (synthSummary ? 1 : 0) * 0.05,
+            model_price_table_version: "2026-05",
+        },
+    });
+    return {
+        scanSummaryPath: scanSummaryYamlPath,
+        perTraceReportPaths: perTrace.map((p) => path.join(tracesDir, `${p.convId}.yaml`)),
+        tracesDiagnosed: allReports.length,
+        tracesReused,
+    };
+}

package/dist/trace-ai/scan/prompts/builtin/cross-trace-synthesizer-v1.prompt.md

@@ -0,0 +1,44 @@
+# Cross-Trace Synthesizer
+
+You are summarizing a batch of {{n_total}} agent trace diagnoses for agent
+{{agent_id}}. All traces belong to this single agent. Aggregate statistics
+have been computed deterministically. You see {{sample_count}} representative
+trace summaries selected as samples ({{sample_ratio}} of total). Your job:
+compose a short narrative explaining the dominant failure patterns,
+prioritized rule-level fixes, and cross-rule relationships **specific to
+this agent's program**.
+
+## Aggregated Stats (deterministic)
+
+```yaml
+{{aggregates}}
+```
+
+## Representative Samples ({{sample_count}} of {{n_total}})
+
+{{samples_yaml}}
+
+## Output Schema
+Reply with a single JSON object satisfying this schema. No prose outside the
+JSON.
+
+```json
+{{output_schema}}
+```
+
+{{language_instruction}}
+
+## Composition Rules
+1. `headline` ≤ 160 chars; lead with the dominant rule pattern named in
+   aggregates.rule_frequency. Frame as "this agent does X" since all traces
+   share the same agent.
+2. `primary_root_cause.rule_ids` lists rules that, if fixed in THIS agent's
+   program, would resolve the most traces. Cite aggregate counts; do not
+   invent rule_ids not in aggregates.
+3. `fix_priority` MUST order ALL rules in aggregates.rule_frequency from
+   highest to lowest impact. `affected_trace_count` must match aggregates.
+4. `cross_rule_links` only when ≥ 2 rules fire on the same trace (sampler
+   shows co-fire cases; aggregator surfaces counts indirectly).
+5. Aggregate-grounded only: every claim in `primary_root_cause.description`
+   and `fix_priority[].reason` must be backed by aggregates or samples; the
+   LLM does not invent new rule_ids or trace counts.

package/dist/trace-ai/scan/prompts/builtin/rubric-judge-batch-v1.prompt.md

@@ -0,0 +1,44 @@
+# Trace-Diagnose Rubric Judge (Batched)
+
+You are evaluating one rubric rule across multiple agent traces from the
+same agent (agent_id: {{agent_id}}). Read the rule's judge question, the
+supplied traces, and reply with a single JSON object containing one verdict
+per trace.
+
+## Rule
+- **rule_id**: `{{rule_id}}`
+- **batch_size**: {{batch_size}}
+
+## Judge Question
+{{judge_question}}
+
+## Traces
+Each trace below is identified by `trace_id`. Each trace's inputs follow the
+rule's `inputs` schema (resolved from the trace's spans).
+
+{{traces_yaml}}
+
+## Output Schema
+Reply with a single JSON object. Each entry in `trace_results` corresponds to
+one trace in the supplied batch, in any order. The `trace_id` field MUST echo
+back the trace_id from the input.
+
+```json
+{{output_schema}}
+```
+
+{{language_instruction}}
+
+## Output Rules
+1. ONE entry per input trace_id, no duplicates, no extra entries.
+2. `first_violating_step_id` MUST be a real span id from THAT trace's spans —
+   the diagnose pipeline cross-checks; mis-attributed IDs cause the entry to
+   be discarded with `agent-error:schema_violation`.
+3. `reasoning` should cite span ids in the affected trace. When multiple traces
+   share a pattern, you may cite that in one trace's reasoning ("same retry
+   pattern as trace tr_xxx").
+4. Pick the closest category even if imperfect; do not fall through to `other`
+   unless evidence actively rules out every named category.
+5. If you cannot evaluate a trace (missing spans, malformed input), emit an
+   entry with `category: other`, `reasoning` explaining the gap, `severity: low`,
+   `first_violating_step_id` = any real span_id from that trace.

package/dist/trace-ai/scan/runner.d.ts

@@ -0,0 +1,25 @@
+export interface DiagnoseInvocation {
+    /** Invoked by runPerTracePipeline. MUST write the per-trace yaml to `partialPath`;
+     *  the runner then atomic-renames to `<conv_id>.yaml`. */
+    (convId: string, partialPath: string): Promise<{
+        traceId: string;
+        agentId: string | null;
+    }>;
+}
+export interface RunPerTracePipelineOpts {
+    convId: string;
+    outDir: string;
+    runDiagnose: DiagnoseInvocation;
+}
+export interface RunPerTracePipelineResult {
+    reused: boolean;
+    traceId?: string;
+    agentId?: string | null;
+}
+/**
+ * Process one conv_id: skip if the per-trace yaml already exists and parses;
+ * otherwise invoke runDiagnose (which writes to a .partial path), then
+ * atomic-rename to the final path on success. Corrupt existing yaml is
+ * logged + overwritten.
+ */
+export declare function runPerTracePipeline(opts: RunPerTracePipelineOpts): Promise<RunPerTracePipelineResult>;

package/dist/trace-ai/scan/runner.js

@@ -0,0 +1,42 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import yaml from "js-yaml";
+import { ReportSchema } from "../diagnose/schemas.js";
+async function safeReadYaml(filePath) {
+    try {
+        const text = await fs.readFile(filePath, "utf8");
+        return yaml.load(text);
+    }
+    catch {
+        return null;
+    }
+}
+async function isValidExistingReport(filePath) {
+    const obj = await safeReadYaml(filePath);
+    if (obj === null)
+        return false;
+    return ReportSchema.safeParse(obj).success;
+}
+/**
+ * Process one conv_id: skip if the per-trace yaml already exists and parses;
+ * otherwise invoke runDiagnose (which writes to a .partial path), then
+ * atomic-rename to the final path on success. Corrupt existing yaml is
+ * logged + overwritten.
+ */
+export async function runPerTracePipeline(opts) {
+    const finalPath = path.join(opts.outDir, `${opts.convId}.yaml`);
+    const partialPath = `${finalPath}.partial`;
+    const existed = await fs.stat(finalPath).then(() => true).catch(() => false);
+    if (existed) {
+        if (await isValidExistingReport(finalPath)) {
+            return { reused: true };
+        }
+        process.stderr.write(`warning: existing ${finalPath} is corrupt or schema-incompatible; re-diagnosing\n`);
+        await fs.rm(finalPath, { force: true });
+    }
+    await fs.mkdir(opts.outDir, { recursive: true });
+    const result = await opts.runDiagnose(opts.convId, partialPath);
+    // Atomic rename .partial → final
+    await fs.rename(partialPath, finalPath);
+    return { reused: false, traceId: result.traceId, agentId: result.agentId };
+}

package/dist/trace-ai/scan/sampler.d.ts

@@ -0,0 +1,18 @@
+import type { Report } from "../diagnose/types.js";
+export interface Sample {
+    trace_id: string;
+    conversation_id: string | null;
+    headline: string;
+    rule_ids: string[];
+    selected_as: string;
+}
+export interface SamplerOutput {
+    samples: Sample[];
+}
+/**
+ * Deterministic K=5 sampler: top-1 by severity per dominant rule (count ≥
+ * max(3, 5% of N)) + up to one outlier (rubric self-labeled FP, e.g.
+ * likely_cause='other' or severity='low'). Sorted by selected_as / trace_id
+ * for stability.
+ */
+export declare function sample(reports: Report[]): SamplerOutput;

package/dist/trace-ai/scan/sampler.js

@@ -0,0 +1,81 @@
+const SEVERITY_RANK = { high: 3, medium: 2, low: 1 };
+const K_MAX = 5;
+function dominantThreshold(N) {
+    return Math.max(3, Math.ceil(0.05 * N));
+}
+function pickTopBySeverityForRule(reports, ruleId) {
+    let best = null;
+    for (const r of reports) {
+        for (const f of r.findings) {
+            if (f.ruleId !== ruleId)
+                continue;
+            const rank = SEVERITY_RANK[f.severity] ?? 0;
+            if (!best || rank > best.rank || (rank === best.rank && r.trace.traceId < best.report.trace.traceId)) {
+                best = { report: r, rank };
+            }
+        }
+    }
+    return best?.report ?? null;
+}
+function isOutlierFinding(f) {
+    return f.judgmentKind === "rubric" && (f.likelyCause === "other" || f.severity === "low");
+}
+function toSample(r, selectedAs) {
+    const rule_ids = [...new Set(r.findings.map((f) => f.ruleId))].sort();
+    return {
+        trace_id: r.trace.traceId,
+        conversation_id: null,
+        headline: r.summary.headline,
+        rule_ids,
+        selected_as: selectedAs,
+    };
+}
+/**
+ * Deterministic K=5 sampler: top-1 by severity per dominant rule (count ≥
+ * max(3, 5% of N)) + up to one outlier (rubric self-labeled FP, e.g.
+ * likely_cause='other' or severity='low'). Sorted by selected_as / trace_id
+ * for stability.
+ */
+export function sample(reports) {
+    const N = reports.length;
+    if (N === 0)
+        return { samples: [] };
+    // Count rule frequency, identify dominant.
+    const counts = new Map();
+    for (const r of reports) {
+        for (const f of r.findings) {
+            counts.set(f.ruleId, (counts.get(f.ruleId) ?? 0) + 1);
+        }
+    }
+    const threshold = dominantThreshold(N);
+    const dominantRules = [...counts.entries()]
+        .filter(([, c]) => c >= threshold)
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .map(([id]) => id);
+    const picked = [];
+    const usedTraceIds = new Set();
+    // Top-1 by severity per dominant rule.
+    for (const ruleId of dominantRules) {
+        if (picked.length >= K_MAX)
+            break;
+        const r = pickTopBySeverityForRule(reports, ruleId);
+        if (r && !usedTraceIds.has(r.trace.traceId)) {
+            picked.push(toSample(r, `top-1 high-severity for ${ruleId}`));
+            usedTraceIds.add(r.trace.traceId);
+        }
+    }
+    // One outlier (rubric self-labeled FP) if there's slack.
+    if (picked.length < K_MAX) {
+        for (const r of reports) {
+            if (usedTraceIds.has(r.trace.traceId))
+                continue;
+            const fpFinding = r.findings.find(isOutlierFinding);
+            if (fpFinding) {
+                picked.push(toSample(r, `outlier (rubric self-labeled FP for ${fpFinding.ruleId})`));
+                usedTraceIds.add(r.trace.traceId);
+                break;
+            }
+        }
+    }
+    return { samples: picked.slice(0, K_MAX) };
+}

package/dist/trace-ai/scan/scan-summary-markdown.d.ts

@@ -0,0 +1,2 @@
+import type { ScanSummary } from "./scan-summary-schema.js";
+export declare function renderScanSummaryMarkdown(s: ScanSummary): string;