onto-mcp 0.3.0

package/dist/core-runtime/review/review-record-validation.js

@@ -0,0 +1,251 @@
+import { readYamlDocument, } from "./review-artifact-utils.js";
+import { REVIEW_SEVERITY_ORDER, isReviewFindingSeverity, isMaterialSeverity, } from "./review-result-classification.js";
+const REVIEW_RECORD_STATUS_VALUES = new Set([
+    "completed",
+    "completed_with_degradation",
+    "halted_partial",
+]);
+const SHARED_PHENOMENON_RELATION_VALUES = new Set([
+    "corroboration",
+    "disagreement",
+    "partial overlap",
+    "dedup",
+]);
+const ACTION_CANDIDATE_VALUES = new Set([
+    "fix_now",
+    "fix_before_release",
+    "accept_risk",
+    "follow_up",
+    "out_of_scope",
+    "needs_evidence",
+    "continue_review",
+    "retry_execution",
+]);
+function requireRecord(value, label) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${label} must be a YAML mapping.`);
+    }
+    return value;
+}
+function requireString(value, label) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`${label} must be a non-empty string.`);
+    }
+    return value;
+}
+function requireNullableString(value, label) {
+    if (value === null)
+        return null;
+    return requireString(value, label);
+}
+function requireNumber(value, label) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`${label} must be a finite number.`);
+    }
+    return value;
+}
+function requireInteger(value, label) {
+    const number = requireNumber(value, label);
+    if (!Number.isInteger(number)) {
+        throw new Error(`${label} must be an integer.`);
+    }
+    return number;
+}
+function requireArray(value, label) {
+    if (!Array.isArray(value)) {
+        throw new Error(`${label} must be a YAML list.`);
+    }
+    return value;
+}
+function requireStringArray(value, label) {
+    return requireArray(value, label).map((item, index) => requireString(item, `${label}[${index}]`));
+}
+function requireAllowed(value, allowed, label) {
+    const text = requireString(value, label);
+    if (!allowed.has(text)) {
+        throw new Error(`${label} has unsupported value: ${text}. Allowed values: ${[
+            ...allowed,
+        ].join(", ")}`);
+    }
+    return text;
+}
+function requireStringMap(value, label) {
+    const record = requireRecord(value, label);
+    const result = {};
+    for (const [key, item] of Object.entries(record)) {
+        result[key] = requireString(item, `${label}.${key}`);
+    }
+    return result;
+}
+function ensureUnique(values, label) {
+    const seen = new Set();
+    for (const value of values) {
+        if (seen.has(value)) {
+            throw new Error(`${label} contains duplicate value: ${value}`);
+        }
+        seen.add(value);
+    }
+}
+function validateProvenance(value, participatingLensIds) {
+    const provenance = requireRecord(value, "ReviewRecord.per_lens_provenance");
+    for (const lensId of participatingLensIds) {
+        const lensProvenance = requireRecord(provenance[lensId], `ReviewRecord.per_lens_provenance.${lensId}`);
+        if (lensProvenance.domain_constraints_used !== null) {
+            for (const [index, item] of requireArray(lensProvenance.domain_constraints_used, `ReviewRecord.per_lens_provenance.${lensId}.domain_constraints_used`).entries()) {
+                const constraint = requireRecord(item, `ReviewRecord.per_lens_provenance.${lensId}.domain_constraints_used[${index}]`);
+                requireString(constraint.source_doc, `ReviewRecord.per_lens_provenance.${lensId}.domain_constraints_used[${index}].source_doc`);
+                requireString(constraint.source_version_or_snapshot_id, `ReviewRecord.per_lens_provenance.${lensId}.domain_constraints_used[${index}].source_version_or_snapshot_id`);
+                requireString(constraint.anchor, `ReviewRecord.per_lens_provenance.${lensId}.domain_constraints_used[${index}].anchor`);
+            }
+        }
+        if (lensProvenance.domain_context_assumptions !== null) {
+            requireStringArray(lensProvenance.domain_context_assumptions, `ReviewRecord.per_lens_provenance.${lensId}.domain_context_assumptions`);
+        }
+    }
+}
+function validateIssueProjection(value, label) {
+    const projection = requireRecord(value, label);
+    requireString(projection.issue_id, `${label}.issue_id`);
+    const severity = requireAllowed(projection.severity, new Set(REVIEW_SEVERITY_ORDER), `${label}.severity`);
+    if (projection.material !== isMaterialSeverity(severity)) {
+        throw new Error(`${label}.material must match severity-derived materiality.`);
+    }
+    requireString(projection.affected_purpose, `${label}.affected_purpose`);
+    requireString(projection.failure_condition, `${label}.failure_condition`);
+    requireString(projection.impact, `${label}.impact`);
+    requireStringArray(projection.evidence_refs, `${label}.evidence_refs`);
+    requireStringArray(projection.source_lens_ids, `${label}.source_lens_ids`);
+    for (const [index, candidate] of requireStringArray(projection.action_candidates, `${label}.action_candidates`).entries()) {
+        requireAllowed(candidate, ACTION_CANDIDATE_VALUES, `${label}.action_candidates[${index}]`);
+    }
+    requireString(projection.rationale, `${label}.rationale`);
+}
+function validateClassificationSummary(value) {
+    if (value === null || value === undefined)
+        return;
+    const summary = requireRecord(value, "ReviewRecord.result_classification_summary");
+    if (summary.highest_severity !== null &&
+        !isReviewFindingSeverity(summary.highest_severity)) {
+        throw new Error("ReviewRecord.result_classification_summary.highest_severity must be a known severity or null.");
+    }
+    requireInteger(summary.finding_count, "ReviewRecord.result_classification_summary.finding_count");
+    requireInteger(summary.issue_count, "ReviewRecord.result_classification_summary.issue_count");
+    for (const countField of [
+        "finding_severity_counts",
+        "issue_severity_counts",
+        "severity_counts",
+    ]) {
+        const counts = requireRecord(summary[countField], `ReviewRecord.result_classification_summary.${countField}`);
+        for (const severity of REVIEW_SEVERITY_ORDER) {
+            requireInteger(counts[severity], `ReviewRecord.result_classification_summary.${countField}.${severity}`);
+        }
+    }
+    requireInteger(summary.material_issue_count, "ReviewRecord.result_classification_summary.material_issue_count");
+    requireInteger(summary.non_material_finding_count, "ReviewRecord.result_classification_summary.non_material_finding_count");
+    for (const [index, item] of requireArray(summary.material_issues, "ReviewRecord.result_classification_summary.material_issues").entries()) {
+        validateIssueProjection(item, `ReviewRecord.result_classification_summary.material_issues[${index}]`);
+    }
+    for (const [index, item] of requireArray(summary.non_material_findings, "ReviewRecord.result_classification_summary.non_material_findings").entries()) {
+        validateIssueProjection(item, `ReviewRecord.result_classification_summary.non_material_findings[${index}]`);
+    }
+    for (const [index, item] of requireArray(summary.action_candidates, "ReviewRecord.result_classification_summary.action_candidates").entries()) {
+        const action = requireRecord(item, `ReviewRecord.result_classification_summary.action_candidates[${index}]`);
+        requireString(action.issue_id, `ReviewRecord.result_classification_summary.action_candidates[${index}].issue_id`);
+        for (const [candidateIndex, candidate] of requireStringArray(action.candidates, `ReviewRecord.result_classification_summary.action_candidates[${index}].candidates`).entries()) {
+            requireAllowed(candidate, ACTION_CANDIDATE_VALUES, `ReviewRecord.result_classification_summary.action_candidates[${index}].candidates[${candidateIndex}]`);
+        }
+        requireStringArray(action.derivation_refs, `ReviewRecord.result_classification_summary.action_candidates[${index}].derivation_refs`);
+        requireString(action.rationale, `ReviewRecord.result_classification_summary.action_candidates[${index}].rationale`);
+    }
+}
+function validateSharedPhenomenonSummary(value) {
+    for (const [index, item] of requireArray(value, "ReviewRecord.shared_phenomenon_summary").entries()) {
+        const entry = requireRecord(item, `ReviewRecord.shared_phenomenon_summary[${index}]`);
+        requireString(entry.target, `ReviewRecord.shared_phenomenon_summary[${index}].target`);
+        requireString(entry.evidence_anchor, `ReviewRecord.shared_phenomenon_summary[${index}].evidence_anchor`);
+        requireStringArray(entry.participating_lens_ids, `ReviewRecord.shared_phenomenon_summary[${index}].participating_lens_ids`);
+        requireAllowed(entry.claim_relation, SHARED_PHENOMENON_RELATION_VALUES, `ReviewRecord.shared_phenomenon_summary[${index}].claim_relation`);
+    }
+}
+export function validateReviewRecordObject(value) {
+    const record = requireRecord(value, "ReviewRecord");
+    requireString(record.review_record_id, "ReviewRecord.review_record_id");
+    requireString(record.session_id, "ReviewRecord.session_id");
+    if (record.entrypoint !== "review") {
+        throw new Error("ReviewRecord.entrypoint must be review.");
+    }
+    const recordStatus = requireAllowed(record.record_status, REVIEW_RECORD_STATUS_VALUES, "ReviewRecord.record_status");
+    requireString(record.created_at, "ReviewRecord.created_at");
+    requireString(record.updated_at, "ReviewRecord.updated_at");
+    requireString(record.request_text, "ReviewRecord.request_text");
+    requireString(record.review_target_scope_ref, "ReviewRecord.review_target_scope_ref");
+    requireString(record.interpretation_ref, "ReviewRecord.interpretation_ref");
+    requireString(record.binding_ref, "ReviewRecord.binding_ref");
+    requireString(record.domain_final_selection_ref, "ReviewRecord.domain_final_selection_ref");
+    const resolvedLensIds = requireStringArray(record.resolved_lens_ids, "ReviewRecord.resolved_lens_ids");
+    ensureUnique(resolvedLensIds, "ReviewRecord.resolved_lens_ids");
+    requireString(record.execution_result_ref, "ReviewRecord.execution_result_ref");
+    requireString(record.session_metadata_ref, "ReviewRecord.session_metadata_ref");
+    requireString(record.target_snapshot_ref, "ReviewRecord.target_snapshot_ref");
+    requireString(record.materialized_input_ref, "ReviewRecord.materialized_input_ref");
+    requireString(record.review_target_profile_ref, "ReviewRecord.review_target_profile_ref");
+    requireString(record.context_candidate_assembly_ref, "ReviewRecord.context_candidate_assembly_ref");
+    const lensResultRefs = requireStringMap(record.lens_result_refs, "ReviewRecord.lens_result_refs");
+    const lensOutputSchemaVersion = requireInteger(record.lens_output_schema_version, "ReviewRecord.lens_output_schema_version");
+    if (lensOutputSchemaVersion < 1) {
+        throw new Error("ReviewRecord.lens_output_schema_version must be >= 1.");
+    }
+    const participatingLensIds = requireStringArray(record.participating_lens_ids, "ReviewRecord.participating_lens_ids");
+    ensureUnique(participatingLensIds, "ReviewRecord.participating_lens_ids");
+    requireStringArray(record.excluded_lens_ids, "ReviewRecord.excluded_lens_ids");
+    requireStringArray(record.degraded_lens_ids, "ReviewRecord.degraded_lens_ids");
+    for (const lensId of participatingLensIds) {
+        if (!lensResultRefs[lensId]) {
+            throw new Error(`ReviewRecord.lens_result_refs missing participating lens: ${lensId}`);
+        }
+    }
+    validateProvenance(record.per_lens_provenance, participatingLensIds);
+    if (record.degradation_notes_ref !== undefined) {
+        requireNullableString(record.degradation_notes_ref, "ReviewRecord.degradation_notes_ref");
+    }
+    for (const fieldName of [
+        "finding_ledger_ref",
+        "finding_relation_graph_ref",
+        "issue_ledger_ref",
+        "issue_stance_matrix_ref",
+        "deliberation_plan_ref",
+        "problem_framing_ref",
+    ]) {
+        if (record[fieldName] !== undefined) {
+            requireNullableString(record[fieldName], `ReviewRecord.${fieldName}`);
+        }
+    }
+    if (record.issue_resolution_summary !== undefined) {
+        requireArray(record.issue_resolution_summary, "ReviewRecord.issue_resolution_summary");
+    }
+    validateClassificationSummary(record.result_classification_summary);
+    requireNullableString(record.synthesis_result_ref, "ReviewRecord.synthesis_result_ref");
+    requireAllowed(record.deliberation_status, new Set(["performed", "not_performed"]), "ReviewRecord.deliberation_status");
+    requireNullableString(record.deliberation_result_ref, "ReviewRecord.deliberation_result_ref");
+    requireString(record.final_output_ref, "ReviewRecord.final_output_ref");
+    validateSharedPhenomenonSummary(record.shared_phenomenon_summary);
+    if (recordStatus === "completed") {
+        requireString(record.synthesis_result_ref, "ReviewRecord.synthesis_result_ref for completed records");
+        requireString(record.deliberation_result_ref, "ReviewRecord.deliberation_result_ref for completed records");
+        if (record.deliberation_status !== "performed") {
+            throw new Error("Completed ReviewRecord must declare deliberation_status=performed.");
+        }
+    }
+    if (record.deliberation_status === "not_performed") {
+        if (record.deliberation_result_ref !== null) {
+            throw new Error("ReviewRecord.deliberation_result_ref must be null when deliberation_status=not_performed.");
+        }
+        if (record.synthesis_result_ref !== null) {
+            throw new Error("ReviewRecord.synthesis_result_ref must be null when deliberation_status=not_performed.");
+        }
+    }
+    return record;
+}
+export async function readValidatedReviewRecord(filePath) {
+    return validateReviewRecordObject(await readYamlDocument(filePath));
+}

package/dist/core-runtime/review/review-result-classification.js

@@ -0,0 +1,379 @@
+import path from "node:path";
+import { fileExists, readYamlDocument, } from "./review-artifact-utils.js";
+export const REVIEW_SEVERITY_ORDER = [
+    "blocker",
+    "high",
+    "medium",
+    "low",
+    "info",
+];
+const REVIEW_SEVERITY_VALUES = new Set(REVIEW_SEVERITY_ORDER);
+const MATERIAL_SEVERITIES = new Set([
+    "blocker",
+    "high",
+    "medium",
+]);
+export function isReviewFindingSeverity(value) {
+    return typeof value === "string" && REVIEW_SEVERITY_VALUES.has(value);
+}
+export function normalizeReviewFindingSeverity(value) {
+    if (isReviewFindingSeverity(value))
+        return value;
+    if (value === "critical")
+        return "blocker";
+    return "info";
+}
+export function isMaterialSeverity(severity) {
+    return MATERIAL_SEVERITIES.has(severity);
+}
+export function emptyReviewSeverityCounts() {
+    return {
+        blocker: 0,
+        high: 0,
+        medium: 0,
+        low: 0,
+        info: 0,
+    };
+}
+function incrementSeverityCount(counts, severity) {
+    counts[severity] += 1;
+}
+function records(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => item !== null && typeof item === "object" && !Array.isArray(item));
+}
+function stringValue(value, fallback = "") {
+    return typeof value === "string" && value.trim().length > 0
+        ? value.trim()
+        : fallback;
+}
+function nullableStringValue(value) {
+    return typeof value === "string" && value.trim().length > 0
+        ? value.trim()
+        : null;
+}
+function stringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .filter((item) => typeof item === "string")
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+}
+function unique(values) {
+    return [...new Set(values)];
+}
+async function readOptionalYaml(filePath) {
+    if (!(await fileExists(filePath)))
+        return null;
+    return readYamlDocument(filePath);
+}
+function buildFindingEvidenceRefs(finding) {
+    const directRefs = stringArray(finding.evidence_refs);
+    if (directRefs.length > 0)
+        return unique(directRefs);
+    const refs = [
+        stringValue(finding.source_ref),
+        stringValue(finding.evidence_anchor),
+    ].filter((ref) => ref.length > 0);
+    return unique(refs);
+}
+function candidateFallbackForSeverity(severity) {
+    switch (severity) {
+        case "blocker":
+            return ["fix_now"];
+        case "high":
+            return ["fix_before_release"];
+        case "medium":
+            return ["accept_risk", "follow_up"];
+        case "low":
+            return ["follow_up"];
+        case "info":
+            return ["needs_evidence"];
+    }
+}
+function pushCandidate(candidates, candidate) {
+    if (!candidates.includes(candidate))
+        candidates.push(candidate);
+}
+function deriveActionCandidates(args) {
+    const candidates = [];
+    const classification = args.classification;
+    switch (classification?.timing_class) {
+        case "current_blocker":
+            pushCandidate(candidates, "fix_now");
+            break;
+        case "next_step_blocker":
+            pushCandidate(candidates, "fix_before_release");
+            break;
+        case "planned_follow_up":
+        case "defer_watch":
+            pushCandidate(candidates, "follow_up");
+            break;
+    }
+    switch (classification?.closure_class) {
+        case "fix_now":
+            pushCandidate(candidates, "fix_now");
+            break;
+        case "needs_decision":
+            pushCandidate(candidates, "accept_risk");
+            break;
+        case "needs_evidence":
+            pushCandidate(candidates, "needs_evidence");
+            break;
+        case "carry_forward":
+        case "document_only":
+        case "watch":
+            pushCandidate(candidates, "follow_up");
+            break;
+    }
+    switch (classification?.closure_obligation) {
+        case "must_close_in_target":
+            pushCandidate(candidates, "fix_now");
+            break;
+        case "must_close_before_next_stage":
+            pushCandidate(candidates, "fix_before_release");
+            break;
+        case "may_close_during_next_stage":
+        case "planned_later":
+            pushCandidate(candidates, "follow_up");
+            break;
+        case "out_of_scope":
+            pushCandidate(candidates, "out_of_scope");
+            break;
+    }
+    switch (classification?.judgment_state) {
+        case "insufficient_evidence":
+            pushCandidate(candidates, "needs_evidence");
+            break;
+        case "outside_boundary":
+            pushCandidate(candidates, "out_of_scope");
+            break;
+    }
+    if (candidates.length > 0)
+        return candidates;
+    if (args.hasProblemFraming)
+        return ["follow_up"];
+    return candidateFallbackForSeverity(args.severity);
+}
+function actionRationale(args) {
+    const classificationRationale = stringValue(args.classification?.rationale);
+    if (classificationRationale.length > 0)
+        return classificationRationale;
+    if (args.hasProblemFraming) {
+        return "Problem framing is present but does not provide a more specific action rationale.";
+    }
+    if (args.issueStatement.length > 0)
+        return args.issueStatement;
+    return `Action candidates are derived from severity=${args.severity} because problem framing is unavailable.`;
+}
+function classificationMap(problemFraming) {
+    const map = new Map();
+    for (const classification of records(problemFraming?.classifications)) {
+        const issueId = stringValue(classification.issue_id);
+        if (issueId.length > 0)
+            map.set(issueId, classification);
+    }
+    return map;
+}
+function findingMap(findings) {
+    const map = new Map();
+    for (const finding of findings) {
+        const findingId = stringValue(finding.finding_id);
+        if (findingId.length > 0)
+            map.set(findingId, finding);
+    }
+    return map;
+}
+function evidenceRefsForIssue(issue, findingsById) {
+    const directRefs = stringArray(issue.evidence_refs);
+    if (directRefs.length > 0)
+        return unique(directRefs);
+    const refs = [];
+    for (const findingId of stringArray(issue.surface_finding_ids)) {
+        const finding = findingsById.get(findingId);
+        if (!finding)
+            continue;
+        refs.push(...buildFindingEvidenceRefs(finding));
+    }
+    return unique(refs);
+}
+function sourceLensIdsForIssue(issue, findingsById) {
+    const direct = stringArray(issue.raised_by_lens_ids);
+    if (direct.length > 0)
+        return unique(direct);
+    const lensIds = [];
+    for (const findingId of stringArray(issue.surface_finding_ids)) {
+        const lensId = stringValue(findingsById.get(findingId)?.lens_id);
+        if (lensId.length > 0)
+            lensIds.push(lensId);
+    }
+    return unique(lensIds);
+}
+function severityCountsFor(recordsToCount) {
+    const counts = emptyReviewSeverityCounts();
+    for (const record of recordsToCount) {
+        incrementSeverityCount(counts, normalizeReviewFindingSeverity(record.severity));
+    }
+    return counts;
+}
+function highestSeverity(counts) {
+    return REVIEW_SEVERITY_ORDER.find((severity) => counts[severity] > 0) ?? null;
+}
+function sortBySeverityAndId(projections) {
+    return [...projections].sort((left, right) => {
+        const severityDelta = REVIEW_SEVERITY_ORDER.indexOf(left.severity) -
+            REVIEW_SEVERITY_ORDER.indexOf(right.severity);
+        if (severityDelta !== 0)
+            return severityDelta;
+        return left.issue_id.localeCompare(right.issue_id);
+    });
+}
+function projectionFromIssue(args) {
+    const severity = normalizeReviewFindingSeverity(args.issue.severity);
+    const issueId = stringValue(args.issue.issue_id, "issue-unknown");
+    const issueStatement = stringValue(args.issue.issue_statement);
+    const affectedPurpose = stringValue(args.issue.affected_purpose, stringValue(args.classification?.problem_definition, "declared review purpose"));
+    const failureCondition = stringValue(args.issue.failure_condition, stringValue(args.issue.root_cause_hypothesis, issueStatement));
+    const impact = stringValue(args.issue.impact, stringValue(args.classification?.impact_kind, issueStatement));
+    const actionCandidates = deriveActionCandidates({
+        severity,
+        classification: args.classification,
+        hasProblemFraming: args.hasProblemFraming,
+    });
+    const projection = {
+        issue_id: issueId,
+        severity,
+        material: isMaterialSeverity(severity),
+        affected_purpose: affectedPurpose,
+        failure_condition: failureCondition,
+        impact,
+        evidence_refs: evidenceRefsForIssue(args.issue, args.findingsById),
+        source_lens_ids: sourceLensIdsForIssue(args.issue, args.findingsById),
+        action_candidates: actionCandidates,
+        rationale: actionRationale({
+            classification: args.classification,
+            hasProblemFraming: args.hasProblemFraming,
+            severity,
+            issueStatement,
+        }),
+    };
+    const domainThresholdUsed = nullableStringValue(args.issue.domain_threshold_used);
+    if (domainThresholdUsed !== null)
+        projection.domain_threshold_used = domainThresholdUsed;
+    const problemDefinition = stringValue(args.classification?.problem_definition);
+    if (problemDefinition.length > 0)
+        projection.problem_definition = problemDefinition;
+    if (issueStatement.length > 0)
+        projection.issue_statement = issueStatement;
+    const timingClass = stringValue(args.classification?.timing_class);
+    if (timingClass.length > 0)
+        projection.timing_class = timingClass;
+    const closureClass = stringValue(args.classification?.closure_class);
+    if (closureClass.length > 0)
+        projection.closure_class = closureClass;
+    const closureObligation = stringValue(args.classification?.closure_obligation);
+    if (closureObligation.length > 0)
+        projection.closure_obligation = closureObligation;
+    const judgmentState = stringValue(args.classification?.judgment_state);
+    if (judgmentState.length > 0)
+        projection.judgment_state = judgmentState;
+    return projection;
+}
+function projectionFromFinding(finding) {
+    const severity = normalizeReviewFindingSeverity(finding.severity);
+    const findingId = stringValue(finding.finding_id, "finding-unknown");
+    const claim = stringValue(finding.claim);
+    const projection = {
+        issue_id: `finding:${findingId}`,
+        severity,
+        material: isMaterialSeverity(severity),
+        affected_purpose: stringValue(finding.affected_purpose, "declared review purpose"),
+        failure_condition: stringValue(finding.failure_condition, claim),
+        impact: stringValue(finding.impact, claim.length > 0
+            ? claim
+            : "Finding has not yet been clustered into a root-cause issue."),
+        evidence_refs: buildFindingEvidenceRefs(finding),
+        source_lens_ids: stringValue(finding.lens_id).length > 0
+            ? [stringValue(finding.lens_id)]
+            : [],
+        action_candidates: ["continue_review"],
+        rationale: "Finding-level projection is available before root-cause issue classification.",
+    };
+    const domainThresholdUsed = nullableStringValue(finding.domain_threshold_used);
+    if (domainThresholdUsed !== null)
+        projection.domain_threshold_used = domainThresholdUsed;
+    if (claim.length > 0)
+        projection.issue_statement = claim;
+    return projection;
+}
+function buildActionCandidateProjection(projection, hasProblemFraming) {
+    const refs = projection.issue_id.startsWith("finding:")
+        ? ["finding-ledger.yaml"]
+        : [
+            "issue-ledger.yaml",
+            ...(hasProblemFraming ? ["problem-framing.yaml"] : []),
+        ];
+    return {
+        issue_id: projection.issue_id,
+        candidates: projection.action_candidates,
+        derivation_refs: refs,
+        rationale: projection.rationale,
+    };
+}
+function runtimeHaltActionCandidate(executionResult) {
+    if (executionResult?.execution_status !== "halted_partial")
+        return null;
+    return {
+        issue_id: "runtime-halt",
+        candidates: ["retry_execution", "continue_review"],
+        derivation_refs: ["execution-result.yaml"],
+        rationale: executionResult.halt_reason ?? "Review execution halted before completion.",
+    };
+}
+export async function readReviewResultClassification(sessionRoot) {
+    const findingLedger = await readOptionalYaml(path.join(sessionRoot, "finding-ledger.yaml"));
+    const issueLedger = await readOptionalYaml(path.join(sessionRoot, "issue-ledger.yaml"));
+    const problemFraming = await readOptionalYaml(path.join(sessionRoot, "problem-framing.yaml"));
+    const executionResult = await readOptionalYaml(path.join(sessionRoot, "execution-result.yaml"));
+    const findings = records(findingLedger?.findings);
+    const issues = records(issueLedger?.issues);
+    const findingsById = findingMap(findings);
+    const classificationsByIssueId = classificationMap(problemFraming);
+    const hasProblemFraming = problemFraming !== null;
+    const findingSeverityCounts = severityCountsFor(findings);
+    const issueSeverityCounts = severityCountsFor(issues);
+    const projectionSourceIsIssueLedger = issues.length > 0;
+    const severityCounts = projectionSourceIsIssueLedger
+        ? issueSeverityCounts
+        : findingSeverityCounts;
+    const projections = projectionSourceIsIssueLedger
+        ? issues.map((issue) => projectionFromIssue({
+            issue,
+            findingsById,
+            classification: classificationsByIssueId.get(stringValue(issue.issue_id)) ?? null,
+            hasProblemFraming,
+        }))
+        : findings.map(projectionFromFinding);
+    const sortedProjections = sortBySeverityAndId(projections);
+    const materialIssues = sortedProjections.filter((projection) => projection.material);
+    const nonMaterialFindings = sortedProjections.filter((projection) => !projection.material);
+    const actionCandidates = sortedProjections.map((projection) => buildActionCandidateProjection(projection, hasProblemFraming));
+    const haltActionCandidate = runtimeHaltActionCandidate(executionResult);
+    if (haltActionCandidate)
+        actionCandidates.push(haltActionCandidate);
+    return {
+        highest_severity: highestSeverity(severityCounts),
+        finding_count: findings.length,
+        issue_count: issues.length,
+        finding_severity_counts: findingSeverityCounts,
+        issue_severity_counts: issueSeverityCounts,
+        severity_counts: severityCounts,
+        material_issue_count: materialIssues.length,
+        non_material_finding_count: nonMaterialFindings.length,
+        material_issues: materialIssues,
+        non_material_findings: nonMaterialFindings,
+        action_candidates: actionCandidates,
+    };
+}

package/dist/core-runtime/review/review-state-machine.js

@@ -0,0 +1,39 @@
+export const REVIEW_STATES = [
+    "preparing",
+    "awaiting_lens_dispatch",
+    "validating_lenses",
+    "awaiting_adjudication",
+    "awaiting_synthesize_dispatch",
+    "awaiting_deliberation",
+    "completing",
+    "completed",
+    "halted_partial",
+    "failed",
+];
+export const REVIEW_TERMINAL_STATES = new Set([
+    "completed",
+    "halted_partial",
+    "failed",
+]);
+export const REVIEW_TRANSITIONS = {
+    "(init)": ["preparing"],
+    preparing: ["awaiting_lens_dispatch", "failed"],
+    awaiting_lens_dispatch: ["validating_lenses"],
+    validating_lenses: [
+        "awaiting_adjudication",
+        "awaiting_deliberation",
+        "halted_partial",
+        "failed",
+    ],
+    awaiting_adjudication: ["awaiting_deliberation", "failed"],
+    awaiting_deliberation: ["awaiting_synthesize_dispatch", "failed"],
+    awaiting_synthesize_dispatch: ["completing"],
+    completing: ["completed", "failed"],
+    completed: [],
+    halted_partial: [],
+    failed: [],
+};
+export function canReviewTransition(from, to) {
+    const allowed = REVIEW_TRANSITIONS[from];
+    return allowed != null && allowed.includes(to);
+}