TypeScript Domain Model

/**
 * AutoQA Foundation types - schema version 0.1.0
 *
 * These interfaces mirror the JSON Schemas in ../schemas. Runtime validation
 * must use the JSON Schemas; TypeScript types alone are not a trust boundary.
 */

export type JsonPrimitive = string | number | boolean | null;
export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };

export type Identifier = string;
export type SemVer = string;
export type ContentHash = `sha256:${string}`;
export type DateTime = string;

export type ConfidenceBand = "high" | "medium" | "low" | "uncalibrated";
export type Severity = "none" | "advisory" | "minor" | "major" | "critical";
export type DecisionTarget = "attempt" | "annotation" | "composite_case" | "batch";
export type OperationalAction =
 | "accept"
 | "accept_with_notes"
 | "rework"
 | "reject"
 | "escalate";
export type CriterionVerdict =
 | "met"
 | "partially_met"
 | "not_met"
 | "ambiguous"
 | "unknown"
 | "not_applicable";

export interface ContractRef {
 contractId: Identifier;
 contractVersion: SemVer;
 contentHash: ContentHash;
}

export interface CaseRef {
 caseId: Identifier;
 contentHash?: ContentHash;
}

export interface SpanRef {
 artifactType:
 | "task"
 | "evidence"
 | "attempt"
 | "human_review"
 | "reference"
 | "tool_trace";
 artifactId: Identifier;
 startChar?: number;
 endChar?: number;
 quotedText: string;
 locator?: string;
}

export interface Confidence {
 /** Model-native or component-native confidence. Never use alone for autonomy. */
 rawScore?: number;
 /** Empirically calibrated probability for the defined event and slice. */
 calibratedScore?: number;
 band: ConfidenceBand;
 calibrationProfileId?: Identifier;
 rationale?: string;
}

export interface GenerationSource {
 kind: "deterministic_validator" | "llm_judge" | "human" | "hybrid";
 componentId: Identifier;
 modelRunId?: Identifier;
 humanActorId?: Identifier;
}

export type Condition =
 | { kind: "always" }
 | {
 kind: "predicate";
 fieldPath: string;
 operator:
 | "equals"
 | "not_equals"
 | "in"
 | "not_in"
 | "contains"
 | "exists"
 | "greater_than"
 | "greater_than_or_equal"
 | "less_than"
 | "less_than_or_equal"
 | "matches_regex";
 value?: JsonValue;
 }
 | { kind: "all"; conditions: Condition[] }
 | { kind: "any"; conditions: Condition[] }
 | { kind: "not"; condition: Condition };

export interface Finding {
 findingId: Identifier;
 findingType:
 | "positive"
 | "negative"
 | "omission"
 | "ambiguity"
 | "counterevidence"
 | "integrity";
 criterionId?: Identifier;
 summary: string;
 detail?: string;
 claimIds?: Identifier[];
 expectedElementIds?: Identifier[];
 targetSpans?: SpanRef[];
 evidenceIds?: Identifier[];
 relationship?:
 | "directly_entails"
 | "reasonably_supports"
 | "weakly_supports"
 | "contradicts"
 | "irrelevant"
 | "insufficient"
 | "not_applicable";
 materiality: "incidental" | "supporting" | "central" | "decisive";
 severity: Severity;
 confidence: Confidence;
 status: "observed" | "challenged" | "confirmed" | "retracted";
 source: GenerationSource;
}

export interface Claim {
 claimId: Identifier;
 proposition: string;
 claimType:
 | "factual"
 | "interpretive"
 | "predictive"
 | "normative"
 | "preference"
 | "procedural";
 importance: "incidental" | "supporting" | "central";
 explicitness: "explicit" | "implied";
 attemptSpans: SpanRef[];
 qualifiers?: string[];
 citedEvidenceIds?: Identifier[];
}

export interface ExpectedElement {
 elementId: Identifier;
 criterionId: Identifier;
 description: string;
 required: boolean;
 importance: "supporting" | "central" | "decisive";
 acceptableAlternatives?: string[];
 observedSpans?: SpanRef[];
 coverage: "complete" | "partial" | "missing" | "not_applicable" | "unknown";
}

export interface EvidenceRelationship {
 relationshipId: Identifier;
 subjectType: "claim" | "expected_element" | "finding";
 subjectId: Identifier;
 evidenceId: Identifier;
 relationship:
 | "directly_entails"
 | "reasonably_supports"
 | "weakly_supports"
 | "contradicts"
 | "irrelevant"
 | "insufficient";
 sourceQuality: "high" | "acceptable" | "weak" | "disallowed" | "unknown";
 temporalValidity: "valid" | "stale" | "not_time_sensitive" | "unknown";
 evidenceSpans?: SpanRef[];
 confidence: Confidence;
 notes?: string;
}

export interface CriterionAssessment {
 criterionId: Identifier;
 applicability: "applies" | "does_not_apply" | "uncertain";
 positiveFindingIds: Identifier[];
 negativeFindingIds: Identifier[];
 omissionFindingIds: Identifier[];
 counterEvidenceFindingIds: Identifier[];
 unresolvedFindingIds: Identifier[];
 groundingStatus:
 | "grounded"
 | "partially_grounded"
 | "ungrounded"
 | "not_applicable"
 | "unknown";
 truthStatus:
 | "verified_true"
 | "verified_false"
 | "mixed"
 | "not_evaluated"
 | "not_applicable"
 | "unknown";
 warrantStatus: "justified" | "overstated" | "invalid" | "not_applicable" | "unknown";
 relevanceStatus:
 | "relevant"
 | "partially_relevant"
 | "irrelevant"
 | "not_applicable"
 | "unknown";
 verdict: CriterionVerdict;
 severity: Severity;
 confidence: Confidence;
 decisionEffect: "none" | "accept_with_note" | "rework" | "reject" | "escalate";
 rationale: string;
}

export interface GlobalAssessment {
 axisId: Identifier;
 verdict: CriterionVerdict;
 findingIds: Identifier[];
 score?: number;
 confidence: Confidence;
 rationale: string;
}

export interface PolicyTraceEntry {
 ruleId: Identifier;
 matched: boolean;
 inputs?: Record<string, JsonValue>;
 result: string;
}

export interface Decision {
 target: DecisionTarget;
 action: OperationalAction;
 policyVersion: SemVer;
 triggeredRuleIds: Identifier[];
 decisiveCriterionIds: Identifier[];
 unresolvedFindingIds: Identifier[];
 confidence: Confidence;
 policyTrace: PolicyTraceEntry[];
 rationale: string;
 decidedAt: DateTime;
}

export interface ResolutionOption {
 optionId: Identifier;
 label: string;
 description?: string;
 effectSummary?: string;
}

export interface HumanResolutionRequest {
 requestId: Identifier;
 triggerCriterionIds: Identifier[];
 questionType:
 | "applicability"
 | "instruction_precedence"
 | "evidence_authority"
 | "inference_permission"
 | "severity"
 | "valid_alternative"
 | "rubric_ambiguity"
 | "domain_expertise";
 question: string;
 contextFindingIds: Identifier[];
 options: ResolutionOption[];
 decisionChanging: boolean;
 hideProvisionalDecision: boolean;
 requiredExpertiseTags?: string[];
 status: "pending" | "answered" | "cancelled";
 createdAt: DateTime;
}

export interface HumanResolutionResponse {
 requestId: Identifier;
 selectedOptionId: Identifier;
 responderId: Identifier;
 rationale?: string;
 respondedAt: DateTime;
}

export interface HumanResolutionInteraction {
 decisionTarget: DecisionTarget;
 request: HumanResolutionRequest;
 response?: HumanResolutionResponse;
 decisionBefore?: OperationalAction;
 decisionAfter?: OperationalAction;
 changedDecision?: boolean;
}


export interface HumanResolutionPacket {
 documentType: "human_resolution_packet";
 schemaVersion: SemVer;
 caseRef: CaseRef;
 contractRef: ContractRef;
 contextFindings: Finding[];
 interaction: HumanResolutionInteraction;
}

export interface FeedbackItem {
 feedbackId: Identifier;
 audience: "attempter" | "reviewer" | "project_owner";
 criterionId?: Identifier;
 feedbackType: "strength" | "defect" | "omission" | "ambiguity";
 findingIds: Identifier[];
 message: string;
 minimalRepair?: string;
 priority: number;
 repairValidationStatus: "validated" | "plausible_unvalidated" | "not_applicable";
}

export interface AnnotationAssessment {
 annotationPresent: boolean;
 labelSupport:
 | "supported"
 | "partially_supported"
 | "unsupported"
 | "reasonable_disagreement"
 | "rubric_ambiguous"
 | "not_applicable";
 rationaleSupport:
 | "supported"
 | "contains_unsupported_reasoning"
 | "does_not_support_label"
 | "missing"
 | "not_applicable";
 criterionAttribution:
 | "correct"
 | "partially_correct"
 | "wrong_criterion"
 | "unstated_preference"
 | "not_applicable";
 evidenceAlignment:
 | "aligned"
 | "partially_aligned"
 | "misquoted"
 | "irrelevant"
 | "missing"
 | "not_applicable";
 severityAlignment: "appropriate" | "too_severe" | "too_lenient" | "uncertain" | "not_applicable";
 omittedPositiveFindingIds: Identifier[];
 omittedNegativeFindingIds: Identifier[];
 unsupportedReviewerFindingIds: Identifier[];
 disagreementTypes: Array<
 | "none"
 | "observation"
 | "evidence_authority"
 | "applicability"
 | "criterion_interpretation"
 | "inference"
 | "threshold"
 | "severity"
 | "attention"
 | "expertise"
 | "reasonable_disagreement"
 | "rubric_defect"
 >;
 confidence: Confidence;
 rationale: string;
}

export interface ModelRun {
 modelRunId: Identifier;
 role:
 | "claim_extractor"
 | "evidence_retriever"
 | "positive_prover"
 | "negative_challenger"
 | "coverage_auditor"
 | "warrant_auditor"
 | "criterion_adjudicator"
 | "holistic_judge"
 | "annotation_auditor"
 | "feedback_generator"
 | "repair_validator"
 | "ensemble_aggregator";
 provider: string;
 modelName: string;
 modelVersion?: string;
 promptTemplateId: Identifier;
 promptTemplateVersion: SemVer;
 promptTemplateHash: ContentHash;
 parameters?: Record<string, JsonValue>;
 parentRunIds?: Identifier[];
 inputHash?: ContentHash;
 outputHash?: ContentHash;
 startedAt: DateTime;
 completedAt: DateTime;
}

export interface ValidatorRun {
 validatorRunId: Identifier;
 validatorId: Identifier;
 validatorVersion: SemVer;
 role:
 | "schema_validation"
 | "format_check"
 | "citation_check"
 | "calculation"
 | "code_execution"
 | "duplicate_detection"
 | "integrity_check"
 | "custom";
 status: "passed" | "failed" | "warning" | "error";
 parameters?: Record<string, JsonValue>;
 inputHash: ContentHash;
 outputHash: ContentHash;
 startedAt: DateTime;
 completedAt: DateTime;
}

export interface InstructionDocument {
 instructionId: Identifier;
 title: string;
 authority: "primary" | "supplemental" | "example" | "historical";
 content: string;
 contentHash: ContentHash;
 precedenceRank?: number;
}

export interface EvidenceClass {
 classId: Identifier;
 name: string;
 description?: string;
 permitted: boolean;
 authorityRank: number;
}

export interface InstructionRef {
 instructionId: Identifier;
 locator: string;
 quotedText?: string;
}

export interface CriterionAnchor {
 anchorId: Identifier;
 label: string;
 description?: string;
 example: string;
 expectedVerdict: CriterionVerdict;
 notes?: string;
}

export interface CriterionDefinition {
 criterionId: Identifier;
 name: string;
 requirement: string;
 intent: string;
 criterionType:
 | "required_presence"
 | "prohibited_presence"
 | "conditional"
 | "factual"
 | "grounding"
 | "inferential_warrant"
 | "comparative"
 | "completeness"
 | "holistic_quality"
 | "mechanically_verifiable"
 | "annotation_fidelity";
 scope: "attempt" | "claim" | "citation" | "annotation" | "global" | "batch";
 subjectivity: "objective" | "bounded_judgment" | "holistic_expert";
 instructionRefs: InstructionRef[];
 applicability: { ruleText: string; condition: Condition };
 proofPolicy: {
 positiveProofRequired: boolean;
 positiveProofStandard: string;
 failureCondition: string;
 omissionCondition?: string;
 passOnNoViolation: boolean;
 allowPartialCredit: boolean;
 allowCompensation: boolean;
 };
 evidencePolicy: {
 allowedEvidenceClassIds: Identifier[];
 minimumAuthorityRank: number;
 citationRequired: boolean;
 externalVerificationMode: "forbidden" | "optional" | "required";
 deterministicValidatorIds: Identifier[];
 };
 anchors: CriterionAnchor[];
 validAlternatives?: string[];
 exceptions?: string[];
 dependencies: {
 requiredBeforeCriterionIds: Identifier[];
 impliesCriterionIds: Identifier[];
 };
 precedence: {
 overridesCriterionIds: Identifier[];
 overriddenByCriterionIds: Identifier[];
 };
 defaultSeverity: Severity;
 defaultDecisionEffect: "none" | "accept_with_note" | "rework" | "reject" | "escalate";
 tags: string[];
}

export interface DecisionRuleMatch {
 criterionIds?: string[];
 criterionTags?: string[];
 verdicts?: CriterionVerdict[];
 severities?: Severity[];
 decisionEffects?: Array<"none" | "accept_with_note" | "rework" | "reject" | "escalate">;
 minimumCalibratedConfidence?: number;
 hasUnresolvedFindings?: boolean;
 annotationDisagreementTypes?: string[];
}

export interface DecisionRule {
 target: DecisionTarget;
 ruleId: Identifier;
 priority: number;
 description: string;
 match: DecisionRuleMatch;
 action: OperationalAction;
 terminal: boolean;
 explanationTemplate?: string;
}

export interface ProjectContract {
 documentType: "project_contract";
 schemaVersion: SemVer;
 contractId: Identifier;
 contractVersion: SemVer;
 projectName: string;
 description?: string;
 status: "draft" | "approved" | "deprecated" | "retired";
 createdAt: DateTime;
 effectiveFrom?: DateTime;
 supersedesContractVersion?: SemVer;
 owners?: Array<{
 actorId: Identifier;
 role: "project_owner" | "rubric_owner" | "domain_expert" | "qa_owner";
 }>;
 instructionDocuments: InstructionDocument[];
 sourcePolicy: {
 worldMode: "closed_world" | "open_world" | "hybrid";
 parametricKnowledgePolicy: "never_evidence" | "common_knowledge_only" | "allowed_with_verification";
 externalRetrievalAllowed: boolean;
 defaultCitationRequirement: "none" | "material_claims" | "all_verifiable_claims" | "project_defined";
 snapshotRequired: boolean;
 conflictPolicy: string;
 freshnessRules?: string[];
 evidenceClasses: EvidenceClass[];
 };
 criteria: CriterionDefinition[];
 decisionTargets: DecisionTarget[];
 decisionPolicy: {
 policyVersion: SemVer;
 allowedActions: OperationalAction[];
 rules: DecisionRule[];
 defaultAction: OperationalAction;
 tieBreakOrder: OperationalAction[];
 confidencePolicy: {
 requiresCalibrationForActions: OperationalAction[];
 uncalibratedAction: OperationalAction;
 minimumCalibrationCasesPerSlice?: number;
 };
 };
 humanReviewPolicy: {
 maxInteractionsPerCase: 0 | 1;
 onlyAskIfDecisionChanging: boolean;
 hideProvisionalDecision: boolean;
 requireAmbiguityOption: boolean;
 allowedQuestionTypes: HumanResolutionRequest["questionType"][];
 expertiseRoutingRules?: string[];
 };
 feedbackPolicy: {
 audiences: FeedbackItem["audience"][];
 maxItemsPerAudience: number;
 includeValidatedStrengths: boolean;
 validateRepairs: boolean;
 priorityOrder: Array<"decisive" | "critical" | "major" | "minor" | "strength">;
 };
 securityPolicy: {
 treatCandidateContentAsUntrusted: boolean;
 ignoreEmbeddedEvaluatorInstructions: boolean;
 requireStructuredOutputs: boolean;
 allowCandidateToOverrideRubric: boolean;
 redactionRules?: string[];
 };
 auditPolicy: {
 retainExactSourceSnapshots: boolean;
 retainPromptVersions: boolean;
 retainModelRunMetadata: boolean;
 retainHumanResolutions: boolean;
 replayRequired: boolean;
 retentionDays?: number;
 };
 metadata?: Record<string, JsonValue>;
}

export interface TaskInput {
 taskId: Identifier;
 taskType: string;
 prompt: string;
 taskInstructions?: string[];
 expectedOutputFormat?: string;
 contentHash: ContentHash;
 metadata?: Record<string, JsonValue>;
}

export interface EvidenceArtifact {
 evidenceId: Identifier;
 evidenceClassId: Identifier;
 title: string;
 content: string;
 contentHash: ContentHash;
 sourceUri?: string;
 authorityRank: number;
 permitted: boolean;
 publishedAt?: DateTime;
 capturedAt: DateTime;
 metadata?: Record<string, JsonValue>;
}

export interface AttemptInput {
 attemptId: Identifier;
 authorId?: Identifier;
 content: string;
 contentHash: ContentHash;
 submittedAt: DateTime;
 attachments?: Array<{
 artifactId: Identifier;
 artifactType: string;
 content?: string;
 contentHash: ContentHash;
 }>;
 toolTraces?: Array<{
 traceId: Identifier;
 toolName: string;
 input: JsonValue;
 output: JsonValue;
 contentHash: ContentHash;
 }>;
}

export interface HumanReviewInput {
 annotationId: Identifier;
 reviewerId: Identifier;
 label: string;
 score?: number;
 reasonCodes: string[];
 rationale: string;
 criterionAnnotations?: Array<{
 criterionId: Identifier;
 verdict: CriterionVerdict;
 severity?: Severity;
 rationale: string;
 citedSpans?: SpanRef[];
 }>;
 reviewerConfidence?: Confidence;
 submittedAt: DateTime;
}

export interface CaseInput {
 documentType: "case_input";
 schemaVersion: SemVer;
 caseId: Identifier;
 createdAt: DateTime;
 contractRef: ContractRef;
 task: TaskInput;
 evidenceBundle: EvidenceArtifact[];
 attempt: AttemptInput;
 humanReview?: HumanReviewInput;
 referenceAnswers?: Array<{
 referenceId: Identifier;
 role: "authoritative" | "illustrative" | "positive_anchor" | "negative_anchor";
 content: string;
 contentHash: ContentHash;
 }>;
 declaredExpectedElements?: ExpectedElement[];
 caseTags: string[];
 metadata?: Record<string, JsonValue>;
}

export interface EvaluationOutput {
 documentType: "evaluation_output";
 schemaVersion: SemVer;
 evaluationId: Identifier;
 evaluationVersion: SemVer;
 caseRef: CaseRef;
 contractRef: ContractRef;
 createdAt: DateTime;
 status: "provisional" | "awaiting_human" | "final" | "failed";
 runManifest: ModelRun[];
 validatorManifest: ValidatorRun[];
 integrityStatus?: "clean" | "warning" | "failed" | "unknown";
 findings: Finding[];
 claims: Claim[];
 expectedElements: ExpectedElement[];
 evidenceRelationships: EvidenceRelationship[];
 criterionAssessments: CriterionAssessment[];
 globalAssessments: GlobalAssessment[];
 annotationAssessment?: AnnotationAssessment;
 provisionalDecisions: Decision[];
 humanResolution?: HumanResolutionInteraction;
 finalDecisions: Decision[];
 feedback: FeedbackItem[];
 audit: {
 caseInputHash: ContentHash;
 contractHash: ContentHash;
 sourceSnapshotHashes: ContentHash[];
 replayable: boolean;
 warnings: string[];
 };
}

export interface BenchmarkCriterionGold {
 criterionId: Identifier;
 applicability: "applies" | "does_not_apply" | "uncertain";
 acceptableVerdicts: CriterionVerdict[];
 severity: Severity;
 positiveEvidenceSpans: SpanRef[];
 negativeEvidenceSpans: SpanRef[];
 omissionDescriptions: string[];
 notes: string;
}

export interface BenchmarkItem {
 documentType: "benchmark_item";
 schemaVersion: SemVer;
 benchmarkItemId: Identifier;
 benchmarkVersion: SemVer;
 split: "development" | "calibration" | "test" | "challenge" | "shadow" | "held_out_project";
 contractRef: ContractRef;
 caseRef: CaseRef;
 sliceTags: string[];
 challengeAttributes: Array<
 | "strong_positive"
 | "subtle_valid_alternative"
 | "polished_falsehood"
 | "unsupported_rationale"
 | "citation_mismatch"
 | "partial_support"
 | "required_content_omission"
 | "severity_edge"
 | "instruction_conflict"
 | "ambiguous_case"
 | "prompt_injection"
 | "rubric_parroting"
 | "correct_label_wrong_reason"
 | "wrong_label_correct_observation"
 | "long_context"
 | "domain_expertise"
 | "position_bias_probe"
 >;
 goldStandard: {
 criterionGold: BenchmarkCriterionGold[];
 acceptableDecisions: Array<{
 target: DecisionTarget;
 acceptableActions: OperationalAction[];
 }>;
 annotationGold?: {
 acceptableLabelSupport?: string[];
 expectedDisagreementTypes?: string[];
 notes?: string;
 };
 ambiguityStatus: "clear" | "reasonable_disagreement" | "rubric_ambiguous" | "insufficient_evidence";
 validAlternativeNotes?: string[];
 };
 adjudication: {
 method: "single_expert" | "independent_then_adjudicate" | "consensus_panel" | "latent_label_model";
 adjudicatorCount: number;
 domainExpertCount: number;
 blindToAutoQA: boolean;
 blindToReviewerLabel: boolean;
 initialAgreementRate?: number;
 disagreementTypes: string[];
 adjudicationNotes?: string;
 completedAt: DateTime;
 };
 leakageControl: {
 allowedForPromptDevelopment: boolean;
 heldOutProject: boolean;
 firstFrozenAt: DateTime;
 accessPolicy: string;
 };
 weight: number;
 exclusionReason?: string;
 metadata?: Record<string, JsonValue>;
}

/**
 * Stable domain boundary for a Vercel/TypeScript application.
 * The orchestration layer can accept and return these documents without
 * depending on any particular model provider.
 */
export interface AutoQAEvaluator {
 evaluate(caseInput: CaseInput, contract: ProjectContract): Promise<EvaluationOutput>;
}