@minionry/minion 0.7.36

package/dist/server/services/sdk/quality.js

@@ -0,0 +1,602 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { isEngineId } from '../../engines/types.js';
+import { getClientId } from '../client-id.js';
+import { getQualityAgentNotes, getQualityEffortLevel, getQualityEngine, getQualityFastMode, getQualityModel, makeSpaceKey, updateQualitySettings, } from '../settings.js';
+import { getPersistence, resolveQualitySdkPath } from '../websocket/quality-handlers.js';
+import { operationRegistry } from '../websocket/quality-operations.js';
+import { mergeCodeReview } from '../websocket/quality-persistence.js';
+import { runQualityPipeline, } from '../websocket/quality-run.js';
+import { applyDismissals, detectTools, indexDismissals, installTools, stampDismissals } from '../websocket/quality-service.js';
+import { getGrant } from './grant-store.js';
+import { deregisterLiveSubscription, listLiveSubscriptions, registerLiveSubscription } from './live-registry.js';
+import { notifyQualityChanged, registerQualityChangeListener } from './quality-change-notify.js';
+import { listQualityScheduleSnapshots } from './quality-schedule.js';
+import { SdkMethodError } from './registry.js';
+const MAX_HISTORY_ENTRIES = 100;
+const MAX_FINGERPRINTS_PER_CALL = 1_000;
+const MAX_DISMISSAL_REASON_LENGTH = 500;
+function paramsObject(params) {
+    return typeof params === 'object' && params !== null && !Array.isArray(params)
+        ? params
+        : {};
+}
+function resolvePathParam(args, raw) {
+    if (raw.path !== undefined && (typeof raw.path !== 'string' || raw.path === '')) {
+        throw new SdkMethodError('BAD_REQUEST', `${args.method}: path must be a non-empty string when present`);
+    }
+    const reportPath = typeof raw.path === 'string' ? raw.path : '.';
+    const { resolved, error } = resolveQualitySdkPath(args.workingDir, raw.path);
+    if (error)
+        throw new SdkMethodError('BAD_REQUEST', `${args.method}: ${error}`);
+    return { reportPath, dirPath: resolved };
+}
+function loadSuppressions(workingDir) {
+    return getPersistence(workingDir).loadSuppressions();
+}
+function toSdkReport(path, persisted, suppressions) {
+    const results = applyDismissals(persisted, indexDismissals(path, suppressions));
+    return {
+        path,
+        overall: results.grade === 'N/A' ? null : results.overall,
+        grade: results.grade,
+        dimensions: (results.dimensions ?? []).map((d) => ({ ...d, score: d.available ? d.score : null })),
+        categories: (results.categories ?? []).map(({ name, score, available, issueCount, reason }) => ({
+            name,
+            score,
+            available,
+            issueCount,
+            ...(reason === undefined ? {} : { reason }),
+        })),
+        findings: results.findings ?? [],
+        codeReview: results.codeReview ?? [],
+        analyzedFiles: results.analyzedFiles,
+        totalLines: results.totalLines,
+        timestamp: results.timestamp,
+        ecosystem: results.ecosystem ?? [],
+        scoreBreakdown: results.scoreBreakdown,
+        gate: results.qualityGate,
+        gradeRationale: results.gradeRationale,
+        readiness: results.readiness,
+        triage: results.triage,
+        scanDurationMs: results.scanDurationMs,
+        reviewDurationMs: results.reviewDurationMs,
+        reviewSessionId: results.reviewSessionId,
+        ...(results.baselineAt === undefined ? {} : { baselineAt: results.baselineAt }),
+        ...(results.agentCost === undefined ? {} : { agentCost: results.agentCost }),
+        ...(results.structuralScope === undefined ? {} : { structuralScope: results.structuralScope }),
+        ...(results.changeActivity === undefined ? {} : { changeActivity: results.changeActivity }),
+        ...(results.commit === undefined ? {} : { commit: results.commit }),
+    };
+}
+function toSdkHistoryEntry(entry) {
+    return {
+        ...entry,
+        ...(entry.commit === undefined ? {} : { commit: entry.commit }),
+        overall: entry.grade === 'N/A' ? null : entry.overall,
+        dimensionScores: entry.dimensionScores && {
+            security: {
+                score: entry.dimensionScores.security.grade === 'N/A' ? null : entry.dimensionScores.security.score,
+                grade: entry.dimensionScores.security.grade,
+            },
+            reliability: {
+                score: entry.dimensionScores.reliability.grade === 'N/A' ? null : entry.dimensionScores.reliability.score,
+                grade: entry.dimensionScores.reliability.grade,
+            },
+            maintainability: {
+                score: entry.dimensionScores.maintainability.grade === 'N/A' ? null : entry.dimensionScores.maintainability.score,
+                grade: entry.dimensionScores.maintainability.grade,
+            },
+        },
+        directories: entry.directories.map((d) => ({ ...d, score: d.grade === 'N/A' ? null : d.score })),
+    };
+}
+function toSdkPendingResult(pending, suppressions) {
+    const data = pending.data;
+    if (pending.type === 'scanResults') {
+        return data.results
+            ? { kind: 'scanResults', path: pending.path, completedAt: pending.completedAt, report: toSdkReport(pending.path, data.results, suppressions) }
+            : null;
+    }
+    return Array.isArray(data.findings)
+        ? {
+            kind: 'codeReview',
+            path: pending.path,
+            completedAt: pending.completedAt,
+            findings: stampDismissals(data.findings.map((f) => ({ ...f })), indexDismissals(pending.path, suppressions)),
+        }
+        : null;
+}
+const qualityRuns = new Map();
+const MAX_TERMINAL_RUNS = 50;
+function runKey(workingDir, path) {
+    return `${workingDir}::${path}`;
+}
+function pruneTerminalRuns() {
+    let excess = qualityRuns.size - MAX_TERMINAL_RUNS;
+    if (excess <= 0)
+        return;
+    for (const [key, record] of qualityRuns) {
+        if (excess <= 0)
+            break;
+        if (record.outcome) {
+            qualityRuns.delete(key);
+            excess -= 1;
+        }
+    }
+}
+export function resetSdkQualityRuns() {
+    qualityRuns.clear();
+}
+function newRunRecord(workingDir, path, phase) {
+    const record = { workingDir, path, phase, listeners: new Map(), waiters: [] };
+    qualityRuns.set(runKey(workingDir, path), record);
+    pruneTerminalRuns();
+    return record;
+}
+function emitRunEvent(record, event, payload) {
+    for (const listener of record.listeners.values()) {
+        try {
+            listener(event, payload);
+        }
+        catch (error) {
+            console.error('[SdkQuality] run event delivery failed:', error);
+        }
+    }
+}
+function settleRun(record, outcome) {
+    if (record.outcome)
+        return;
+    record.outcome = outcome;
+    for (const waiter of record.waiters.splice(0))
+        waiter(outcome);
+    for (const requestId of record.listeners.keys())
+        deregisterLiveSubscription(requestId);
+    record.listeners.clear();
+}
+function toSdkLeg(leg) {
+    return {
+        status: leg.status,
+        ...(leg.code !== undefined ? { code: leg.code } : {}),
+        ...(leg.message !== undefined ? { message: leg.message } : {}),
+        ...(leg.sessionId !== undefined ? { sessionId: leg.sessionId } : {}),
+    };
+}
+function toSdkRunResult(path, outcome, suppressions) {
+    return {
+        path,
+        status: outcome.status,
+        report: outcome.report ? toSdkReport(path, outcome.report, suppressions) : null,
+        legs: { scan: toSdkLeg(outcome.legs.scan), review: toSdkLeg(outcome.legs.review) },
+        ...(outcome.sessionId === undefined ? {} : { sessionId: outcome.sessionId }),
+    };
+}
+function deliverLeg(workingDir, type, path, data) {
+    try {
+        getPersistence(workingDir).addPendingResult({ type, path, data, completedAt: new Date().toISOString() });
+    }
+    catch {
+    }
+}
+function startRun(workingDir, spaceKey, reportPath, dirPath, initiator) {
+    const persistence = getPersistence(workingDir);
+    const controller = operationRegistry.start(workingDir, reportPath, 'scanning');
+    persistence.setActiveOperation(reportPath, 'scanning');
+    const record = newRunRecord(workingDir, reportPath, 'detecting');
+    queueMicrotask(() => {
+        void runQualityPipeline({
+            workingDir,
+            reportPath,
+            dirPath,
+            persistence,
+            signal: controller.signal,
+            initiator,
+            onPhase: (phase, meta) => {
+                record.phase = phase;
+                if (meta?.sessionId)
+                    record.sessionId = meta.sessionId;
+                emitRunEvent(record, 'phase', { phase, ...(meta?.sessionId ? { sessionId: meta.sessionId } : {}) });
+            },
+            onSession: (sessionId) => {
+                record.sessionId = sessionId;
+                emitRunEvent(record, 'session', { sessionId });
+            },
+            onProgress: (frame) => {
+                record.lastProgress = frame;
+                emitRunEvent(record, 'progress', frame);
+            },
+            onScanResults: (results) => {
+                deliverLeg(workingDir, 'scanResults', reportPath, { path: reportPath, results });
+                notifyQualityChanged(spaceKey, { kind: 'results', path: reportPath, results });
+            },
+            onReviewResults: ({ findings, summary, results }) => {
+                const data = { path: reportPath, findings, summary, results };
+                deliverLeg(workingDir, 'codeReview', reportPath, data);
+                if (results)
+                    notifyQualityChanged(spaceKey, { kind: 'results', path: reportPath, results });
+            },
+        })
+            .catch((error) => ({
+            status: 'error',
+            report: null,
+            legs: {
+                scan: { status: 'failed', message: error instanceof Error ? error.message : String(error) },
+                review: { status: 'skipped' },
+            },
+        }))
+            .then((outcome) => {
+            operationRegistry.finish(workingDir, reportPath);
+            persistence.clearActiveOperation(reportPath);
+            settleRun(record, toSdkRunResult(reportPath, outcome, loadSuppressions(workingDir)));
+        });
+    });
+    return record;
+}
+export function startScheduledQualityRun(workingDir, reportPath, initiator) {
+    const { resolved, error } = resolveQualitySdkPath(workingDir, reportPath);
+    if (error)
+        throw new Error(error);
+    if (operationRegistry.has(workingDir, reportPath)) {
+        throw new Error(`a quality operation already holds '${reportPath}'`);
+    }
+    const spaceKey = makeSpaceKey(getClientId(), workingDir);
+    const record = startRun(workingDir, spaceKey, reportPath, resolved, initiator);
+    let settledError;
+    let settleCallback = null;
+    const finish = (error) => {
+        if (settledError !== undefined)
+            return;
+        settledError = error;
+        settleCallback?.(error);
+    };
+    if (record.outcome)
+        finish(scheduledOutcomeError(record.outcome));
+    else
+        record.waiters.push((outcome) => finish(scheduledOutcomeError(outcome)));
+    return {
+        path: reportPath,
+        onSettle(callback) {
+            settleCallback = callback;
+            if (settledError !== undefined)
+                callback(settledError);
+        },
+        isActive: () => record.outcome === undefined,
+    };
+}
+function scheduledOutcomeError(outcome) {
+    if (outcome.status === 'ok' || outcome.status === 'partial')
+        return null;
+    if (outcome.status === 'cancelled')
+        return 'cancelled';
+    return outcome.legs.scan.message ?? outcome.legs.review.message ?? 'quality run failed';
+}
+function attachForeignRun(workingDir, reportPath) {
+    const kind = operationRegistry.getKind(workingDir, reportPath);
+    const record = newRunRecord(workingDir, reportPath, kind === 'reviewing' ? 'reviewing' : 'scanning');
+    void operationRegistry.whenFinished(workingDir, reportPath).then(() => {
+        const report = getPersistence(workingDir).loadReport(reportPath);
+        settleRun(record, report
+            ? {
+                path: reportPath,
+                status: 'ok',
+                report: toSdkReport(reportPath, report, loadSuppressions(workingDir)),
+                legs: { scan: { status: 'ok' }, review: { status: kind === 'reviewing' ? 'ok' : 'skipped' } },
+            }
+            : {
+                path: reportPath,
+                status: 'error',
+                report: null,
+                legs: {
+                    scan: { status: 'failed', message: 'the operation this run attached to produced no report' },
+                    review: { status: 'skipped' },
+                },
+            });
+    });
+    return record;
+}
+function subscribeRun(record, args, attached) {
+    const listener = (event, payload) => args.emit(event, payload);
+    record.listeners.set(args.requestId, listener);
+    registerLiveSubscription({
+        requestId: args.requestId,
+        appId: args.appId,
+        origin: args.origin,
+        spaceKey: args.spaceKey,
+        kind: 'quality.run',
+        viewerId: getGrant(args.appId, args.spaceKey) ? undefined : args.viewerId,
+        teardown: () => {
+            record.listeners.delete(args.requestId);
+        },
+    });
+    if (!attached)
+        return;
+    args.emit('phase', { phase: record.phase, ...(record.sessionId ? { sessionId: record.sessionId } : {}) });
+    if (record.sessionId)
+        args.emit('session', { sessionId: record.sessionId });
+    if (record.lastProgress)
+        args.emit('progress', record.lastProgress);
+}
+export function qualityStateHandler(args) {
+    const persistence = getPersistence(args.workingDir);
+    const state = persistence.loadState();
+    const suppressions = persistence.loadSuppressions();
+    const pendingResults = state.pendingResults
+        .map((pending) => toSdkPendingResult(pending, suppressions))
+        .filter((entry) => entry !== null);
+    if (state.pendingResults.length > 0)
+        persistence.clearPendingResults();
+    const live = [];
+    for (const op of state.activeOperations) {
+        if (operationRegistry.has(args.workingDir, op.path)) {
+            live.push(op);
+        }
+        else {
+            persistence.clearActiveOperation(op.path);
+        }
+    }
+    const reports = {};
+    for (const [path, results] of Object.entries(state.reports)) {
+        reports[path] = toSdkReport(path, results, suppressions);
+    }
+    return {
+        directories: state.directories.map(({ path, label }) => ({ path, label })),
+        reports,
+        history: state.history.slice(-MAX_HISTORY_ENTRIES).map(toSdkHistoryEntry),
+        activeOperations: live.map((op) => ({
+            kind: op.type,
+            path: op.path,
+            startedAt: op.startedAt,
+            ...(op.sessionId ? { sessionId: op.sessionId } : {}),
+        })),
+        pendingResults,
+        schedules: listQualityScheduleSnapshots(args.workingDir),
+    };
+}
+export function qualityResultHandler(args) {
+    const { reportPath } = resolvePathParam(args, paramsObject(args.params));
+    const tracked = qualityRuns.get(runKey(args.workingDir, reportPath));
+    if (!tracked && !operationRegistry.has(args.workingDir, reportPath)) {
+        throw new SdkMethodError('BAD_REQUEST', `${args.method}: no quality run is tracked for '${reportPath}' — start one with run(), or read the last report with state()`);
+    }
+    const record = tracked ?? attachForeignRun(args.workingDir, reportPath);
+    if (record.outcome)
+        return record.outcome;
+    return new Promise((resolve) => record.waiters.push(resolve));
+}
+export async function qualityDetectToolsHandler(args) {
+    const { reportPath, dirPath } = resolvePathParam(args, paramsObject(args.params));
+    const { tools, ecosystem } = await detectTools(dirPath);
+    return { path: reportPath, tools, ecosystem };
+}
+export function qualitySettingsHandler(_args) {
+    return {
+        engine: getQualityEngine(),
+        model: getQualityModel(),
+        effortLevel: getQualityEffortLevel(),
+        fastMode: getQualityFastMode(),
+        agentNotes: getQualityAgentNotes(),
+    };
+}
+function toSdkChangeEvent(workingDir, change) {
+    switch (change.kind) {
+        case 'results':
+            return { kind: 'results', path: change.path, report: toSdkReport(change.path, change.results, loadSuppressions(workingDir)) };
+        case 'directories':
+            return { kind: 'directories', directories: change.directories };
+        case 'tools':
+            return { kind: 'tools', path: change.path, tools: change.tools, ecosystem: change.ecosystem };
+        case 'postSession':
+            return { kind: 'postSession', path: change.path, report: toSdkReport(change.path, change.results, loadSuppressions(workingDir)) };
+        case 'agentTurn':
+            return {
+                kind: 'agentTurn',
+                path: change.path,
+                ...(change.worktree ? { worktree: true } : {}),
+                changedFiles: change.changedFiles,
+                report: toSdkReport(change.path, change.results, loadSuppressions(workingDir)),
+            };
+        case 'schedules':
+            return { kind: 'schedules', schedules: change.schedules };
+    }
+}
+export function qualitySubscribeChangesHandler(args) {
+    if (listLiveSubscriptions().some((sub) => sub.requestId === args.requestId)) {
+        throw new SdkMethodError('BAD_REQUEST', `requestId '${args.requestId}' already holds a live subscription`);
+    }
+    let active = true;
+    const unsubscribe = registerQualityChangeListener(args.spaceKey, (change) => {
+        if (!active)
+            return;
+        args.emit('changed', toSdkChangeEvent(args.workingDir, change));
+    });
+    registerLiveSubscription({
+        requestId: args.requestId,
+        appId: args.appId,
+        origin: args.origin,
+        spaceKey: args.spaceKey,
+        kind: 'quality.subscribeChanges',
+        viewerId: getGrant(args.appId, args.spaceKey) ? undefined : args.viewerId,
+        teardown: () => {
+            active = false;
+            unsubscribe();
+        },
+    });
+    return { subscribed: true };
+}
+export function qualityRunHandler(args) {
+    const { reportPath, dirPath } = resolvePathParam(args, paramsObject(args.params));
+    const live = qualityRuns.get(runKey(args.workingDir, reportPath));
+    let record;
+    let attached = true;
+    if (live && !live.outcome) {
+        record = live;
+    }
+    else if (operationRegistry.has(args.workingDir, reportPath)) {
+        record = attachForeignRun(args.workingDir, reportPath);
+    }
+    else {
+        record = startRun(args.workingDir, args.spaceKey, reportPath, dirPath, { appId: args.appId, origin: args.origin });
+        attached = false;
+    }
+    subscribeRun(record, args, attached);
+    return { path: reportPath, attached };
+}
+export async function qualityInstallToolsHandler(args) {
+    const raw = paramsObject(args.params);
+    const { reportPath, dirPath } = resolvePathParam(args, raw);
+    const requested = raw.tools;
+    if (requested !== undefined && !(Array.isArray(requested) && requested.every((name) => typeof name === 'string'))) {
+        throw new SdkMethodError('BAD_REQUEST', `${args.method}: tools must be an array of strings when present`);
+    }
+    if (operationRegistry.has(args.workingDir, reportPath)) {
+        const kind = operationRegistry.getKind(args.workingDir, reportPath);
+        throw new SdkMethodError('OPERATION_IN_PROGRESS', `${args.method}: a ${kind ?? 'quality'} operation is already running for '${reportPath}' — installing into it would corrupt its inputs`);
+    }
+    const { tools, ecosystem } = await installTools(dirPath, requested);
+    notifyQualityChanged(args.spaceKey, { kind: 'tools', path: reportPath, tools, ecosystem });
+    return { path: reportPath, tools, ecosystem };
+}
+export function qualityCancelHandler(args) {
+    const { reportPath } = resolvePathParam(args, paramsObject(args.params));
+    operationRegistry.cancel(args.workingDir, reportPath);
+    getPersistence(args.workingDir).clearActiveOperation(reportPath);
+    return null;
+}
+export function qualitySaveDirectoriesHandler(args) {
+    const raw = paramsObject(args.params);
+    const input = raw.directories;
+    if (!Array.isArray(input)) {
+        throw new SdkMethodError('BAD_REQUEST', `${args.method} requires params { directories } — an array of { path, label }`);
+    }
+    const directories = [];
+    for (const entry of input) {
+        const dir = paramsObject(entry);
+        if (typeof dir.path !== 'string' || dir.path === '' || typeof dir.label !== 'string') {
+            throw new SdkMethodError('BAD_REQUEST', `${args.method}: every directory needs a non-empty string path and a string label`);
+        }
+        const { error } = resolveQualitySdkPath(args.workingDir, dir.path);
+        if (error)
+            throw new SdkMethodError('BAD_REQUEST', `${args.method}: ${error}`);
+        directories.push({ path: dir.path, label: dir.label });
+    }
+    getPersistence(args.workingDir).saveConfig(directories);
+    notifyQualityChanged(args.spaceKey, { kind: 'directories', directories });
+    return null;
+}
+export function qualitySetSettingsHandler(args) {
+    const raw = paramsObject(args.params);
+    const { engine, model, effortLevel } = raw;
+    if (engine !== undefined && !isEngineId(engine)) {
+        throw new SdkMethodError('BAD_REQUEST', `${args.method}: engine must be a known engine id`);
+    }
+    if (model !== undefined && (typeof model !== 'string' || model === '')) {
+        throw new SdkMethodError('BAD_REQUEST', `${args.method}: model must be a non-empty string`);
+    }
+    if (effortLevel !== undefined && (typeof effortLevel !== 'string' || effortLevel === '')) {
+        throw new SdkMethodError('BAD_REQUEST', `${args.method}: effortLevel must be a non-empty string`);
+    }
+    const fastMode = booleanParam(args, raw, 'fastMode');
+    const agentNotes = booleanParam(args, raw, 'agentNotes');
+    updateQualitySettings({
+        qualityEngine: engine,
+        qualityModel: model,
+        qualityEffortLevel: effortLevel,
+        qualityFastMode: fastMode,
+        qualityAgentNotes: agentNotes,
+    });
+    return qualitySettingsHandler(args);
+}
+function booleanParam(args, raw, key) {
+    const value = raw[key];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'boolean') {
+        throw new SdkMethodError('BAD_REQUEST', `${args.method}: ${key} must be a boolean`);
+    }
+    return value;
+}
+function displayCopyOf(finding) {
+    return {
+        title: typeof finding.title === 'string' ? finding.title : '',
+        file: typeof finding.file === 'string' ? finding.file : '',
+    };
+}
+function indexPersistedFingerprints(report, review) {
+    const known = new Map();
+    const listed = [
+        ...(report.findings ?? []),
+        ...(report.codeReview ?? []),
+        ...(review?.findings ?? []),
+    ];
+    for (const finding of listed) {
+        if (typeof finding.fingerprint === 'string' && !known.has(finding.fingerprint)) {
+            known.set(finding.fingerprint, displayCopyOf(finding));
+        }
+    }
+    for (const fingerprint of [...(report.fingerprints ?? []), ...(review?.fingerprints ?? [])]) {
+        if (!known.has(fingerprint))
+            known.set(fingerprint, { title: '', file: '' });
+    }
+    return known;
+}
+function parseFindingStateRequest(args) {
+    const raw = paramsObject(args.params);
+    if (typeof raw.path !== 'string' || raw.path === '') {
+        throw new SdkMethodError('BAD_REQUEST', `${args.method}: path is required (a directory relative to the working directory)`);
+    }
+    const { error } = resolveQualitySdkPath(args.workingDir, raw.path);
+    if (error)
+        throw new SdkMethodError('BAD_REQUEST', `${args.method}: ${error}`);
+    const fingerprints = raw.fingerprints;
+    if (!Array.isArray(fingerprints) || fingerprints.length === 0 || fingerprints.some((entry) => typeof entry !== 'string' || entry === '')) {
+        throw new SdkMethodError('BAD_REQUEST', `${args.method}: fingerprints must be a non-empty array of non-empty strings`);
+    }
+    if (fingerprints.length > MAX_FINGERPRINTS_PER_CALL) {
+        throw new SdkMethodError('BAD_REQUEST', `${args.method}: fingerprints holds ${fingerprints.length} entries; at most ${MAX_FINGERPRINTS_PER_CALL} per call`);
+    }
+    if (raw.state !== 'dismissed' && raw.state !== 'active') {
+        throw new SdkMethodError('BAD_REQUEST', `${args.method}: state must be 'dismissed' or 'active'`);
+    }
+    return {
+        reportPath: raw.path,
+        fingerprints: [...new Set(fingerprints)],
+        state: raw.state,
+        reason: typeof raw.reason === 'string' ? raw.reason.trim() : '',
+    };
+}
+export function qualitySetFindingStateHandler(args) {
+    const request = parseFindingStateRequest(args);
+    const persistence = getPersistence(args.workingDir);
+    const report = persistence.loadReport(request.reportPath);
+    const review = persistence.loadCodeReview(request.reportPath);
+    const entries = persistence.loadSuppressions();
+    const requested = new Set(request.fingerprints);
+    const kept = entries.filter((entry) => !(entry.path === request.reportPath && requested.has(entry.fingerprint)));
+    if (request.state === 'active') {
+        const present = new Set(entries.filter((entry) => entry.path === request.reportPath).map((entry) => entry.fingerprint));
+        const applied = request.fingerprints.filter((fingerprint) => present.has(fingerprint)).length;
+        const { dropped } = persistence.saveSuppressions(kept);
+        if (report) {
+            notifyQualityChanged(args.spaceKey, { kind: 'results', path: request.reportPath, results: mergeCodeReview(report, review) });
+        }
+        return { applied, dropped };
+    }
+    if (request.reason === '' || request.reason.length > MAX_DISMISSAL_REASON_LENGTH) {
+        throw new SdkMethodError('BAD_REQUEST', `${args.method}: reason is required to dismiss (1–${MAX_DISMISSAL_REASON_LENGTH} characters after trimming)`);
+    }
+    const known = report ? indexPersistedFingerprints(report, review) : new Map();
+    const unknown = request.fingerprints.filter((fingerprint) => !known.has(fingerprint));
+    if (!report || unknown.length > 0) {
+        throw new SdkMethodError('BAD_REQUEST', `${args.method}: unknown fingerprint(s) for '${request.reportPath}': ${unknown.join(', ')}`);
+    }
+    const dismissedAt = new Date().toISOString();
+    const written = [];
+    for (const fingerprint of request.fingerprints) {
+        const copy = known.get(fingerprint);
+        if (copy)
+            written.push({ fingerprint, path: request.reportPath, reason: request.reason, dismissedAt, title: copy.title, file: copy.file });
+    }
+    const { dropped } = persistence.saveSuppressions([...kept, ...written]);
+    notifyQualityChanged(args.spaceKey, { kind: 'results', path: request.reportPath, results: mergeCodeReview(report, review) });
+    return { applied: written.length, dropped };
+}