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%).