@saiteja1123/mcp-server 1.1.4 → 1.1.6

package/src/deep-scan/contracts.js

@@ -0,0 +1,201 @@
+import { assertSourceSafePayload, cloneSourceSafe } from './sourceSafe.js';
+
+export const STEP_STATUSES = Object.freeze([
+  'pending',
+  'running',
+  'passed',
+  'failed',
+  'skipped',
+  'blocked',
+  'needs_human',
+]);
+
+export const APPROVAL_DECISIONS = Object.freeze(['requested', 'approved', 'denied']);
+
+const UUIDISH = /^[a-zA-Z0-9_.:-]+$/;
+const SHA256 = /^[a-f0-9]{64}$/i;
+
+const requireString = (value, name, { max = 500, pattern = null } = {}) => {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new Error(`${name} must be a non-empty string`);
+  }
+  if (value.length > max) throw new Error(`${name} must be ${max} characters or fewer`);
+  if (pattern && !pattern.test(value)) throw new Error(`${name} has an invalid format`);
+  return value;
+};
+
+const optionalString = (value, name, options) => {
+  if (value === undefined || value === null) return undefined;
+  return requireString(value, name, options);
+};
+
+const requireIsoDate = (value, name) => {
+  requireString(value, name, { max: 40 });
+  if (Number.isNaN(Date.parse(value))) throw new Error(`${name} must be an ISO timestamp`);
+  return value;
+};
+
+export const validateRunIdSegment = (value, name = 'runId') => {
+  const runId = requireString(value, name, { max: 160, pattern: UUIDISH });
+  if (runId === '.' || runId === '..') throw new Error(`${name} must not be a dot-only path segment`);
+  return runId;
+};
+
+const asArray = (value, name) => {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) throw new Error(`${name} must be an array`);
+  return value;
+};
+
+export function createArtifactRef(input) {
+  assertSourceSafePayload(input, 'artifact');
+  const artifact = {
+    id: requireString(input?.id, 'artifact.id', { max: 120, pattern: UUIDISH }),
+    type: requireString(input?.type, 'artifact.type', { max: 80, pattern: UUIDISH }),
+    storage: requireString(input?.storage, 'artifact.storage', { max: 40, pattern: UUIDISH }),
+    uri: optionalString(input?.uri, 'artifact.uri', { max: 1000 }),
+    hash: optionalString(input?.hash, 'artifact.hash', { max: 64, pattern: SHA256 }),
+    preview: optionalString(input?.preview, 'artifact.preview', { max: 500 }),
+    metadata: cloneSourceSafe(input?.metadata || {}, 'artifact.metadata'),
+  };
+  assertSourceSafePayload(artifact, 'artifact');
+  return artifact;
+}
+
+export function validateArtifactRef(input) {
+  return createArtifactRef(input);
+}
+
+export function createReceiptRef(input = {}) {
+  assertSourceSafePayload(input, 'receipt');
+  const receipt = {
+    id: requireString(input.id, 'receipt.id', { max: 160, pattern: UUIDISH }),
+    type: requireString(input.type, 'receipt.type', { max: 80, pattern: UUIDISH }),
+    source: requireString(input.source, 'receipt.source', { max: 80, pattern: UUIDISH }),
+    artifactId: optionalString(input.artifactId, 'receipt.artifactId', { max: 120, pattern: UUIDISH }),
+    artifactHash: optionalString(input.artifactHash, 'receipt.artifactHash', { max: 64, pattern: SHA256 }),
+    engine: cloneSourceSafe(input.engine || {}, 'receipt.engine'),
+    summary: cloneSourceSafe(input.summary || {}, 'receipt.summary'),
+    verification: cloneSourceSafe(input.verification || {}, 'receipt.verification'),
+    metadata: cloneSourceSafe(input.metadata || {}, 'receipt.metadata'),
+    createdAt: input.createdAt ? requireIsoDate(input.createdAt, 'receipt.createdAt') : new Date().toISOString(),
+  };
+  assertSourceSafePayload(receipt, 'receipt');
+  return receipt;
+}
+
+export function validateReceiptRef(input) {
+  return createReceiptRef(input);
+}
+
+export function validateEvidence(input = {}) {
+  assertSourceSafePayload(input, 'evidence');
+  const evidence = {
+    type: requireString(input.type, 'evidence.type', { max: 80, pattern: UUIDISH }),
+    label: requireString(input.label, 'evidence.label', { max: 160 }),
+    uri: optionalString(input.uri, 'evidence.uri', { max: 1000 }),
+    hash: optionalString(input.hash, 'evidence.hash', { max: 64, pattern: SHA256 }),
+    preview: optionalString(input.preview, 'evidence.preview', { max: 500 }),
+    summary: optionalString(input.summary, 'evidence.summary', { max: 1000 }),
+    metadata: cloneSourceSafe(input.metadata || {}, 'evidence.metadata'),
+  };
+  assertSourceSafePayload(evidence, 'evidence');
+  return evidence;
+}
+
+export function validateFinding(input = {}) {
+  assertSourceSafePayload(input, 'finding');
+  const finding = {
+    id: optionalString(input.id, 'finding.id', { max: 120, pattern: UUIDISH }),
+    ruleId: optionalString(input.ruleId, 'finding.ruleId', { max: 80, pattern: UUIDISH }),
+    ruleName: optionalString(input.ruleName, 'finding.ruleName', { max: 160 }),
+    severity: optionalString(input.severity, 'finding.severity', { max: 20, pattern: UUIDISH }),
+    category: optionalString(input.category, 'finding.category', { max: 80, pattern: UUIDISH }),
+    title: optionalString(input.title, 'finding.title', { max: 200 }),
+    status: optionalString(input.status, 'finding.status', { max: 40, pattern: UUIDISH }),
+    source: cloneSourceSafe(input.source || {}, 'finding.source'),
+    fingerprint: optionalString(input.fingerprint, 'finding.fingerprint', { max: 64, pattern: SHA256 }),
+    snippetPreview: optionalString(input.snippetPreview, 'finding.snippetPreview', { max: 200 }),
+    fix: optionalString(input.fix, 'finding.fix', { max: 500 }),
+    evidence: asArray(input.evidence, 'finding.evidence').map(validateEvidence),
+    metadata: cloneSourceSafe(input.metadata || {}, 'finding.metadata'),
+  };
+  assertSourceSafePayload(finding, 'finding');
+  return finding;
+}
+
+export function validateApproval(input = {}) {
+  assertSourceSafePayload(input, 'approval');
+  const approval = {
+    id: optionalString(input.id, 'approval.id', { max: 120, pattern: UUIDISH }),
+    requirementId: requireString(input.requirementId, 'approval.requirementId', { max: 160 }),
+    decision: requireString(input.decision, 'approval.decision', { max: 20, pattern: UUIDISH }),
+    approvedBy: optionalString(input.approvedBy, 'approval.approvedBy', { max: 255 }),
+    reason: optionalString(input.reason, 'approval.reason', { max: 1000 }),
+    relatedFindingId: optionalString(input.relatedFindingId, 'approval.relatedFindingId', { max: 120 }),
+    relatedArtifactId: optionalString(input.relatedArtifactId, 'approval.relatedArtifactId', { max: 120 }),
+    metadata: cloneSourceSafe(input.metadata || {}, 'approval.metadata'),
+    createdAt: input.createdAt ? requireIsoDate(input.createdAt, 'approval.createdAt') : new Date().toISOString(),
+  };
+  if (!APPROVAL_DECISIONS.includes(approval.decision)) {
+    throw new Error(`approval.decision must be one of ${APPROVAL_DECISIONS.join(', ')}`);
+  }
+  if (approval.decision !== 'requested' && !approval.reason) {
+    throw new Error('approval.reason is required for approved or denied decisions');
+  }
+  assertSourceSafePayload(approval, 'approval');
+  return approval;
+}
+
+export function validateStepResult(input = {}, expected = {}) {
+  assertSourceSafePayload(input, 'stepResult');
+  const stepperId = requireString(input.stepperId, 'stepResult.stepperId', { max: 160 });
+  const version = requireString(input.version, 'stepResult.version', { max: 80 });
+  if (expected.stepperId && stepperId !== expected.stepperId) {
+    throw new Error(`stepResult.stepperId must match ${expected.stepperId}`);
+  }
+  if (expected.version && version !== expected.version) {
+    throw new Error(`stepResult.version must match ${expected.version}`);
+  }
+  const status = requireString(input.status, 'stepResult.status', { max: 40, pattern: UUIDISH });
+  if (!STEP_STATUSES.includes(status)) {
+    throw new Error(`stepResult.status must be one of ${STEP_STATUSES.join(', ')}`);
+  }
+  const result = {
+    stepperId,
+    version,
+    status,
+    startedAt: requireIsoDate(input.startedAt, 'stepResult.startedAt'),
+    finishedAt: requireIsoDate(input.finishedAt, 'stepResult.finishedAt'),
+    evidence: asArray(input.evidence, 'stepResult.evidence').map(validateEvidence),
+    findings: asArray(input.findings, 'stepResult.findings').map(validateFinding),
+    artifacts: asArray(input.artifacts, 'stepResult.artifacts').map(validateArtifactRef),
+    receipts: asArray(input.receipts, 'stepResult.receipts').map(validateReceiptRef),
+    summary: requireString(input.summary, 'stepResult.summary', { max: 1000 }),
+    nextActions: asArray(input.nextActions, 'stepResult.nextActions').map((item, index) =>
+      requireString(item, `stepResult.nextActions[${index}]`, { max: 300 })),
+    skippedReason: optionalString(input.skippedReason, 'stepResult.skippedReason', { max: 500 }),
+    blockedReason: optionalString(input.blockedReason, 'stepResult.blockedReason', { max: 500 }),
+    needsHumanReason: optionalString(input.needsHumanReason, 'stepResult.needsHumanReason', { max: 500 }),
+  };
+  if (status === 'skipped' && !result.skippedReason) throw new Error('skipped steps require skippedReason');
+  if (status === 'blocked' && !result.blockedReason) throw new Error('blocked steps require blockedReason');
+  if (status === 'needs_human' && !result.needsHumanReason) {
+    throw new Error('needs_human steps require needsHumanReason');
+  }
+  assertSourceSafePayload(result, 'stepResult');
+  return result;
+}
+
+export function validateDeepScanState(input = {}) {
+  const state = cloneSourceSafe(input, 'deepScanState');
+  validateRunIdSegment(state.runId, 'deepScanState.runId');
+  requireString(state.projectId, 'deepScanState.projectId', { max: 160 });
+  requireString(state.graphProfileId, 'deepScanState.graphProfileId', { max: 160 });
+  if (!STEP_STATUSES.includes(state.status)) {
+    throw new Error(`deepScanState.status must be one of ${STEP_STATUSES.join(', ')}`);
+  }
+  requireIsoDate(state.createdAt, 'deepScanState.createdAt');
+  requireIsoDate(state.updatedAt, 'deepScanState.updatedAt');
+  return state;
+}

package/src/deep-scan/deterministic-scan.js

@@ -0,0 +1,337 @@
+import crypto from 'crypto';
+import fs from 'fs/promises';
+import path from 'path';
+import {
+  DEFAULT_EXCLUDE,
+  DEFAULT_INCLUDE,
+  gatherRepoScan,
+} from '../repo-scan.mjs';
+import { getGrade, getRuleEngineMetadata } from '../rule-engine/index.js';
+import { createArtifactRef, createReceiptRef, validateRunIdSegment } from './contracts.js';
+import { assertSourceSafePayload, cloneSourceSafe, findRawSourceField } from './sourceSafe.js';
+
+export const DETERMINISTIC_SCAN_SCHEMA_VERSION = 'deterministic_scan.v1';
+export const DETERMINISTIC_SCAN_STEPPER_ID = 'rules.scan';
+export const DETERMINISTIC_SCAN_STEPPER_VERSION = '1.0.0';
+
+const DEFAULT_MAX_FILES = 300;
+const LOCAL_ASSURANCE_EXCLUDE = ['**/.vibesecur/**'];
+const SECRETISH_PATTERNS = [
+  /\b(?:sk|pk)_(?:live|test)_[a-zA-Z0-9_=-]{6,}\b/gi,
+  /\bgh[pousr]_[a-zA-Z0-9_]{10,}\b/g,
+  /\bAKIA[0-9A-Z]{12,}\b/g,
+  /\bxox[baprs]-[a-zA-Z0-9-]{10,}\b/gi,
+  /-----BEGIN [A-Z ]*(?:PRIVATE KEY|SECRET|TOKEN|CERTIFICATE)-----[\s\S]*?-----END [A-Z ]*-----/gi,
+];
+const nowIso = () => new Date().toISOString();
+const toPosix = (value) => String(value || '').replace(/\\/g, '/');
+
+function stableSort(value) {
+  if (Array.isArray(value)) return value.map(stableSort);
+  if (!value || typeof value !== 'object') return value;
+  return Object.keys(value)
+    .sort()
+    .reduce((acc, key) => {
+      acc[key] = stableSort(value[key]);
+      return acc;
+    }, {});
+}
+
+function stableStringify(value) {
+  return JSON.stringify(stableSort(value));
+}
+
+function sha256(value) {
+  return crypto.createHash('sha256').update(value).digest('hex');
+}
+
+function redactString(value) {
+  if (typeof value !== 'string') return value;
+  let redacted = value;
+  for (const pattern of SECRETISH_PATTERNS) redacted = redacted.replace(pattern, '[redacted]');
+  redacted = redacted.replace(
+    /\b([A-Z0-9_]*(?:TOKEN|SECRET|PASSWORD|API_KEY|PRIVATE_KEY)[A-Z0-9_]*)=("[^"]*"|'[^']*'|\S+)/gi,
+    '$1=[redacted]',
+  );
+  return redacted;
+}
+
+function safeText(value, fallback, max = 200) {
+  const redacted = redactString(String(value || '').replace(/\s+/g, ' ').trim()).slice(0, max);
+  if (!redacted) return fallback;
+  if (findRawSourceField(redacted, 'preview')) return fallback;
+  return redacted;
+}
+
+function safeToken(value, fallback, max = 80) {
+  const text = safeText(value, fallback, max)
+    .toLowerCase()
+    .replace(/[^a-z0-9_.:-]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .slice(0, max);
+  return text || fallback;
+}
+
+function safeSnippetPreview(_value, fallback) {
+  return fallback;
+}
+
+function safeRelativePath(rootPath, filePath) {
+  const relative = path.relative(rootPath, filePath);
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) return path.basename(filePath);
+  return toPosix(relative);
+}
+
+function findingCounts(findings) {
+  return findings.reduce((acc, finding) => {
+    acc[finding.severity] = (acc[finding.severity] || 0) + 1;
+    return acc;
+  }, { critical: 0, high: 0, medium: 0, low: 0 });
+}
+
+function normalizeFinding({ rootPath, filePath, finding }) {
+  const relativePath = safeRelativePath(rootPath, filePath);
+  const lineNumber = Number.isInteger(finding.lineNumber) ? finding.lineNumber : null;
+  const endLineNumber = Number.isInteger(finding.endLineNumber) ? finding.endLineNumber : lineNumber;
+  const snippetHash = sha256(String(finding.snippetPreview || finding.snippet || ''));
+  const fingerprint = sha256(stableStringify({
+    ruleId: finding.ruleId || 'unknown_rule',
+    filePath: relativePath,
+    lineNumber,
+    snippetHash,
+  }));
+  const ruleId = safeText(finding.ruleId, 'unknown_rule', 80);
+  const ruleName = safeText(finding.ruleName, ruleId, 160);
+  const severity = safeText(finding.severity, 'medium', 20);
+  const category = safeToken(finding.category, 'general', 80);
+  const snippetPreview = safeSnippetPreview(
+    finding.snippetPreview || finding.snippet,
+    `Preview withheld for ${ruleId}; inspect local source at ${relativePath}:${lineNumber || 1}.`,
+  );
+
+  return {
+    id: `finding-${fingerprint.slice(0, 48)}`,
+    ruleId,
+    ruleName,
+    severity,
+    category,
+    title: `${ruleId}: ${ruleName}`.slice(0, 200),
+    status: 'open',
+    source: {
+      filePath: relativePath,
+      lineNumber,
+      endLineNumber,
+      language: finding.lang || undefined,
+    },
+    fingerprint,
+    snippetPreview,
+    fix: safeText(finding.fix, 'Review and fix this finding in local source.', 500),
+    evidence: [{
+      type: 'finding_location',
+      label: `${ruleId} location`,
+      preview: `${relativePath}:${lineNumber || 1}`,
+      summary: `${severity} ${category} finding from ${ruleName}.`,
+      metadata: {
+        ruleId,
+        filePath: relativePath,
+        lineNumber,
+        endLineNumber,
+        snippetHash,
+      },
+    }],
+    metadata: {
+      normalizedBy: DETERMINISTIC_SCAN_STEPPER_ID,
+      scannerSurface: 'mcp-bundled',
+      snippetHash,
+    },
+  };
+}
+
+function normalizeFindings(rootPath, fileResults) {
+  return fileResults.flatMap((fileResult) =>
+    (fileResult.result.findings || []).map((finding) =>
+      normalizeFinding({
+        rootPath,
+        filePath: fileResult.filePath,
+        finding: { ...finding, lang: fileResult.lang },
+      })));
+}
+
+function normalizeTopRiskFiles(rootPath, topRiskFiles) {
+  return topRiskFiles.map((item) => ({
+    filePath: safeRelativePath(rootPath, item.filePath),
+    score: item.score,
+    findings: item.findings,
+    critical: item.critical,
+    high: item.high,
+  }));
+}
+
+export function hashDeterministicScanArtifact(artifact) {
+  assertSourceSafePayload(artifact, 'deterministicScanArtifact');
+  return sha256(stableStringify(artifact));
+}
+
+export async function buildDeterministicScanArtifact({
+  rootPath,
+  includeGlobs = DEFAULT_INCLUDE,
+  excludeGlobs = DEFAULT_EXCLUDE,
+  maxFiles = DEFAULT_MAX_FILES,
+  generatedAt = nowIso(),
+} = {}) {
+  if (!rootPath || typeof rootPath !== 'string') throw new Error('Deterministic Scan requires rootPath');
+  const resolvedRoot = path.resolve(rootPath);
+  const stat = await fs.stat(resolvedRoot);
+  if (!stat.isDirectory()) throw new Error(`Deterministic Scan rootPath is not a directory: ${resolvedRoot}`);
+
+  const effectiveExcludeGlobs = [...new Set([...excludeGlobs, ...LOCAL_ASSURANCE_EXCLUDE])];
+  const scan = await gatherRepoScan(resolvedRoot, includeGlobs, effectiveExcludeGlobs, maxFiles);
+  const findings = normalizeFindings(resolvedRoot, scan.fileResults);
+  const bySeverity = findingCounts(findings);
+  const engine = getRuleEngineMetadata('mcp-bundled');
+  const artifact = {
+    schemaVersion: DETERMINISTIC_SCAN_SCHEMA_VERSION,
+    generatedAt,
+    root: {
+      name: path.basename(resolvedRoot),
+      pathHash: sha256(resolvedRoot.toLowerCase()),
+    },
+    scanMode: 'local_mcp_rule_engine',
+    limits: {
+      maxFiles,
+      matchedFiles: scan.matchedFiles.length,
+      scannedFiles: scan.limitedFiles.length,
+      cappedByMaxFiles: scan.matchedFiles.length > maxFiles,
+    },
+    includeGlobs,
+    excludeGlobs: effectiveExcludeGlobs,
+    engine,
+    summary: {
+      ...scan.aggregate.summary,
+      bySeverity,
+      totalIssues: findings.length,
+    },
+    grade: getGrade(scan.aggregate.summary.score),
+    checklist: scan.aggregate.checklist,
+    findings,
+    topRiskFiles: normalizeTopRiskFiles(resolvedRoot, scan.topRiskFiles),
+    privacy: {
+      rawSourceStored: false,
+      snippetPreviewsCapped: true,
+      secretValuesRedacted: true,
+      artifactStorage: 'local_metadata_and_hash_refs',
+    },
+  };
+
+  assertSourceSafePayload(artifact, 'deterministicScanArtifact');
+  return cloneSourceSafe(artifact, 'deterministicScanArtifact');
+}
+
+export async function writeDeterministicScanArtifact({ rootPath, runId, artifact }) {
+  assertSourceSafePayload(artifact, 'deterministicScanArtifact');
+  const safeRunId = validateRunIdSegment(runId, 'runId');
+  const relativeUri = `.vibesecur/deep-scans/${safeRunId}/deterministic-scan.json`;
+  const target = path.join(path.resolve(rootPath), relativeUri);
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  const serialized = `${JSON.stringify(stableSort(artifact), null, 2)}\n`;
+  const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+  await fs.writeFile(tmp, serialized, 'utf8');
+  await fs.rename(tmp, target);
+  return {
+    uri: relativeUri,
+    hash: sha256(serialized),
+  };
+}
+
+export function deterministicScanStepper() {
+  return {
+    id: DETERMINISTIC_SCAN_STEPPER_ID,
+    version: DETERMINISTIC_SCAN_STEPPER_VERSION,
+    title: 'Deterministic Rule Scan Stepper',
+    category: 'deterministic_rule_scan',
+    requiredInputs: ['bound_project_root'],
+    producedArtifacts: ['deterministic_scan'],
+    defaultTimeoutMs: 60000,
+    async run({ runId, config = {}, tools = {} }) {
+      const rootPath = tools.rootPath || config.rootPath || '.';
+      const startedAt = nowIso();
+      const artifact = await buildDeterministicScanArtifact({
+        rootPath,
+        generatedAt: config.generatedAt || startedAt,
+        includeGlobs: Array.isArray(config.includeGlobs) ? config.includeGlobs : DEFAULT_INCLUDE,
+        excludeGlobs: Array.isArray(config.excludeGlobs) ? config.excludeGlobs : DEFAULT_EXCLUDE,
+        maxFiles: Number.isFinite(Number(config.maxFiles)) ? Number(config.maxFiles) : DEFAULT_MAX_FILES,
+      });
+      const contentHash = hashDeterministicScanArtifact(artifact);
+      const written = await writeDeterministicScanArtifact({ rootPath, runId, artifact });
+      const safeRunId = validateRunIdSegment(runId, 'runId');
+      const ref = createArtifactRef({
+        id: `artifact-${safeRunId}-deterministic-scan`,
+        type: 'deterministic_scan',
+        storage: 'local',
+        uri: written.uri,
+        hash: written.hash,
+        preview: 'Deterministic scan metadata: normalized findings, counts, receipts, and engine metadata only.',
+        metadata: {
+          schemaVersion: DETERMINISTIC_SCAN_SCHEMA_VERSION,
+          contentHash,
+          generatedBy: DETERMINISTIC_SCAN_STEPPER_ID,
+          engineVersion: artifact.engine.version,
+          deterministicRuleCount: artifact.engine.counts.deterministic,
+          checklistCount: artifact.engine.counts.checklist,
+          totalIssues: artifact.summary.totalIssues,
+        },
+      });
+      const receipt = createReceiptRef({
+        id: `receipt-${safeRunId}-deterministic-scan`,
+        type: 'deterministic_scan',
+        source: 'mcp_deep_scan',
+        artifactId: ref.id,
+        artifactHash: ref.hash,
+        engine: artifact.engine,
+        summary: {
+          filesScanned: artifact.limits.scannedFiles,
+          totalIssues: artifact.summary.totalIssues,
+          bySeverity: artifact.summary.bySeverity,
+          score: artifact.summary.score,
+          grade: artifact.grade,
+        },
+        verification: {
+          benchmarkContinuity: 'covered_by_security_benchmark_gate',
+          sourceRetention: 'metadata_only',
+        },
+        metadata: {
+          schemaVersion: DETERMINISTIC_SCAN_SCHEMA_VERSION,
+          scanMode: artifact.scanMode,
+          contentHash,
+        },
+        createdAt: startedAt,
+      });
+
+      return {
+        stepperId: DETERMINISTIC_SCAN_STEPPER_ID,
+        version: DETERMINISTIC_SCAN_STEPPER_VERSION,
+        status: 'passed',
+        startedAt,
+        finishedAt: nowIso(),
+        evidence: [{
+          type: 'receipt',
+          label: 'Deterministic scan receipt',
+          hash: ref.hash,
+          preview: 'Receipt-backed deterministic scan artifact written locally.',
+          summary: `${artifact.summary.totalIssues} issue(s) across ${artifact.limits.scannedFiles} scanned file(s).`,
+          metadata: {
+            receiptId: receipt.id,
+            artifactId: ref.id,
+            contentHash,
+          },
+        }],
+        findings: artifact.findings,
+        artifacts: [ref],
+        receipts: [receipt],
+        summary: `Deterministic rule scan completed: ${artifact.summary.totalIssues} issue(s), score ${artifact.summary.score} (${artifact.grade}).`,
+        nextActions: ['Use normalized findings and receipt metadata for test planning, reports, passports, and reruns.'],
+      };
+    },
+  };
+}

package/src/deep-scan/index.js

@@ -0,0 +1,109 @@
+export {
+  APPROVAL_DECISIONS,
+  STEP_STATUSES,
+  createArtifactRef,
+  createReceiptRef,
+  validateApproval,
+  validateArtifactRef,
+  validateDeepScanState,
+  validateEvidence,
+  validateFinding,
+  validateReceiptRef,
+  validateStepResult,
+} from './contracts.js';
+export { StepperRegistry } from './registry.js';
+export { LocalDeepScanStore } from './store.js';
+export { DeepScanRuntime } from './runtime.js';
+export { assertSourceSafePayload, cloneSourceSafe, findRawSourceField } from './sourceSafe.js';
+export {
+  DETERMINISTIC_SCAN_SCHEMA_VERSION,
+  DETERMINISTIC_SCAN_STEPPER_ID,
+  DETERMINISTIC_SCAN_STEPPER_VERSION,
+  buildDeterministicScanArtifact,
+  deterministicScanStepper,
+  hashDeterministicScanArtifact,
+  writeDeterministicScanArtifact,
+} from './deterministic-scan.js';
+export {
+  PROJECT_MAP_SCHEMA_VERSION,
+  PROJECT_MAP_STEPPER_ID,
+  PROJECT_MAP_STEPPER_VERSION,
+  buildProjectMapArtifact,
+  hashProjectMapArtifact,
+  projectMapStepper,
+  writeProjectMapArtifact,
+} from './project-map.js';
+export {
+  RALPH_COMPARISON_SCHEMA_VERSION,
+  RALPH_COMPARISON_STATUSES,
+  RALPH_COMPARISON_STEPPER_ID,
+  RALPH_COMPARISON_STEPPER_VERSION,
+  buildRalphComparisonArtifact,
+  hashRalphComparisonArtifact,
+  ralphComparisonStepper,
+  validateRalphComparisonArtifact,
+  writeRalphComparisonArtifact,
+} from './ralph-compare.js';
+export {
+  DEFAULT_RALPH_LOOP_RETRY,
+  RALPH_ESCALATION_STATUSES,
+  RALPH_FAILURE_STATE_SCHEMA_VERSION,
+  RALPH_FAILURE_STATE_STEPPER_ID,
+  RALPH_FAILURE_STATE_STEPPER_VERSION,
+  buildRalphFailureStateArtifact,
+  hashRalphFailureStateArtifact,
+  ralphFailureTrackStepper,
+  validateRalphFailureStateArtifact,
+  writeRalphFailureStateArtifact,
+} from './ralph-track.js';
+export {
+  ACCEPTED_RISK_REGISTER_SCHEMA_VERSION,
+  ACCEPTED_RISK_STATE_SCHEMA_VERSION,
+  ACCEPTED_RISK_STATUSES,
+  ACCEPTED_RISK_STEPPER_ID,
+  ACCEPTED_RISK_STEPPER_VERSION,
+  ACCEPTED_RISK_REPORT_VISIBILITY,
+  ACCEPTED_RISK_HIGH_RISK_SEVERITIES,
+  appendAcceptedRiskRecord,
+  buildAcceptedRiskStateArtifact,
+  evaluateActiveAcceptedRisk,
+  hashAcceptedRiskStateArtifact,
+  indexAcceptedRiskForComparison,
+  ralphAcceptStepper,
+  readAcceptedRiskRegister,
+  validateAcceptedRiskRecord,
+  validateAcceptedRiskRegister,
+  validateAcceptedRiskStateArtifact,
+  writeAcceptedRiskStateArtifact,
+} from './ralph-accept.js';
+export {
+  AGENT_FIX_TASK_SCHEMA_VERSION,
+  AGENT_FIX_TASK_STATUSES,
+  AGENT_FIX_TASK_STEPPER_ID,
+  AGENT_FIX_TASK_STEPPER_VERSION,
+  buildAgentFixTaskArtifact,
+  hashAgentFixTaskArtifact,
+  ralphTaskStepper,
+  validateAgentFixTaskArtifact,
+  writeAgentFixTaskArtifact,
+} from './ralph-tasks.js';
+export {
+  SECURITY_TEST_PLAN_SCHEMA_VERSION,
+  SECURITY_TEST_PLAN_STATUSES,
+  SECURITY_TEST_PLAN_STATUS_SEMANTICS,
+  SECURITY_TEST_PLAN_STABLE_CANDIDATE_FIELDS,
+  SECURITY_TEST_PLAN_STEPPER_ID,
+  SECURITY_TEST_PLAN_STEPPER_VERSION,
+  buildSecurityTestPlanArtifact,
+  hashSecurityTestPlanArtifact,
+  securityTestPlanStepper,
+  validateSecurityTestPlanArtifact,
+  writeSecurityTestPlanArtifact,
+} from './test-plan.js';
+export { buildDeepScanStatus, nextActionForState } from './status.js';
+export {
+  createSampleStepperRegistry,
+  sampleArtifactStepper,
+  sampleNeedsHumanStepper,
+  sampleNoopStepper,
+} from './sample-steppers.js';