Assessor_2.0/src/api/assessor-api-contract.ts

import type { Assessment, ScanRun } from '../domain/canonical-model';
import type { ReimportReviewTransferSummary } from '../domain/reimport-review-transfer';
import type { ImportBatchPreview, ImportBatchSelection, ImportFingerprint } from '../domain/import-workflow';
import type { MicrosoftSecurityBaselineRecord, MicrosoftSecurityBaselineSelection } from '../domain/microsoft-security-baseline';
import type { StoredMicrosoftSecurityBaselineAnalysis } from '../domain/microsoft-security-baseline-analysis';
import type { StoredGpoPolicyAnalysis } from '../domain/gpo-analysis-persistence';
import type {
  CreateEnvironmentProfileRequest,
  CreatePolicySnapshotAggregationRequest,
  EnvironmentProfile,
  StoredPolicySnapshotAggregation
} from '../domain/gpo-snapshot-aggregation';
export type { DbStructureResponse } from '../domain/db-structure';
import type { CreatePolicyEvaluationRequest, StoredPolicyEvaluation } from '../domain/policy-evaluation';
import type { CreatePolicyFindingRunRequest, StoredPolicyFindingRun } from '../domain/policy-finding';
import type { PolicyEvaluationRuleCatalog } from '../domain/policy-evaluation-rules';
import type { PolicyAnalysisOverview } from '../domain/policy-analysis-overview';
import type { MitreGraphData } from '../features/mitre-graph/mitre-graph';
import type { AssessmentContext } from '../assessment-context/context-engine';
import type { RemediationResult } from '../remediation/remediation-engine';
export type WorkPackagesResponse = { status: 'ready'; result: RemediationResult } | { status: 'context-required' };
export type { AiOverviewCreateRequest, AiOverviewResponse } from '../domain/ai-overview';
export type {
  RegulatoryMappingCreateRequest,
  RegulatoryMappingDecisionCreateRequest,
  RegulatoryMappingResponse
} from '../domain/regulatory-mapping';
export const ASSESSOR_API_PREFIX = '/api/v1';
export const ASSESSOR_MUTATION_HEADER = 'X-Assessor-Request';

export interface MitreCatalogResponse {
  version: 1;
  catalog: MitreGraphData;
  origin: 'bundled' | 'mitre';
  updated?: boolean;
}

/** Read-only context layer of the selected timeslot (Phase 13E); never a verdict. */
export type AssessmentContextResponse = AssessmentContext;

/** Request of one archived Report Engine run; both files are archived, one is returned. */
export interface ReportRunRequest {
  kind: 'management' | 'technical';
  assessmentIds?: string[];
  scanRunIds?: string[];
}

export interface ReportRunResponse {
  runId: string;
  generatedAt: string;
  repositoryRevision: number;
  kind: ReportRunRequest['kind'];
  fileName: string;
  html: string;
}

export interface AssessorHealthResponse {
  status: 'ok';
  application: 'ASSESSOR';
  productVersion: string;
  apiVersion: 1;
  releaseId?: string;
  developmentInstanceId?: string;
  repositoryRevision: number;
  persistence: 'memory' | 'postgresql';
}

export interface AssessorApiErrorBody {
  error: {
    code: string;
    message: string;
    requestId: string;
  };
}

export interface ImportSourceValidationRequest {
  fileName: string;
  sizeBytes: number;
}

export interface ImportSourceValidationResponse {
  accepted: true;
  format: 'CSV' | 'JSON' | 'XML' | 'HTML' | 'XLSX' | 'XLS';
  maximumSizeBytes: number;
}

export interface ImportSourceParseRequest {
  fileName: string;
  sizeBytes: number;
  lastModified: number;
  mediaType?: string;
  bytesBase64: string;
  delimiter?: string;
}
export interface ImportBatchPreviewRequest {
  files: ImportSourceParseRequest[];
  targetProjectId?: string;
  targetAssessmentId?: string;
  replacesScanRunId?: string;
}

export interface ImportBatchCompleteRequest {
  batchId: string;
  entries: ImportBatchSelection[];
  targetProjectId?: string;
  targetAssessmentId?: string;
  replacesScanRunId?: string;
}

export interface ImportBatchCompleteResponse {
  batchId: string;
  fingerprints: ImportFingerprint[];
  repositoryRevision: number;
  projectId: string;
  assessmentId: string;
  scanRunId: string;
  replacedScanRunId?: string;
  importedFiles: number;
  importedOccurrences: number;
  reimportReviewTransfer?: ReimportReviewTransferSummary;
}

export interface GpoBackupSubmissionRequest {
  restoreArtifactId?: string;
  fileName: string;
  sizeBytes: number;
  bytesBase64: string;
  assessmentId?: string;
}

export interface GpoBackupSubmissionResponse {
  sourceRestored?: boolean;
  version: 1;
  artifactId: string;
  jobId: string;
  sha256: string;
  sizeBytes: number;
  status: 'queued';
  deduplicated: boolean;
  repositoryRevision: number;
}
export interface GpoBackupRetryResponse {
  version: 1;
  artifactId: string;
  jobId: string;
  status: 'queued';
  attempts: number;
}

export interface GpoBackupDeleteResponse {
  version: 1;
  artifactId: string;
  deleted: true;
  storageRemoval: 'complete' | 'pending';
}
export interface GpoBackupReprocessResponse {
  version: 1;
  artifactId: string;
  jobId: string;
  status: 'queued' | 'running' | 'succeeded' | 'dead-letter';
  supersedesProcessingRunId: string;
}
export type GpoBackupDisplayState = 'queued' | 'running' | 'succeeded' | 'partial' | 'dead-letter' | 'recovery-required' | 'upload-required' | 'storage-unavailable';

/** A newer GPO analyzer changes retained parsing output, so the source must be reprocessed. */
export interface GpoAnalysisUpdate {
  identityAnalysisRunId: string;
  expectedLatestProcessingRunId: string;
  previousAnalyzerVersion: string;
  currentAnalyzerVersion: string;
}

export interface GpoBackupStatusRecord {
  /** Existing input can be re-evaluated; this is distinct from source reimport. */
  evaluationUpdates?: import('../domain/policy-analysis-overview').GpoEvaluationUpdate[];
  /** Retained parsing output is outdated; reprocessing the stored source is required. */
  analysisUpdate?: GpoAnalysisUpdate;
  version: 1;
  artifactId: string;
  assessmentId?: string;
  jobId?: string;
  fileName: string;
  sizeBytes: number;
  submittedAt: string;
  updatedAt: string;
  state: GpoBackupDisplayState;
  jobStatus?: 'queued' | 'running' | 'succeeded' | 'dead-letter';
  attempts: number;
  maxAttempts: number;
  lastErrorCode?: string;
  processingStatus?: 'complete' | 'partial' | 'failed';
  completedAt?: string;
  /** Number of individual GPOs detected inside this one uploaded tenant backup snapshot. */
  gpoCount: number;
  /** @deprecated Compatibility alias for gpoCount; it never counts tenant backup snapshots. */
  backupInstanceCount: number;
  /** GPOs whose own backup report states no enabled link; absent until link facts are retained. */
  notLinkedGpoCount?: number;
}

export interface ProjectAssessmentHistoryResponse {
  version: 1;
  projectId: string;
  assessments: Assessment[];
  scanRuns: ScanRun[];
}

export interface GpoBackupStatusResponse {
  version: 1;
  projectId: string;
  generatedAt: string;
  records: GpoBackupStatusRecord[];
}
export interface MicrosoftSecurityBaselineListResponse { version: 1; records: MicrosoftSecurityBaselineRecord[]; }
export type PolicyEvaluationCreateRequest = CreatePolicyEvaluationRequest;
export interface PolicyEvaluationResponse { version: 1; record: StoredPolicyEvaluation; }
export interface PolicyEvaluationListResponse { version: 1; projectId: string; records: StoredPolicyEvaluation[]; }
export type PolicyFindingRunCreateRequest = CreatePolicyFindingRunRequest;
export interface PolicyFindingRunResponse { version: 1; record: StoredPolicyFindingRun; }
export interface PolicyFindingRunListResponse { version: 1; projectId: string; records: StoredPolicyFindingRun[]; }
export type PolicyAnalysisOverviewResponse = PolicyAnalysisOverview;
export interface PolicyEvaluationRuleCatalogResponse { version: 1; catalog: PolicyEvaluationRuleCatalog; }
export interface MicrosoftSecurityBaselineSubmissionResponse { version: 1; record: MicrosoftSecurityBaselineRecord; }
export interface MicrosoftSecurityBaselineDeletionResponse { version: 1; record: MicrosoftSecurityBaselineRecord; }
export interface MicrosoftSecurityBaselineAnalysisResponse { version: 1; record: StoredMicrosoftSecurityBaselineAnalysis; }
export interface MicrosoftSecurityBaselineAnalysisListResponse { version: 1; records: StoredMicrosoftSecurityBaselineAnalysis[]; }
export interface GpoPolicyAnalysisListResponse { version: 1; projectId: string; records: StoredGpoPolicyAnalysis[]; }
export type EnvironmentProfileCreateRequest = CreateEnvironmentProfileRequest;
export interface EnvironmentProfileResponse { version: 1; record: EnvironmentProfile; }
export interface EnvironmentProfileListResponse { version: 1; projectId: string; records: EnvironmentProfile[]; }
export type PolicySnapshotAggregationCreateRequest = CreatePolicySnapshotAggregationRequest;
export interface PolicySnapshotAggregationResponse { version: 1; record: StoredPolicySnapshotAggregation; }
export interface PolicySnapshotAggregationListResponse { version: 1; projectId: string; records: StoredPolicySnapshotAggregation[]; }
export type MicrosoftSecurityBaselineSelectionResponse = MicrosoftSecurityBaselineSelection;

export type ImportBatchPreviewResponse = ImportBatchPreview;
export interface ReferenceRecognitionStatus {
  totalScans: number;
  indexedScans: number;
  pendingScans: number;
  catalogs: Array<{ framework: import('../domain/reference-recognition').ReferenceFramework; version: string; sha256: string }>;
}
export interface ReferenceRecognitionResponse {
  processedScans: number;
  unchangedScans: number;
  references: number;
}