mjolnir-qa 0.5.6 → 0.5.7

package/CHANGELOG.md

@@ -74,6 +74,14 @@ scan`. Unknown categories are a usage error (exit 10).
 - help registry gained `why`, `handoff`, `install` and the new flags;
   site/reference/cli.md documents the handoff trust model.
 
+## [0.5.7] — 2026-09-06
+
+### Changes since 0.5.6
+
+- Merge pull request #40 from Sergey-Bar/eng/machine-contract-2.1
+- test: plural + unknown-cause arms for inconclusive resolution rendering
+- feat: machine verification contract + finding detectorRevision + lifecycle resolution (blueprint §12-§15, §17, §25)
+
 ## [0.5.6] — 2026-09-06
 
 ### Changes since 0.5.5

package/dist/cli.d.mts

@@ -103,6 +103,15 @@ interface Finding {
   measuredFpRate?: number;
   /** Classified (TP+FP) verdicts behind `measuredFpRate`. */
   measuredFpN?: number;
+  /**
+   * Detector revision of the rule that produced this finding, stamped
+   * from the registry at scan time (blueprint §13, G-16). Identity
+   * participates: "same ruleId, different detectorRevision" is formally
+   * a different detector for comparison purposes. Additive within
+   * schemaVersion 1; absent means the producer predates the field
+   * (revision-unknown).
+   */
+  detectorRevision?: number;
   /**
    * Runtime corroboration from a real run report (plan §16), stamped
    * when a report was available and matched this finding's file/test.
@@ -690,7 +699,7 @@ declare const runScan: typeof runScan$1, buildUniversalRules: typeof buildUniver
  * `scripts/sync-sarif-version.cjs` on release and guarded by
  * `tests/version-consistency.spec.ts` locally.
  */
-declare const CLI_VERSION = "0.5.6";
+declare const CLI_VERSION = "0.5.7";
 /** A usage-error detail: the offending token, when one exists. */
 interface UsageErrorDetail {
   /** The unknown flag or rejected value (e.g. `--nope`, `loud`). */

package/dist/cli.mjs

@@ -11407,6 +11407,7 @@ async function runScan$1(args, hooks = {}) {
 	});
 	const tierByRuleId = tiers;
 	const pluginsLoaded = pluginMeta;
+	const REVISION_BY_RULE_ID = new Map(activeRules.map((r) => [r.id, r.detectorRevision ?? MEASURED_FP[r.id]?.detectorRevision ?? 1]));
 	const cache = args.cache ? createScanCache(workspace.root) : disabledScanCache;
 	const rulesDigest = computeRulesDigest(activeRules);
 	for (const perr of pluginErrors) findings.push({
@@ -11619,6 +11620,10 @@ async function runScan$1(args, hooks = {}) {
 			f.measuredFpN = m.n;
 		}
 	}
+	for (const f of findings) {
+		const rev = REVISION_BY_RULE_ID.get(f.ruleId);
+		if (rev !== void 0) f.detectorRevision = rev;
+	}
 	enforceTierPolicy(findings, tierByRuleId);
 	for (const f of findings) f.fixGroupId = f.ruleId;
 	const runtimeReportPath = discoverRuntimeReport$1(scanRoot.root);
@@ -11676,6 +11681,103 @@ async function runScan$1(args, hooks = {}) {
 	await releaseTreeSitterResources();
 	return result;
 }
+/**
+* Fields that participate in the verification digest: identity (ruleId,
+* detectorRevision, file, line, column) + evidence (severity,
+* evidenceLevel, trustLevel, confidence, findingType) + lifecycle-adjacent
+* metadata (fixGroupId). PRESENTATION (message/why/fix) is excluded by
+* design: rewording a detector's prose must not change the digest of a
+* scan whose semantics are identical.
+*/
+function digestView(f) {
+	return {
+		ruleId: f.ruleId,
+		detectorRevision: f.detectorRevision ?? null,
+		file: f.file,
+		line: f.line,
+		column: f.column,
+		severity: f.severity,
+		evidenceLevel: f.evidenceLevel ?? null,
+		trustLevel: f.trustLevel ?? null,
+		confidence: f.confidence,
+		findingType: f.findingType,
+		fixGroupId: f.fixGroupId ?? null
+	};
+}
+/**
+* Deterministic canonical serialization: findings in ScanResult order
+* (already compareFindings-sorted), stable key insertion order, no
+* indentation. JSON.stringify of plain objects with fixed key order is
+* deterministic across runs and platforms. `durationMs` is EXCLUDED —
+* it is wall-clock, not semantics; including it would make two runs of
+* the same repo produce different digests.
+*/
+function canonicalScanJson(result) {
+	return JSON.stringify({
+		score: result.score,
+		partial: result.partial,
+		analysisStatus: {
+			discovery: result.analysisStatus.discovery,
+			rules: result.analysisStatus.rules,
+			skippedFiles: result.analysisStatus.skippedFiles,
+			rulesCrashed: result.analysisStatus.rulesCrashed ?? 0,
+			truncationReasons: result.analysisStatus.truncationReasons ?? []
+		},
+		findings: result.findings.map(digestView)
+	});
+}
+/** Advisory when the DERIVED evidence level is E0 (same rule as scoring). */
+function isAdvisory(f) {
+	return (f.evidenceLevel ?? deriveEvidenceLevel(f.findingType, f.confidence)) === "E0";
+}
+function levelFor(f) {
+	if (f.severity === "error") return "failure";
+	if (f.severity === "warning") return "warning";
+	return "notice";
+}
+function countBy(findings, predicate) {
+	return findings.filter(predicate).length;
+}
+/**
+* Project a canonical ScanResult into the machine contract. Pure:
+* same input → same output, always (§16 semantic integrity, §25.1).
+*/
+function buildMachineContract(result) {
+	const digest = createHash("sha256").update(canonicalScanJson(result)).digest("hex");
+	const annotations = result.findings.map((f) => ({
+		path: f.file,
+		start_line: f.line,
+		annotation_level: levelFor(f),
+		message: `${f.ruleId}: ${f.message}`,
+		ruleId: f.ruleId,
+		...f.detectorRevision !== void 0 ? { detectorRevision: f.detectorRevision } : {},
+		advisory: isAdvisory(f)
+	}));
+	return {
+		contractVersion: 1,
+		summary: {
+			digest: `sha256:${digest}`,
+			findings: result.findings.length,
+			score: result.score,
+			errors: countBy(result.findings, (f) => f.severity === "error"),
+			warnings: countBy(result.findings, (f) => f.severity === "warning"),
+			infos: countBy(result.findings, (f) => f.severity === "info"),
+			advisory: countBy(result.findings, isAdvisory)
+		},
+		annotations: annotations.slice(0, 50),
+		annotationsTruncated: result.findings.length > 50,
+		completeness: {
+			partial: result.partial,
+			discovery: result.analysisStatus.discovery,
+			rules: result.analysisStatus.rules,
+			skippedFiles: result.analysisStatus.skippedFiles,
+			rulesCrashed: result.analysisStatus.rulesCrashed ?? 0,
+			truncationReasons: result.analysisStatus.truncationReasons ?? [],
+			frameworkDetectionUnknown: result.frameworkDetectionUnknown,
+			durationMs: result.analysisStatus.durationMs
+		}
+	};
+}
 //#endregion
 //#region src/scorer/prioritize.ts
 /**
@@ -12473,7 +12575,7 @@ function renderSarif(result, repoRootUri) {
 		tool: { driver: {
 			name: "Mjölnir",
 			informationUri: "https://github.com/Sergey-Bar/Mjolnir",
-			version: "0.5.6",
+			version: "0.5.7",
 			rules: [...rules.values()].map((r) => {
 				const meta = RULES.find((x) => x.id === r.id);
 				return {
@@ -12888,8 +12990,17 @@ function renderPrComment(result, options = {}) {
 	lines.push("");
 	lines.push(`_Advisory only — this comment never blocks merging. Generated by [Mjölnir](${options.repoUrl ?? "https://github.com/Sergey-Bar/Mjolnir"})._`);
 	if (usingDiff && diff.resolvedFindings.length > 0) {
-		lines.push("");
-		lines.push(`✨ ${diff.resolvedFindings.length} pre-existing finding${diff.resolvedFindings.length === 1 ? "" : "s"} fixed in this PR.`);
+		const verified = diff.resolvedFindings.filter((f) => f.resolution.status === "VERIFIED-RESOLVED");
+		const inconclusive = diff.resolvedFindings.filter((f) => f.resolution.status === "INCONCLUSIVE");
+		if (verified.length > 0) {
+			lines.push("");
+			lines.push(`✨ ${verified.length} pre-existing finding${verified.length === 1 ? "" : "s"} verified as fixed in this PR.`);
+		}
+		if (inconclusive.length > 0) {
+			const causes = [...new Set(inconclusive.map((f) => f.resolution.cause ?? "unknown"))].join(", ");
+			lines.push("");
+			lines.push(`ℹ ${inconclusive.length} pre-existing finding${inconclusive.length === 1 ? "" : "s"} disappeared, but this scan can't confirm a fix (${causes}).`);
+		}
 	}
 	return lines.join("\n");
 }
@@ -15185,7 +15296,7 @@ function gitBuffer(root, args) {
 	}
 }
 /** Fingerprint a finding for cross-commit matching (line numbers shift). */
-function fingerprint$1(f) {
+function fingerprint$2(f) {
 	return `${f.ruleId}\u0000${f.file}\u0000${f.message}`;
 }
 async function computeImpact(root, options) {
@@ -15292,9 +15403,9 @@ async function computeImpact(root, options) {
 	}
 	const headResult = await options.runScan(root);
 	const baseSet = /* @__PURE__ */ new Map();
-	for (const f of baseResult.findings) baseSet.set(fingerprint$1(f), f);
+	for (const f of baseResult.findings) baseSet.set(fingerprint$2(f), f);
 	const headSet = /* @__PURE__ */ new Map();
-	for (const f of headResult.findings) headSet.set(fingerprint$1(f), f);
+	for (const f of headResult.findings) headSet.set(fingerprint$2(f), f);
 	const resolved = [];
 	for (const [key, f] of baseSet) if (!headSet.has(key)) resolved.push({
 		ruleId: f.ruleId,
@@ -15352,6 +15463,79 @@ function renderImpact(report) {
 	return lines.join("\n");
 }
 //#endregion
+//#region src/engine/resolution.ts
+/** Correlation identity (v1-compatible): ruleId\0file\0message. */
+function fingerprint$1(entry) {
+	return `${entry.ruleId}\u0000${entry.file}\u0000${entry.message}`;
+}
+/**
+* The §15 ordered algorithm. Pure; first match wins.
+*/
+function resolve$1(input) {
+	const { entry, baseline, current } = input;
+	const fp = fingerprint$1(entry);
+	const comparedAgainst = input.baselineCommit ?? baseline.commit ?? "unknown baseline";
+	if (current.partial || current.analysisStatus.rules !== "complete") return {
+		status: "INCONCLUSIVE",
+		cause: "partial",
+		comparedAgainst
+	};
+	if (input.crashedRuleIds?.has(entry.ruleId)) return {
+		status: "INCONCLUSIVE",
+		cause: "crash",
+		comparedAgainst
+	};
+	if (input.skippedFiles?.has(entry.file)) return {
+		status: "INCONCLUSIVE",
+		cause: "skipped",
+		comparedAgainst
+	};
+	if (input.suppressed?.has(`${entry.ruleId}\u0000${entry.file}`)) return {
+		status: "SUPPRESSED",
+		comparedAgainst
+	};
+	if (input.excludedFiles?.has(entry.file)) return {
+		status: "DISAPPEARED-NON-FIX",
+		cause: "excluded",
+		comparedAgainst
+	};
+	const entryRev = entry.detectorRevision;
+	if (entryRev === void 0) return {
+		status: "INCONCLUSIVE",
+		cause: "legacy-baseline",
+		comparedAgainst
+	};
+	const registryRev = input.registryRevisions.get(entry.ruleId);
+	if (registryRev === void 0) return {
+		status: "DISAPPEARED-NON-FIX",
+		cause: "retired",
+		comparedAgainst
+	};
+	if (registryRev !== entryRev) return {
+		status: "INCONCLUSIVE",
+		cause: "revision-changed",
+		comparedAgainst
+	};
+	if (current.findings.some((f) => fingerprint$1(f) === fp)) return {
+		status: "STILL-PRESENT",
+		comparedAgainst
+	};
+	return {
+		status: "VERIFIED-RESOLVED",
+		comparedAgainst
+	};
+}
+/** The §15 rendering law: "FIXED" only for VERIFIED-RESOLVED. */
+function renderResolution(r) {
+	switch (r.status) {
+		case "VERIFIED-RESOLVED": return "FIXED SINCE BASELINE (verified by a complete same-revision scan)";
+		case "STILL-PRESENT": return "STILL PRESENT";
+		case "SUPPRESSED": return "SUPPRESSED (active ignore entry)";
+		case "INCONCLUSIVE": return `INCONCLUSIVE (${r.cause})`;
+		case "DISAPPEARED-NON-FIX": return `DISAPPEARED — NOT A FIX (${r.cause})`;
+	}
+}
+//#endregion
 //#region src/commands/baseline.ts
 /**
 * `mjolnir baseline` / `mjolnir diff` — Sprint 6 Task 24
@@ -15376,6 +15560,14 @@ function renderImpact(report) {
 const ui$7 = plainContext();
 const DEFAULT_BASELINE_PATH = join(".mjolnir", "baseline.json");
 /**
+* Registry-declared detector revisions (§17): a baseline entry whose
+* revision differs from today's registry is INCONCLUSIVE(revision-
+* changed), never resolved. Omitted declarations mean revision 1 (the
+* documented RuleMeta default for first-generation detectors); a
+* ruleId ABSENT from this map means the rule is retired.
+*/
+const REGISTRY_REVISIONS = new Map(RULES.map((r) => [r.id, r.detectorRevision ?? 1]));
+/**
 * Correlation identity for before/after comparison (agent-handoff plan
 * §5.2): ruleId + file + message, deliberately EXCLUDING `line` — a
 * source edit that shifts a finding still correlates. file:line is an
@@ -15397,7 +15589,8 @@ function buildBaseline(result, commit) {
 			ruleId: f.ruleId,
 			file: f.file,
 			message: f.message,
-			severity: f.severity
+			severity: f.severity,
+			...f.detectorRevision !== void 0 ? { detectorRevision: f.detectorRevision } : {}
 		}))
 	};
 }
@@ -15467,7 +15660,18 @@ function diffAgainstBaseline(result, baseline) {
 		else newFindings.push(f);
 	}
 	const resolvedFindings = [];
-	for (const [key, f] of baseSet) if (!headKeys.has(key)) resolvedFindings.push(f);
+	for (const [key, f] of baseSet) if (!headKeys.has(key)) {
+		const resolution = resolve$1({
+			entry: f,
+			baseline,
+			current: result,
+			registryRevisions: REGISTRY_REVISIONS
+		});
+		resolvedFindings.push({
+			...f,
+			resolution
+		});
+	}
 	return {
 		hasBaseline: true,
 		baselineCapturedAt: baseline.capturedAt,
@@ -15507,8 +15711,17 @@ function renderBaselineDiff(diff) {
 	}
 	lines.push("");
 	if (diff.resolvedFindings.length > 0) {
-		lines.push(`FIXED SINCE BASELINE (${diff.resolvedFindings.length}):`);
-		for (const f of diff.resolvedFindings) lines.push(`  ✓ ${f.ruleId} (${f.severity}) · ${f.file} — ${f.message}`);
+		const verified = diff.resolvedFindings.filter((f) => f.resolution.status === "VERIFIED-RESOLVED");
+		const unresolved = diff.resolvedFindings.filter((f) => f.resolution.status !== "VERIFIED-RESOLVED");
+		if (verified.length > 0) {
+			lines.push(`FIXED SINCE BASELINE (${verified.length}):`);
+			for (const f of verified) lines.push(`  ✓ ${f.ruleId} (${f.severity}) · ${f.file} — ${f.message}`);
+			lines.push("");
+		}
+		if (unresolved.length > 0) {
+			lines.push(`DISAPPEARED — NOT CLASSIFIED AS FIXED (${unresolved.length}):`);
+			for (const f of unresolved) lines.push(`  ${renderResolution(f.resolution)} · ${f.ruleId} (${f.severity}) · ${f.file} — ${f.message}`);
+		}
 	}
 	return lines.join("\n");
 }
@@ -16787,7 +17000,7 @@ const { runScan, buildUniversalRules, fallbackWorkspace, pathMatchesGlob, isVali
 * `scripts/sync-sarif-version.cjs` on release and guarded by
 * `tests/version-consistency.spec.ts` locally.
 */
-const CLI_VERSION = "0.5.6";
+const CLI_VERSION = "0.5.7";
 function parseArgs(argv, onError) {
 	const args = {
 		target: ".",
@@ -17214,7 +17427,10 @@ async function runScanCommand(argv, io = {
 		}
 		if (args.format === "sarif") io.out(renderSarif(result));
 		else if (args.format === "mermaid") io.out(renderMermaid(result));
-		else if (args.json) io.out(JSON.stringify(result, null, 2));
+		else if (args.json) io.out(JSON.stringify({
+			...result,
+			contract: buildMachineContract(result)
+		}, null, 2));
 		else {
 			const categories = args.categories;
 			const visible = categories && categories.length > 0 ? result.findings.filter((f) => categories.includes(f.category)) : result.findings;
@@ -17490,7 +17706,7 @@ async function runDiffCommand(argv, io = {
 			const statsPath = join(target, DEFAULT_STATS_PATH);
 			const stats = recordResolved(loadStats(statsPath), diff);
 			if (!saveStats(stats, statsPath)) io.err("  (warning: stats could not be written — read-only filesystem? counters not recorded)");
-			if (diff.resolvedFindings.length > 0) {
+			if (diff.resolvedFindings.some((f) => f.resolution.status === "VERIFIED-RESOLVED")) {
 				const milestone = recordMilestones(stats, ["first-debt-reduction"]);
 				if (milestone.newlyAnnounced.length > 0) {
 					if (saveStats(milestone.stats, statsPath)) for (const id of milestone.newlyAnnounced) io.out(MILESTONE_MESSAGES[id]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mjolnir-qa",
-  "version": "0.5.6",
+  "version": "0.5.7",
   "description": "Mjölnir — the Verification Trust Engine for QA. Audits test suites and CI pipelines, reports a worthiness score and prioritized findings.",
   "type": "module",
   "engines": {
@@ -35,6 +35,7 @@
     "fp-audit:generate": "tsx scripts/generate-fp-audit-table.ts",
     "docs:rules": "tsx scripts/generate-rule-docs.ts",
     "docs:capability": "tsx scripts/generate-capability-matrix.ts",
+    "docs:machine-contract": "tsx scripts/generate-machine-contract-doc.ts",
     "docs:hero": "tsx scripts/generate-readme-hero.ts",
     "docs:formats": "tsx scripts/generate-site-formats.ts",
     "docs:forensics-samples": "tsx scripts/generate-forensics-samples.ts",