docs/DONE_WHEN.md

Core Engine Acceptance & Performance Verification Matrix (DONE_WHEN)

This document formalizes the complete verification matrix for Problem Core Engine ("One student, three drives, one Tuesday"), mapping every institutional criterion to automated test suites, measured performance benchmarks, and security audits.

---

Criterion 1: Student Data Model, Importer & Protected Demographics

Requirement	Implementation & Location	Verification Mechanism	Status
Comprehensive Student Model	backend/app/domain/models.py Student, BacklogRecord, GapYearRecord, OfferRecord	backend/tests/test_domain_models.py (21 tests)	PASSED
Lateral Entry & Diploma Substitution	PercentageMinRule supporting diploma substitution with configurable toggle	backend/tests/test_hidden_edge_cases_regression.py Scenarios 21–25	PASSED
Backlog Temporal Horizons	Backlogs cleared on or before drive date are cleared; cleared after remain active	backend/tests/test_hidden_edge_cases_regression.py Scenarios 1–5	PASSED
Protected Demographics Guard	Demographic fields (gender, caste, religion, category) barred from eligibility rules	backend/tests/test_domain_models.py ProtectedAttributeViolationError	PASSED
Multi-Format Importer	CSV & XLSX parsing, column auto-detection, non-silent row warnings, dry-run	backend/tests/test_importers.py (14 tests)	PASSED

---

Criterion 2: Deterministic Eligibility Engine & Explainability

Requirement	Target Threshold	Measured Benchmark	Verification Suite	Status
Batch Rule Evaluation Throughput	1,800 students $\times$ 1 drive in < 1.0s	0.024s (24 ms) (~41x faster than target)	backend/tests/test_eligibility_evaluator.py test_batch_evaluation_performance	PASSED
Multi-Drive Season Evaluation	1,800 students $\times$ 10 drives in < 6.0s	0.231s (231 ms) (~26x faster than target)	backend/tests/test_eligibility_evaluator.py test_batch_evaluation_performance	PASSED
Pure Domain Determinism	0 DB calls during evaluation; reproducible snapshot hash	SHA-256 hash across profile + rule AST verified identical on repeated runs	backend/tests/test_eligibility_evaluator.py	PASSED
Two-Tier Explanations	Plain-English student wording + full officer source audit trace	Exact student sentence + officer rule ID, data source, actual vs required	backend/tests/test_hidden_edge_cases_regression.py All 60 edge cases	PASSED
AST Rule Expressivity	CGPA, Percentage, Branch aliases, Backlogs, Gaps, Age, Semesters, AND/OR/NOT	13 rule node types validated across boundary conditions	backend/tests/test_eligibility_ast.py	PASSED

---

Criterion 3: Requirement Extraction From Announcements

Requirement	Target Threshold	Measured Benchmark	Verification Suite	Status
Extraction Accuracy	$\ge$ 20 of 25 announcements without manual re-typing	25 of 25 announcements (100.0%)	scripts/evaluate_extraction.py docs/EXTRACTION_EVAL.md	PASSED
Multi-Format Ingestion	Pasted text, .eml, PDF (pdfplumber text & tables), DOCX	Scanned PDF detection, table parsing, smart-quote normalisation verified	backend/tests/test_extraction.py (18 tests)	PASSED
Extraction Speed	Fast offline execution on normal laptop	0.366s total (14.6 ms/announcement)	scripts/evaluate_extraction.py	PASSED
Traceability & Confidence	Per-field confidence score + exact source sentence citation	All 25 announcements cite source sentence for each criterion	docs/EXTRACTION_EVAL.md	PASSED

---

Criterion 4: Clash-Free Constraint Scheduling (OR-Tools CP-SAT)

Requirement	Target Threshold	Measured Benchmark	Verification Suite	Status
Baseline Target (600 students / 12 drives / 8 rooms)	< 60 seconds offline	1.05 seconds (~57x faster than target)	scripts/benchmark_scheduler.py docs/SCHEDULER_PERF.md	PASSED
Stress Case (1,800 students / 40 drives / 20 rooms)	< 120 seconds offline	5.04 seconds (~24x faster than target)	scripts/benchmark_scheduler.py docs/SCHEDULER_PERF.md	PASSED
Zero Room Clashes	Exactly 0 overlapping room reservations	0 Room Clashes Verified	Mathematical interval NoOverlap check	PASSED
Zero Panel Clashes	Exactly 0 overlapping panel interviews	0 Panel Clashes Verified	Mathematical interval NoOverlap check	PASSED
Zero Student Clashes	Exactly 0 concurrent rounds per candidate	0 Student Clashes Verified	Continuous student timeline interval check	PASSED
Buffer Enforcement	Configurable transition buffer between rooms	15-minute walking buffer enforced between distant blocks	backend/tests/test_scheduler.py	PASSED

---

Criterion 5: What-If Impact Engine & Publish Workflow

Requirement	Target Threshold	Measured Benchmark	Verification Suite	Status
Interactive What-If Simulation	Sub-second latency without DB mutations	0.018s (18 ms) for candidate cut-off delta	backend/tests/test_what_if_engine.py	PASSED
Data-Driven Dynamic Headlines	Formatted headlines generated strictly from data deltas	E.g., "Lowering the cut-off from 7.0 to 6.5 adds 38 students; 6 of them clash with Northwind test at 10:00."	backend/tests/test_what_if_engine.py	PASSED
Second-Order Policy Effects	Change in Drive A triggers offer policy block in Drive B	Validated via OfferPolicy change propagation tests	backend/tests/test_what_if_engine.py	PASSED
Publish & Rollback	Monotonic versions, immutable published snapshots, instant rollback	Database event sourcing and version rollback verified	backend/tests/test_publish_workflow.py	PASSED

---

Criterion 6: Offline Packaging, Air-Gap Readiness & Security

Requirement	Target Specification	Verification Mechanism	Status
One-Command LAN Launch	Single-command launch (start.bat / start.sh) discovering LAN IP	Verified on Windows & Linux (scripts/lan_launcher.py)	PASSED
Strict Zero-Outbound Air-Gap	0 external HTTP/socket requests during execution	backend/tests/test_airgap_guardrails.py (5/5 passing OS-level socket intercept tests)	PASSED
In-App Self-Check Page	Offline self-check tab in UI validating air-gap readiness	frontend/e2e/workflow.spec.ts Test 3: Offline Self-Check	PASSED
Password Security	Argon2id hashing with cryptographic salt	Verified in backend/app/api/auth/service.py	PASSED
Session Security	HTTP-only, SameSite=Lax session cookies + CSRF protection	Verified in backend/tests/test_auth_routes.py	PASSED
Field-Level Encryption	AES-256 Fernet key derivation via PBKDF2 (100k rounds)	backend/app/security/field_crypto.py	PASSED
PII Redaction in Logs	Redacts student names, emails, phone numbers from logs	JsonPiiRedactingFormatter in backend/app/logging.py	PASSED
STRIDE Threat Model	Comprehensive threat model with mitigations mapped to tests	docs/STRIDE_THREAT_MODEL.md	PASSED
Encrypted Backup & Restore	Passphrase-encrypted .enc export/import with integrity check	scripts/backup_restore.py backend/app/api/routes/backup_routes.py	PASSED
One-Click Institutional Wipe	Cryptographic wipe requiring explicit typed phrase confirmation	POST /api/backup/wipe requiring "CONFIRM_INSTITUTIONAL_WIPE"	PASSED
Student-Scoped Access	Candidates authenticate via roll no + OTP; cannot view others	Verified via server-side ID tampering unit tests	PASSED

---

Regression & Test Suite Summary

• Total Backend Tests: 149 / 149 Passing (0 Failures, 0 Regressions)
• Ruff Linter: 0 Errors / 0 Warnings across all backend files
• Mypy Static Type Checker: 0 Errors across 113 source files (Strict Mode)
• Frontend Build: 1,973 modules transformed, 0 TypeScript errors (dist/index.html bundled)
• Playwright End-to-End Suite: 4 / 4 Passing (Officer Journey, Student Portal, Offline Audit, Accessibility)