auditor-lambda 0.2.5 → 0.2.6

package/dist/validation/auditResults.js

@@ -9,77 +9,193 @@ const REQUIRED_FINDING_FIELDS = [
 ];
 const VALID_SEVERITIES = new Set(["critical", "high", "medium", "low", "info"]);
 const VALID_CONFIDENCES = new Set(["high", "medium", "low"]);
+const VALID_LENSES = new Set([
+    "correctness",
+    "architecture",
+    "maintainability",
+    "security",
+    "reliability",
+    "performance",
+    "data_integrity",
+    "tests",
+    "operability",
+    "config_deployment",
+]);
+function pushIssue(issues, params) {
+    issues.push({
+        ...params,
+        severity: params.severity ?? "error",
+    });
+}
+function describeValue(value) {
+    if (Array.isArray(value)) {
+        return "array";
+    }
+    if (value === null) {
+        return "null";
+    }
+    return typeof value;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function issueTaskId(record, resultIndex) {
+    const taskId = record.task_id;
+    return typeof taskId === "string" && taskId.trim().length > 0
+        ? taskId
+        : `result[${resultIndex}]`;
+}
+function validateRequiredStringField(value, label, taskId, resultIndex, issues) {
+    if (typeof value !== "string") {
+        pushIssue(issues, {
+            result_index: resultIndex,
+            task_id: taskId,
+            field: label,
+            message: `${label} must be a string, got ${describeValue(value)}.`,
+        });
+        return;
+    }
+    if (value.trim().length === 0) {
+        pushIssue(issues, {
+            result_index: resultIndex,
+            task_id: taskId,
+            field: label,
+            message: `${label} must not be empty.`,
+        });
+    }
+}
 function validateFinding(finding, label, taskId, resultIndex) {
     const issues = [];
+    if (!isRecord(finding)) {
+        pushIssue(issues, {
+            result_index: resultIndex,
+            task_id: taskId,
+            field: label,
+            message: `${label} must be an object, got ${describeValue(finding)}.`,
+        });
+        return issues;
+    }
     for (const field of REQUIRED_FINDING_FIELDS) {
-        const value = finding[field];
-        if (value === undefined || value === null || String(value).trim() === "") {
-            issues.push({
-                result_index: resultIndex,
-                task_id: taskId,
-                severity: "error",
-                field: `${label}.${field}`,
-                message: `Required field '${field}' is missing or empty.`,
-            });
-        }
+        validateRequiredStringField(finding[field], `${label}.${field}`, taskId, resultIndex, issues);
     }
-    if (finding.severity && !VALID_SEVERITIES.has(finding.severity)) {
-        issues.push({
+    if (typeof finding.severity === "string" &&
+        !VALID_SEVERITIES.has(finding.severity)) {
+        pushIssue(issues, {
             result_index: resultIndex,
             task_id: taskId,
-            severity: "error",
             field: `${label}.severity`,
             message: `Invalid severity '${finding.severity}'. Must be one of: ${[...VALID_SEVERITIES].join(", ")}.`,
         });
     }
-    if (finding.confidence && !VALID_CONFIDENCES.has(finding.confidence)) {
-        issues.push({
+    if (typeof finding.confidence === "string" &&
+        !VALID_CONFIDENCES.has(finding.confidence)) {
+        pushIssue(issues, {
             result_index: resultIndex,
             task_id: taskId,
-            severity: "error",
             field: `${label}.confidence`,
             message: `Invalid confidence '${finding.confidence}'. Must be one of: ${[...VALID_CONFIDENCES].join(", ")}.`,
         });
     }
-    if (!finding.affected_files || finding.affected_files.length === 0) {
-        issues.push({
+    if (typeof finding.lens === "string" && !VALID_LENSES.has(finding.lens)) {
+        pushIssue(issues, {
+            result_index: resultIndex,
+            task_id: taskId,
+            field: `${label}.lens`,
+            message: `Invalid lens '${finding.lens}'. Must be one of: ${[...VALID_LENSES].join(", ")}.`,
+        });
+    }
+    const affectedFiles = finding.affected_files;
+    if (!Array.isArray(affectedFiles) || affectedFiles.length === 0) {
+        pushIssue(issues, {
             result_index: resultIndex,
             task_id: taskId,
-            severity: "error",
             field: `${label}.affected_files`,
-            message: "affected_files is empty — at least one file location is required.",
+            message: "affected_files must be a non-empty array.",
         });
     }
     else {
-        for (let k = 0; k < finding.affected_files.length; k++) {
-            const af = finding.affected_files[k];
-            if (!af.path?.trim()) {
-                issues.push({
+        for (let k = 0; k < affectedFiles.length; k++) {
+            const item = affectedFiles[k];
+            if (!isRecord(item)) {
+                pushIssue(issues, {
+                    result_index: resultIndex,
+                    task_id: taskId,
+                    field: `${label}.affected_files[${k}]`,
+                    message: `affected_files[${k}] must be an object, got ${describeValue(item)}.`,
+                });
+                continue;
+            }
+            if (!isNonEmptyString(item.path)) {
+                pushIssue(issues, {
                     result_index: resultIndex,
                     task_id: taskId,
-                    severity: "error",
                     field: `${label}.affected_files[${k}].path`,
                     message: "affected_files entry has an empty path.",
                 });
             }
+            if (item.line_start !== undefined &&
+                !Number.isInteger(item.line_start)) {
+                pushIssue(issues, {
+                    result_index: resultIndex,
+                    task_id: taskId,
+                    field: `${label}.affected_files[${k}].line_start`,
+                    message: `affected_files[${k}].line_start must be an integer, got ${describeValue(item.line_start)}.`,
+                });
+            }
+            if (item.line_end !== undefined &&
+                !Number.isInteger(item.line_end)) {
+                pushIssue(issues, {
+                    result_index: resultIndex,
+                    task_id: taskId,
+                    field: `${label}.affected_files[${k}].line_end`,
+                    message: `affected_files[${k}].line_end must be an integer, got ${describeValue(item.line_end)}.`,
+                });
+            }
+            if (Number.isInteger(item.line_start) &&
+                Number.isInteger(item.line_end) &&
+                Number(item.line_start) > Number(item.line_end)) {
+                pushIssue(issues, {
+                    result_index: resultIndex,
+                    task_id: taskId,
+                    field: `${label}.affected_files[${k}]`,
+                    message: "affected_files line_start must be less than or equal to line_end.",
+                });
+            }
         }
     }
-    if (!finding.evidence || finding.evidence.length === 0) {
-        issues.push({
+    const evidence = finding.evidence;
+    if (!Array.isArray(evidence) || evidence.length === 0) {
+        pushIssue(issues, {
             result_index: resultIndex,
             task_id: taskId,
-            severity: "error",
             field: `${label}.evidence`,
-            message: "evidence is empty — at least one quoted or referenced excerpt from the reviewed file is required for every finding.",
+            message: "evidence is empty — provide an array of plain strings such as \"src/foo.ts:42 - variable overwritten before use\".",
         });
     }
     else {
-        const hasSubstantiveEntry = finding.evidence.some((e) => e.trim().length > 0);
+        let hasSubstantiveEntry = false;
+        for (let k = 0; k < evidence.length; k++) {
+            const entry = evidence[k];
+            if (typeof entry !== "string") {
+                pushIssue(issues, {
+                    result_index: resultIndex,
+                    task_id: taskId,
+                    field: `${label}.evidence[${k}]`,
+                    message: `evidence[${k}] must be a string, got ${describeValue(entry)}.`,
+                });
+                continue;
+            }
+            if (entry.trim().length > 0) {
+                hasSubstantiveEntry = true;
+            }
+        }
         if (!hasSubstantiveEntry) {
-            issues.push({
+            pushIssue(issues, {
                 result_index: resultIndex,
                 task_id: taskId,
-                severity: "error",
                 field: `${label}.evidence`,
                 message: "All evidence entries are empty strings.",
             });
@@ -87,26 +203,237 @@ function validateFinding(finding, label, taskId, resultIndex) {
     }
     return issues;
 }
-export function validateAuditResults(results, tasks) {
+function coversAffectedSpan(ranges, path, start, end) {
+    return ranges.some((range) => range.path === path &&
+        range.start <= start &&
+        range.end >= end);
+}
+export function validateAuditResults(results, tasks, options = {}) {
     const issues = [];
-    const taskMap = new Map(tasks.map((t) => [t.task_id, t]));
+    const taskMap = new Map(tasks.map((task) => [task.task_id, task]));
+    if (!Array.isArray(results)) {
+        pushIssue(issues, {
+            result_index: -1,
+            task_id: "results",
+            field: "results",
+            message: `Audit results payload must be a JSON array, got ${describeValue(results)}.`,
+        });
+        return issues;
+    }
     for (let i = 0; i < results.length; i++) {
         const result = results[i];
-        const taskId = result.task_id ?? `result[${i}]`;
-        if (!result.reviewed_ranges || result.reviewed_ranges.length === 0) {
-            issues.push({
+        if (!isRecord(result)) {
+            pushIssue(issues, {
+                result_index: i,
+                task_id: `result[${i}]`,
+                field: `results[${i}]`,
+                message: `Each audit result must be an object, got ${describeValue(result)}.`,
+            });
+            continue;
+        }
+        const taskId = issueTaskId(result, i);
+        const task = taskMap.get(taskId);
+        validateRequiredStringField(result.task_id, "task_id", taskId, i, issues);
+        validateRequiredStringField(result.unit_id, "unit_id", taskId, i, issues);
+        validateRequiredStringField(result.pass_id, "pass_id", taskId, i, issues);
+        validateRequiredStringField(result.lens, "lens", taskId, i, issues);
+        if (typeof result.lens === "string" &&
+            !VALID_LENSES.has(result.lens)) {
+            pushIssue(issues, {
+                result_index: i,
+                task_id: taskId,
+                field: "lens",
+                message: `Invalid lens '${result.lens}'. Must be one of: ${[...VALID_LENSES].join(", ")}.`,
+            });
+        }
+        if (tasks.length > 0 && !task) {
+            pushIssue(issues, {
+                result_index: i,
+                task_id: taskId,
+                field: "task_id",
+                message: `Unknown task_id '${taskId}'.`,
+            });
+        }
+        const reviewedRanges = result.reviewed_ranges;
+        const normalizedReviewedRanges = [];
+        if (!Array.isArray(reviewedRanges) || reviewedRanges.length === 0) {
+            pushIssue(issues, {
                 result_index: i,
                 task_id: taskId,
-                severity: "error",
                 field: "reviewed_ranges",
-                message: "reviewed_ranges is empty — no proof of file reading was recorded. " +
-                    "Each result must include the line ranges actually read.",
+                message: "reviewed_ranges is empty — no proof of file reading was recorded. Each result must include the line ranges actually read.",
             });
         }
-        for (let j = 0; j < (result.findings ?? []).length; j++) {
-            const finding = result.findings[j];
+        else {
+            for (let j = 0; j < reviewedRanges.length; j++) {
+                const range = reviewedRanges[j];
+                if (!isRecord(range)) {
+                    pushIssue(issues, {
+                        result_index: i,
+                        task_id: taskId,
+                        field: `reviewed_ranges[${j}]`,
+                        message: `reviewed_ranges[${j}] must be an object, got ${describeValue(range)}.`,
+                    });
+                    continue;
+                }
+                if (!isNonEmptyString(range.path)) {
+                    pushIssue(issues, {
+                        result_index: i,
+                        task_id: taskId,
+                        field: `reviewed_ranges[${j}].path`,
+                        message: "reviewed_ranges entry has an empty path.",
+                    });
+                }
+                else if (task && !task.file_paths.includes(range.path)) {
+                    pushIssue(issues, {
+                        result_index: i,
+                        task_id: taskId,
+                        severity: "warning",
+                        field: `reviewed_ranges[${j}].path`,
+                        message: `reviewed_ranges path '${range.path}' is not listed in the task file_paths.`,
+                    });
+                }
+                if (!Number.isInteger(range.start)) {
+                    pushIssue(issues, {
+                        result_index: i,
+                        task_id: taskId,
+                        field: `reviewed_ranges[${j}].start`,
+                        message: `reviewed_ranges[${j}].start must be an integer, got ${describeValue(range.start)}.`,
+                    });
+                }
+                if (!Number.isInteger(range.end)) {
+                    pushIssue(issues, {
+                        result_index: i,
+                        task_id: taskId,
+                        field: `reviewed_ranges[${j}].end`,
+                        message: `reviewed_ranges[${j}].end must be an integer, got ${describeValue(range.end)}.`,
+                    });
+                }
+                if (!Number.isInteger(range.line_count)) {
+                    pushIssue(issues, {
+                        result_index: i,
+                        task_id: taskId,
+                        field: `reviewed_ranges[${j}].line_count`,
+                        message: `reviewed_ranges[${j}].line_count must be an integer, got ${describeValue(range.line_count)}.`,
+                    });
+                }
+                if (Number.isInteger(range.start) &&
+                    Number.isInteger(range.end) &&
+                    Number(range.start) > Number(range.end)) {
+                    pushIssue(issues, {
+                        result_index: i,
+                        task_id: taskId,
+                        field: `reviewed_ranges[${j}]`,
+                        message: "reviewed_ranges start must be less than or equal to end.",
+                    });
+                }
+                if (Number.isInteger(range.line_count) &&
+                    Number(range.line_count) <= 0) {
+                    pushIssue(issues, {
+                        result_index: i,
+                        task_id: taskId,
+                        field: `reviewed_ranges[${j}].line_count`,
+                        message: "reviewed_ranges line_count must be greater than zero.",
+                    });
+                }
+                if (Number.isInteger(range.start) &&
+                    Number(range.start) <= 0) {
+                    pushIssue(issues, {
+                        result_index: i,
+                        task_id: taskId,
+                        field: `reviewed_ranges[${j}].start`,
+                        message: "reviewed_ranges start must be greater than zero.",
+                    });
+                }
+                if (Number.isInteger(range.end) &&
+                    Number(range.end) <= 0) {
+                    pushIssue(issues, {
+                        result_index: i,
+                        task_id: taskId,
+                        field: `reviewed_ranges[${j}].end`,
+                        message: "reviewed_ranges end must be greater than zero.",
+                    });
+                }
+                if (Number.isInteger(range.end) &&
+                    Number.isInteger(range.line_count) &&
+                    Number(range.end) > Number(range.line_count)) {
+                    pushIssue(issues, {
+                        result_index: i,
+                        task_id: taskId,
+                        field: `reviewed_ranges[${j}]`,
+                        message: "reviewed_ranges end must not exceed the declared file line_count.",
+                    });
+                }
+                const expectedLineCount = typeof range.path === "string"
+                    ? options.lineIndex?.[range.path]
+                    : undefined;
+                if (Number.isInteger(range.line_count) &&
+                    typeof expectedLineCount === "number" &&
+                    Number(range.line_count) !== expectedLineCount) {
+                    pushIssue(issues, {
+                        result_index: i,
+                        task_id: taskId,
+                        field: `reviewed_ranges[${j}].line_count`,
+                        message: `reviewed_ranges[${j}].line_count must match the current file line count for '${range.path}' ` +
+                            `(expected ${expectedLineCount}, got ${range.line_count}).`,
+                    });
+                }
+                if (isNonEmptyString(range.path) &&
+                    Number.isInteger(range.start) &&
+                    Number.isInteger(range.end) &&
+                    Number.isInteger(range.line_count) &&
+                    Number(range.start) > 0 &&
+                    Number(range.end) > 0 &&
+                    Number(range.start) <= Number(range.end) &&
+                    Number(range.end) <= Number(range.line_count)) {
+                    normalizedReviewedRanges.push({
+                        path: range.path,
+                        start: Number(range.start),
+                        end: Number(range.end),
+                        line_count: Number(range.line_count),
+                    });
+                }
+            }
+        }
+        const findings = result.findings;
+        if (!Array.isArray(findings)) {
+            pushIssue(issues, {
+                result_index: i,
+                task_id: taskId,
+                field: "findings",
+                message: `findings must be an array, got ${describeValue(findings)}.`,
+            });
+            continue;
+        }
+        for (let j = 0; j < findings.length; j++) {
             const label = `findings[${j}]`;
+            const finding = findings[j];
             issues.push(...validateFinding(finding, label, taskId, i));
+            if (!isRecord(finding) || !Array.isArray(finding.affected_files)) {
+                continue;
+            }
+            for (let k = 0; k < finding.affected_files.length; k++) {
+                const affected = finding.affected_files[k];
+                if (!isRecord(affected) || !isNonEmptyString(affected.path)) {
+                    continue;
+                }
+                if (!Number.isInteger(affected.line_start)) {
+                    continue;
+                }
+                const start = Number(affected.line_start);
+                const end = Number.isInteger(affected.line_end)
+                    ? Number(affected.line_end)
+                    : start;
+                if (!coversAffectedSpan(normalizedReviewedRanges, affected.path, start, end)) {
+                    pushIssue(issues, {
+                        result_index: i,
+                        task_id: taskId,
+                        field: `${label}.affected_files[${k}]`,
+                        message: `affected_files line span ${affected.path}:${start}-${end} falls outside the declared reviewed_ranges. ` +
+                            "Expand reviewed_ranges to cover the cited lines or fix the affected_files location.",
+                    });
+                }
+            }
         }
     }
     return issues;

package/docs/artifacts.md

@@ -16,7 +16,8 @@ These JSON artifacts are the stable contract between deterministic tooling and L
 - `runtime_validation_tasks.json`
 - `runtime_validation_report.json`
 - `external_analyzer_results.json`
-- `audit_results.json`
+- `audit_tasks.json`
+- `audit_results.jsonl`
 - `requeue_tasks.json`
 - `merged_findings.json`
 - `root_cause_clusters.json`
@@ -67,3 +68,9 @@ External analyzer results now also influence:
 - dedicated analyzer follow-up tasks
 - requeue priority
 - synthesis evidence and summaries
+
+## Key schema notes
+
+- `audit_tasks.json`: each task already contains the resolved `file_paths` it covers. Use `audit-code explain-task <task_id>` when you want that task joined back to current `coverage_matrix.json` state.
+- `coverage_matrix.json`: each file records `classification_status`, `audit_status`, `required_lenses`, and `completed_lenses`.
+- `synthesis_report.json`: this is the top-level synthesis artifact. It includes `merged_findings`, semantic `root_cause_clusters`, and `work_blocks`; `work_blocks` are the primary remediation grouping.

package/docs/contract.md

@@ -1,6 +1,6 @@
 # audit-code response contract
 
-This document describes the backend fallback JSON response contract for the `audit-code` wrapper.
+This document describes the backend fallback JSON contract for `audit-code`.
 
 The canonical product remains `/audit-code` in conversation.
 
@@ -12,16 +12,13 @@ Repo-local fallback command from the target repository root:
 audit-code
 ```
 
-Installed helper for locating the packaged conversation prompt asset:
+Useful helpers:
 
 ```bash
 audit-code prompt-path
-```
-
-Installed helper for validating the current backend artifact bundle:
-
-```bash
 audit-code validate
+audit-code explain-task <task_id>
+audit-code --batch-results /path/to/audit-results-dir
 ```
 
 Repository-local wrapper equivalent:
@@ -42,30 +39,21 @@ Consumers should verify this value before assuming the response shape.
 
 ## Source of truth
 
-The versioned JSON schema is:
+The versioned wrapper schema is:
 
 ```text
 schemas/audit-code-v1alpha1.schema.json
 ```
 
-Product tests validate live wrapper output against that schema.
-
-## Reproducible installed-command smoke check
-
-From the repository root:
-
-```bash
-npm install
-npm run build
-npm link
-npm run smoke:linked-audit-code
-```
+Artifact-level schemas also live in `schemas/`, including:
 
-This exercises the installed backend fallback command end-to-end and validates the emitted JSON against the versioned schema.
+- `schemas/audit_task.schema.json`
+- `schemas/audit_result.schema.json`
+- `schemas/finding.schema.json`
 
-## Top-level fields
+## Top-level wrapper fields
 
-The current v1alpha1 contract includes these top-level fields:
+The current v1alpha1 wrapper contract includes:
 
 - `contract_version`
 - `audit_state`
@@ -79,11 +67,11 @@ The current v1alpha1 contract includes these top-level fields:
 
 `handoff` is a companion operator-context object. It includes:
 
-- current top-level status
 - repo and artifacts paths
 - pending obligations
-- suggested evidence-import paths and commands when manual continuation is required
-- stable paths to companion handoff files under `.audit-artifacts`
+- suggested evidence-import paths and commands
+- provider guidance
+- stable paths to operator handoff artifacts
 
 ## Terminal states
 
@@ -102,7 +90,110 @@ When the wrapper emits a response, it also refreshes:
 - `.audit-artifacts/operator-handoff.json`
 - `.audit-artifacts/operator-handoff.md`
 
-Those files mirror the structured `handoff` guidance in machine-readable and human-readable forms.
+## Artifact contract
+
+These are the primary machine-readable artifacts:
+
+- `repo_manifest.json`
+- `file_disposition.json`
+- `unit_manifest.json`
+- `critical_flows.json`
+- `coverage_matrix.json`
+- `runtime_validation_tasks.json`
+- `runtime_validation_report.json`
+- `audit_tasks.json`
+- `audit_results.jsonl`
+- `requeue_tasks.json`
+- `merged_findings.json`
+- `root_cause_clusters.json`
+- `synthesis_report.json`
+
+Important shape notes:
+
+- `audit_tasks.json`: each task already contains its resolved `file_paths`.
+- `coverage_matrix.json`: each file records `classification_status`, `audit_status`, `required_lenses`, and `completed_lenses`.
+- `synthesis_report.json`: includes `merged_findings`, semantic `root_cause_clusters`, and `work_blocks`.
+
+## Task id conventions
+
+Current task ids follow a few stable patterns:
+
+- Standard unit/lens task: `<unit_id>:<lens>`
+- Large-file split task: `<unit_id>:<lens>:<file_path>`
+- External analyzer follow-up: `analyzer:<tool>:<lens>:<path>:<result_id>`
+- Requeue task: `requeue:<lens>:<path>`
+
+If you need the resolved task payload plus current coverage state, use:
+
+```bash
+audit-code explain-task <task_id>
+```
+
+## AuditResult contract
+
+`AuditResult.findings[].evidence` is an array of plain strings only. Use entries like:
+
+```text
+src/foo.ts:42 - variable overwritten before use
+```
+
+`reviewed_ranges` now carries mechanical verification metadata:
+
+- `path`
+- `start`
+- `end`
+- `line_count`
+
+`line_count` must match the current total line count of the file. Ingestion also checks that any cited `affected_files` line span falls inside the declared `reviewed_ranges`.
+
+Worked example:
+
+```json
+[
+  {
+    "task_id": "src-api-auth:security",
+    "unit_id": "src-api-auth",
+    "pass_id": "pass:security",
+    "lens": "security",
+    "agent_role": "security-auditor",
+    "reviewed_ranges": [
+      {
+        "path": "src/api/auth.ts",
+        "start": 1,
+        "end": 48,
+        "line_count": 48
+      }
+    ],
+    "findings": [
+      {
+        "id": "finding-auth-1",
+        "title": "Authentication failures are not logged",
+        "category": "security",
+        "severity": "medium",
+        "confidence": "high",
+        "lens": "security",
+        "summary": "Rejected authentication attempts bypass structured audit logging.",
+        "affected_files": [
+          {
+            "path": "src/api/auth.ts",
+            "line_start": 18,
+            "line_end": 26
+          }
+        ],
+        "evidence": [
+          "src/api/auth.ts:18 - failure branch returns without emitting audit telemetry"
+        ]
+      }
+    ],
+    "notes": [
+      "Reviewed the entire file under the security lens."
+    ],
+    "requires_followup": false
+  }
+]
+```
+
+Workers should validate against these schemas before submission instead of discovering shape errors during ingestion.
 
 ## Audit state shape