auditor-lambda 0.1.0

package/dist/orchestrator/chunking.js

@@ -0,0 +1,13 @@
+export function chunkLineCount(totalLines, chunkSize = 200) {
+    if (totalLines <= 0) {
+        return [];
+    }
+    const ranges = [];
+    let start = 1;
+    while (start <= totalLines) {
+        const end = Math.min(start + chunkSize - 1, totalLines);
+        ranges.push({ start, end });
+        start = end + 1;
+    }
+    return ranges;
+}

package/dist/orchestrator/dependencyMap.d.ts

@@ -0,0 +1 @@
+export declare const ARTIFACT_DEPENDENCY_MAP: Record<string, string[]>;

package/dist/orchestrator/dependencyMap.js

@@ -0,0 +1,82 @@
+export const ARTIFACT_DEPENDENCY_MAP = {
+    "repo_manifest.json": [
+        "file_disposition.json",
+        "unit_manifest.json",
+        "surface_manifest.json",
+        "graph_bundle.json",
+        "critical_flows.json",
+        "risk_register.json",
+        "coverage_matrix.json",
+        "flow_coverage.json",
+        "audit_tasks.json",
+        "requeue_tasks.json",
+        "runtime_validation_tasks.json",
+        "runtime_validation_report.json",
+        "synthesis_report.json",
+    ],
+    "file_disposition.json": [
+        "unit_manifest.json",
+        "surface_manifest.json",
+        "graph_bundle.json",
+        "critical_flows.json",
+        "risk_register.json",
+        "coverage_matrix.json",
+        "flow_coverage.json",
+        "audit_tasks.json",
+        "requeue_tasks.json",
+        "runtime_validation_tasks.json",
+        "runtime_validation_report.json",
+        "synthesis_report.json",
+    ],
+    "unit_manifest.json": [
+        "risk_register.json",
+        "coverage_matrix.json",
+        "audit_tasks.json",
+        "runtime_validation_tasks.json",
+        "requeue_tasks.json",
+        "synthesis_report.json",
+    ],
+    "surface_manifest.json": [
+        "critical_flows.json",
+        "risk_register.json",
+        "runtime_validation_tasks.json",
+        "synthesis_report.json",
+    ],
+    "critical_flows.json": [
+        "flow_coverage.json",
+        "risk_register.json",
+        "audit_tasks.json",
+        "requeue_tasks.json",
+        "runtime_validation_tasks.json",
+        "runtime_validation_report.json",
+        "synthesis_report.json",
+    ],
+    "audit_results.jsonl": [
+        "coverage_matrix.json",
+        "flow_coverage.json",
+        "requeue_tasks.json",
+        "runtime_validation_tasks.json",
+        "runtime_validation_report.json",
+        "merged_findings.json",
+        "root_cause_clusters.json",
+        "synthesis_report.json",
+    ],
+    "coverage_matrix.json": [
+        "flow_coverage.json",
+        "requeue_tasks.json",
+        "runtime_validation_tasks.json",
+        "runtime_validation_report.json",
+        "synthesis_report.json",
+    ],
+    "flow_coverage.json": [
+        "requeue_tasks.json",
+        "runtime_validation_tasks.json",
+        "runtime_validation_report.json",
+        "synthesis_report.json",
+    ],
+    "runtime_validation_report.json": [
+        "merged_findings.json",
+        "root_cause_clusters.json",
+        "synthesis_report.json",
+    ],
+};

package/dist/orchestrator/executors.d.ts

@@ -0,0 +1,6 @@
+export interface ExecutorDefinition {
+    id: string;
+    obligation_ids: string[];
+    description: string;
+}
+export declare const EXECUTOR_REGISTRY: ExecutorDefinition[];

package/dist/orchestrator/executors.js

@@ -0,0 +1,52 @@
+export const EXECUTOR_REGISTRY = [
+    {
+        id: "intake_executor",
+        obligation_ids: ["repo_manifest", "file_disposition"],
+        description: "Create intake artifacts for repository discovery and disposition.",
+    },
+    {
+        id: "structure_executor",
+        obligation_ids: ["structure_artifacts"],
+        description: "Build structure artifacts such as units, surfaces, graphs, flows, and risk.",
+    },
+    {
+        id: "planning_executor",
+        obligation_ids: ["planning_artifacts"],
+        description: "Build coverage, tasks, runtime validation planning artifacts, and related planning outputs.",
+    },
+    {
+        id: "result_ingestion_executor",
+        obligation_ids: ["audit_results_ingested"],
+        description: "Ingest available audit result artifacts and refresh dependent coverage artifacts.",
+    },
+    {
+        id: "runtime_validation_update_executor",
+        obligation_ids: ["runtime_validation_current"],
+        description: "Merge runtime validation evidence updates when provided.",
+    },
+    {
+        id: "synthesis_executor",
+        obligation_ids: ["synthesis_current"],
+        description: "Refresh merged findings, clusters, and synthesis outputs.",
+    },
+    {
+        id: "external_analyzer_import_executor",
+        obligation_ids: [],
+        description: "Import normalized external analyzer results into the artifact set.",
+    },
+    {
+        id: "auto_fix_executor",
+        obligation_ids: ["auto_fixes_applied"],
+        description: "Run configured deterministic code formatters to apply surface-level fixes automatically.",
+    },
+    {
+        id: "syntax_resolution_executor",
+        obligation_ids: ["syntax_resolved"],
+        description: "Run deterministic static analysis/compilers and extract any remaining unfixable syntactical errors into external signals.",
+    },
+    {
+        id: "agent",
+        obligation_ids: ["audit_tasks_completed"],
+        description: "Pause the pipeline and delegate pending codebase review tasks or syntax resolutions to the active LLM agent.",
+    },
+];

package/dist/orchestrator/flowCoverage.d.ts

@@ -0,0 +1,4 @@
+import type { CoverageMatrix } from "../types.js";
+import type { FlowCoverageManifest } from "../types/flowCoverage.js";
+import type { CriticalFlowManifest } from "../types/flows.js";
+export declare function buildFlowCoverage(criticalFlows: CriticalFlowManifest, coverageMatrix: CoverageMatrix): FlowCoverageManifest;

package/dist/orchestrator/flowCoverage.js

@@ -0,0 +1,44 @@
+function lensSetForFlow(concerns) {
+    const allowed = [
+        "security",
+        "reliability",
+        "correctness",
+        "data_integrity",
+        "operability",
+        "performance",
+    ];
+    return concerns.filter((concern) => allowed.includes(concern));
+}
+export function buildFlowCoverage(criticalFlows, coverageMatrix) {
+    const flows = criticalFlows.flows.map((flow) => {
+        const required = lensSetForFlow(flow.concerns);
+        const completed = new Set();
+        for (const path of flow.paths) {
+            const record = coverageMatrix.files.find((file) => file.path === path);
+            if (!record || record.audit_status === "excluded") {
+                continue;
+            }
+            for (const lens of record.completed_lenses) {
+                if (required.includes(lens)) {
+                    completed.add(lens);
+                }
+            }
+        }
+        const completed_lenses = [...completed];
+        const status = required.length > 0 &&
+            required.every((lens) => completed_lenses.includes(lens))
+            ? "complete"
+            : completed_lenses.length > 0
+                ? "partial"
+                : "pending";
+        return {
+            flow_id: flow.id,
+            paths: flow.paths,
+            required_lenses: required,
+            completed_lenses,
+            status,
+            notes: [`Derived from ${flow.paths.length} path(s).`],
+        };
+    });
+    return { flows };
+}

package/dist/orchestrator/flowPlanning.d.ts

@@ -0,0 +1,3 @@
+import type { AuditTask } from "../types.js";
+import type { CriticalFlowManifest } from "../types/flows.js";
+export declare function buildFlowAwareTaskAugmentations(existingTasks: AuditTask[], criticalFlows: CriticalFlowManifest, lineIndex: Record<string, number>): AuditTask[];

package/dist/orchestrator/flowPlanning.js

@@ -0,0 +1,42 @@
+const DEFAULT_FLOW_LENS_PRIORITY = [
+    "security",
+    "reliability",
+    "correctness",
+];
+function normalizeTaskSignature(task) {
+    const path = task.file_paths.join(",");
+    const range = task.line_ranges?.map((r) => `${r.path}:${r.start}-${r.end}`).join(",") ??
+        "full";
+    return `${task.lens}|${path}|${range}`;
+}
+export function buildFlowAwareTaskAugmentations(existingTasks, criticalFlows, lineIndex) {
+    const seenTaskIds = new Set(existingTasks.map((task) => task.task_id));
+    const existingSignatures = new Set(existingTasks.map(normalizeTaskSignature));
+    const extraTasks = [];
+    for (const flow of criticalFlows.flows) {
+        const desiredLenses = flow.concerns.filter((concern) => DEFAULT_FLOW_LENS_PRIORITY.includes(concern));
+        for (const path of flow.paths) {
+            const totalLines = lineIndex[path] ?? 0;
+            for (const lens of desiredLenses) {
+                const candidate = {
+                    task_id: `flow:${flow.id}:${lens}:${path}`,
+                    unit_id: `flow:${flow.id}`,
+                    pass_id: `flow-pass:${lens}`,
+                    lens,
+                    file_paths: [path],
+                    line_ranges: totalLines > 0 ? [{ path, start: 1, end: totalLines }] : undefined,
+                    rationale: `Flow-aware audit for ${path} because it participates in critical flow ${flow.id} under the ${lens} lens.`,
+                };
+                const signature = normalizeTaskSignature(candidate);
+                if (seenTaskIds.has(candidate.task_id) ||
+                    existingSignatures.has(signature)) {
+                    continue;
+                }
+                extraTasks.push(candidate);
+                seenTaskIds.add(candidate.task_id);
+                existingSignatures.add(signature);
+            }
+        }
+    }
+    return extraTasks;
+}

package/dist/orchestrator/flowRequeue.d.ts

@@ -0,0 +1,5 @@
+import type { ExternalAnalyzerResults } from "../types/externalAnalyzer.js";
+import type { AuditTask } from "../types.js";
+import type { FlowCoverageManifest } from "../types/flowCoverage.js";
+import type { CriticalFlowManifest } from "../types/flows.js";
+export declare function buildFlowRequeueTasks(criticalFlows: CriticalFlowManifest, flowCoverage: FlowCoverageManifest, externalAnalyzerResults?: ExternalAnalyzerResults): AuditTask[];

package/dist/orchestrator/flowRequeue.js

@@ -0,0 +1,58 @@
+function isLens(value) {
+    return [
+        "correctness",
+        "architecture",
+        "maintainability",
+        "security",
+        "reliability",
+        "performance",
+        "data_integrity",
+        "tests",
+        "operability",
+        "config_deployment",
+    ].includes(value);
+}
+function taskPriority(hasExternalSignal, lens) {
+    if (hasExternalSignal &&
+        (lens === "security" || lens === "data_integrity" || lens === "reliability")) {
+        return "high";
+    }
+    return hasExternalSignal ? "medium" : "low";
+}
+export function buildFlowRequeueTasks(criticalFlows, flowCoverage, externalAnalyzerResults) {
+    const flowMap = new Map(criticalFlows.flows.map((flow) => [flow.id, flow]));
+    const tasks = [];
+    const seen = new Set();
+    const externalPaths = new Set((externalAnalyzerResults?.results ?? []).map((item) => item.path));
+    for (const record of flowCoverage.flows) {
+        const flow = flowMap.get(record.flow_id);
+        if (!flow) {
+            continue;
+        }
+        const missingLenses = record.required_lenses.filter((lens) => !record.completed_lenses.includes(lens));
+        for (const lensName of missingLenses) {
+            if (!isLens(lensName)) {
+                continue;
+            }
+            for (const path of flow.paths) {
+                const signature = `${flow.id}|${lensName}|${path}`;
+                if (seen.has(signature)) {
+                    continue;
+                }
+                seen.add(signature);
+                const hasExternalSignal = externalPaths.has(path);
+                tasks.push({
+                    task_id: `flow-requeue:${flow.id}:${lensName}:${path}`,
+                    unit_id: flow.id,
+                    pass_id: `flow-requeue:${lensName}`,
+                    lens: lensName,
+                    file_paths: [path],
+                    rationale: `Requeue ${path} because critical flow ${flow.id} is still missing the ${lensName} lens.${hasExternalSignal ? " External analyzer signals make this follow-up higher priority." : ""}`,
+                    priority: taskPriority(hasExternalSignal, lensName),
+                    tags: hasExternalSignal ? ["external_analyzer_signal"] : [],
+                });
+            }
+        }
+    }
+    return tasks;
+}

package/dist/orchestrator/internalExecutors.d.ts

@@ -0,0 +1,16 @@
+import type { ArtifactBundle } from "../io/artifacts.js";
+import type { AuditResult } from "../types.js";
+import type { RuntimeValidationReport } from "../types/runtimeValidation.js";
+import type { ExternalAnalyzerResults } from "../types/externalAnalyzer.js";
+export interface ExecutorRunResult {
+    updated: ArtifactBundle;
+    artifacts_written: string[];
+    progress_summary: string;
+}
+export declare function runIntakeExecutor(bundle: ArtifactBundle, root: string): Promise<ExecutorRunResult>;
+export declare function runStructureExecutor(bundle: ArtifactBundle): ExecutorRunResult;
+export declare function runPlanningExecutor(bundle: ArtifactBundle, lineIndex?: Record<string, number>): ExecutorRunResult;
+export declare function runResultIngestionExecutor(bundle: ArtifactBundle, results: AuditResult[]): ExecutorRunResult;
+export declare function runRuntimeValidationUpdateExecutor(bundle: ArtifactBundle, updates: RuntimeValidationReport): ExecutorRunResult;
+export declare function runSynthesisExecutor(bundle: ArtifactBundle, results?: AuditResult[]): ExecutorRunResult;
+export declare function runExternalAnalyzerImportExecutor(bundle: ArtifactBundle, externalResults: ExternalAnalyzerResults): ExecutorRunResult;

package/dist/orchestrator/internalExecutors.js

@@ -0,0 +1,212 @@
+import { buildFileDisposition } from "../extractors/disposition.js";
+import { buildGraphBundle } from "../extractors/graph.js";
+import { buildCriticalFlowManifest } from "../extractors/flows.js";
+import { buildRiskRegister } from "../extractors/risk.js";
+import { buildSurfaceManifest } from "../extractors/surfaces.js";
+import { initializeCoverageFromPlan } from "./planning.js";
+import { buildFlowCoverage } from "./flowCoverage.js";
+import { buildFlowAwareTaskAugmentations } from "./flowPlanning.js";
+import { buildRequeuePayload } from "./requeueCommand.js";
+import { buildRuntimeValidationTasks, buildPlaceholderRuntimeValidationReport, mergeRuntimeValidationReport, } from "./runtimeValidation.js";
+import { buildSynthesisReport } from "../reporting/synthesis.js";
+import { buildChunkedAuditTasks, buildExternalSignalTasks, } from "./taskBuilder.js";
+import { buildUnitManifest } from "./unitBuilder.js";
+import { buildRepoManifestFromFs } from "../extractors/fsIntake.js";
+import { loadIgnoreFile } from "../extractors/ignore.js";
+import { ingestAuditResults } from "./resultIngestion.js";
+import { updateRuntimeValidationReport } from "./runtimeValidationUpdate.js";
+function preserveOrPlaceholder(tasks, existing) {
+    return existing
+        ? mergeRuntimeValidationReport(tasks, existing)
+        : buildPlaceholderRuntimeValidationReport(tasks);
+}
+export async function runIntakeExecutor(bundle, root) {
+    const ignore = await loadIgnoreFile(root);
+    const repoManifest = await buildRepoManifestFromFs({
+        root,
+        ignore,
+        hash_files: false,
+    });
+    const disposition = buildFileDisposition(repoManifest);
+    return {
+        updated: {
+            ...bundle,
+            repo_manifest: repoManifest,
+            file_disposition: disposition,
+        },
+        artifacts_written: ["repo_manifest.json", "file_disposition.json"],
+        progress_summary: `Created intake artifacts for ${repoManifest.files.length} files.`,
+    };
+}
+export function runStructureExecutor(bundle) {
+    if (!bundle.repo_manifest) {
+        throw new Error("Cannot run structure executor without repo_manifest");
+    }
+    const externalAnalyzerResults = bundle.external_analyzer_results;
+    const disposition = bundle.file_disposition ?? buildFileDisposition(bundle.repo_manifest);
+    const unitManifest = buildUnitManifest(bundle.repo_manifest, disposition);
+    const surfaceManifest = buildSurfaceManifest(bundle.repo_manifest, disposition);
+    const criticalFlows = buildCriticalFlowManifest(bundle.repo_manifest, surfaceManifest, disposition);
+    const graphBundle = buildGraphBundle(bundle.repo_manifest, disposition);
+    const riskRegister = buildRiskRegister(unitManifest, criticalFlows, externalAnalyzerResults);
+    return {
+        updated: {
+            ...bundle,
+            file_disposition: disposition,
+            unit_manifest: unitManifest,
+            surface_manifest: surfaceManifest,
+            graph_bundle: graphBundle,
+            critical_flows: criticalFlows,
+            risk_register: riskRegister,
+        },
+        artifacts_written: [
+            "file_disposition.json",
+            "unit_manifest.json",
+            "surface_manifest.json",
+            "graph_bundle.json",
+            "critical_flows.json",
+            "risk_register.json",
+        ],
+        progress_summary: `Built structure artifacts for ${unitManifest.units.length} units and ${criticalFlows.flows.length} critical flows.`,
+    };
+}
+export function runPlanningExecutor(bundle, lineIndex = {}) {
+    if (!bundle.repo_manifest) {
+        throw new Error("Cannot run planning executor without repo_manifest");
+    }
+    if (!bundle.file_disposition ||
+        !bundle.unit_manifest ||
+        !bundle.surface_manifest ||
+        !bundle.critical_flows ||
+        !bundle.risk_register) {
+        throw new Error("Cannot run planning executor without current structure artifacts");
+    }
+    const externalAnalyzerResults = bundle.external_analyzer_results;
+    const coverage = initializeCoverageFromPlan(bundle.repo_manifest, bundle.unit_manifest, bundle.file_disposition, externalAnalyzerResults);
+    const flowCoverage = buildFlowCoverage(bundle.critical_flows, coverage);
+    const runtimeValidationTasks = buildRuntimeValidationTasks(bundle.unit_manifest, bundle.critical_flows, flowCoverage);
+    const runtimeValidationReport = preserveOrPlaceholder(runtimeValidationTasks, bundle.runtime_validation_report);
+    const baseTasks = buildChunkedAuditTasks(bundle.unit_manifest, lineIndex, {
+        chunk_size: 200,
+        external_analyzer_results: externalAnalyzerResults,
+    });
+    const analyzerTasks = buildExternalSignalTasks(coverage, lineIndex, externalAnalyzerResults);
+    const flowTasks = buildFlowAwareTaskAugmentations([...baseTasks, ...analyzerTasks], bundle.critical_flows, lineIndex);
+    const auditTasks = [...baseTasks, ...analyzerTasks, ...flowTasks];
+    const requeuePayload = buildRequeuePayload(coverage, bundle.critical_flows, flowCoverage, externalAnalyzerResults);
+    return {
+        updated: {
+            ...bundle,
+            coverage_matrix: coverage,
+            flow_coverage: flowCoverage,
+            runtime_validation_tasks: runtimeValidationTasks,
+            runtime_validation_report: runtimeValidationReport,
+            audit_tasks: auditTasks,
+            requeue_tasks: requeuePayload.tasks,
+        },
+        artifacts_written: [
+            "coverage_matrix.json",
+            "flow_coverage.json",
+            "runtime_validation_tasks.json",
+            "runtime_validation_report.json",
+            "audit_tasks.json",
+            "requeue_tasks.json",
+        ],
+        progress_summary: `Built planning artifacts; generated ${auditTasks.length} tasks and ${requeuePayload.task_count} requeue tasks.${externalAnalyzerResults?.results.length ? ` External analyzer signals influenced lenses and produced ${analyzerTasks.length} dedicated follow-up task(s).` : ""}`,
+    };
+}
+export function runResultIngestionExecutor(bundle, results) {
+    if (!bundle.coverage_matrix) {
+        throw new Error("Cannot ingest results without coverage_matrix");
+    }
+    ingestAuditResults(bundle.coverage_matrix, results);
+    const flowCoverage = bundle.critical_flows
+        ? buildFlowCoverage(bundle.critical_flows, bundle.coverage_matrix)
+        : bundle.flow_coverage;
+    const runtimeValidationTasks = bundle.unit_manifest
+        ? buildRuntimeValidationTasks(bundle.unit_manifest, bundle.critical_flows, flowCoverage)
+        : bundle.runtime_validation_tasks;
+    const runtimeValidationReport = runtimeValidationTasks
+        ? preserveOrPlaceholder(runtimeValidationTasks, bundle.runtime_validation_report)
+        : bundle.runtime_validation_report;
+    const requeuePayload = bundle.coverage_matrix
+        ? buildRequeuePayload(bundle.coverage_matrix, bundle.critical_flows, flowCoverage, bundle.external_analyzer_results)
+        : { tasks: [], task_count: 0 };
+    const mergedResults = [...(bundle.audit_results ?? []), ...results];
+    const synthesisReport = buildSynthesisReport(mergedResults, runtimeValidationReport, bundle.external_analyzer_results);
+    return {
+        updated: {
+            ...bundle,
+            coverage_matrix: bundle.coverage_matrix,
+            flow_coverage: flowCoverage,
+            runtime_validation_tasks: runtimeValidationTasks,
+            runtime_validation_report: runtimeValidationReport,
+            audit_results: mergedResults,
+            requeue_tasks: requeuePayload.tasks,
+            synthesis_report: synthesisReport,
+        },
+        artifacts_written: [
+            "coverage_matrix.json",
+            "flow_coverage.json",
+            "runtime_validation_tasks.json",
+            "runtime_validation_report.json",
+            "audit_results.jsonl",
+            "requeue_tasks.json",
+            "synthesis_report.json",
+        ],
+        progress_summary: `Ingested ${results.length} audit result entries and refreshed dependent artifacts.`,
+    };
+}
+export function runRuntimeValidationUpdateExecutor(bundle, updates) {
+    if (!bundle.runtime_validation_tasks) {
+        throw new Error("Cannot update runtime validation without runtime_validation_tasks");
+    }
+    const existingReport = bundle.runtime_validation_report ??
+        buildPlaceholderRuntimeValidationReport(bundle.runtime_validation_tasks);
+    const mergedReport = updateRuntimeValidationReport(bundle.runtime_validation_tasks, existingReport, updates);
+    const synthesisReport = buildSynthesisReport(bundle.audit_results ?? [], mergedReport, bundle.external_analyzer_results);
+    return {
+        updated: {
+            ...bundle,
+            runtime_validation_report: mergedReport,
+            synthesis_report: synthesisReport,
+        },
+        artifacts_written: [
+            "runtime_validation_report.json",
+            "synthesis_report.json",
+        ],
+        progress_summary: `Merged ${updates.results.length} runtime validation updates.`,
+    };
+}
+export function runSynthesisExecutor(bundle, results) {
+    const finalResults = results ?? bundle.audit_results ?? [];
+    const synthesisReport = buildSynthesisReport(finalResults, bundle.runtime_validation_report, bundle.external_analyzer_results);
+    const mergedFindings = { findings: synthesisReport.merged_findings };
+    const rootCauseClusters = { clusters: synthesisReport.root_cause_clusters };
+    return {
+        updated: {
+            ...bundle,
+            audit_results: finalResults,
+            merged_findings: mergedFindings,
+            root_cause_clusters: rootCauseClusters,
+            synthesis_report: synthesisReport,
+        },
+        artifacts_written: [
+            "merged_findings.json",
+            "root_cause_clusters.json",
+            "synthesis_report.json",
+        ],
+        progress_summary: `Refreshed synthesis for ${finalResults.length} audit result entries.`,
+    };
+}
+export function runExternalAnalyzerImportExecutor(bundle, externalResults) {
+    const summary = `Imported ${externalResults.results.length} normalized findings from ${externalResults.tool}.`;
+    return {
+        updated: {
+            ...bundle,
+            external_analyzer_results: externalResults,
+        },
+        artifacts_written: ["external_analyzer_results.json"],
+        progress_summary: summary,
+    };
+}

package/dist/orchestrator/nextStep.d.ts

@@ -0,0 +1,9 @@
+import type { ArtifactBundle } from "../io/artifacts.js";
+import type { AuditState } from "../types/auditState.js";
+export interface NextStepDecision {
+    state: AuditState;
+    selected_obligation: string | null;
+    selected_executor: string | null;
+    reason: string;
+}
+export declare function decideNextStep(bundle: ArtifactBundle): NextStepDecision;

package/dist/orchestrator/nextStep.js

@@ -0,0 +1,44 @@
+import { EXECUTOR_REGISTRY } from "./executors.js";
+import { deriveAuditState } from "./state.js";
+const PRIORITY = [
+    "repo_manifest",
+    "file_disposition",
+    "auto_fixes_applied",
+    "syntax_resolved",
+    "structure_artifacts",
+    "planning_artifacts",
+    "audit_tasks_completed",
+    "audit_results_ingested",
+    "runtime_validation_current",
+    "synthesis_current",
+];
+function findObligation(obligations) {
+    for (const id of PRIORITY) {
+        const item = obligations.find((o) => o.id === id);
+        if (item && (item.state === "missing" || item.state === "stale")) {
+            return item;
+        }
+    }
+    return undefined;
+}
+export function decideNextStep(bundle) {
+    const state = deriveAuditState(bundle);
+    const next = findObligation(state.obligations);
+    if (!next) {
+        return {
+            state,
+            selected_obligation: null,
+            selected_executor: null,
+            reason: state.status === "complete"
+                ? "All known obligations are currently satisfied."
+                : "No actionable missing obligation was found.",
+        };
+    }
+    const executor = EXECUTOR_REGISTRY.find((item) => item.obligation_ids.includes(next.id));
+    return {
+        state,
+        selected_obligation: next.id,
+        selected_executor: executor?.id ?? null,
+        reason: `Selected highest-priority actionable obligation ${next.id}.`,
+    };
+}

package/dist/orchestrator/planning.d.ts

@@ -0,0 +1,4 @@
+import type { CoverageMatrix, RepoManifest, UnitManifest } from "../types.js";
+import type { FileDisposition } from "../types/disposition.js";
+import type { ExternalAnalyzerResults } from "../types/externalAnalyzer.js";
+export declare function initializeCoverageFromPlan(repoManifest: RepoManifest, unitManifest: UnitManifest, disposition: FileDisposition, externalAnalyzerResults?: ExternalAnalyzerResults): CoverageMatrix;