@adversarylabs/sdk 0.1.3 → 0.1.5

package/dist/index.js

@@ -1,9 +1,11 @@
 import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { Ajv2020 } from "ajv/dist/2020.js";
 export const DEFAULT_INPUT_PATH = "/adversary/input.json";
 export const DEFAULT_OUTPUT_PATH = "/adversary/output.json";
 export const ADVERSARY_RUN_PROTOCOL_VERSION = 1;
 const verboseValues = new Set(["1", "true", "TRUE", "yes", "YES"]);
+let envelopeValidator;
 export const Severity = {
     Info: "info",
     Low: "low",
@@ -46,19 +48,63 @@ export class RuleRegistry {
     rules = new Map();
     register(rule) {
         assertRuleDefinition(rule);
-        this.rules.set(rule.id, rule);
+        if (this.rules.has(rule.id)) {
+            throw new Error(`Rule definition "${rule.id}" is already registered.`);
+        }
+        this.rules.set(rule.id, cloneRuleDefinition(rule));
+    }
+    replace(rule) {
+        assertRuleDefinition(rule);
+        if (!this.rules.has(rule.id)) {
+            throw new Error(`Rule definition "${rule.id}" is not registered.`);
+        }
+        this.rules.set(rule.id, cloneRuleDefinition(rule));
     }
     lookup(ruleId) {
-        return this.rules.get(ruleId);
+        const rule = this.rules.get(ruleId);
+        return rule === undefined ? undefined : cloneRuleDefinition(rule);
     }
     has(ruleId) {
         return this.rules.has(ruleId);
     }
+    snapshot() {
+        const snapshot = new RuleRegistry();
+        for (const rule of this.rules.values()) {
+            snapshot.register(rule);
+        }
+        return snapshot;
+    }
+    importMissing(source) {
+        for (const rule of source.rules.values()) {
+            if (!this.rules.has(rule.id)) {
+                this.rules.set(rule.id, cloneRuleDefinition(rule));
+            }
+        }
+    }
+}
+function cloneRuleDefinition(rule) {
+    return {
+        ...rule,
+        groupBy: rule.groupBy === undefined ? undefined : [...rule.groupBy],
+    };
 }
+function cloneReviewPolicy(policy) {
+    return {
+        ...policy,
+        confidenceThresholds: policy.confidenceThresholds === undefined ? undefined : { ...policy.confidenceThresholds },
+        severityOverrides: policy.severityOverrides === undefined ? undefined : { ...policy.severityOverrides },
+    };
+}
+/** @deprecated Prefer app.defineRule(...) so definitions remain instance-scoped. */
 export const ruleRegistry = new RuleRegistry();
+/** @deprecated Prefer app.defineRule(...) so definitions remain instance-scoped. */
 export function defineRule(rule) {
     ruleRegistry.register(rule);
 }
+/** @deprecated Prefer app.replaceRule(...) so definitions remain instance-scoped. */
+export function replaceRule(rule) {
+    ruleRegistry.replace(rule);
+}
 export const log = {
     debug(message) {
         if (isVerbose()) {
@@ -82,29 +128,48 @@ export class Adversary {
     version;
     rules = [];
     reviewPolicy;
+    ruleDefinitions;
     constructor(options) {
         if (options.name.length === 0) {
             throw new Error("Adversary name must be a non-empty string.");
         }
         this.name = options.name;
         this.version = options.version;
-        this.reviewPolicy = options.review ?? {};
+        this.reviewPolicy = cloneReviewPolicy(options.review ?? {});
+        assertReviewPolicy(this.reviewPolicy, `adversary "${this.name}" review policy`);
+        this.ruleDefinitions = ruleRegistry.snapshot();
+    }
+    defineRule(rule) {
+        this.ruleDefinitions.register(rule);
+    }
+    replaceRule(rule) {
+        this.ruleDefinitions.replace(rule);
+    }
+    hasRuleDefinition(ruleId) {
+        return this.ruleDefinitions.has(ruleId);
     }
     rule(id, handler) {
         if (id.length === 0) {
             throw new Error("Rule id must be a non-empty string.");
         }
+        if (this.rules.some((rule) => rule.id === id)) {
+            throw new Error(`App rule "${id}" is already registered.`);
+        }
+        // Compatibility for definitions registered with the deprecated top-level API after
+        // this Adversary was constructed. Once copied, later global changes cannot affect it.
+        this.ruleDefinitions.importMissing(ruleRegistry);
         this.rules.push({ id, handler });
     }
-    async run(options = {}) {
+    async run(options) {
         const startedAt = performance.now();
-        const input = options.input ?? (await parseInput(options.inputPath));
-        const repoPath = process.env.ADVERSARY_REPO ?? input.source.path;
+        assertReviewPolicy(options.review ?? {}, `adversary "${this.name}" run review policy`);
+        const repoPath = options.input.source.path;
         const summary = {};
         const cache = new Map();
         const collector = createReviewCollector();
-        const context = createRuleContext(repoPath, summary, cache, collector);
-        const includeSuppressed = options.includeSuppressed ?? parseBooleanEnv(process.env.ADVERSARY_INCLUDE_SUPPRESSED);
+        const registry = this.ruleDefinitions.snapshot();
+        const context = createRuleContext(repoPath, summary, cache, collector, registry);
+        const includeSuppressed = options.includeSuppressed;
         for (const rule of this.rules) {
             log.debug(`running rule ${rule.id}`);
             await rule.handler(context);
@@ -114,24 +179,92 @@ export class Adversary {
             repository: repoPath,
             filesScanned: typeof summary.files_scanned === "number" ? summary.files_scanned : undefined,
             collector,
-            policy: { ...this.reviewPolicy, ...options.review },
+            policy: cloneReviewPolicy({ ...this.reviewPolicy, ...options.review }),
+            registry,
             includeSuppressed,
             includeRawObservations: options.includeRawObservations,
-            timing: { totalMs: Math.round(performance.now() - startedAt) },
+            timing: options.includeTiming
+                ? { totalMs: Math.round(performance.now() - startedAt) }
+                : undefined,
         });
-        if (options.write !== false) {
-            await writeOutput(createAdversaryRunEnvelope(output), options.outputPath);
-        }
         return output;
     }
+    async runFromEnvironment(options = {}) {
+        const input = options.input ??
+            (await parseInput(options.inputPath ?? process.env.ADVERSARY_INPUT ?? DEFAULT_INPUT_PATH));
+        const repository = options.input
+            ? input.source.path
+            : (process.env.ADVERSARY_REPO ?? input.source.path);
+        const result = await this.run({
+            input: { ...input, source: { ...input.source, path: repository } },
+            review: options.review,
+            includeSuppressed: options.includeSuppressed ?? parseBooleanEnv(process.env.ADVERSARY_INCLUDE_SUPPRESSED),
+            includeRawObservations: options.includeRawObservations,
+            includeTiming: options.includeTiming,
+        });
+        await writeOutput(createAdversaryRunEnvelope(result), options.outputPath ?? process.env.ADVERSARY_OUTPUT ?? DEFAULT_OUTPUT_PATH);
+        return result;
+    }
 }
 export function createAdversaryRunEnvelope(result) {
     return {
         protocolVersion: ADVERSARY_RUN_PROTOCOL_VERSION,
-        result,
+        result: toWireReviewResult(result),
     };
 }
-export async function parseInput(path = process.env.ADVERSARY_INPUT ?? DEFAULT_INPUT_PATH) {
+function toWireReviewResult(result) {
+    return omitUndefined({
+        adversary: omitUndefined(result.adversary),
+        target: omitUndefined(result.target),
+        assessment: result.assessment === undefined ? undefined : omitUndefined({ ...result.assessment }),
+        positives: result.positives.map(toWireReviewNote),
+        observations: result.observations.map(toWireReviewNote),
+        findings: result.findings.map(toWireFinding),
+        opinion: result.opinion === undefined ? undefined : omitUndefined({ ...result.opinion }),
+        suppressed: result.suppressed,
+        timing: result.timing === undefined ? undefined : omitUndefined(result.timing),
+        suppressedFindings: result.suppressedFindings?.map(toWireFinding),
+        rawObservations: result.rawObservations,
+    });
+}
+function toWireReviewNote(note) {
+    return omitUndefined({
+        key: note.key,
+        summary: note.summary,
+        evidence: note.evidence?.map(toWireEvidence),
+        metadata: note.metadata,
+    });
+}
+function toWireFinding(finding) {
+    return omitUndefined({
+        id: finding.id,
+        ruleId: finding.ruleId,
+        groupKey: finding.groupKey,
+        title: finding.title,
+        category: finding.category,
+        severity: finding.severity,
+        confidence: finding.confidence,
+        summary: finding.summary,
+        whyItMatters: finding.whyItMatters,
+        impact: finding.impact,
+        evidence: finding.evidence.map(toWireEvidence),
+        recommendation: finding.recommendation,
+        remediation: finding.remediation === undefined ? undefined : omitUndefined({ ...finding.remediation }),
+        tags: finding.tags,
+        metadata: finding.metadata,
+    });
+}
+function toWireEvidence(evidence) {
+    return omitUndefined({
+        file: evidence.location?.file,
+        line: evidence.location?.line,
+        endLine: evidence.location?.endLine,
+        message: evidence.message ?? evidence.label,
+        snippet: evidence.snippet,
+        metadata: evidence.data,
+    });
+}
+export async function parseInput(path = DEFAULT_INPUT_PATH) {
     const raw = await readFile(path, "utf8");
     const parsed = JSON.parse(raw);
     if (!isRecord(parsed)) {
@@ -145,10 +278,22 @@ export async function parseInput(path = process.env.ADVERSARY_INPUT ?? DEFAULT_I
     }
     return parsed;
 }
-export async function writeOutput(output, path = process.env.ADVERSARY_OUTPUT ?? DEFAULT_OUTPUT_PATH) {
+export async function writeOutput(output, path = DEFAULT_OUTPUT_PATH) {
+    await validateRunEnvelope(output);
     await mkdir(dirname(path), { recursive: true });
     await writeFile(path, `${JSON.stringify(output, null, 2)}\n`, "utf8");
 }
+export async function validateRunEnvelope(output) {
+    let validator = envelopeValidator;
+    if (validator === undefined) {
+        const schema = JSON.parse(await readFile(new URL("../schemas/adversary.review.v1.schema.json", import.meta.url), "utf8"));
+        validator = new Ajv2020({ allErrors: true, strict: true }).compile(schema);
+        envelopeValidator = validator;
+    }
+    if (!validator(output)) {
+        throw new Error(`Invalid adversary.review.v1 envelope: ${JSON.stringify(validator.errors)}`);
+    }
+}
 export function normalizeConfidence(confidence, thresholds = DEFAULT_CONFIDENCE_THRESHOLDS) {
     if (isConfidence(confidence)) {
         return confidence;
@@ -190,7 +335,7 @@ export class JsonRenderer {
         this.write = write;
     }
     render(result) {
-        this.write(`${JSON.stringify(result, null, 2)}\n`);
+        this.write(`${JSON.stringify(toWireReviewResult(result), null, 2)}\n`);
     }
 }
 export class TerminalRenderer {
@@ -212,10 +357,12 @@ export class TerminalRenderer {
                 lines.push(normalizeParagraph(result.assessment.summary), "");
             }
         }
-        if (result.scores !== undefined && result.scores.length > 0) {
+        const scoreNotes = result.observations.filter(isScoreReviewNote);
+        const additionalObservations = result.observations.filter((note) => !isScoreReviewNote(note));
+        if (scoreNotes.length > 0) {
             lines.push("Scores", "");
-            for (const score of result.scores) {
-                lines.push(formatScore(score));
+            for (const note of scoreNotes) {
+                lines.push(note.summary);
             }
             lines.push("");
         }
@@ -226,9 +373,9 @@ export class TerminalRenderer {
             }
             lines.push("");
         }
-        if (result.observations.length > 0) {
+        if (additionalObservations.length > 0) {
             lines.push("Additional observations", "");
-            for (const observation of result.observations) {
+            for (const observation of additionalObservations) {
                 lines.push(`- ${normalizeParagraph(observation.summary)}`);
             }
             lines.push("");
@@ -248,8 +395,8 @@ export class TerminalRenderer {
         lines.push(`Findings: ${result.findings.length}`, "");
         for (const finding of result.findings) {
             lines.push(`[${finding.severity}] ${finding.title}`);
-            const firstEvidence = finding.evidence.find((item) => item.file !== undefined);
-            if (firstEvidence?.file !== undefined) {
+            const firstEvidence = finding.evidence.find((item) => item.location?.file !== undefined);
+            if (firstEvidence?.location?.file !== undefined) {
                 lines.push(formatEvidenceLocation(firstEvidence));
             }
             lines.push("");
@@ -276,7 +423,7 @@ export class TerminalRenderer {
         this.write(`${lines.join("\n").trimEnd()}\n`);
     }
 }
-function createRuleContext(repoPath, summary, cache, collector) {
+function createRuleContext(repoPath, summary, cache, collector, registry) {
     const absoluteRepoPath = resolve(repoPath);
     return {
         repoPath: absoluteRepoPath,
@@ -292,12 +439,15 @@ function createRuleContext(repoPath, summary, cache, collector) {
             return findMatchingPaths(absoluteRepoPath, pattern, true);
         },
         observe(observation) {
-            assertObservationInit(observation, "ctx.observe");
+            assertObservationInit(observation, "ctx.observe", registry);
             collector.observations.push(observation);
         },
         finding(finding) {
             assertFindingInput(finding, "ctx.finding");
-            collector.findings.push(normalizeFindingInput(finding));
+            collector.findings.push({
+                finding: normalizeFindingInput(finding, collector.findings.length),
+                deduplicate: finding.deduplicate !== false,
+            });
         },
         review: {
             assessment(assessment) {
@@ -306,11 +456,11 @@ function createRuleContext(repoPath, summary, cache, collector) {
             },
             positive(note) {
                 assertReviewNote(note, "ctx.review.positive");
-                collector.positives.push(note);
+                collector.positives.push(normalizeReviewNote(note));
             },
             observe(note) {
                 assertReviewNote(note, "ctx.review.observe");
-                collector.reviewObservations.push(note);
+                collector.reviewObservations.push(normalizeReviewNote(note));
             },
             score(score) {
                 assertReviewScore(score);
@@ -373,8 +523,11 @@ function createReviewCollector() {
 }
 function buildReviewResult(input) {
     const thresholds = input.policy.confidenceThresholds ?? DEFAULT_CONFIDENCE_THRESHOLDS;
-    const synthesized = synthesizeObservationFindings(input.collector.observations, thresholds);
-    const allFindings = deduplicateFindings([...synthesized, ...input.collector.findings]).map((finding) => calibrateFindingSeverity(finding, input.policy));
+    const synthesis = synthesizeObservationFindings(input.collector.observations, thresholds, input.registry);
+    const allFindings = deduplicateFindings([
+        ...synthesis.findings.map((finding) => ({ finding, deduplicate: true })),
+        ...input.collector.findings,
+    ]).map((finding) => calibrateFindingSeverity(finding, input.policy));
     const ranked = rankFindings(allFindings);
     const minimumConfidence = input.policy.minimumConfidence ?? Confidence.Medium;
     const includeInformational = input.policy.includeInformational ?? false;
@@ -393,7 +546,10 @@ function buildReviewResult(input) {
         }
     }
     const positives = selectPositiveSignals(input.collector.positives);
-    const reviewObservations = deduplicateReviewObservations(input.collector.reviewObservations, positives);
+    const reviewObservations = deduplicateReviewObservations([
+        ...input.collector.reviewObservations,
+        ...deduplicateScores(input.collector.scores).map(scoreToReviewNote),
+    ], positives);
     return omitUndefined({
         adversary: input.adversary,
         target: omitUndefined({
@@ -403,11 +559,10 @@ function buildReviewResult(input) {
         assessment: input.collector.assessment ?? synthesizeAssessment(eligible, positives),
         positives,
         observations: reviewObservations,
-        scores: input.collector.scores.length > 0 ? deduplicateScores(input.collector.scores) : undefined,
         findings: eligible,
         opinion: input.collector.opinion ?? synthesizeOpinion(eligible),
         suppressed: {
-            observations: 0,
+            observations: synthesis.suppressedObservations,
             findings: suppressedFindings.length,
         },
         timing: input.timing,
@@ -415,25 +570,27 @@ function buildReviewResult(input) {
         rawObservations: input.includeRawObservations ? input.collector.observations : undefined,
     });
 }
-function synthesizeObservationFindings(observations, thresholds) {
+function synthesizeObservationFindings(observations, thresholds, registry) {
     const grouped = new Map();
     const seen = new Set();
+    let suppressedObservations = 0;
     for (const observation of observations) {
-        const rule = ruleRegistry.lookup(observation.ruleId);
+        const rule = registry.lookup(observation.ruleId);
         const groupKey = observation.groupKey ?? defaultObservationGroupKey(observation, rule);
         const dedupeKey = stableStringify({ groupKey, observation });
         if (observation.deduplicate !== false && seen.has(dedupeKey)) {
+            suppressedObservations += 1;
             continue;
         }
         seen.add(dedupeKey);
         grouped.set(groupKey, [...(grouped.get(groupKey) ?? []), observation]);
     }
-    return [...grouped.entries()].map(([groupKey, group]) => {
+    const findings = [...grouped.entries()].map(([groupKey, group]) => {
         const first = group[0];
         if (first === undefined) {
             throw new Error("Cannot synthesize finding from an empty observation group.");
         }
-        const rule = ruleRegistry.lookup(first.ruleId);
+        const rule = registry.lookup(first.ruleId);
         const synthesis = rule?.aggregate?.(group) ?? {};
         const synthesisSource = rule?.aggregate === undefined ? "generic" : "rule";
         log.debug(`review synthesis ruleId=${first.ruleId} groupKey=${groupKey} observations=${group.length} selected=${synthesisSource} fallback=${synthesisSource === "generic"}`);
@@ -443,7 +600,7 @@ function synthesizeObservationFindings(observations, thresholds) {
             : normalizeParagraph(synthesis.recommendation);
         const confidence = aggregateConfidence(group.map((observation) => normalizeConfidence(observation.confidence ?? rule?.defaultConfidence ?? Confidence.Medium, thresholds)), first.confidenceAggregation ?? "maximum");
         const severity = aggregateSeverity(group.map((observation) => observation.severity ?? rule?.defaultSeverity ?? Severity.Info), first.severityAggregation ?? "highest");
-        return {
+        const finding = {
             id: synthesis.id ?? stableId(`${first.ruleId}:${groupKey}`),
             ruleId: synthesis.ruleId ?? first.ruleId,
             groupKey: synthesis.groupKey ?? groupKey,
@@ -461,15 +618,18 @@ function synthesizeObservationFindings(observations, thresholds) {
             evidence,
             recommendation: recommendation.length > 0 ? recommendation : undefined,
             remediation: synthesis.remediation ?? first.remediation,
-            synthesisSource,
             tags: synthesis.tags ?? uniqueStrings(group.flatMap((observation) => observation.tags ?? [])),
             metadata: synthesis.metadata ?? first.metadata,
         };
+        assertFindingInput(finding, `adversary aggregate rule "${first.ruleId}"`);
+        return finding;
     });
+    return { findings, suppressedObservations };
 }
-function normalizeFindingInput(input) {
+function normalizeFindingInput(input, occurrence = 0) {
     return omitUndefined({
-        id: input.id ?? stableId(`${input.ruleId ?? input.title}:${input.groupKey ?? input.category}`),
+        id: input.id ??
+            stableId(`${input.ruleId ?? input.title}:${input.groupKey ?? input.category}${input.deduplicate === false ? `:${occurrence}` : ""}`),
         ruleId: input.ruleId,
         groupKey: input.groupKey,
         title: input.title,
@@ -489,7 +649,12 @@ function normalizeFindingInput(input) {
 function deduplicateFindings(findings) {
     const seen = new Set();
     const result = [];
-    for (const finding of findings) {
+    for (const collected of findings) {
+        const { finding } = collected;
+        if (!collected.deduplicate) {
+            result.push({ ...finding, evidence: deduplicateEvidence(finding.evidence) });
+            continue;
+        }
         const key = finding.groupKey ?? finding.id;
         if (seen.has(key)) {
             const existing = result.find((item) => (item.groupKey ?? item.id) === key);
@@ -508,7 +673,7 @@ function deduplicateEvidence(evidence) {
     const seen = new Set();
     const result = [];
     for (const item of evidence) {
-        const normalized = omitUndefined(item);
+        const normalized = normalizeEvidence(item);
         const key = stableStringify(normalized);
         if (!seen.has(key)) {
             seen.add(key);
@@ -516,17 +681,44 @@ function deduplicateEvidence(evidence) {
         }
     }
     return result.sort((left, right) => {
-        const fileComparison = compareStrings(left.file ?? "", right.file ?? "");
+        const fileComparison = compareStrings(left.location?.file ?? "", right.location?.file ?? "");
         if (fileComparison !== 0) {
             return fileComparison;
         }
-        const lineComparison = compareNumbers(left.line, right.line);
+        const lineComparison = compareNumbers(left.location?.line, right.location?.line);
         if (lineComparison !== 0) {
             return lineComparison;
         }
         return compareStrings(left.message ?? "", right.message ?? "");
     });
 }
+function normalizeEvidence(input) {
+    const legacy = input;
+    const hasLocation = legacy.location !== undefined ||
+        legacy.file !== undefined ||
+        legacy.line !== undefined ||
+        legacy.endLine !== undefined;
+    const location = hasLocation
+        ? omitUndefined({
+            file: legacy.location?.file ?? legacy.file,
+            line: legacy.location?.line ?? legacy.line,
+            endLine: legacy.location?.endLine ?? legacy.endLine,
+        })
+        : undefined;
+    return omitUndefined({
+        location,
+        label: input.label,
+        message: input.message,
+        snippet: input.snippet,
+        data: input.data ?? legacy.metadata,
+    });
+}
+function normalizeReviewNote(note) {
+    return omitUndefined({
+        ...note,
+        evidence: note.evidence === undefined ? undefined : deduplicateEvidence(note.evidence),
+    });
+}
 function deduplicateNotes(notes) {
     const seen = new Set();
     const result = [];
@@ -571,15 +763,10 @@ function notesDescribeSameFact(positive, observation) {
     }
     const positiveText = normalizeSemanticText(`${positive.key} ${positive.summary}`);
     const observationText = normalizeSemanticText(`${observation.key} ${observation.summary}`);
-    if (positiveText.length > 0 && positiveText === observationText) {
-        return true;
-    }
-    const positiveSignals = highSignalSemanticTokens(positiveText);
-    const observationSignals = highSignalSemanticTokens(observationText);
-    return positiveSignals.some((token) => observationSignals.includes(token));
+    return positiveText.length > 0 && positiveText === observationText;
 }
 function synthesizeAssessment(findings, positives = []) {
-    const strength = assessmentStrength(positives[0], findings);
+    const strength = assessmentStrength(positives[0]);
     if (findings.length === 0) {
         return {
             risk: "none",
@@ -600,13 +787,10 @@ function synthesizeAssessment(findings, positives = []) {
         summary: joinSentences(strength, `${numberWord(findings.length)} material concerns were identified. The highest-value improvement is ${primaryConcern}.`),
     };
 }
-function assessmentStrength(positive, findings) {
+function assessmentStrength(positive) {
     if (positive === undefined) {
         return undefined;
     }
-    if (findingsReferenceDockerfile(findings)) {
-        return "This is a well-structured production Dockerfile.";
-    }
     const summary = normalizeParagraph(positive.summary);
     if (/^uses\b/i.test(summary)) {
         return `The repository ${lowercaseFirst(summary)}`;
@@ -614,12 +798,6 @@ function assessmentStrength(positive, findings) {
     return summary;
 }
 function assessmentConcern(finding) {
-    const title = findingConcern(finding);
-    const recommendation = recommendationSubject(finding.recommendation);
-    if (recommendation === "Digest pinning" || /base images?.*digest/i.test(title)) {
-        const plural = /base images\b/i.test(title);
-        return `that the base ${plural ? "images are" : "image is"} referenced by mutable tags rather than immutable digests`;
-    }
     const summary = normalizeParagraph(finding.summary).split(/(?<=[.!?])\s+/, 1)[0];
     return concernClause(lowercaseFirst(trimTrailingSentencePunctuation(summary ?? findingConcern(finding))));
 }
@@ -643,7 +821,6 @@ function synthesizeOpinion(findings) {
     }
     const highestSeverity = highestFindingSeverity(findings);
     const ship = severityWeight(highestSeverity) < severityWeight(Severity.High);
-    const subject = findingsReferenceDockerfile(findings) ? "this Dockerfile" : "this";
     if (findings.length > 1) {
         return {
             ship,
@@ -655,16 +832,10 @@ function synthesizeOpinion(findings) {
     return {
         ship,
         summary: ship
-            ? `I would ship ${subject} as-is. ${improvement} is the only improvement I would recommend before production.`
+            ? `I would ship this as-is. ${improvement} is the only improvement I would recommend before production.`
             : `${improvement} is the most important improvement to address before production.`,
     };
 }
-function findingsReferenceDockerfile(findings) {
-    const files = findings.flatMap((finding) => finding.evidence
-        .map((evidence) => evidence.location?.file ?? evidence.file)
-        .filter(isNonEmptyString));
-    return files.length > 0 && files.every((file) => /(?:^|\/)Dockerfile$/.test(file));
-}
 function deduplicateScores(scores) {
     const seen = new Set();
     const result = [];
@@ -676,8 +847,27 @@ function deduplicateScores(scores) {
     }
     return result.sort((left, right) => compareStrings(left.key, right.key));
 }
+function scoreToReviewNote(score) {
+    return {
+        key: `score.${score.key}`,
+        summary: formatScore(score),
+        metadata: {
+            kind: "score",
+            score: omitUndefined({
+                key: score.key,
+                label: score.label,
+                score: score.score,
+                max: score.max,
+                summary: score.summary,
+            }),
+        },
+    };
+}
+function isScoreReviewNote(note) {
+    return note.metadata?.kind === "score" && isRecord(note.metadata.score);
+}
 function observationToEvidence(observation) {
-    const metadata = isRecord(observation.evidence)
+    const data = isRecord(observation.evidence)
         ? observation.evidence
         : observation.evidence === undefined
             ? undefined
@@ -690,19 +880,11 @@ function observationToEvidence(observation) {
             stringFromUnknown(observation.evidence.instruction))
         : observation.location?.snippet;
     return omitUndefined({
-        location: observation.location?.location ?? {
-            file: observation.location?.file,
-            line: observation.location?.line,
-            endLine: observation.location?.endLine,
-        },
-        file: observation.location?.file,
-        line: observation.location?.line,
-        endLine: observation.location?.endLine,
+        location: normalizeEvidence(observation.location ?? {}).location,
         label: observation.location?.label ?? message,
         message: observation.location?.message ?? message,
         snippet,
-        data: metadata,
-        metadata,
+        data,
     });
 }
 function structuredEvidenceMessage(evidence) {
@@ -710,10 +892,6 @@ function structuredEvidenceMessage(evidence) {
     if (explicitMessage !== undefined) {
         return explicitMessage;
     }
-    const stage = stringFromUnknown(evidence.stage);
-    if (stage !== undefined) {
-        return `${stage} stage`;
-    }
     const label = stringFromUnknown(evidence.label) ?? stringFromUnknown(evidence.name);
     if (label !== undefined) {
         return label;
@@ -789,7 +967,6 @@ function renderObservationTemplate(template, group) {
 function observationTemplateValues(group) {
     const first = group[0];
     const subjects = uniqueStrings(group.map((observation) => observation.subject));
-    const stages = uniqueStrings(group.map(extractStage).filter(isNonEmptyString));
     const locations = uniqueStrings(group.map(formatObservationLocation).filter(isNonEmptyString));
     return omitUndefined({
         count: numberWord(group.length),
@@ -797,8 +974,6 @@ function observationTemplateValues(group) {
         locations: joinHumanList(locations),
         subject: first?.subject,
         subjects: joinHumanList(subjects),
-        stage: stages[0],
-        stages: joinHumanList(stages),
     });
 }
 function observationValue(observation, field) {
@@ -809,19 +984,6 @@ function observationValue(observation, field) {
     }
     return observation[field];
 }
-function extractStage(observation) {
-    if (isRecord(observation.evidence)) {
-        const explicit = stringFromUnknown(observation.evidence.stage);
-        if (explicit !== undefined) {
-            return explicit;
-        }
-        const label = stringFromUnknown(observation.evidence.label);
-        if (label !== undefined) {
-            return trimTrailingWord(label, "stage");
-        }
-    }
-    return trimTrailingWord(observation.location?.label, "stage");
-}
 function formatObservationLocation(observation) {
     if (observation.location?.file === undefined) {
         return undefined;
@@ -862,10 +1024,6 @@ function recommendationSubject(recommendation) {
         return undefined;
     }
     const normalized = trimTrailingSentencePunctuation(normalizeParagraph(recommendation));
-    const pinDigest = normalized.match(/\bpin\b.*\bby digest\b/i);
-    if (pinDigest !== null) {
-        return "Digest pinning";
-    }
     const firstClause = normalized.split(/\s+(?:and|when|where|with)\s+/i)[0]?.trim();
     if (!isNonEmptyString(firstClause)) {
         return undefined;
@@ -883,6 +1041,7 @@ function gerundPhrase(phrase) {
 function toGerund(verb) {
     const lower = verb.toLowerCase();
     const irregular = {
+        pin: "pinning",
         run: "running",
         use: "using",
     };
@@ -895,21 +1054,6 @@ function toGerund(verb) {
     }
     return `${lower}ing`;
 }
-function highSignalSemanticTokens(value) {
-    return value
-        .split(" ")
-        .map(canonicalSemanticToken)
-        .filter((word) => highSignalReviewTerms.has(word));
-}
-function canonicalSemanticToken(value) {
-    if (value === "stages") {
-        return "stage";
-    }
-    if (value === "artifacts") {
-        return "artifact";
-    }
-    return trimTrailingWord(trimTrailingWord(value, "ing"), "ed") ?? value;
-}
 function normalizeSemanticText(value) {
     return value
         .toLowerCase()
@@ -947,12 +1091,10 @@ function calibrateFindingSeverity(finding, policy) {
 }
 function scoreFinding(finding) {
     const locationScore = Math.min(finding.evidence.length, 5) * 3;
-    const runtimeScore = finding.tags?.some((tag) => ["production", "runtime"].includes(tag)) ? 8 : 0;
     const remediationScore = finding.remediation?.complexity === "trivial" ? 3 : 0;
     return (severityWeight(finding.severity) * 10 +
         confidenceWeight(finding.confidence) * 12 +
         locationScore +
-        runtimeScore +
         remediationScore);
 }
 function severityWeight(severity) {
@@ -1034,11 +1176,11 @@ function stableStringify(value) {
 function uniqueStrings(values) {
     return [...new Set(values.filter(isNonEmptyString))].sort(compareStrings);
 }
-function assertObservationInit(value, source) {
+function assertObservationInit(value, source, registry) {
     requireString(value.ruleId, `${source}.ruleId`);
     requireString(value.subject, `${source}.subject`);
     requireObservationTitle(value.title, `${source}.title`);
-    const rule = ruleRegistry.lookup(value.ruleId);
+    const rule = registry.lookup(value.ruleId);
     if (value.category === undefined && rule?.category === undefined) {
         throw new Error(`${source}.category is required when rule.category is not defined.`);
     }
@@ -1080,6 +1222,7 @@ function assertFindingInput(value, source) {
     optionalString(value.ruleId, `${source}.ruleId`);
     optionalString(value.groupKey, `${source}.groupKey`);
     optionalStringArray(value.tags, `${source}.tags`);
+    optionalRemediation(value.remediation, `${source}.remediation`);
 }
 function assertReviewNote(value, source) {
     requireString(value.key, `${source}.key`);
@@ -1092,11 +1235,17 @@ function assertReviewNote(value, source) {
 }
 function assertReviewScore(value) {
     requireString(value.key, "ctx.review.score.key");
-    if (typeof value.score !== "number" || Number.isNaN(value.score)) {
-        throw new Error("ctx.review.score.score must be a number.");
+    if (typeof value.score !== "number" || !Number.isFinite(value.score)) {
+        throw new Error("ctx.review.score.score must be a finite number.");
+    }
+    if (value.max !== undefined && (typeof value.max !== "number" || !Number.isFinite(value.max))) {
+        throw new Error("ctx.review.score.max must be a finite number.");
     }
-    if (value.max !== undefined && (typeof value.max !== "number" || Number.isNaN(value.max))) {
-        throw new Error("ctx.review.score.max must be a number.");
+    if (value.score < 0) {
+        throw new Error("ctx.review.score.score must be greater than or equal to zero.");
+    }
+    if (value.max !== undefined && (value.max <= 0 || value.score > value.max)) {
+        throw new Error("ctx.review.score.max must be positive and no smaller than score.");
     }
     optionalString(value.label, "ctx.review.score.label");
     optionalString(value.summary, "ctx.review.score.summary");
@@ -1124,6 +1273,37 @@ function assertRuleDefinition(rule) {
         throw new Error("rule.aggregate must be a function.");
     }
 }
+function assertReviewPolicy(policy, source) {
+    if (policy.minimumConfidence !== undefined && !isConfidence(policy.minimumConfidence)) {
+        throw new Error(`${source}.minimumConfidence must be one of low, medium, high.`);
+    }
+    if (policy.maximumFindings !== undefined &&
+        (!Number.isInteger(policy.maximumFindings) || policy.maximumFindings < 0)) {
+        throw new Error(`${source}.maximumFindings must be a non-negative integer.`);
+    }
+    if (policy.confidenceThresholds !== undefined) {
+        const { medium, high } = policy.confidenceThresholds;
+        if (medium < 0 || high > 1 || medium > high) {
+            throw new Error(`${source}.confidenceThresholds must satisfy 0 <= medium <= high <= 1.`);
+        }
+    }
+    for (const [ruleId, severity] of Object.entries(policy.severityOverrides ?? {})) {
+        if (!isSeverity(severity)) {
+            throw new Error(`${source}.severityOverrides["${ruleId}"] is not a valid severity.`);
+        }
+    }
+}
+function optionalRemediation(value, field) {
+    if (value === undefined)
+        return;
+    if (!isRecord(value))
+        throw new Error(`${field} must be an object.`);
+    if (value.complexity !== undefined &&
+        (typeof value.complexity !== "string" ||
+            !["trivial", "small", "medium", "large", "architectural"].includes(value.complexity))) {
+        throw new Error(`${field}.complexity is invalid.`);
+    }
+}
 function requireObservationTitle(value, field) {
     if (typeof value === "string") {
         requireString(value, field);
@@ -1156,12 +1336,35 @@ function optionalEvidence(value, field) {
     if (!isRecord(value)) {
         throw new Error(`${field} must be an object.`);
     }
-    optionalString(value.file, `${field}.file`);
-    optionalPositiveInteger(value.line, `${field}.line`);
-    optionalPositiveInteger(value.endLine, `${field}.endLine`);
+    const input = value;
+    optionalString(input.file, `${field}.file`);
+    optionalPositiveInteger(input.line, `${field}.line`);
+    optionalPositiveInteger(input.endLine, `${field}.endLine`);
     optionalString(value.message, `${field}.message`);
     optionalString(value.snippet, `${field}.snippet`);
     optionalString(value.label, `${field}.label`);
+    if (value.location !== undefined) {
+        if (!isRecord(value.location)) {
+            throw new Error(`${field}.location must be an object.`);
+        }
+        optionalString(value.location.file, `${field}.location.file`);
+        optionalPositiveInteger(value.location.line, `${field}.location.line`);
+        optionalPositiveInteger(value.location.endLine, `${field}.location.endLine`);
+    }
+    const line = value.location?.line ?? input.line;
+    const endLine = value.location?.endLine ?? input.endLine;
+    if (endLine !== undefined && line === undefined) {
+        throw new Error(`${field}.endLine requires line.`);
+    }
+    if (endLine !== undefined && line !== undefined && endLine < line) {
+        throw new Error(`${field}.endLine must not precede line.`);
+    }
+    if (value.data !== undefined && !isRecord(value.data)) {
+        throw new Error(`${field}.data must be an object.`);
+    }
+    if (input.metadata !== undefined && !isRecord(input.metadata)) {
+        throw new Error(`${field}.metadata must be an object.`);
+    }
 }
 function writeLog(level, message) {
     process.stderr.write(`[adversary] ${level}: ${String(message)}\n`);
@@ -1245,18 +1448,10 @@ const semanticStopWords = new Set([
     "uses",
     "using",
 ]);
-const highSignalReviewTerms = new Set([
-    "artifact",
-    "builder",
-    "digest",
-    "multi",
-    "runtime",
-    "stage",
-]);
 function formatEvidenceLocation(evidence) {
-    const file = evidence.location?.file ?? evidence.file;
-    const line = evidence.location?.line ?? evidence.line;
-    const endLine = evidence.location?.endLine ?? evidence.endLine;
+    const file = evidence.location?.file;
+    const line = evidence.location?.line;
+    const endLine = evidence.location?.endLine;
     if (file === undefined) {
         return "";
     }