@dev-tren/mapd 0.21.0

package/src/core/regression.js

@@ -0,0 +1,193 @@
+/**
+ * regression.js — Baseline diffing.
+ *
+ * `mapd baseline` snapshots the scored graph into .mapd/baseline.json.
+ * `mapd check` re-maps and diffs. Findings are deterministic facts about the
+ * graph delta; severity is rule-derived. The optional LLM layer may *explain*
+ * a finding or *propose* a fix, but it may not create, suppress, or rescore one.
+ *
+ * Approval flow: findings are written to .mapd/findings.json with
+ * status "awaiting-approval". Nothing is ever auto-fixed.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+const MAPD_DIR = ".mapd";
+
+/** Bump when the graph shape changes in a way that invalidates old baselines. */
+export const BASELINE_SCHEMA = 4; // 3 = honest testPresence; 4 = per-workflow resolutionRate + repo-level coverageOfRepo — scores shift, old baselines aren't comparable
+
+export function baselinePath(rootDir) {
+  return path.join(rootDir, MAPD_DIR, "baseline.json");
+}
+
+export function saveBaseline(rootDir, graph) {
+  const dir = path.join(rootDir, MAPD_DIR);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(baselinePath(rootDir), JSON.stringify({ ...graph, mapdSchema: BASELINE_SCHEMA }, null, 2));
+  return baselinePath(rootDir);
+}
+
+/** Returns { graph, schemaMismatch } — a mismatch means re-baseline, not silent diffing. */
+export function loadBaseline(rootDir) {
+  try {
+    const graph = JSON.parse(fs.readFileSync(baselinePath(rootDir), "utf8"));
+    return { graph, schemaMismatch: graph.mapdSchema !== BASELINE_SCHEMA ? { found: graph.mapdSchema ?? 1, expected: BASELINE_SCHEMA } : null };
+  } catch {
+    return null;
+  }
+}
+
+const fnKey = (f) => f; // "file#name" ids already unique
+
+export function diffGraphs(baseline, current) {
+  const findings = [];
+  const add = (severity, kind, detail, evidence) =>
+    findings.push({ severity, kind, detail, evidence, status: "awaiting-approval" });
+
+  const baseWf = new Map(baseline.workflows.map((w) => [w.id, w]));
+  const curWf = new Map(current.workflows.map((w) => [w.id, w]));
+
+  // 1. Removed / added workflows
+  for (const [id, w] of baseWf) {
+    if (!curWf.has(id)) add("high", "workflow-removed",
+      `Workflow ${id} (entry: ${w.entry.file}) no longer exists.`,
+      { baselineFiles: w.files.length, workflow: id });
+  }
+  for (const [id, w] of curWf) {
+    if (!baseWf.has(id)) add("info", "workflow-added",
+      `New workflow ${id} detected (entry: ${w.entry.file}).`,
+      { files: w.files.length });
+  }
+
+  // 2. Confidence regressions (derived score dropped materially)
+  for (const [id, cw] of curWf) {
+    const bw = baseWf.get(id);
+    if (!bw?.confidence || !cw.confidence) continue;
+    const drop = bw.confidence.score - cw.confidence.score;
+    if (drop >= 0.1) {
+      // find which signals degraded — evidence, not narrative
+      const degraded = Object.entries(cw.confidence.signals)
+        .filter(([k, s]) => {
+          const b = bw.confidence.signals[k];
+          return b && s.value !== null && b.value !== null && b.value - s.value >= 0.05;
+        })
+        .map(([k, s]) => ({ signal: k, from: bw.confidence.signals[k].value, to: s.value }));
+      add(drop >= 0.25 ? "high" : "medium", "confidence-regression",
+        `Workflow ${id} confidence dropped ${bw.confidence.score} → ${cw.confidence.score}.`,
+        { degradedSignals: degraded, workflow: id });
+    }
+  }
+
+  // 3. Exported-surface breaks (removed exports = potential breaking change)
+  for (const [id, cw] of curWf) {
+    const bw = baseWf.get(id);
+    if (!bw) continue;
+    const removed = bw.exportedSurface.filter((e) => !cw.exportedSurface.includes(e));
+    if (!removed.length) continue;
+    // name the file(s) that exported them at baseline, so evidence/impact can point at real code
+    const gone = new Set(removed);
+    const definers = baseline.files
+      .filter((f) => bw.files.includes(f.file) && (f.exports ?? []).some((e) => gone.has(e)))
+      .map((f) => f.file);
+    add("high", "export-removed",
+      `Workflow ${id} removed exported symbols: ${removed.join(", ")}.`,
+      { removed, workflow: id, files: definers });
+  }
+
+  // 4. Call-resolution degradation (new dangling call edges)
+  const baseUnresolved = baseline.stats.totalCalls - baseline.stats.resolvedCalls;
+  const curUnresolved = current.stats.totalCalls - current.stats.resolvedCalls;
+  if (curUnresolved > baseUnresolved + 5 &&
+      current.stats.callResolutionRate < baseline.stats.callResolutionRate - 0.03) {
+    add("medium", "resolution-degradation",
+      `Unresolved call edges grew ${baseUnresolved} → ${curUnresolved}; resolution rate ` +
+      `${baseline.stats.callResolutionRate.toFixed(3)} → ${current.stats.callResolutionRate.toFixed(3)}.`,
+      { baseUnresolved, curUnresolved });
+  }
+
+  // 5. New orphans (files that fell out of every workflow)
+  const newOrphans = current.orphans.filter((f) => !baseline.orphans.includes(f));
+  if (newOrphans.length) add("low", "new-orphans",
+    `${newOrphans.length} file(s) are no longer reachable from any entry point.`,
+    { files: newOrphans });
+
+  // 6. New parse failures
+  const baseUnparsed = new Set(baseline.files.filter((f) => !f.parsed).map((f) => f.file));
+  const newUnparsed = current.files.filter((f) => !f.parsed && !baseUnparsed.has(f.file)).map((f) => f.file);
+  if (newUnparsed.length) add("high", "parse-failure",
+    `File(s) newly failing to parse: ${newUnparsed.join(", ")}.`, { files: newUnparsed });
+
+  return findings;
+}
+
+/**
+ * Merge a fresh scan's findings against a previous report's so the finding
+ * lifecycle closes itself instead of silently forgetting. Shared by `mapd
+ * check` (findings.json, kind+detail identity) and `mapd modernize`
+ * (modernize-<mode>.json, rule+detail identity):
+ *
+ * - a previously open (awaiting-approval/approved) finding that no longer
+ *   reproduces is carried forward as status "resolved" with the re-scan as
+ *   evidence — never just dropped;
+ * - a finding that still reproduces and was already dismissed KEEPS its
+ *   dismissal (Map'd does not re-nag a human decision) — same for an existing
+ *   resolved/applied record;
+ * - already-terminal entries (resolved/dismissed) are carried as audit trail.
+ *
+ * `key` is the content-identity function (must match what review.js hashes
+ * into queue IDs for that report type). Returns { findings, resolvedNow }.
+ */
+export function mergeFindingLifecycle(newFindings, prevFindings, key, resolvedBy) {
+  const prevByKey = new Map((prevFindings ?? []).map((f) => [key(f), f]));
+  const newKeys = new Set(newFindings.map(key));
+
+  const merged = newFindings.map((f) => {
+    const old = prevByKey.get(key(f));
+    if (old && old.status && old.status !== "awaiting-approval") {
+      // still reproduces, but a human (or an applied fix) already decided —
+      // preserve that decision and its stamp instead of resurrecting the item
+      const carried = { ...f, status: old.status };
+      for (const k of ["dismissed", "approved", "resolved", "applied"]) if (old[k]) carried[k] = old[k];
+      return carried;
+    }
+    return f;
+  });
+
+  let resolvedNow = 0;
+  for (const old of prevFindings ?? []) {
+    if (key(old) && newKeys.has(key(old))) continue;
+    if (old.status === "awaiting-approval" || old.status === "approved") {
+      merged.push({
+        ...old,
+        status: "resolved",
+        resolved: { at: new Date().toISOString(), by: resolvedBy, reason: "not reproduced by re-scan against the current tree" },
+      });
+      resolvedNow++;
+    } else if (old.status === "resolved" || old.status === "dismissed") {
+      merged.push(old); // terminal states stay visible as audit trail
+    }
+  }
+  return { findings: merged, resolvedNow };
+}
+
+/** Content identity for a check finding — the same kind+detail key review.js hashes into queue IDs. */
+const findingKey = (f) => `${f.kind}:${f.detail}`;
+
+/**
+ * Persist a check run's findings through mergeFindingLifecycle (see above).
+ * Returns { path, resolvedNow } — resolvedNow is how many open findings this
+ * run auto-resolved, for callers to disclose.
+ */
+export function saveFindings(rootDir, findings) {
+  const p = path.join(rootDir, MAPD_DIR, "findings.json");
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+
+  let prev = null;
+  try { prev = JSON.parse(fs.readFileSync(p, "utf8")); } catch { /* first run */ }
+
+  const { findings: merged, resolvedNow } = mergeFindingLifecycle(findings, prev?.findings, findingKey, "mapd check");
+  fs.writeFileSync(p, JSON.stringify({ generatedAt: new Date().toISOString(), findings: merged }, null, 2));
+  return { path: p, resolvedNow };
+}

package/src/core/resolution.js

@@ -0,0 +1,92 @@
+/**
+ * resolution.js — `mapd resolution`. Call resolution is 25% of the confidence
+ * score, but the raw rate doesn't tell you WHERE to act. This ranks the call
+ * sites dragging it down by real blast radius, names the anonymous functions
+ * that hide edges, and — crucially — does NOT treat calls into external
+ * packages as your problem to fix.
+ *
+ * All deterministic: it reads the call edges the graph already classified
+ * (external / cross-file / dynamic / unresolved / local / global) plus the
+ * parsed function list. No guessing which call "should" resolve.
+ */
+
+const fileOf = (ref) => String(ref).split("#")[0];
+const ANON = /^<anon[:>]/;
+
+export function analyzeResolution(graph, { top = 10 } = {}) {
+  const edges = graph.callEdges ?? [];
+  const byType = {};
+  for (const e of edges) byType[e.resolution] = (byType[e.resolution] ?? 0) + 1;
+
+  const wfByFile = new Map();
+  for (const w of graph.workflows) for (const f of w.files) {
+    if (!wfByFile.has(f)) wfByFile.set(f, []);
+    wfByFile.get(f).push(w.id);
+  }
+
+  // Hotspots: files with the most fixable (dynamic + unresolved) call sites,
+  // ranked by count × workflow blast radius. External/local/global are excluded —
+  // external is not yours to fix, local/global already resolve.
+  const fixable = edges.filter((e) => e.resolution === "dynamic" || e.resolution === "unresolved");
+  const perFile = new Map();
+  for (const e of fixable) {
+    const f = fileOf(e.from);
+    const rec = perFile.get(f) ?? { file: f, dynamic: 0, unresolved: 0, receivers: new Set() };
+    if (e.resolution === "dynamic") { rec.dynamic++; if (e.dynamicReceiver) rec.receivers.add(e.dynamicReceiver); }
+    else rec.unresolved++;
+    perFile.set(f, rec);
+  }
+  const hotspots = [...perFile.values()].map((r) => {
+    const workflows = wfByFile.get(r.file) ?? [];
+    const count = r.dynamic + r.unresolved;
+    return {
+      file: r.file, dynamic: r.dynamic, unresolved: r.unresolved, count,
+      workflows, blastRadius: workflows.length,
+      receivers: [...r.receivers].slice(0, 6),
+      score: count * Math.max(1, workflows.length), // rank: volume × reach
+    };
+  }).sort((a, b) => b.score - a.score).slice(0, top);
+
+  // Anonymous functions hide call edges (an unnamed callee can't be resolved).
+  const anon = graph.files.map((f) => ({
+    file: f.file,
+    count: (f.functions ?? []).filter((fn) => !fn.name || ANON.test(fn.name)).length,
+  })).filter((x) => x.count > 0).sort((a, b) => b.count - a.count).slice(0, top);
+
+  const totalCalls = graph.stats.totalCalls ?? edges.length;
+  const external = byType.external ?? 0;
+
+  return {
+    summary: {
+      totalCalls,
+      resolutionRate: graph.stats.callResolutionRate ?? null,
+      byType,
+      fixable: fixable.length,
+      externalExcused: external,
+    },
+    hotspots,
+    anonymous: anon,
+    anonymousTotal: graph.files.reduce((a, f) => a + (f.functions ?? []).filter((fn) => !fn.name || ANON.test(fn.name)).length, 0),
+  };
+}
+
+export function renderResolution(data, theme) {
+  const { bold, dim, red, green, yellow, cyan } = theme;
+  const s = data.summary;
+  const lines = [`\n${bold("Call resolution")} — rate ${s.resolutionRate != null ? cyan(s.resolutionRate.toFixed(3)) : "n/a"} over ${s.totalCalls} call(s)`];
+  const order = ["cross-file", "local", "global", "dynamic", "unresolved", "external"];
+  lines.push("  by type: " + order.filter((t) => s.byType[t]).map((t) => `${t} ${s.byType[t]}`).join(" · "));
+  lines.push(dim(`  ${s.externalExcused} external call(s) into packages are NOT counted against you — Map'd can't resolve into node_modules and doesn't pretend to.`));
+
+  lines.push(`\n${bold("  Resolution hotspots")} ${dim("(fixable call sites × workflow blast radius)")}`);
+  if (!data.hotspots.length) lines.push(green("    None — every fixable call already resolves."));
+  for (const h of data.hotspots) {
+    lines.push(`    ${bold(h.file)}  ${yellow(`${h.count} fixable`)} ${dim(`(${h.dynamic} dynamic, ${h.unresolved} unresolved; reaches ${h.blastRadius} workflow(s))`)}`);
+    if (h.receivers.length) lines.push(dim(`        dynamic receivers: ${h.receivers.join(", ")} — if a receiver resolves to a constant path it can be made static; if it's computed at runtime, keep it lazy and consider annotating dynamically-loaded.`));
+  }
+
+  lines.push(`\n${bold("  Anonymous functions")} ${dim(`(${data.anonymousTotal} total — naming them lets callers resolve)`)}`);
+  if (!data.anonymous.length) lines.push(green("    None."));
+  for (const a of data.anonymous) lines.push(`    ${a.file}  ${dim(`${a.count} anonymous`)}`);
+  return lines.join("\n");
+}

package/src/core/retry.js

@@ -0,0 +1,61 @@
+/**
+ * retry.js — general-purpose retry engine with structured gate feedback.
+ * Used by fix.js (mapd fix), and available to chat/mcp/modernize proposal
+ * flows for the same gate-fail -> structured-feedback -> retry loop.
+ *
+ * The deterministic gates remain the final judge — this module never lets an
+ * attempt mark itself successful; success is `gates.every(g => g.passed)`.
+ *
+ * Stopping rules: all gates pass; maxAttempts reached; the same set of failed
+ * gates repeats with no new information (no point burning another attempt).
+ */
+
+/** Turn one attempt's failed gates into one deterministic feedback sentence. */
+export function buildRetryFeedback(gateResults) {
+  const failed = gateResults.filter((g) => !g.passed);
+  if (!failed.length) return null;
+  const parts = failed.map((g) => {
+    const bits = [];
+    if (g.missing?.length) bits.push(`missing: ${g.missing.join(", ")}`);
+    if (g.exitCode != null) bits.push(`exit code ${g.exitCode}`);
+    if (g.stderr) bits.push(`stderr: ${g.stderr.slice(0, 300).trim()}`);
+    return `${g.gate} failed${bits.length ? ` (${bits.join("; ")})` : ""}`;
+  });
+  return `${parts.join(". ")}. Do not repeat the same mistake — address exactly this feedback.`;
+}
+
+function failedGateSignature(gateResults) {
+  return gateResults.filter((g) => !g.passed).map((g) => g.gate).sort().join(",");
+}
+
+/**
+ * `attemptFn({attempt, feedback})` must return `{ gates, ...rest }`.
+ * Returns `{ success, attempts, finalAttempt, stopReason }`.
+ * `stopReason` is one of: "passed", "max-attempts", "repeated-failure".
+ */
+export async function runWithRetry({ attemptFn, maxAttempts = 2, onAttemptResult } = {}) {
+  const attempts = [];
+  let previousFeedback = null;
+  let previousSignature = null;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    const result = await attemptFn({ attempt, feedback: previousFeedback });
+    const gates = result.gates ?? [];
+    const passed = gates.length > 0 && gates.every((g) => g.passed);
+    const feedbackForRetry = passed ? null : buildRetryFeedback(gates);
+    const record = { attempt, gates, passed, feedbackForRetry, result };
+    attempts.push(record);
+    onAttemptResult?.(record);
+
+    if (passed) return { success: true, attempts, finalAttempt: record, stopReason: "passed" };
+
+    const signature = failedGateSignature(gates);
+    if (previousSignature !== null && signature === previousSignature && signature !== "") {
+      return { success: false, attempts, finalAttempt: record, stopReason: "repeated-failure" };
+    }
+    previousSignature = signature;
+    previousFeedback = feedbackForRetry;
+  }
+
+  return { success: false, attempts, finalAttempt: attempts[attempts.length - 1], stopReason: "max-attempts" };
+}

package/src/core/review.js

@@ -0,0 +1,219 @@
+/**
+ * review.js — the human half of "autonomous routing, human approval."
+ *
+ * Every Map'd function emits items with status "awaiting-approval" into
+ * .mapd/*.json. This module presents them as one queue with stable IDs and
+ * performs the only two state transitions a human can make:
+ *
+ *   approve — for an integration proposal, writes the verified merged source
+ *             into the working tree (the one place approval has a side effect,
+ *             because the artifact IS a file). For check/modernize findings,
+ *             marks "approved" — a work-queue signal for the fix pass.
+ *   dismiss — marks "dismissed" with an optional reason; item leaves the queue
+ *             but stays in the report (audit trail, never deleted).
+ *
+ * IDs are content-derived (kind + file/rule hash), so they are stable across
+ * re-listing but change if the underlying finding changes — you can never
+ * approve a stale version of an item by accident.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { applyRealTreeWrite } from "./changes.js";
+import { checkReportFreshness } from "./staleness.js";
+
+const MAPD = ".mapd";
+
+const id8 = (s) => crypto.createHash("sha256").update(s).digest("hex").slice(0, 8);
+
+function readJson(p) {
+  try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch { return null; }
+}
+
+/** Collect every reviewable item across all report files. */
+export function loadQueue(rootDir) {
+  const dir = path.join(rootDir, MAPD);
+  const items = [];
+
+  // findings from `mapd check`
+  const findingsPath = path.join(dir, "findings.json");
+  const findings = readJson(findingsPath);
+  findings?.findings?.forEach((f, i) => {
+    items.push({
+      id: id8(`check:${f.kind}:${f.detail}`),
+      source: "check", file: findingsPath, index: i,
+      kind: f.kind, severity: f.severity, detail: f.detail, status: f.status,
+      hasProposal: !!f.proposal,
+    });
+  });
+
+  // modernization reports (any mode)
+  for (const mode of ["light", "medium", "heavy"]) {
+    const p = path.join(dir, `modernize-${mode}.json`);
+    const rep = readJson(p);
+    rep?.findings?.forEach((f, i) => {
+      if (f.informational) return;
+      items.push({
+        id: id8(`modernize:${f.rule}:${f.detail}`),
+        source: `modernize-${mode}`, file: p, index: i,
+        kind: f.rule, severity: null,
+        priority: f.operationalImpact?.priority ?? null,
+        detail: f.detail, status: f.status,
+        hasProposal: !!f.migrationPlan,
+      });
+    });
+  }
+
+  // integration reports
+  const intDir = path.join(dir, "integration");
+  if (fs.existsSync(intDir)) {
+    for (const name of fs.readdirSync(intDir).filter((n) => n.startsWith("report-") && n.endsWith(".json"))) {
+      const p = path.join(intDir, name);
+      const rep = readJson(p);
+      rep?.conflicts?.forEach((c, i) => {
+        if (!c.proposal) return;
+        items.push({
+          id: id8(`integrate:${rep.branch}:${c.file}`),
+          source: `integrate:${rep.branch}`, file: p, index: i,
+          kind: c.classification, severity: null,
+          score: c.proposal.resolutionScore?.score ?? null,
+          detail: `${c.file} — merge resolution proposal (${c.proposal.status})`,
+          status: c.proposal.status,
+          hasProposal: !!c.proposal.mergedSource,
+          targetFile: c.file,
+        });
+      });
+    }
+  }
+
+  // mapd fix proposals — mapd review --approve <id> feeds directly into applying a verified fix
+  const proposalsDir = path.join(dir, "proposals");
+  if (fs.existsSync(proposalsDir)) {
+    for (const name of fs.readdirSync(proposalsDir).filter((n) => n.endsWith(".json"))) {
+      const p = path.join(proposalsDir, name);
+      const prop = readJson(p);
+      if (!prop) continue;
+      const files = Object.keys(prop.filesPatch ?? {});
+      items.push({
+        id: id8(`fix:${prop.findingId}`),
+        source: "fix", file: p, index: null,
+        kind: prop.findingKind ?? "fix", severity: null,
+        detail: `${files.join(", ") || "(no files)"} — verified fix proposal (${prop.status})`,
+        status: prop.status,
+        hasProposal: files.length > 0,
+        targetFile: files[0] ?? null,
+      });
+    }
+  }
+  return items;
+}
+
+export function pending(items) {
+  return items.filter((i) => i.status === "awaiting-approval");
+}
+
+/**
+ * The five finding states the master prompt requires to be obvious, derived —
+ * never stored — from the raw report status plus report freshness:
+ *
+ *   active     — awaiting approval AND the source report is current with the tree
+ *   stale      — awaiting approval, but the source report predates a newer
+ *                source change (see staleness.js) — act only after refreshing
+ *   approved   — human marked it approved; queued for a fix pass
+ *   resolved   — a verified fix/merge was applied to the real tree
+ *   dismissed  — human dismissed it (kept in the report as audit trail)
+ *   historical — terminal leftovers: rolled back after apply, failed gates, etc.
+ *
+ * Deriving keeps a single source of truth: staleness can change with every
+ * file save, so persisting a state would immediately overclaim.
+ */
+export function stateOf(item, staleReports = []) {
+  const staleSet = staleReports instanceof Set ? staleReports : new Set(staleReports);
+  switch (item.status) {
+    case "awaiting-approval":
+      return item.file && staleSet.has(path.basename(item.file)) ? "stale" : "active";
+    case "approved": return "approved";
+    case "approved-applied": return "resolved";
+    case "resolved": return "resolved"; // auto-resolved by re-check (see regression.js saveFindings)
+    case "dismissed": return "dismissed";
+    default: return "historical";
+  }
+}
+
+/**
+ * loadQueue plus a derived `state` on every item and the freshness result it
+ * was derived from — the one call sites should prefer whenever they show a
+ * queue to a human or an agent, so stale findings are never presented as
+ * current fact.
+ */
+export function loadQueueWithStates(rootDir) {
+  const freshness = checkReportFreshness(rootDir);
+  const items = loadQueue(rootDir).map((i) => ({ ...i, state: stateOf(i, freshness.staleReports) }));
+  return { items, freshness };
+}
+
+/**
+ * Transition one item. Returns { ok, action, detail }.
+ * Approving an integration proposal writes the (already gate-verified) merged
+ * source to the working tree; everything else is a status change only.
+ */
+export function transition(rootDir, item, action, reason) {
+  const rep = readJson(item.file);
+  if (!rep) return { ok: false, detail: `report file missing: ${item.file}` };
+
+  const stamp = { at: new Date().toISOString(), by: "mapd review" };
+
+  if (item.source.startsWith("integrate:")) {
+    const c = rep.conflicts[item.index];
+    if (!c?.proposal) return { ok: false, detail: "proposal no longer present in report" };
+    if (c.proposal.status !== "awaiting-approval")
+      return { ok: false, detail: `proposal is '${c.proposal.status}', not awaiting-approval` };
+    if (action === "approve") {
+      const change = applyRealTreeWrite(rootDir, c.file, c.proposal.mergedSource, "integrate");
+      c.proposal.status = "approved-applied";
+      c.proposal.applied = stamp;
+      c.proposal.changeId = change.id;
+      fs.writeFileSync(item.file, JSON.stringify(rep, null, 2));
+      return { ok: true, action, detail: `merged source written to ${c.file} (change ${change.id}) — review the diff, then commit`, changeId: change.id, changeIds: [change.id] };
+    }
+    c.proposal.status = "dismissed";
+    c.proposal.dismissed = { ...stamp, reason: reason ?? null };
+    fs.writeFileSync(item.file, JSON.stringify(rep, null, 2));
+    return { ok: true, action, detail: `proposal for ${c.file} dismissed` };
+  }
+
+  if (item.source === "fix") {
+    const prop = rep; // proposals/*.json holds a single proposal object, not a report with an array
+    if (prop.status !== "awaiting-approval")
+      return { ok: false, detail: `fix proposal is '${prop.status}', not awaiting-approval` };
+    if (action === "approve") {
+      const changeIds = [];
+      for (const [file, newSource] of Object.entries(prop.filesPatch ?? {})) {
+        const change = applyRealTreeWrite(rootDir, file, newSource, "fix");
+        changeIds.push(change.id);
+      }
+      prop.status = "approved-applied";
+      prop.applied = stamp;
+      prop.changeIds = changeIds;
+      fs.writeFileSync(item.file, JSON.stringify(prop, null, 2));
+      return { ok: true, action, detail: `fix applied to ${Object.keys(prop.filesPatch ?? {}).join(", ")} (changes ${changeIds.join(", ")})`, changeIds };
+    }
+    prop.status = "dismissed";
+    prop.dismissed = { ...stamp, reason: reason ?? null };
+    fs.writeFileSync(item.file, JSON.stringify(prop, null, 2));
+    return { ok: true, action, detail: `fix proposal dismissed` };
+  }
+
+  const f = rep.findings[item.index];
+  if (!f) return { ok: false, detail: "finding no longer present in report" };
+  f.status = action === "approve" ? "approved" : "dismissed";
+  f[action === "approve" ? "approved" : "dismissed"] = { ...stamp, ...(reason ? { reason } : {}) };
+  fs.writeFileSync(item.file, JSON.stringify(rep, null, 2));
+  return {
+    ok: true, action,
+    detail: action === "approve"
+      ? `finding marked approved — queued for a fix pass (mapd never auto-fixes)`
+      : `finding dismissed`,
+  };
+}