add test batches

docs/alrahma_end_to_end_use_case_test_plan.md

@@ -2073,3 +2073,383 @@ A use case is done only when:
 - The test is automated or has a documented manual test script.
 
 Anything less is not done. It is merely optimistic.
+
+---
+
+# Part VI: Executable Coverage Gates Added
+
+## 26. API Route to Use-Case Matrix
+
+The test suite now includes `tests/Feature/Api/ApiUseCaseCoverageMatrixTest.php`.
+
+Purpose:
+
+- Every API route must be assigned to a business use-case domain.
+- Every required domain must have at least one route.
+- Every protected API route must reject anonymous traffic before business logic is reached.
+
+This is not a substitute for feature tests. It is a guardrail that prevents undocumented endpoints from quietly entering the system. Silent endpoint creep is how applications become archaeology projects.
+
+The current executable domains are:
+
+- Public content and support
+- Legacy compatibility
+- Preferences, navigation, and UI
+- Administration, enrollment, and school years
+- Students, parents, and families
+- Teachers, staff, and class operations
+- Attendance and safety
+- Grading, scores, and reporting
+- Finance, billing, and inventory
+- Communications and messaging
+- Competition and public results
+
+When a new route is added, update the matrix and add or extend the corresponding workflow test. A route without a use case is not an API, it is a liability with a URL.
+
+## 27. New Workflow Scenarios
+
+The suite now includes two cross-cutting workflow files:
+
+- `ScenarioIPublicAuthAndSystemUseCaseTest.php`
+- `ScenarioJCrossModuleApiUseCaseSmokeTest.php`
+
+Scenario I covers the public front door: public content, policies, pages, captcha, contact form, login, current-user lookup, logout, invalid login, and suspended-account handling.
+
+Scenario J covers broad authenticated module reachability and validation safety across admin, teacher, and parent workflows. It deliberately checks that major modules reject bad input cleanly instead of turning malformed requests into 500 errors, because production users are excellent chaos generators.
+
+## 28. Expansion Rule for “All APIs and Features”
+
+For every feature area, keep three layers:
+
+1. Route coverage matrix: the endpoint belongs to an explicit use-case domain.
+2. Cross-module smoke test: authenticated users can reach the module and malformed requests do not crash it.
+3. Dedicated end-to-end workflow: the correct role performs the real business action, the wrong role is blocked, and the expected database state is left behind.
+
+The suite already has Scenarios A through J. Future expansion should add one scenario file per real business journey, not one random test per controller method. Controller-method testing is a map of plumbing. Use-case testing is a map of the school actually running.
+
+## 29. Expanded Executable Workflow Scenarios
+
+The suite now adds two deeper workflow files beyond broad smoke coverage:
+
+- `ScenarioKParentSelfServiceAndPrivacyTest.php`
+- `ScenarioLTeacherAcademicOperationsTest.php`
+
+Scenario K covers the parent portal as a complete use case: the parent reviews profile, attendance, invoices, enrollments, updates contact information, adds emergency contacts, and is blocked from mutating another family’s student or emergency contact records.
+
+Scenario L covers a teacher’s classroom loop: the teacher loads the roster, retrieves class progress metadata, submits weekly progress, updates progress status, adds homework scoring columns, records homework scores, and checks report-card completeness. It also verifies an unassigned teacher cannot view or update another teacher’s progress report.
+
+These are intentionally not controller-method checklists. They assert business behavior across controllers, services, middleware, and database state. That is the point. If a test cannot explain what real-world workflow it protects, it is probably test-shaped furniture.
+
+### Added executable workflow coverage: Scenarios M through O
+
+The expanded workflow suite adds three more explicit use-case tests. These are intentionally written as end-to-end API flows rather than isolated controller pokes, because endpoint confetti is not test strategy.
+
+- **Scenario M: Administrator enrollment and classroom operations** verifies that an administrator can create a parent, create a student, create a class section, assign the student to that class, assign a teacher, confirm roster visibility, and reverse assignments without deleting the underlying student/family records.
+- **Scenario N: Communications and support lifecycle** verifies parent-to-teacher messaging, inbox visibility, read-state persistence, archival state changes, public contact submission, and authenticated support queue behavior.
+- **Scenario O: Inventory, finance, and audit controls** verifies inventory category/item creation, quantity adjustment, audit fields, movement logging, inventory summary visibility, and finance follow-up actions for unpaid balances.
+
+These tests should continue to grow by scenario. The rule is simple: when a feature exists because a real person performs a job, the test should describe that job from beginning to end. Testing individual URLs is useful, but only after the business workflow is nailed down.
+
+### Added broad-batch executable workflow coverage: Scenarios P through Z
+
+The latest expansion adds a broad pass instead of incremental drip-feed coverage. The new tests are organized by real operational workflows, not by whichever controller happened to annoy the developer that day.
+
+- **Scenario P: Settings, configuration, and calendar governance** covers settings review/update, school calendar CRUD, notifications, and configuration-admin CRUD.
+- **Scenario Q: School-year promotion and closure lifecycle** covers admin promotion review/evaluation, parent promotion steps, year close validation, preview, close, and reopen guardrails.
+- **Scenario R: Attendance operations and exception handling** covers teacher attendance grids/submission, admin manual attendance edits, staff attendance, early dismissal, late slip surfaces, violation tracking, and attendance comment template lifecycle including legacy aliases.
+- **Scenario S: Scoring, grading, and report-card lifecycle** covers teacher entry for homework, quizzes, projects, midterm, final, participation, score comments, grading overview/decisions, locks, below-sixty intervention, and report-card completeness.
+- **Scenario T: Documents, print, badges, stickers, slips, and certificates** covers teacher print requests, admin print processing, file access, badge generation/logging, sticker/slip surfaces, and certificate generation/audit.
+- **Scenario U: Finance billing, payments, refunds, and installments** covers invoice visibility, payment creation, transaction logging, receipts, fee calculations, installment plans, refund approval/payment, and balance carryforward drafts.
+- **Scenario V: Procurement, suppliers, purchase orders, and reimbursements** covers supply categories, suppliers, purchase orders, receiving, reimbursement submission, reimbursement processing, batches, locks, exports, and donation marking.
+- **Scenario W: Access control, roles, navigation, and preferences** covers role-permission management, permission assignment, nav-builder lifecycle, role switching, preferences, and non-admin denial.
+- **Scenario X: Public, kiosk, scanner, and verification surfaces** covers public content/documentation, health checks, badge scan processing, scanner processing, badge scan logs, and invalid public token handling.
+- **Scenario Y: Family, guardians, authorized users, and WhatsApp** covers family bootstrap, second guardian attachment, guardian flags, family lookup/card surfaces, authorized-user invite/update, parent-contact exports, WhatsApp link lifecycle, and membership updates.
+- **Scenario Z: Legacy aliases, validation contracts, and compatibility** covers legacy teacher GET/POST aliases, structured validation errors for representative public/authenticated forms, redirects, and non-versioned auth aliases.
+
+This creates a stronger testing spine for “all APIs and features.” It still does not mean the entire product is done. That claim would be a clown car with a CI badge. The next hardening layer should add wrong-owner and wrong-role negative tests inside each scenario where the feature has ownership semantics, then tighten flexible assertions once production controllers have stable response contracts.
+
+## Full-Surface Batch Expansion
+
+The suite now includes a full-surface E2E contract layer under `tests/Feature/Api/V1/FullSurface`.
+
+These files are intentionally broad rather than drip-fed by individual feature:
+
+- `ApiFullSurfaceEndToEndContractTest.php` walks the registered Laravel API route table and probes every route with seeded administrator, teacher, parent, and student context. It verifies controlled response status, no 5xx crashes, malformed-payload safety, and wrong-role portal boundaries.
+- `ApiRouteUseCaseCatalogCompletenessTest.php` forces every registered API route to map to a named user journey, not merely a controller namespace.
+- `ApiPublicAndAuthFullSurfaceContractTest.php` covers public, documentation, page, policy, health, kiosk, registration, login, me, logout, and frontend identity contracts.
+- `ApiAdminOperationsFullSurfaceContractTest.php` covers administrator enrollment, promotion, staff, emergency contacts, school years, permissions, finance dashboards, certificates, reimbursements, flags, and printables.
+- `ApiAcademicAttendanceFullSurfaceContractTest.php` covers teacher classroom operations, attendance, tracking, templates, grading, score entry, report cards, print requests, and legacy teacher routes.
+- `ApiFinanceInventoryCommunicationsFullSurfaceContractTest.php` covers finance, billing, refunds, carryforwards, event charges, installments, notifications, inventory, suppliers, support, messages, email, communications, and WhatsApp.
+- `ApiFamilyPortalFullSurfaceContractTest.php` covers parent profile, student privacy, attendance, invoices, enrollments, promotions, emergency contacts, family guardians, and authorized users.
+
+Expansion rule: new APIs must now satisfy two layers. First, the route must be owned by an explicit user journey in the catalog. Second, it must either be covered by the full-surface contract probe or by a named scenario with stronger business assertions. Endpoint existence alone is not coverage. It is merely a URL with opinions.
+
+### Full-surface deep contract expansion
+
+The next expansion adds a deeper executable contract layer under `tests/Feature/Api/V1/FullSurface`.
+
+New support base:
+
+- `Support/FullSurfaceE2EContractCase.php` centralizes deterministic users, class/student/parent fixtures, route materialization, actor selection, payload generation, and controlled-response assertions.
+
+New deep contract suites:
+
+- `ApiDeepResponseShapeAndEnvelopeContractTest` verifies that successful API responses are parseable JSON and that collection endpoints expose a stable list/envelope shape.
+- `ApiDeepValidationFailureContractTest` sends empty, wrong-type, oversized, and hostile nested payloads to mutating routes and requires clean validation/authorization responses instead of 5xx crashes.
+- `ApiDeepAuthorizationIsolationMatrixTest` expands role isolation checks across parent, teacher, student, and administrator boundaries, including wrong-family access attempts.
+- `ApiDeepPaginationSearchAndFilterContractTest` probes list endpoints with pagination, search, sort, status, school-year, and semester filters, plus invalid date ranges.
+- `ApiDeepIdempotencyAndDuplicateSubmissionContractTest` checks duplicate-sensitive POST routes and retryable destructive/archive routes for controlled behavior.
+- `ApiDeepFileImportExportAndPrintableContractTest` probes download/export/printable endpoints and upload/import-style endpoints with fake files.
+- `ApiDeepStateTransitionInvariantContractTest` targets school-year transitions, promotion previews, attendance transitions, and finance transitions with invalid and repeated states.
+- `ApiDeepDocumentationAndRouteParityContractTest` keeps documentation/catalog endpoints reachable and checks the route table remains documentable and grouped by deeper contract domains.
+
+These tests are intentionally broader than named workflow stories. The workflow tests prove business journeys. The full-surface tests prove API discipline: response shape, validation, authorization, idempotency, list/filter safety, file boundary safety, and state transition control. That is the layer that catches boring production failures before users discover them with the enthusiasm of unpaid QA.
+
+### Full-surface expansion v6: security, privacy, hygiene, and boundary contracts
+
+This pass adds another broad layer under `tests/Feature/Api/V1/FullSurface/`. It is intentionally not a new sequence of tiny scenario drips; it expands the contract net across the whole API surface.
+
+New test classes:
+
+- `ApiSecurityAndTransportContractTest` verifies unauthenticated transport behavior, wrong-method handling, and CORS/preflight-style control responses across major domains.
+- `ApiErrorEnvelopeConsistencyContractTest` verifies missing routes, validation envelopes, and authorization denials do not leak stack traces, framework internals, or SQL errors.
+- `ApiOwnerBoundaryAndPrivacyExpansionTest` verifies family isolation, unassigned-teacher isolation, and sensitive user serialization boundaries.
+- `ApiDestructiveActionSafeguardContractTest` verifies delete, archive, remove, cancel, void, close, reopen, and bulk destructive routes handle missing/empty/duplicate attempts without uncontrolled failures.
+- `ApiWriteAuditAndTimestampContractTest` verifies successful writes expose usable identifiers or status envelopes, timestamp fields are not serialized as broken values, and audit/log mutation routes are not public.
+- `ApiRouteNamingVersioningAndHygieneTest` verifies routes do not drift into debug/temp naming, duplicate URI/method pairs, vague placeholders, or undocumented unversioned API surfaces.
+- `ApiBulkImportExportAndPartialFailureExpansionTest` verifies bulk routes handle mixed valid/invalid targets, import routes reject wrong file types cleanly, and export/download/print routes remain controlled.
+- `ApiLegacyCurrentAliasParityExpansionTest` verifies auth aliases, legacy teacher aliases, and unversioned compatibility routes do not drift into incompatible or crashing behavior.
+- `ApiPermissionMatrixExhaustiveContractTest` adds explicit role-matrix probes for admin, teacher, parent, and student access boundaries.
+- `ApiEmptyDatasetAndNullStateContractTest` verifies empty result sets, missing current school-year state, and empty class rosters remain controlled.
+- `ApiQueryParameterFuzzingContractTest` probes hostile search, pagination, sort, filter, date, and include parameters to catch SQL leakage and uncontrolled crashes.
+- `ApiContractSnapshotSeedTest` adds lightweight contract-key snapshots for core successful payloads so API responses cannot silently lose identity/resource keys without tests noticing.
+
+The intent is to force the backend to answer five hard questions for every feature area:
+
+1. Does the endpoint fail safely?
+2. Does it expose the right role and owner boundary?
+3. Does it keep response shape stable enough for clients?
+4. Does it handle empty, duplicate, malformed, and hostile inputs?
+5. Does compatibility stay deliberate rather than accidental?
+
+Future additions should be made in one of two places: workflow scenarios for business journeys, or full-surface contracts for systemic guarantees. Do not add isolated one-off tests unless the bug is too specific to generalize.
+
+## Full-surface v7 expansion: hardening, privacy, and invariants
+
+This pass adds another broad contract layer rather than isolated scenario trickles. The new tests are deliberately written as cross-cutting quality gates over the route table and seeded E2E actors.
+
+New coverage areas:
+
+- Token/session hardening: repeated bad login attempts, garbage bearer tokens, repeat logout safety.
+- Sensitive serialization redaction: passwords, remember tokens, provider secrets, payment secrets, and credentials must not leak in success or error responses.
+- Mass-assignment and overposting: write endpoints must ignore or reject privilege, ownership, audit, and finance tampering fields.
+- Referential integrity: impossible foreign keys must fail with controlled validation/authorization/not-found responses, not raw database errors.
+- Read-after-write consistency: successful creates must return an identifier, envelope, or location that supports follow-up reads; successful updates must not null out identity.
+- Date, money, and timezone boundaries: impossible dates, ambiguous dates, negative amounts, overflow amounts, NaN/Infinity-style values, and invalid timezones must fail cleanly.
+- Attachment/file safety: upload-like endpoints must reject executable files and download-like endpoints must resist path traversal probes.
+- Observability: correlation/request IDs must be accepted safely without becoming response-header injection or error-handling hazards.
+- Cache correctness: authenticated private resources must not be publicly cacheable, and conditional headers must not bypass authorization.
+- Concurrency/stale writes: duplicate submissions and stale version headers must stay controlled and must not leak deadlock/duplicate-key internals.
+- Localization fallback: supported and unsupported locales must not cause missing-translation or timezone runtime failures.
+- External provider callbacks: webhook/callback/payment-provider routes must reject unsigned malformed payloads without exposing provider secrets.
+- Report/export privacy: downloadable and aggregate reporting routes must stay scoped to the actor's family, class, or role.
+
+These tests are not replacements for scenario-level assertions. They are guardrails around the failure classes that normally escape happy-path E2E suites: identity leaks, unsafe error envelopes, overposting, stale writes, bad money math, attachment abuse, and report/export privacy leaks.
+
+## Full-surface v8 expansion: lifecycle depth, edge cases, and operational resilience
+
+This pass adds another broad batch of contract tests under `tests/Feature/Api/V1/FullSurface/`. It is designed to widen the test net without slipping back into route-by-route drip testing.
+
+New coverage areas:
+
+- Authentication lifecycle depth: valid login contract parity, invalid login behavior, identity endpoints, logout idempotency, password reset, registration, and verification safety.
+- Role workflow negative matrix: non-admin mutation denial, actor-specific read boundaries, and blocked/suspended/unverified user access probes.
+- Schema key stability: successful resource payloads must retain identity/display keys, and error envelopes must remain actionable for clients.
+- Business rule edge cases: mismatched school year/semester/class payloads, financial amount boundary rules, and attendance status/time abuse.
+- Notification and messaging delivery: recipient validation, bad channels, oversized messages, invalid email/phone values, read/archive/star/delete idempotency.
+- Data export least privilege: parent, teacher, and student export/download/report access must remain scoped and must not leak sensitive bulk data.
+- Audit and administrative traceability: admin mutations must remain controlled and audit/log routes must not be public or low-privilege mutable.
+- Calendar and schedule conflicts: invalid date ranges, reversed times, impossible recurrence, broad private-event queries, and actor-scoped calendar reads.
+- Search and autocomplete resilience: empty, tiny, hostile, huge, wildcard, and script-like search inputs must not leak SQL or reflect raw scripts.
+- Feature flag/configuration drift: missing core configuration rows must fail closed, and low-privilege users must not mutate privileged settings.
+- Transaction rollback backstops: failed multi-step mutations must not spray obvious partial users/students, and failed destructive actions must not remove seeded fixtures.
+- Client compatibility/versioning: API routes must be versioned or explicitly legacy, route names must stay unique enough for client generation, and legacy/current auth failures must remain compatible.
+- School operations regression backstop: administrator probes across core domains must stay controlled, and each user-facing portal must retain at least one reachable read contract.
+- Operational payload resilience: huge bodies, deep arrays, huge ID lists, abusive include/fields/expand query strings must fail safely without memory or framework leaks.
+
+The point of v8 is not to worship the number of test files. The point is to make failure categories explicit: lifecycle, permissions, schema, business rules, delivery, exports, auditability, scheduling, search, config drift, transaction safety, versioning, portal reachability, and payload resilience. That is how the suite becomes a quality system rather than a decorative pile of assertions.
+
+## v9 broad expansion: documentation, media, cache, lifecycle, and abuse contracts
+
+This pass adds another full-surface contract layer rather than another drip of isolated scenarios. The v9 tests focus on API behavior that often slips between business workflows and endpoint smoke tests:
+
+- OpenAPI/documentation route drift and machine-readable route inventory expectations.
+- Content negotiation and malformed media-type behavior.
+- Soft-delete, restore, archive, cancel, void, and repeated destructive-action safeguards.
+- Model lifecycle invariants across create/update/show/index-style resources.
+- Notification preference, opt-out, recipient, and broadcast authorization boundaries.
+- Report aggregation filters, date windows, grouping, and scoped report access.
+- Deeply nested payloads, sparse arrays, oversized ID lists, and array abuse.
+- Public/private cache separation and conditional request authorization.
+- File upload/download metadata safety, misleading MIME types, and path traversal probes.
+- Sorting, field selection, include/expand controls, and sensitive-field redaction.
+- Calendar, schedule, timezone, recurrence, and DST boundary inputs.
+- Webhook replay, missing signature, bad signature, and provider-secret redaction.
+- Impersonation/delegation/acting-as route controls.
+- Policy/authorization discovery for protected mutations and wildcard permissions.
+- Cross-module referential misuse, where valid IDs from one domain are submitted as IDs for another domain.
+
+The intent remains the same: every new API surface should either be owned by a named user journey or covered by a full-surface contract probe that catches drift, unsafe errors, privacy leaks, role leaks, and malformed-input failures. Endpoint quantity is not quality; it is just a larger blast radius unless these contracts stay strict.
+
+## v10 broad contract expansion
+
+The v10 batch adds another full-surface test layer without executing the suite locally. The goal is to widen contractual pressure across the API surface instead of adding a few isolated scenario crumbs.
+
+New coverage areas:
+
+- Route-family heatmap coverage and mutating-route ownership checks.
+- HTTP method semantics, wrong-method behavior, bodyless deletes, and GET routes receiving mutation-looking query input.
+- Null and string relationship failure modes for write endpoints.
+- Frontend/backend identity and login alias parity.
+- Route-parameter abuse: path traversal, script payloads, overflow IDs, and malformed placeholders.
+- Privacy, retention, archive, erasure, and sensitive-field redaction boundaries.
+- Async/queue/job-style trigger authorization and duplicate client request IDs.
+- Financial/report math invariants, invalid money formats, and impossible aggregation windows.
+- Migration-safe defaults when optional configuration rows or school-year context are absent.
+- Polymorphic ownership overposting and cross-actor owner query isolation.
+- Enum/state-machine boundaries for unknown statuses and terminal-state transitions.
+- Unicode, bidi, zero-width, email, and phone normalization probes.
+- Backward-compatible response envelope shape for collection and detail endpoints.
+- Academic calendar boundary dates and hostile semester/term values.
+- Mobile-client headers and offline retry/idempotency tolerance.
+- Import/template/CSV malformed input and template download access boundaries.
+- Cross-version auth route compatibility and containment of unversioned legacy routes.
+
+Rule added by v10: every future API expansion must be visible in the route-family heatmap, must have controlled failure behavior under malformed relationship IDs, and must not rely on frontend assumptions that are absent from API response contracts. Otherwise the frontend gets to discover the contract in production, which is one way to run QA if you hate everyone.
+
+
+## Batch 11 full-surface hardening expansion
+
+Batch 11 adds another broad contract layer rather than another drip of isolated scenarios. It targets high-risk API failure modes that are easy to miss when teams worship happy-path workflows like tiny golden idols.
+
+New coverage includes:
+
+- Tenant, school-year, and semester isolation across academic, attendance, finance, and reporting routes.
+- Open redirect and hostile return-url handling for login, auth, navigation, dashboard, and frontend bootstrap routes.
+- SSRF-style URL payloads for callback, webhook, import/export, media, notification, and settings routes.
+- HTML/script reflection safety for user-controlled text fields.
+- CSV and Excel formula injection payloads in import/export-facing text fields.
+- Conditional request and stale ETag behavior on mutating routes.
+- Idempotency-key replay and malformed idempotency header behavior.
+- Authorization-cache and role-escalation probes after permission-like mutations.
+- Null/boolean/string type coercion across broad mutation routes.
+- Data minimization checks for parent and student responses.
+- Suspended/disabled/pending account lifecycle access probes.
+- Header spoofing checks for forwarded, override, impersonation, and fake admin headers.
+- Relationship cardinality abuse where single IDs receive arrays or objects.
+- Cursor, offset, page, and per-page abuse across list endpoints.
+- Operational endpoint exposure checks for debug, logs, metrics, cache, queue, and maintenance-style routes.
+- A batch-level regression net proving the major API families remain represented by high-risk negative probes.
+
+Rule going forward: future additions should be added as broad risk families first, then only split into scenario files when a real business workflow needs deeper assertions. More files are not automatically more quality. Sometimes they are just paperwork wearing a lab coat.
+
+## Batch 12 full-surface risk and abuse expansion
+
+Batch 12 adds another broad contract layer over the API surface rather than another tiny scenario drip. It targets production-grade failure modes that sit between normal workflow tests and security regression tests, where most teams conveniently lose interest because the bugs are ugly and the screenshots are boring.
+
+New Batch 12 classes:
+
+- `ApiBatch12MaintenanceModeAndOperationalControlContractTest` checks that maintenance, cache, queue, metrics, logs, debug, and operational control routes are admin-only and return controlled responses.
+- `ApiBatch12SensitiveConfigurationExposureContractTest` checks that configuration, bootstrap, frontend, health, debug, and settings responses do not expose secrets or environment internals.
+- `ApiBatch12BulkMutationBoundaryContractTest` checks empty bulk targets, cross-domain IDs, and unbounded ID lists across assign/import/delete/archive-style endpoints.
+- `ApiBatch12WebhookProviderMatrixContractTest` expands provider callback coverage for missing, bad, and replay-like signature headers across webhook/payment/provider routes.
+- `ApiBatch12CrossActorDataLeakageContractTest` probes parent, teacher, and student reads for sensitive-field leakage and owner-scope override attempts.
+- `ApiBatch12AttachmentLifecycleContractTest` expands upload/download/file lifecycle checks for MIME spoofing, executable uploads, path traversal, and storage-driver probing.
+- `ApiBatch12FinancialLedgerIntegrityContractTest` stresses finance routes with ledger-breaking amounts, wrong module IDs, and parent attempts to force all-family scope.
+- `ApiBatch12AttendanceCorrectionAuditContractTest` checks attendance correction boundaries around status, dates, reasons, wrong IDs, and low-privilege mutation attempts.
+- `ApiBatch12AcademicGradeBoundaryContractTest` checks score boundaries, wrong student/class contexts, and low-privilege grade finalization overrides.
+- `ApiBatch12GuardianDelegationExpirationContractTest` checks guardian and authorized-user expiration, relationship, pickup/messaging flags, and student mutation denial.
+- `ApiBatch12SearchEnumerationResistanceContractTest` probes search, lookup, autocomplete, user, parent, and student endpoints for enumeration and injection-style inputs.
+- `ApiBatch12LongRunningExportJobContractTest` checks export/report/print/generation routes for async parameters, sensitive field requests, and low-privilege full-school export attempts.
+- `ApiBatch12ConsistencyUnderPartialPayloadContractTest` checks sparse POST/PATCH/PUT payloads so validation failures stay controlled and successful partial updates do not null identity or ownership.
+- `ApiBatch12RouteMetadataRiskRegisterTest` creates an executable risk register for identity, authorization, privacy, attendance, academics, finance, files, integrations, and operations.
+- `ApiBatch12CombinedRegressionSweepTest` applies a combined hostile payload across high-risk route families to catch SQL leaks, environment leaks, auth-internal leaks, and uncontrolled crashes.
+
+Batch 12 is not meant to replace the earlier scenario tests. It is a pressure layer: broad, risk-family based, and intentionally hostile. Future batches should either close a named risk family not covered here or deepen a concrete workflow with stronger business assertions. Otherwise the test suite becomes a decorative haystack, which is less useful than it sounds.
+
+
+## Batch 13 full-surface integrity and abuse expansion
+
+Batch 13 adds another broad contract layer on top of Batch 12. It focuses less on simply finding more endpoints and more on catching cross-domain integrity failures, forged business actions, and dangerous client assumptions. In plain terms: the API should not trust a request just because it contains an integer and a hopeful field name.
+
+New Batch 13 classes:
+
+- `ApiBatch13PaymentProviderLedgerReconciliationContractTest` stresses payment-provider references, transaction replay, ledger reconciliation payloads, and duplicate provider IDs.
+- `ApiBatch13StudentEnrollmentLifecycleIntegrityContractTest` checks enrollment, withdrawal, registration, class assignment, and cross-family/class payload abuse.
+- `ApiBatch13TeacherRosterAndAssignmentBoundaryContractTest` checks teacher roster scoping, forced teacher/class overrides, and unassigned-teacher academic mutations.
+- `ApiBatch13ParentPortalInvoicePrivacyContractTest` checks parent invoice/payment privacy, all-family override attempts, and parent attempts to mark invoices paid/refunded.
+- `ApiBatch13StaffHrPayrollBoundaryContractTest` checks staff/HR/payroll redaction and low-privilege mutation denial for personnel data.
+- `ApiBatch13DiscountVoucherScholarshipAbuseContractTest` checks voucher, discount, scholarship, waiver, and fee-abuse payloads.
+- `ApiBatch13InventoryProcurementReceivingIntegrityContractTest` checks procurement, receiving, supplier, inventory movement, and negative-stock abuse.
+- `ApiBatch13ReportCardTranscriptCertificateForgeryContractTest` checks report-card, transcript, certificate, badge, and print generation forgery payloads.
+- `ApiBatch13ContactMessagingAbuseModerationContractTest` checks message/contact/support/broadcast abuse, header injection, spam payloads, and HTML reflection.
+- `ApiBatch13ApiPaginationPerformanceGuardContractTest` checks unbounded list parameters, deep includes, search abuse, and memory/time-error disclosure.
+- `ApiBatch13LocaleCalendarReligiousDateContractTest` checks locale-specific calendar payloads, Hijri-style dates, reversed ranges, recurrence abuse, and academic date spoofing.
+- `ApiBatch13MobileOfflineSyncConflictContractTest` checks mobile/offline sync headers, stale client versions, duplicate offline UUIDs, and conflict-resolution override attempts.
+- `ApiBatch13AccountRecoveryCredentialChangeContractTest` checks password reset, verification, credential-change, token leakage, and cross-user credential mutation attempts.
+- `ApiBatch13RolePermissionMutationRaceContractTest` checks wildcard permissions, recursive role inheritance, replayed role payloads, and non-admin escalation attempts.
+- `ApiBatch13ObservableErrorCorrelationContractTest` checks request/correlation ID safety, header injection, and stack/controller/model disclosure.
+- `ApiBatch13FullSurfaceRegressionSuperSweepTest` adds a combined cross-family hostile-payload sweep plus a mutation-family representation check.
+
+Batch 13 keeps the same rule: write broad, risk-family tests first; only split into deeper workflow scenarios when a real business flow needs stronger state assertions. Otherwise the suite becomes a decorative maze where bugs go to retire.
+
+## Batch 14 full-surface session, integrity, and tamper-resistance expansion
+
+Batch 14 adds another broad contract layer on top of Batch 13. It focuses on API boundaries that often break after the functional workflow looks “done”: session/cookie confusion, identity enumeration, tampered export scopes, forged approvals, device/kiosk trust, signed URL abuse, and cross-module ownership overrides. In other words, the boring stuff that becomes very exciting when it leaks data.
+
+New Batch 14 classes:
+
+- `ApiBatch14SessionCookieCsrfBoundaryContractTest` checks that API authentication does not silently depend on browser session cookies or fake CSRF headers, and that browser-only headers do not grant API privilege.
+- `ApiBatch14AccountEnumerationAndIdentityPrivacyContractTest` checks recovery/verification routes for user-existence leakage and identity payloads for auth internals.
+- `ApiBatch14BulkAssignmentCollisionContractTest` checks duplicate and conflicting bulk assignment payloads across class, teacher, student, enroll, and batch-style routes.
+- `ApiBatch14PrintExportTamperingContractTest` checks print/export/certificate/report generation routes for forged scope, signature, deleted/private data, and low-privilege full-school export abuse.
+- `ApiBatch14AuditTrailTamperResistanceContractTest` checks audit/log/history routes for forged actor, timestamp, and purge/rewrite attempts.
+- `ApiBatch14FinanceReconciliationAndRefundAbuseContractTest` checks finance ledger, payment, refund, transaction, and reconciliation routes for mismatched ownership, negative amounts, fake provider IDs, and parent self-refund abuse.
+- `ApiBatch14AcademicPromotionRollbackIntegrityContractTest` checks promotion, school-year, semester, close/reopen, and rollback routes for unsafe rollback/delete payloads and low-privilege promotion attempts.
+- `ApiBatch14AttendanceDeviceAndKioskAbuseContractTest` checks scanner, kiosk, badge, dismissal, late, and attendance routes for forged device headers and self-marking abuse.
+- `ApiBatch14NotificationTemplateInjectionContractTest` checks notification, template, broadcast, email, WhatsApp, and message routes for template injection, header injection, and non-admin broadcast abuse.
+- `ApiBatch14ApiConsumerContractCompatibilityTest` checks core auth/frontend/profile contracts across web, mobile, and API consumer headers, including the token/user login contract.
+- `ApiBatch14RelationshipOwnershipMatrixExpansionTest` checks parent, family, guardian, invoice, attendance, score, and student routes for owner override fields and cross-relationship graph access.
+- `ApiBatch14StoragePathAndSignedUrlContractTest` checks file/media/upload/download/import/export/signed routes for path traversal, forged signatures, disk override, and secret exposure.
+- `ApiBatch14AdminDelegationApprovalWorkflowContractTest` checks approval, delegation, impersonation, role, permission, and authorization routes for forged approval metadata and self-delegation abuse.
+- `ApiBatch14DataLifecycleArchivePurgeContractTest` checks archive, restore, purge, erase, retention, delete, and destroy routes for unsafe hard-delete/cascade payloads and non-admin purge attempts.
+- `ApiBatch14CrossModuleInvariantRiskRegisterTest` adds an executable Batch 14 risk register so these route families remain visible as the API evolves.
+- `ApiBatch14RegressionMegaSweepTest` adds a combined hostile-payload sweep across auth, users, school, academic, attendance, finance, inventory, messaging, file, audit, and settings surfaces.
+
+Batch 14 keeps the same expansion rule: add risk-family tests when the API surface is broad, and only add narrower scenario tests when a workflow has stateful business rules worth proving. Endpoint confetti is still not a strategy, even if it makes the directory look busy.
+
+
+## Batch 15: Identity, Privacy, Operations, and Abuse-Resistance Contract Expansion
+
+Batch 15 adds another full-surface contract layer focused on long-lived operational and security risks that are easy to miss when tests only chase happy-path workflows.
+
+New coverage areas:
+
+- Token rotation, revocation, refresh replay, logout replay, and identity/session route parity.
+- Privacy, consent, erasure, retention, data-subject export, and student/family scope boundaries.
+- Repeated abuse patterns across login, password recovery, contact, support, badge, and scanner endpoints.
+- Route parameter poisoning with encoded traversal, null bytes, script payloads, SQL-ish values, overflowing IDs, and non-ASCII numeric forms.
+- Feature flag, experiment, rollout, settings, and configuration override attempts by low-privilege actors.
+- Command, scheduler, queue, sync, cleanup, recalculation, and background trigger authorization.
+- Backup, restore, snapshot, database dump, archive, tenant, and residency exposure controls.
+- Cross-school duplicate identity, external ID collision, student-number collision, and tenant alias abuse.
+- Form-request authorization bypass attempts using `_method`, wildcard permissions, and fake roles.
+- Domain event, outbox, notification, webhook, broadcast, email, and WhatsApp forged metadata.
+- Impersonation, delegation, acting-as, switch-user, and behalf-of boundary assertions.
+- Report drilldown, analytics, dashboard, summary, and export aggregate privacy.
+- RTL, Unicode, bidi override, combining characters, emoji, and malformed encoding text payloads.
+- Student safety, incident escalation, attendance alerts, flags, and parent/student mutation denial.
+- Sparse fieldsets, metadata expansion, debug includes, global search, directory, lookup, and autocomplete enumeration resistance.
+- A Batch 15 ultra sweep combining tenant override, owner override, secret includes, hard-delete flags, forged signatures, hostile redirects, and path traversal probes.
+
+This batch continues the rule used by the full-surface suite: broad risk-family tests first, then deeper scenario-specific tests only when a business workflow needs dedicated assertions. Otherwise the test suite becomes a very expensive scrapbook.