agiledancers/docs/validation/S16-validation.md

Historical validation evidence from application commit bd898e92d22f6c412e671908770f4d89c8ae12bc. Commands retain their original paths; current tooling is documented in README.md.

S16 implementation validation

Delivered behavior

PostgreSQL owns normalized school, dancer, coach, group, membership, style, show, daypart, appearance and ordered-assignment tables, plus the latest scheduling run. Flyway V1 creates the schema, persistent identifier sequence, cross-school-safe foreign keys and row constraints. School keys, runtime identifiers, relationship identity, coach links, draft assignments and finalized state survive reload.

Application persistence uses JPA/Hibernate ORM with mapped entities in repository.entity and EntityManager repositories. Relationships, element collections, daypart order and orphan removal are managed by Hibernate; domain objects and API responses remain framework independent. The hand-written JDBC query/update layer and row readers have been removed.

The HTTP interceptor runs each school operation in a short repeatable-read JTA transaction under the existing domain monitor. Reads convert managed entities into detached domain snapshots. Hibernate's school @Version checks optimistic changes; a change stamp marks child-only edits so the school revision advances exactly once. Missing or stale caller revisions conflict before applying edits, and stale detached JPA entities also fail. Successful graph merges flush before commit, and status publication remains after durable commit. A single school-data endpoint gives the editor a consistent data/revision snapshot. Open editors retain their original revision across background refreshes; conflict responses preserve their input and require reload before retry. Replacement imports retain the target school ID and check the revision returned by preview. Existing JSON import/export semantics remain.

Domain-to-view projection now uses MapStruct 1.6.3 in the REST layer. The generated CDI DomainViewMapper covers schools, dancers, groups, coaches, dayparts and shows. A shared ID conversion projects relationships to ordered ID lists; validation results remain an explicit argument and preferred-daypart defaults delegate to the existing application rule. View record constructors retain their defensive copies. Entity to domain graph construction remains explicit in the persistence adapter. unmappedTargetPolicy = ERROR rejects missing target fields at compilation. A compiler probe with the actual mapper and an added unmapped SchoolView component confirms this failure, without modifying maintained sources. MapStruct's generated implementation is marked lombok.Generated, preserving the existing generated-code scope of coverage and architecture checks; handwritten mapper helpers remain covered and checked.

Flyway remains the schema authority; Hibernate validates rather than generates DDL. V1 is unchanged. V2 preserves existing rows, adds the aggregate change stamp and a JPA-managed identifier counter seeded above previously allocated IDs, and defers date/type uniqueness until commit so Hibernate can reorder retained dayparts safely. Identifier allocation takes a pessimistic lock on the counter row. Coach/dancer and group/coach associations use Hibernate composite join mappings to share the owning school key while letting Hibernate update the linked member column directly.

Run acceptance checks the school revision and persists the run before launch or acknowledgement. Acceptance itself does not change scheduling inputs. Background computation holds neither a database transaction nor the domain monitor. Progress commits before publication. Successful assignment replacement, school revision and terminal run status commit together; publication callbacks run only after commit. Deferred constraint failures roll back both assignments and status without publishing success. Database failure never falls back to acknowledged memory-only writes. Disconnected status subscribers cannot turn a committed result into a solver failure.

Startup recovery marks persisted Running runs Interrupted before serving status, retains their IDs, progress and previous saved assignments, and creates no old run guards. The frontend recognizes Interrupted and retains S12's reconnect/reload notification behavior. Timestamps use PostgreSQL microsecond precision consistently in live and recovered snapshots.

Verification

• Maven clean verify: all 72 backend tests and 19 standards-checker regression tests pass. The JPA integration run also verified Flyway V1 and V2 and Hibernate schema validation against an empty database, as well as an upgrade of the populated V1 test database.
• Backend line coverage: 1763/1827 (96.50%), above the 80% gate.
• Frontend: 32 unit tests, production build and ESLint pass (unchanged by the MapStruct-only backend change).
• Generated-mapper CDI tests cover ordered relationship IDs, an unlinked coach, nested assignment order, defensive copies, explicit validation messages and the configured/default preferred-daypart rule. The compile-time unmapped-field probe passes with the expected compiler error.
• Playwright: the three existing real REST/browser scenarios pass with PostgreSQL; a fourth scenario verifies two screens editing the same revision, conflict handling with retained form input, and successful reload/retry.
• PostgreSQL tests cover simultaneous edits (one succeeds, one conflicts), missing revisions, relational graph recovery, IDs and ordered assignments, finalized state, deferred commit failure without success publication, failed replacement import rollback, stale scheduling inputs and interrupted-run recovery. JPA-specific tests verify stale detached entities, exactly one aggregate version increment for child-only edits, and reordered dayparts retaining their assignments.
• tooling/persistence/restart_test.py runs the packaged production backend against an isolated persistent PostgreSQL container. It passes graceful restart and SIGKILL interruption checks, verifies a completed saved result after every restart, checks stable recovered IDs through HTTP and SSE, starts a new run after interruption, rejects mutations during a database outage, and verifies startup failure for an unreachable database and a deliberately failing Flyway migration.
• CI helper tests: 17 pass. Release and actual deployment-shell behavior tests: 32 pass. Shell syntax and Java/frontend formatting checks pass.

The packaged-process checks deliberately stop/restart only the named disposable test database. Production deployment was not performed. Database provisioning and transition instructions are in docs/persistent-storage.md; export every school before stopping the old in-memory release. Production Compose retains its database volume outside application replacement. CI supplies a separate disposable browser database and removes its anonymous volume during cleanup.

Manual standards assessment

No waivers or weaker gates were added. Architecture tests pass. Persistence entities and their embeddable keys belong to the repository layer, while the scheduling records remain in model.scheduling. Mutable classes, no-argument construction, setters and replaceable collections are deliberate JPA lifecycle requirements; Hibernate installs managed collection wrappers and hydrates fields. Composite key values are assigned before persistence and are not mutated afterward. None of these entities or lazy collections escapes into the solver or the API. Existing immutable snapshot records still defensively copy mutable collections.

Retained review signals in changed code:

• Database fan-out 27 and transaction cyclomatic complexity 8: JPA/JTA lifecycle, rollback and heuristic failures, optimistic-conflict classification, and committed publication are handled in one transaction owner. Its two injected dependencies remain below the review signal.
• SchoolWriter fan-out 17: one adapter builds and merges the school graph, removes deleted-show statuses, checks JPA revisions and flushes changes. PeopleMapping, GroupMapping and ShowMapping separate domain conversion from ORM lifecycle.
• Entity fan-out reflects explicit relationship and collection annotations: DayPartEntity 22, GroupEntity 24, RunEntity 17, SchoolEntity 18 and ShowEntity 23. Each maps one existing table/aggregate boundary; splitting fields merely to lower annotation-driven fan-out would obscure the relational mappings. Entity collections are mutable only within the persistence adapter and Hibernate session.
• SchoolTransactions fan-out 19 and request cyclomatic complexity 9: four collaborators cover the detached domain monitor, transaction owner, loader and writer. The branch structure distinguishes reads, run acceptance and domain mutations and maps storage failures separately from optimistic conflicts. SchoolChange's four components keep the revision and operation classification together.
• SchedulingRuns fan-out 31: it coordinates immutable input/progress/run/result records, the solver port, durable lifecycle operations and subscriber callbacks; its three injected collaborators remain below the dependency review signal.
• SchoolManagementService fan-out 38, 30 public methods, beginScheduling cyclomatic complexity 8 and the existing five-parameter updateShow are retained: aggregate use cases and validations remain together. Load installs detached state and resets transient input counters under the existing monitor.
• REST resource fan-out is 18–28 (DanceSchoolResource 25): resources combine HTTP annotations, use cases, request/view contracts and the injected projection mapper. The consistent data endpoint assembles views inside the transaction. DomainViewMapper fan-out 25 represents six explicit source/target projections plus the MapStruct annotations and two small shared helpers. DomainViewMapperTest fan-out 22 exercises the generated CDI mapper's API edge cases. SchoolView's six components include the revision; SchoolDataView's five components represent one editor snapshot. ImportPreview's seventh component identifies the target revision for replacement.
• PersistenceTest fan-out 47, seven injected fixtures, 335 code lines and methods of 41/33/42 lines: these cross real ORM, graph and transaction boundaries, including detached-entity conflicts, commit-time failure, failed import, child versioning and reordered assignments. The fixtures remain below all blocking limits. Existing changed REST/SSE/background fixture metrics retain their S12/S7 rationale.

One active backend remains the supported deployment model. Global execution capacity, distributed workers, database backup/restore and recovery after database volume loss remain outside S16. S17 owns backup/restore.

Review follow-up: database recovery during calculation

Terminal scheduling outcomes whose transaction fails remain pending in their worker. The worker retries storage once per second without holding the school monitor between attempts, retaining its run guard until the terminal status commits. Publication still happens only after commit. Shutdown interrupts the wait; startup recovery remains responsible for persisted Running statuses after a process restart. If the show was removed during the outage, the pending outcome is discarded rather than recreating its status. The finish method's cognitive complexity 12 and cyclomatic complexity 8 distinguish retryable storage failures, removed shows and shutdown; these lifecycle decisions stay in the run owner. SchedulingRuns fan-out is now 34 and its test fixture fan-out 35: the added storage exception, interruption handling and outage fixture belong to this existing persistence lifecycle boundary.

The regression test simulates unavailable storage during result persistence, verifies that no terminal status is published prematurely and duplicate starts remain rejected, then restores storage without restarting the backend and checks the stable run ID, persisted failure status and released guard. Public transaction/callback documentation now specifies transaction ownership, callback timing and exception behavior.

Follow-up verification: clean Maven verify against PostgreSQL passes all 73 backend tests and 19 standards-checker tests. Standards and the coverage gate pass; backend line coverage is 1769/1841 (96.09%).