@kweaver-ai/kweaver-sdk 0.8.1 → 0.8.3

package/dist/trace-ai/diagnose/output-schema-converter.js

@@ -0,0 +1,81 @@
+/**
+ * Convert a rubric YAML's `output_schema` (a JSON-Schema-ish blob) into a
+ * zod schema the agent provider validates LLM responses against.
+ *
+ * We don't pull in a full JSON-Schema-to-Zod converter — rubric YAMLs use
+ * a deliberately narrow subset: `type: object` with `required[]` and
+ * `properties{type, enum, items}`. Anything richer is rejected at load
+ * time so authors don't accidentally rely on full JSON Schema semantics
+ * we haven't implemented.
+ *
+ * Supported per-property `type` values: `string`, `number`, `boolean`,
+ * `array` (homogeneous items by `items.type`), `object` (recursive).
+ * `enum` (string-only) is supported on `string` properties.
+ *
+ * Unsupported / rejected at conversion time: `type: integer` (use number),
+ * `anyOf`/`oneOf`, `$ref`, `additionalProperties: false`, `format`.
+ */
+import { z } from "zod";
+export class OutputSchemaConversionError extends Error {
+    path;
+    constructor(message, path) {
+        super(`${message} (at ${path})`);
+        this.path = path;
+        this.name = "OutputSchemaConversionError";
+    }
+}
+function convertProp(spec, path) {
+    const t = spec.type;
+    if (typeof t !== "string") {
+        throw new OutputSchemaConversionError(`property is missing 'type' string`, path);
+    }
+    switch (t) {
+        case "string": {
+            if (Array.isArray(spec.enum)) {
+                if (spec.enum.length === 0) {
+                    throw new OutputSchemaConversionError(`empty enum`, path);
+                }
+                for (const v of spec.enum) {
+                    if (typeof v !== "string") {
+                        throw new OutputSchemaConversionError(`enum supports string values only`, path);
+                    }
+                }
+                return z.enum(spec.enum);
+            }
+            return z.string();
+        }
+        case "number": return z.number();
+        case "boolean": return z.boolean();
+        case "array": {
+            const items = spec.items;
+            if (!items) {
+                throw new OutputSchemaConversionError(`array property requires 'items'`, path);
+            }
+            return z.array(convertProp(items, `${path}.items`));
+        }
+        case "object": {
+            const subProps = spec.properties ?? {};
+            const subRequired = spec.required ?? [];
+            return buildObject(subProps, subRequired, path);
+        }
+        default:
+            throw new OutputSchemaConversionError(`unsupported type '${t}'`, path);
+    }
+}
+function buildObject(properties, required, path) {
+    const shape = {};
+    const requiredSet = new Set(required);
+    for (const [key, spec] of Object.entries(properties)) {
+        const sub = convertProp(spec, `${path}.${key}`);
+        shape[key] = requiredSet.has(key) ? sub : sub.optional();
+    }
+    for (const req of required) {
+        if (!(req in properties)) {
+            throw new OutputSchemaConversionError(`required key '${req}' is not present in properties`, path);
+        }
+    }
+    return z.object(shape);
+}
+export function rubricOutputToZod(rubric) {
+    return buildObject(rubric.output_schema.properties, rubric.output_schema.required, "output_schema");
+}

package/dist/trace-ai/diagnose/query-extractor.d.ts

@@ -0,0 +1,14 @@
+import type { TraceTree } from "./types.js";
+/**
+ * Extract the most recent user-role message from a trace's input.messages.
+ *
+ * Scans spans for `gen_ai.input.messages` (a JSON-stringified array of
+ * {role, content}), checking two locations in order:
+ *   1. span.events[*].attributes  — emitted by dolphin otel_listener as the
+ *      "gen_ai.client.inference.operation.details" event (primary path)
+ *   2. span.attributes             — fallback for runtimes that promote the
+ *      field directly onto the span
+ *
+ * Returns the last `role === "user"` message content, or null if not found.
+ */
+export declare function extractUserQueryFromTrace(tree: TraceTree): string | null;

package/dist/trace-ai/diagnose/query-extractor.js

@@ -0,0 +1,45 @@
+/**
+ * Extract the most recent user-role message from a trace's input.messages.
+ *
+ * Scans spans for `gen_ai.input.messages` (a JSON-stringified array of
+ * {role, content}), checking two locations in order:
+ *   1. span.events[*].attributes  — emitted by dolphin otel_listener as the
+ *      "gen_ai.client.inference.operation.details" event (primary path)
+ *   2. span.attributes             — fallback for runtimes that promote the
+ *      field directly onto the span
+ *
+ * Returns the last `role === "user"` message content, or null if not found.
+ */
+export function extractUserQueryFromTrace(tree) {
+    for (const span of tree.spans) {
+        const candidates = [];
+        // Primary: event attributes (dolphin otel_listener path)
+        for (const ev of span.events ?? []) {
+            const v = ev.attributes?.["gen_ai.input.messages"];
+            if (typeof v === "string")
+                candidates.push(v);
+        }
+        // Fallback: span attributes
+        const spanAttr = span.attributes?.["gen_ai.input.messages"];
+        if (typeof spanAttr === "string")
+            candidates.push(spanAttr);
+        for (const raw of candidates) {
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                continue;
+            }
+            if (!Array.isArray(parsed))
+                continue;
+            for (let i = parsed.length - 1; i >= 0; i--) {
+                const m = parsed[i];
+                if (m?.role === "user" && typeof m.content === "string" && m.content.length > 0) {
+                    return m.content;
+                }
+            }
+        }
+    }
+    return null;
+}

package/dist/trace-ai/diagnose/report-assembler.d.ts

@@ -0,0 +1,31 @@
+import type { Finding, Hit, Report, Rule, Summary } from "./types.js";
+export interface AssembleReportOpts {
+    traceId: string;
+    agentId: string | null;
+    tenant: string | null;
+    cliVersion: string;
+    rules: Rule[];
+    hits: Map<string, Hit[]>;
+    /** Additional pre-built findings (rubric judgments come from agent-binding). */
+    extraFindings?: Finding[];
+    summary: Summary;
+    /** Run mode. Default `symbolic-only` for backward compat. */
+    mode?: 'symbolic-only' | 'rubric-only' | 'hybrid';
+    /** Rubric rules skipped due to --no-llm / unavailable provider / etc. */
+    rulesSkipped?: {
+        ruleId: string;
+        reason: string;
+    }[];
+    /** Stage-3 synthesizer that produced `summary`. */
+    synthesizerMode?: 'template' | 'agent';
+    /** User query extracted from trace input.messages (2026-05-13). */
+    userQuery?: string | null;
+    /** Conversation/query ID for suggested_eval_case correlation (2026-05-13). */
+    queryId?: string | null;
+}
+/** Build symbolic-pillar findings from rule+hit pairs.
+ *  Exported so callers (e.g. tests, index.ts) can compose findings from
+ *  multiple sources before handing them to a custom summary path. */
+export declare function symbolicHitsToFindings(rules: Rule[], hits: Map<string, Hit[]>, userQuery?: string | null, queryId?: string | null): Finding[];
+export declare function assembleReport(opts: AssembleReportOpts): Report;
+export declare function reportToYamlObject(r: Report): unknown;

package/dist/{trace-core → trace-ai}/diagnose/report-assembler.js

@@ -4,17 +4,22 @@ function renderTemplate(tpl, bindings) {
         return v === undefined ? `{{${key}}}` : String(v);
     });
 }
-export function assembleReport(opts) {
+/** Build symbolic-pillar findings from rule+hit pairs.
+ *  Exported so callers (e.g. tests, index.ts) can compose findings from
+ *  multiple sources before handing them to a custom summary path. */
+export function symbolicHitsToFindings(rules, hits, userQuery = null, queryId = null) {
     const findings = [];
-    for (const rule of opts.rules) {
-        const ruleHits = opts.hits.get(rule.id) ?? [];
+    for (const rule of rules) {
+        if (rule.predicateRef === null)
+            continue;
+        const ruleHits = hits.get(rule.id) ?? [];
         for (const hit of ruleHits) {
             findings.push({
                 ruleId: rule.id,
                 judgmentKind: "symbolic",
                 severity: rule.severity,
                 symptom: rule.symptom,
-                likelyCause: rule.symptom, // PR-A: no LLM, so we mirror symptom; PR-B agent overrides this
+                likelyCause: rule.symptom, // symbolic: no LLM, so mirror symptom; rubric agent overrides
                 evidence: { spans: hit.evidenceSpans, excerpt: hit.excerpt },
                 suggestedFix: {
                     target: rule.suggestedFix.target,
@@ -23,24 +28,29 @@ export function assembleReport(opts) {
                 confidence: "low",
                 verifyWith: {
                     suggestedEvalCase: {
-                        queryId: null, // PR-A: no query extraction yet (deferred per spec)
-                        query: null,
+                        queryId,
+                        query: userQuery,
                         assertions: rule.verifyWith.assertionTemplates.map((t) => renderTemplate(t, hit.bindings)),
                     },
                 },
             });
         }
     }
+    return findings;
+}
+export function assembleReport(opts) {
+    const symbolicFindings = symbolicHitsToFindings(opts.rules, opts.hits, opts.userQuery ?? null, opts.queryId ?? null);
+    const findings = [...symbolicFindings, ...(opts.extraFindings ?? [])];
     return {
         schemaVersion: "trace-diagnose-report/v1",
         trace: { traceId: opts.traceId, agentId: opts.agentId, tenant: opts.tenant },
         run: {
             diagnosedAt: new Date().toISOString(),
             cliVersion: opts.cliVersion,
-            mode: "symbolic-only",
+            mode: opts.mode ?? "symbolic-only",
             rulesApplied: opts.rules.map((r) => r.id),
-            rulesSkipped: [],
-            synthesizerMode: "template",
+            rulesSkipped: opts.rulesSkipped ?? [],
+            synthesizerMode: opts.synthesizerMode ?? "template",
         },
         summary: opts.summary,
         findings,

package/dist/trace-ai/diagnose/report-markdown.d.ts

@@ -0,0 +1,18 @@
+import type { Report } from "./types.js";
+/**
+ * Optional context the md renderer uses to build runnable verification
+ * commands. None of these are in the yaml schema (which stays v1-locked and
+ * CLI-agnostic) — they live only in the markdown view so users who paste the
+ * md into a ticket / PR have copy-pasteable shell commands without needing to
+ * remember the trace's conversation context.
+ */
+export interface MarkdownRenderOpts {
+    /** The conversation_id passed to `kweaver trace diagnose`. Used to render
+     *  the "re-run diagnosis" command. When undefined, that command is rendered
+     *  with a `<conversation_id>` placeholder. */
+    conversationId?: string;
+    /** Business domain (`-bd` flag). When undefined, commands omit the flag and
+     *  inherit kweaver's default (`bd_public`). */
+    businessDomain?: string;
+}
+export declare function renderReportMarkdown(r: Report, opts?: MarkdownRenderOpts): string;

package/dist/trace-ai/diagnose/report-markdown.js

@@ -0,0 +1,192 @@
+// Human-readable markdown view of a trace-diagnose report.
+//
+// The YAML report (see `report-assembler.reportToYamlObject`) is the source of
+// truth; this file is a pure projection. Persisted alongside the yaml when
+// `--format=both`. Markdown was chosen over a stdout pretty-print because
+// reports are commonly pasted into tickets / PRs / wikis where ephemeral
+// terminal output would be lost.
+//
+// Structure (inverted-pyramid: most actionable first):
+//   1. Title + one-line meta
+//   2. Summary  — headline (+ primary root cause if any)
+//   3. Fix priority table   (omitted when empty)
+//   4. Findings — one section per finding, excerpt as a blockquote
+//   5. Cross-finding links  (omitted when empty)
+//   6. How to verify — kweaver CLI commands the reader can paste to
+//      independently re-confirm the report's claims against the live trace.
+//      Sourced from Report fields + the caller-supplied conversation_id /
+//      business_domain (which are not part of the yaml schema — yaml stays
+//      CLI-agnostic, markdown is the CLI-aware view).
+//   7. Run    — mode / synthesizer / rules applied & skipped (reference)
+export function renderReportMarkdown(r, opts = {}) {
+    const lines = [];
+    const shortId = r.trace.traceId.length > 16 ? `${r.trace.traceId.slice(0, 16)}…` : r.trace.traceId;
+    lines.push(`# Trace Diagnose Report — \`${shortId}\``);
+    lines.push("");
+    lines.push(`> trace \`${r.trace.traceId}\` · agent \`${r.trace.agentId ?? "—"}\` · tenant \`${r.trace.tenant ?? "—"}\` · diagnosed ${r.run.diagnosedAt} · cli \`${r.run.cliVersion}\``);
+    lines.push("");
+    // ── Summary ──────────────────────────────────────────────────────────────
+    lines.push("## Summary");
+    lines.push("");
+    lines.push(`**${r.summary.headline}**`);
+    lines.push("");
+    if (r.summary.primaryRootCause !== null) {
+        const rc = r.summary.primaryRootCause;
+        const fids = rc.findingIds.map((i) => `#${i}`).join(", ");
+        lines.push(`Primary root cause spans findings ${fids} — target for fix: \`${rc.targetForFix}\`.`);
+        lines.push("");
+        lines.push(`> ${escapeBlockquote(rc.description)}`);
+        lines.push("");
+    }
+    // ── Fix priority ─────────────────────────────────────────────────────────
+    if (r.summary.fixPriority.length > 0) {
+        lines.push("## Fix priority");
+        lines.push("");
+        lines.push("| Order | Finding | Rule | Reason |");
+        lines.push("|---|---|---|---|");
+        r.summary.fixPriority.forEach((p, idx) => {
+            const f = r.findings[p.findingId];
+            const ruleCell = f ? `\`${f.ruleId}\` [${f.severity}/${f.judgmentKind}]` : `(unknown #${p.findingId})`;
+            lines.push(`| ${idx + 1} | #${p.findingId} | ${ruleCell} | ${escapeTableCell(p.reason)} |`);
+        });
+        lines.push("");
+    }
+    // ── Findings ─────────────────────────────────────────────────────────────
+    lines.push(`## Findings (${r.findings.length})`);
+    lines.push("");
+    if (r.findings.length === 0) {
+        lines.push(`_No findings were emitted by any of the ${r.run.rulesApplied.length} applied rules._`);
+        lines.push("");
+    }
+    else {
+        r.findings.forEach((f, idx) => renderFinding(lines, f, idx));
+    }
+    // ── Cross-finding links ──────────────────────────────────────────────────
+    if (r.summary.crossFindingLinks.length > 0) {
+        lines.push("## Cross-finding links");
+        lines.push("");
+        for (const link of r.summary.crossFindingLinks) {
+            const ids = link.findingIds.map((i) => `#${i}`).join(" ↔ ");
+            lines.push(`- ${ids} — ${link.relation}`);
+        }
+        lines.push("");
+    }
+    // ── How to verify ────────────────────────────────────────────────────────
+    renderVerificationSection(lines, r, opts);
+    // ── Run reference ────────────────────────────────────────────────────────
+    lines.push("## Run");
+    lines.push("");
+    lines.push(`- **mode**: \`${r.run.mode}\` · **synthesizer**: \`${r.run.synthesizerMode}\` · **rules**: ${r.run.rulesApplied.length} applied, ${r.run.rulesSkipped.length} skipped`);
+    lines.push(`- **applied**: ${r.run.rulesApplied.map((id) => `\`${id}\``).join(", ")}`);
+    if (r.run.rulesSkipped.length > 0) {
+        lines.push("- **skipped**:");
+        for (const s of r.run.rulesSkipped) {
+            lines.push(`    - \`${s.ruleId}\` — ${s.reason}`);
+        }
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+function renderFinding(lines, f, idx) {
+    lines.push(`### #${idx} \`${f.ruleId}\` — [${f.severity}/${f.judgmentKind}]`);
+    lines.push("");
+    if (f.evidence.excerpt.trim().length > 0) {
+        for (const ln of f.evidence.excerpt.trim().split(/\r?\n/)) {
+            lines.push(`> ${ln}`);
+        }
+        lines.push("");
+    }
+    const meta = [];
+    meta.push(`- **symptom**: ${f.symptom}`);
+    meta.push(`- **likely cause**: ${f.likelyCause}`);
+    meta.push(`- **confidence**: ${f.confidence}`);
+    if (f.evidence.spans.length > 0) {
+        meta.push(`- **evidence spans**: ${f.evidence.spans.map((s) => `\`${s}\``).join(", ")}`);
+    }
+    meta.push(`- **suggested fix** → \`${f.suggestedFix.target}\`: ${f.suggestedFix.change}`);
+    if (f.verifyWith.suggestedEvalCase.assertions.length > 0) {
+        meta.push(`- **verify with**:`);
+        for (const a of f.verifyWith.suggestedEvalCase.assertions) {
+            meta.push(`    - ${a}`);
+        }
+    }
+    for (const m of meta)
+        lines.push(m);
+    lines.push("");
+}
+/**
+ * Render kweaver CLI verification commands so a reader can independently
+ * re-confirm the diagnosis against the live trace. Sections:
+ *   1. Re-fetch the raw spans (proves the trace data the report was built
+ *      from still matches what observability returns)
+ *   2. Re-diagnose with --no-llm (reproducibility check — same symbolic
+ *      findings should fire deterministically; rules out claude-side flake)
+ *   3. Inspect suspect spans per finding (only when findings.length > 0)
+ *   4. Check recurrence across the agent's other conversations
+ *
+ * The commands intentionally omit auth flags (--token / --base-url) — the
+ * reader is expected to have `kweaver auth` already configured or to be
+ * working in the same shell session that produced this report.
+ */
+function renderVerificationSection(lines, r, opts) {
+    const bdFlag = opts.businessDomain ? ` -bd ${opts.businessDomain}` : "";
+    const convId = opts.conversationId ?? "<conversation_id>";
+    lines.push("## How to verify");
+    lines.push("");
+    lines.push("Paste these into a shell to independently re-confirm the report against the live trace.");
+    lines.push("");
+    // 1. Re-fetch raw spans for the trace.
+    lines.push("### 1. Re-fetch the raw trace");
+    lines.push("");
+    lines.push("```bash");
+    lines.push(`kweaver call -X POST '/api/agent-observability/v1/traces/_search' \\`);
+    lines.push(`  -d '{"query":{"term":{"traceId":"${r.trace.traceId}"}}}'${bdFlag} \\`);
+    lines.push(`  | jq '.hits.hits[]._source | {spanId, name, kind: .attributes."gen_ai.operation.name", status: .status.code}'`);
+    lines.push("```");
+    lines.push("");
+    // 2. Re-run diagnosis deterministically.
+    lines.push("### 2. Re-run diagnosis (reproducibility check)");
+    lines.push("");
+    lines.push("```bash");
+    lines.push(`kweaver trace diagnose ${convId} --no-llm --out /tmp/verify.yaml${bdFlag}`);
+    lines.push("# then diff against this report's yaml — symbolic findings should match exactly");
+    lines.push("```");
+    lines.push("");
+    // 3. Inspect suspect spans per finding.
+    if (r.findings.length > 0) {
+        lines.push("### 3. Inspect the suspect spans");
+        lines.push("");
+        r.findings.forEach((f, idx) => {
+            if (f.evidence.spans.length === 0)
+                return;
+            const spanList = f.evidence.spans.map((s) => `"${s}"`).join(", ");
+            lines.push(`Finding #${idx} (\`${f.ruleId}\`):`);
+            lines.push("");
+            lines.push("```bash");
+            lines.push(`kweaver call -X POST '/api/agent-observability/v1/traces/_search' \\`);
+            lines.push(`  -d '{"query":{"terms":{"spanId":[${spanList}]}}}'${bdFlag} \\`);
+            lines.push(`  | jq '.hits.hits[]._source.attributes'`);
+            lines.push("```");
+            lines.push("");
+        });
+    }
+    // 4. Recurrence check.
+    if (r.trace.agentId !== null) {
+        const sectionNum = r.findings.length > 0 ? 4 : 3;
+        lines.push(`### ${sectionNum}. Check whether this pattern recurs for the agent`);
+        lines.push("");
+        lines.push("```bash");
+        lines.push(`kweaver agent sessions ${r.trace.agentId} --limit 20${bdFlag}`);
+        lines.push("# sample a few conversation_ids from the list, re-diagnose each, count rule hits");
+        lines.push("```");
+        lines.push("");
+    }
+}
+function escapeTableCell(s) {
+    // Pipes and newlines break GFM tables; collapse newlines and escape `|`.
+    return s.replace(/\r?\n/g, " ").replace(/\|/g, "\\|");
+}
+function escapeBlockquote(s) {
+    // Blockquote-safe; just collapse newlines so the whole description sits in one line.
+    return s.replace(/\r?\n+/g, " ").trim();
+}

package/dist/{trace-core → trace-ai}/diagnose/rule-loader.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import yaml from "js-yaml";
 import { RuleSchema } from "./schemas.js";
 import { resolvePredicate } from "./predicate-registry.js";
+import { rubricOutputToZod, OutputSchemaConversionError } from "./output-schema-converter.js";
 export class RuleLoadError extends Error {
     constructor(message) {
         super(message);
@@ -37,15 +38,47 @@ async function parseOne(filePath) {
         throw new RuleLoadError(`schema validation failed for ${filePath}: ${result.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ')}`);
     }
     const r = result.data;
-    if (!r.predicate) {
-        throw new RuleLoadError(`PR-A only supports symbolic rules; ${filePath} has no predicate`);
+    let predicateRef = null;
+    let rubric = null;
+    if (r.predicate) {
+        // resolvePredicate throws PredicateNotFoundError; rewrap for uniform caller experience.
+        try {
+            resolvePredicate(r.predicate);
+        }
+        catch (e) {
+            throw new RuleLoadError(`${filePath}: ${e.message}`);
+        }
+        predicateRef = r.predicate;
     }
-    // resolvePredicate throws PredicateNotFoundError; rewrap for uniform caller experience.
-    try {
-        resolvePredicate(r.predicate);
+    else if (r.rubric) {
+        // Compile output_schema → zod at load time so authors see schema errors
+        // up-front via `trace diagnose rules validate <path>`, not at LLM call time.
+        let outputZodSchema;
+        try {
+            outputZodSchema = rubricOutputToZod(r.rubric);
+        }
+        catch (e) {
+            if (e instanceof OutputSchemaConversionError) {
+                throw new RuleLoadError(`${filePath}: rubric.output_schema: ${e.message}`);
+            }
+            throw e;
+        }
+        rubric = {
+            judgeQuestion: r.rubric.judge_question,
+            inputs: r.rubric.inputs.map((i) => ({ kind: i.kind, source: i.source })),
+            outputSchemaRaw: r.rubric.output_schema,
+            outputZodSchema,
+            agentBinding: {
+                provider: r.rubric.agent_binding.provider,
+                promptTemplateRef: r.rubric.agent_binding.prompt_template_ref,
+            },
+            gatesOn: r.rubric.gates_on,
+        };
     }
-    catch (e) {
-        throw new RuleLoadError(`${filePath}: ${e.message}`);
+    else {
+        // RuleSchema's XOR refinement should have already caught this; keep an
+        // explicit branch so the failure mode is obvious if schemas drift.
+        throw new RuleLoadError(`${filePath}: rule has neither predicate nor rubric`);
     }
     return {
         schemaVersion: r.schema_version,
@@ -55,7 +88,8 @@ async function parseOne(filePath) {
         taxonomy: { signalsAxis: r.taxonomy.signals_axis, msClass: r.taxonomy.ms_class },
         suggestedFix: { target: r.suggested_fix.target, changeTemplate: r.suggested_fix.change_template },
         verifyWith: { assertionTemplates: r.verify_with.assertion_templates },
-        predicateRef: r.predicate,
+        predicateRef,
+        rubric,
         params: r.params,
         sourcePath: filePath,
     };

package/dist/{trace-core → trace-ai}/diagnose/schemas.d.ts

@@ -1,4 +1,38 @@
 import { z } from "zod";
+/**
+ * Rubric input source descriptor. The supported source prefixes are
+ * resolved by `diagnose/agent-binding.ts` against the in-memory TraceTree:
+ *
+ *   - `extract_from_root_attr:<dot.path>`   → root span attribute by name
+ *   - `filter_by_kind:[kind1,kind2,...]`    → ordered span subset by kind
+ *   - `literal:<json>`                      → constant blob (debug / fixtures)
+ *
+ * Authors describe **which slice of the trace** the agent needs as context;
+ * the binding does the actual extraction so rule YAML stays declarative.
+ */
+declare const RubricInputSchema: z.ZodObject<{
+    kind: z.ZodString;
+    source: z.ZodString;
+}, z.core.$strip>;
+declare const RubricSchema: z.ZodObject<{
+    judge_question: z.ZodString;
+    inputs: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        kind: z.ZodString;
+        source: z.ZodString;
+    }, z.core.$strip>>>;
+    output_schema: z.ZodObject<{
+        type: z.ZodLiteral<"object">;
+        required: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        properties: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>;
+    agent_binding: z.ZodObject<{
+        provider: z.ZodString;
+        prompt_template_ref: z.ZodString;
+    }, z.core.$strip>;
+    gates_on: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type RubricYaml = z.infer<typeof RubricSchema>;
+export type RubricInputYaml = z.infer<typeof RubricInputSchema>;
 export declare const RuleSchema: z.ZodObject<{
     schema_version: z.ZodLiteral<"diagnosis-rule/v1">;
     id: z.ZodString;
@@ -31,7 +65,23 @@ export declare const RuleSchema: z.ZodObject<{
         assertion_templates: z.ZodDefault<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>;
     predicate: z.ZodOptional<z.ZodString>;
-    rubric: z.ZodOptional<z.ZodUnknown>;
+    rubric: z.ZodOptional<z.ZodObject<{
+        judge_question: z.ZodString;
+        inputs: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            kind: z.ZodString;
+            source: z.ZodString;
+        }, z.core.$strip>>>;
+        output_schema: z.ZodObject<{
+            type: z.ZodLiteral<"object">;
+            required: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            properties: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strip>;
+        agent_binding: z.ZodObject<{
+            provider: z.ZodString;
+            prompt_template_ref: z.ZodString;
+        }, z.core.$strip>;
+        gates_on: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
     params: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>;
 export type RuleYaml = z.infer<typeof RuleSchema>;
@@ -80,6 +130,7 @@ export declare const ReportSchema: z.ZodObject<{
         rule_id: z.ZodString;
         judgment_kind: z.ZodEnum<{
             symbolic: "symbolic";
+            rubric: "rubric";
         }>;
         severity: z.ZodEnum<{
             low: "low";
@@ -96,7 +147,11 @@ export declare const ReportSchema: z.ZodObject<{
             target: z.ZodString;
             change: z.ZodString;
         }, z.core.$strip>;
-        confidence: z.ZodLiteral<"low">;
+        confidence: z.ZodEnum<{
+            low: "low";
+            medium: "medium";
+            high: "high";
+        }>;
         verify_with: z.ZodObject<{
             suggested_eval_case: z.ZodObject<{
                 query_id: z.ZodNullable<z.ZodString>;
@@ -107,3 +162,23 @@ export declare const ReportSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type ReportYaml = z.infer<typeof ReportSchema>;
+/** The Summary section in isolation — exported so the agent synthesizer
+ *  can validate its LLM output against the same shape the report uses. */
+export declare const SummaryOutputSchema: z.ZodObject<{
+    headline: z.ZodString;
+    primary_root_cause: z.ZodNullable<z.ZodObject<{
+        finding_ids: z.ZodArray<z.ZodNumber>;
+        description: z.ZodString;
+        target_for_fix: z.ZodString;
+    }, z.core.$strip>>;
+    fix_priority: z.ZodArray<z.ZodObject<{
+        finding_id: z.ZodNumber;
+        reason: z.ZodString;
+    }, z.core.$strip>>;
+    cross_finding_links: z.ZodArray<z.ZodObject<{
+        finding_ids: z.ZodArray<z.ZodNumber>;
+        relation: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SummaryOutput = z.infer<typeof SummaryOutputSchema>;
+export {};