Update dependency org.apache.maven.plugins:maven-dependency-plugin to v3.11.0

Reviewed-on: #25

.gitea/workflows/build.yaml

@@ -5,7 +5,7 @@ on:
 
 jobs:
   verify:
-    runs-on: agiledancers-mini-pc
+    runs-on: mini-pc
     env:
       CI: 'true'
       TARGET_PLATFORM: ${{ vars.TARGET_PLATFORM }}
@@ -19,21 +19,23 @@ jobs:
         uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
         with:
           persist-credentials: false
+      - name: Verify pinned engineering resources
+        run: python3 scripts/engineering.py --check
       - name: Identify workflow attempt
         # Gitea 1.25 does not populate gitea.run_attempt. Use a unique value for
         # container names and diagnostic artifacts, including reruns of one SHA.
-        run: java ci/Ci.java attempt
+        run: java generated/ci/Ci.java attempt
       - name: Build and test both images
-        run: java ci/Ci.java verify
+        run: java generated/ci/Ci.java verify
       - name: Publish verified main images
         if: success() && gitea.ref == 'refs/heads/main'
         env:
           REGISTRY_USER: ${{ secrets.REGISTRY_USER }}
           REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
-        run: java ci/Ci.java publish
+        run: java generated/ci/Ci.java publish
       - name: Collect diagnostics and clean up test containers
         if: always()
-        run: java ci/Ci.java cleanup
+        run: java generated/ci/Ci.java cleanup
       - name: Retain diagnostics for fourteen days
         if: always()
         uses: https://github.com/actions/upload-artifact@ff15f0306b3f739f7b6fd43fb5d26cd321bd4de5

.gitea/workflows/deploy.yaml

@@ -3,7 +3,7 @@ on:
   workflow_dispatch:
     inputs:
       mode:
-        description: 'Release mode — deployment can erase data until S16 is implemented'
+        description: 'Release mode — export legacy data before the first S16 deployment'
         required: true
         type: choice
         default: new
@@ -28,7 +28,7 @@ on:
 jobs:
   deploy:
     if: gitea.ref == 'refs/heads/main'
-    runs-on: agiledancers-mini-pc
+    runs-on: mini-pc
     env:
       CI: 'true'
       GITEA_SERVER_URL: ${{ gitea.server_url }}
@@ -42,9 +42,11 @@ jobs:
         uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
         with:
           persist-credentials: false
+      - name: Verify pinned engineering resources
+        run: python3 scripts/engineering.py --check
       - name: Identify workflow attempt
-        run: java ci/Ci.java attempt
+        run: java generated/ci/Ci.java attempt
-      - name: Release verified images — data can be lost until S16
+      - name: Release verified images — persistent PostgreSQL storage
         env:
           RELEASE_MODE: ${{ inputs.mode }}
           RELEASE_INCREMENT: ${{ inputs.increment }}
@@ -57,7 +59,7 @@ jobs:
           DEPLOY_REGISTRY: ${{ vars.DEPLOY_REGISTRY }}
           DEPLOY_SSH_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
           DEPLOY_KNOWN_HOSTS: ${{ secrets.DEPLOY_KNOWN_HOSTS }}
-        run: java ci/Ci.java deploy
+        run: java generated/ci/Ci.java deploy
       - name: Retain deployment diagnostics for fourteen days
         if: always()
         uses: https://github.com/actions/upload-artifact@ff15f0306b3f739f7b6fd43fb5d26cd321bd4de5

.gitea/workflows/rollback.yaml

@@ -5,7 +5,7 @@ on:
 jobs:
   rollback:
     if: gitea.ref == 'refs/heads/main'
-    runs-on: agiledancers-mini-pc
+    runs-on: mini-pc
     env:
       CI: 'true'
       GITEA_SERVER_URL: ${{ gitea.server_url }}
@@ -19,9 +19,11 @@ jobs:
         uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
         with:
           persist-credentials: false
+      - name: Verify pinned engineering resources
+        run: python3 scripts/engineering.py --check
       - name: Identify workflow attempt
-        run: java ci/Ci.java attempt
+        run: java generated/ci/Ci.java attempt
-      - name: Restore previous successful release — data can be lost until S16
+      - name: Restore previous successful release — requires a compatible database schema
         env:
           RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}
           DEPLOY_HOST: ${{ vars.DEPLOY_HOST }}
@@ -31,7 +33,7 @@ jobs:
           DEPLOY_REGISTRY: ${{ vars.DEPLOY_REGISTRY }}
           DEPLOY_SSH_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
           DEPLOY_KNOWN_HOSTS: ${{ secrets.DEPLOY_KNOWN_HOSTS }}
-        run: java ci/Ci.java rollback
+        run: java generated/ci/Ci.java rollback
       - name: Retain deployment diagnostics for fourteen days
         if: always()
         uses: https://github.com/actions/upload-artifact@ff15f0306b3f739f7b6fd43fb5d26cd321bd4de5

AGENTS.md

@@ -1,22 +1,26 @@
-# Project skills and specifications
+# Shared skills and specifications
 
-- Project skills are stored in `skills/`; specifications belong in `specs/`.
+- Shared agent workflows live in [landscape skills](http://192.168.2.28:3000/wanjakrah/landscape/src/branch/main/skills/README.md).
-- For code reviews, read and follow `skills/code-review/SKILL.md`. If no
+  Read the requested SKILL.md there before applying it. A sibling checkout is optional.
-  dedicated Skill tool is available, load the file directly.
+- For code reviews use landscape's skills/code-review/SKILL.md with docs/backend-review.md.
-- Use `grill-me` only when the user explicitly requests it, for example
+- Use grill-me only when explicitly requested, with its skills/grilling/SKILL.md dependency.
-  `Use grill-me to review this plan` or `Gebruik grill-me voor dit ontwerp`.
+  Installing or mentioning a skill starts no interview.
-- Before using it, read `skills/grill-me/SKILL.md` and its dependency
+- Keep upstream skills unchanged; licenses and revision records live in landscape/skills/.
-  `skills/grilling/SKILL.md`. If no dedicated Skill tool is available, load these
+- Specifications and ADRs belong to landscape. Engineering owns pinned build resources.
-  files directly and follow their instructions within the available tools.
-- Installing or mentioning a skill does not start an interview. Do not apply
-  `grilling` automatically to ordinary development requests.
-- Keep the upstream skill files unchanged. Source revision and license are
-  recorded in `skills/upstream.json` and `skills/LICENSE.mattpocock`.
 
 # Backend changes and reviews
 
 - Before changing backend Java, read `CODING_STANDARDS.md`.
-- For reviews, use `skills/code-review/SKILL.md` together with
+- For reviews, use landscape's `skills/code-review/SKILL.md` together with
   `docs/backend-review.md`. Keep upstream skills unchanged.
 - Obtain maintainer agreement before adding any standards waiver; record its
   narrow scope and reason alongside the affected code or configuration.
+
+# Landscape and engineering
+
+- Read current [landscape guidance](http://192.168.2.28:3000/wanjakrah/landscape),
+  including applicable ADRs and specifications. This repository owns its implementation.
+- Engineering resources are pinned by `engineering.lock.json`. Do not edit
+  `generated/`; change engineering and deliberately adopt a released version.
+- Regenerate with `mvn -N -Pregenerate-engineering validate`; check with
+  `python3 scripts/engineering.py --check`. No sibling checkout is needed.

CODING_STANDARDS.md

@@ -1,255 +1,11 @@
-# Backend coding standards
+# Agile Dancers coding standards
 
-This document is the authoritative policy for handwritten production and test Java
+Read [the pinned engineering standards](generated/CODING_STANDARDS.md) before
-in `agiledancers-be`. Generated code and Java helpers outside that module are out
+changing Java. Their backend-module placeholder means `agiledancers-be` here.
-of scope. Existing frontend conventions in README.md and agiledancers-fe remain in force.
+Frontend conventions remain in README.md and agiledancers-fe.
 
-## Scope and authority
+The existing maintainer-approved exception for Group's eight-parameter canonical
+constructor remains in `tooling/standards/waivers.tsv`. No new waiver is introduced
+by S19. For reviews also read [the local companion](docs/backend-review.md).
 
-- Cover handwritten production and test Java in `agiledancers-be`. Exclude
+Validation evidence: [S7](docs/validation/S7-validation.md).
-  generated code. Dependency injection and production architecture rules apply
-  where relevant. Frontend and Java helpers outside the backend are out of scope.
-- [Java coding guidelines](https://www.geeksforgeeks.org/java/coding-guidelines-in-java/)
-  supplied source material. Only the rules adopted in this local document apply;
-  changes to the article do not change project policy.
-- The project's pinned Palantir formatter wins formatting conflicts, including
-  comment layout. S8 remains responsible for formatter integration.
-- Do not adopt unrelated static-analysis rule bundles.
-
-## Java conventions
-
-- Types use UpperCamelCase; methods and variables use lowerCamelCase; constants
-  use UPPER_SNAKE_CASE; package names are lowercase.
-- One top-level type per file; explicit member visibility; `@Override` on
-  overriding methods. Do not invent visibility modifiers where Java forbids them.
-- Opening braces stay on the declaration/control-statement line. All `if`, `for`
-  and `while` bodies require braces, including enhanced for and do/while bodies.
-- No wildcard imports. Static imports are allowed only in test classes.
-- Comments explain intent or constraints. Document public contracts with Javadoc
-  where their meaning is not clear from the declaration; do not require boilerplate
-  documentation for every accessor.
-- Block comments use the following layout, subject to Palantir formatting:
-
-  ```java
-  /*
-      This is an example of a block comment.
-      It may have more than one line.
-  */
-  ```
-- Prefer records for immutable data carriers. Classes are allowed when mutation,
-  framework requirements or inheritance make records unsuitable. Preserve API and
-  serialization behavior. Record immutability is shallow: protect mutable
-  components appropriately.
-- Require `final` for parameters, local variables and fields wherever they can
-  remain assigned once, including loop variables and catch parameters where Java
-  permits it. Field finality must remain compatible with framework injection and
-  lifecycle requirements. Permit reassignment when the algorithm needs it; do not
-  introduce artificial holder objects to avoid reassignment. This rule does not
-  require final classes or methods.
-- Use explicit types unless the initializer visibly identifies the type. `var` is
-  allowed with `new School(...)` or an explicit cast, but not for method results,
-  literals or other inferred expressions. For example,
-  `final var school = new School(...)` is allowed, while a repository result uses
-  `final School school = repository.find(id)`. Borderline cases require review.
-- No additional member-ordering or line-width policy beyond Palantir.
-
-## Metrics
-
-Targets guide development. Review signals require assessment, not automatic
-failure. Blocking limits fail verification. Strict inequalities matter: a value
-exactly at a blocking limit passes.
-
-| Metric | Target | Review signal | Blocking limit |
-| --- | ---: | ---: | ---: |
-| Cyclomatic complexity per method/constructor | ≤ 5 | > 7 | > 10 |
-| Cognitive complexity per method/constructor | ≤ 10 | > 10 | > 15 |
-| Method/constructor length, code lines | ≤ 20 | > 30 | > 50 |
-| Parameters per method | ≤ 3 | > 4 | > 5 |
-| Parameters per explicitly written constructor | ≤ 4 | > 5 | > 7 |
-| Injected dependencies per class | ≤ 4 | > 5 | > 7 |
-| Fan-out per class, unique used types | ≤ 10 | > 15 | Review only |
-| Own superclass depth, excluding Object | ≤ 1 | > 2 | > 3 |
-| Control-flow nesting | ≤ 2 | > 3 | > 4 |
-| Production duplicated lines density | ≤ 1% | > 1% | > 3% |
-| Class length, code lines | ≤ 200 | > 300 | > 500 |
-| Declared public methods per class, excluding trivial accessors | ≤ 10 | > 15 | Review only |
-
-### Measurement definitions
-
-- Use the pinned PMD algorithms as authoritative for cyclomatic and cognitive
-  complexity. Document their exact configuration, including switch and boolean
-  treatment. Do not accidentally introduce a class-level aggregate complexity gate.
-- Measure each method, constructor and explicitly written record constructor
-  independently. Lambda bodies contribute to their enclosing executable;
-  methods in nested/local classes are separate executables.
-- Parameter limits exclude implicit record constructors and generated members.
-  Record component counts remain a design review concern.
-- Length means physical source lines after Palantir formatting, excluding blank
-  and comment-only lines. Declaration and brace-only lines count; a line containing
-  both code and comments counts. Do not substitute statement counts or NCSS.
-  Measure nested types separately and exclude them from enclosing class length.
-- Count distinct injected collaborators by resolved type and qualifier. Include
-  constructor, field, setter, inherited and implicit constructor injection.
-  Repeated injection of the same type and qualifier counts once; differently
-  qualified instances of the same type count separately.
-- Fan-out counts distinct explicitly referenced resolved types, including JDK and
-  framework types. Exclude primitives, the class itself and generated references.
-- Inheritance depth counts project-owned superclass layers; exclude Object,
-  interfaces and external framework ancestry.
-- Nesting combines `if`, loops, `switch` and `catch`, with the first structure at
-  depth one. An `else if` chain stays at one level. `else`, `try` and `finally`
-  add no level themselves. Lambdas retain surrounding depth; methods in nested
-  classes start fresh.
-- Public-method counts include explicitly declared public instance and static
-  methods; exclude constructors, inherited methods and trivial accessors. A
-  trivial accessor only reads or assigns its corresponding field, with no
-  validation, branching or other work.
-- Duplication limits apply only to production code. Duplication in tests is allowed
-  and has no target, review signal or blocking limit.
-- Detect production clones with CPD, minimum 100 tokens, without ignoring
-  identifier or literal differences. Density is
-  `100 × distinct duplicated code-line locations / all production code-line locations`.
-  Exclude blank/comment-only lines from numerator and denominator. Count every
-  occurrence, including the first; merge overlapping ranges to count each source
-  line once. This project metric need not equal a future Sonar metric.
-
-## Enforcement and developer workflow
-
-- Use explicitly pinned Java-25-compatible Checkstyle and PMD/CPD versions.
-  Retain ArchUnit for architecture checks and add small targeted custom checks
-  where standard rules cannot accurately express the agreed semantics.
-- Automate every blocking metric and explicit rule where reliable checking is
-  available. Identify rules requiring manual review explicitly; do not claim
-  they are automated. Review signals must appear in reports even when builds pass.
-- Run standards checks during `mvn verify`; provide documented standalone commands.
-  Ordinary compile/test commands retain the current S8 formatting behavior.
-- Standards checks report violations without rewriting code. CI passes these
-  checks before image publication. Parser failures or unsupported Java constructs
-  fail with the affected path and actionable diagnostics, rather than being skipped.
-- Add a root AGENTS.md instruction requiring agents to read CODING_STANDARDS.md
-  before changing backend Java. Project review instructions must explicitly cover
-  manual rules, review signals in changed code and approved waivers, without
-  repeating checks already enforced by tooling.
-- Keep upstream skill files unchanged. Put project-specific code-review guidance
-  in a companion file referenced by project instructions and used alongside
-  `skills/code-review/SKILL.md`.
-- Waivers must be explicit, narrowly scoped and carry a recorded reason alongside
-  code or configuration. Agents need maintainer agreement before introducing one.
-  No blanket suppressions, exclusions of difficult files or weakened thresholds
-  merely to make verification pass.
-
-## Coverage
-
-- Require at least 80% backend line coverage across handwritten production code
-  for the module as a whole, not separately per class or package. Compare the
-  unrounded percentage against 80%.
-- Local `mvn verify` must reach 80% using backend unit/integration tests alone.
-  This intentionally tightens the original combined-tests-only requirement.
-- CI additionally instruments the backend exercised by Playwright, merges that
-  coverage with backend unit/integration coverage and gates the combined result.
-  The Playwright contribution need not separately reach 80%.
-- Exclude generated code only; do not broadly exclude DTOs, configuration or
-  difficult code. Publish line and branch coverage reports; branch coverage has
-  no agreed blocking percentage.
-- PIT measures mutation-test effectiveness, not line coverage, and is outside
-  S7's required implementation. Configuring Sonar in the pipeline remains out of
-  scope for S14. FindBugs/SpotBugs is not an additional required check suite.
-
-
-## Implemented checks and manual review
-
-Checkstyle **12.3.1**, PMD/CPD **7.28.0**, and JaCoCo **0.8.14** are pinned.
-`tooling/standards/checkstyle.xml` selects individual naming, structure, import and brace checks; no general analysis bundle is enabled.
-`tooling/standards/src/main/java/Standards.java` supplies the targeted measurements.
-ArchUnit remains in the backend test suite for architectural boundaries.
-
-PMD uses Java 25, the running JDK's `jrt-fs.jar`, compiled backend classes and the
-resolved test dependency classpath. Cyclomatic complexity uses PMD's default
-options: boolean paths count, assertions do not. Decisions include if/loops,
-catch, ternary and throw; non-default switch alternatives count individually,
-including comma-separated labels. There is no aggregate class-complexity gate.
-Cognitive complexity uses PMD's boolean-operation sequences, nesting, switch,
-recursion and flow rules. The scoped visitors retain those algorithms while
-including lambdas in their enclosing executable and excluding nested/local type
-bodies, whose methods are measured independently. Compact record constructors
-use the same visitors and start with cyclomatic complexity one.
-
-Custom checks measure physical code lines from regular parser tokens, including
-brace/declaration lines and mixed code/comment lines. They count multiline literal
-lines while excluding physically blank lines. Class length excludes nested-type
-tokens, preserving lines shared with enclosing code. Other custom measurements
-implement the definitions above: nesting, resolved type fan-out, project-owned
-superclass depth, public non-accessor methods, and injected collaborators.
-Injection includes inherited fields/setters, explicit `@Inject` constructors,
-single constructors on bean classes, records' implicit canonical constructors,
-and Lombok required/all-argument constructor injection. Qualifier keys use resolved
-annotation names and values, including defaults; repeat sites are deduplicated.
-The CPD configuration preserves identifiers/literals, uses 100 tokens and disables
-skip blocks. Its line-location union counts overlapping occurrences only once.
-
-Checkstyle and targeted checks enforce import/brace/naming/visibility rules,
-`@Override`, visible constructor/cast/new-array `var` initializer forms, final parameters, locals (including
-loops/catches and lambdas) and initialized fields. PMD's three selected finality
-rules additionally cover control-flow assignment and private constructor-initialized
-fields. Framework/lifecycle requirements, generated Lombok setters, and external
-writes to public/protected fields need review before changing field finality.
-No tool can infer whether a comment explains intent, whether a public contract
-needs Javadoc, whether a record is appropriate, or whether mutable components are
-sufficiently protected. These are **manual rules**, as are ambiguous type inference
-and architecture/DI design decisions. Review all `DESIGN` record-component entries
-and `REVIEW` signals, even when a build passes, using `docs/backend-review.md`.
-
-Reports never rewrite Java. Formatter application remains S8's separate validate
-execution. Generated output under `target` and generated source directories are
-outside the handwritten `src/main/java` and `src/test/java` scope. No maintained
-file, DTO, configuration class or package is excluded from standards or coverage.
-JaCoCo filters compiler/Lombok-generated members; no handwritten-code exclusions
-are configured. Line and branch results are published, with only lines gated.
-
-Exact metric waivers live in `tooling/standards/waivers.tsv`; each records a metric,
-fully resolved executable signature (or class), exact retained value and the
-maintainer agreement/reason. No wildcard waivers are allowed, and a changed value
-fails again. A waived blocking result remains visible as `WAIVER`. PMD suppression
-annotations/comments cannot silently waive a rule. The only approved waiver is the eight-parameter `Group` canonical constructor,
-which preserves its JSON contract while defensively copying both lists. Adding a waiver always requires maintainer agreement.
-
-## Commands and reports
-
-Run from the root with JDK 25:
-
-```sh
-mvn -Dformat.mode=check clean verify
-# Prepare standalone analysis without running tests:
-mvn -pl agiledancers-be test-compile dependency:build-classpath@standards-classpath
-mvn -f tooling/standards/pom.xml test exec:java
-# Exact local coverage gate after a test/report build:
-java tooling/coverage/Coverage.java agiledancers-be/target/site/jacoco/jacoco.xml
-```
-
-`verify` runs backend tests, builds resolved analysis inputs, generates JaCoCo
-reports, runs checker regression tests and standards analysis, then gates exact
-module-wide line coverage. `compile` and `test` retain existing formatting behavior
-and do not run the verify-only standards checks. Standalone analysis requires its
-classpath preparation; unresolved types fail with the path and preparation advice.
-
-Full metrics and findings: `agiledancers-be/target/standards/report.txt`.
-Checker regression results: `tooling/standards/target/surefire-reports`.
-Coverage HTML/XML/CSV: `agiledancers-be/target/site/jacoco` (local backend tests)
-and `agiledancers-be/target/site/jacoco-combined` (merged browser contribution).
-The gate compares integer line counts (`5 * covered >= 4 * total`), rejecting an
-empty report and percentages that would round up to 80%.
-
-CI first passes local verify. It mounts the pinned JaCoCo agent into its disposable
-backend test container, exposes the agent only on the isolated Docker network,
-and uses the pinned CLI to dump `target/playwright.exec` after Playwright. A missing
-or empty dump fails. The following commands merge both datasets and gate the result
-before the verified-commit marker can authorize publication:
-
-```sh
-mvn -pl agiledancers-be jacoco:merge@combined jacoco:report@combined-report exec:exec@combined-coverage
-```
-
-CI retains both coverage reports, execution data, standards findings and regression
-results with its usual diagnostics artifacts. The agent is mounted only for tests;
-published images contain no agent. PIT and Sonar configuration remain outside S7.
-See `specs/S7-validation.md` for migration evidence and retained-signal assessment.

Dockerfile

@@ -2,11 +2,17 @@ FROM maven:3.9-eclipse-temurin-25 AS build
 WORKDIR /workspace
 COPY pom.xml ./
 COPY .mvn .mvn
+COPY generated generated
 COPY tooling tooling
-COPY ci ci
+COPY engineering.properties engineering.properties
 COPY agiledancers-be/pom.xml agiledancers-be/pom.xml
 COPY agiledancers-be/src agiledancers-be/src
-RUN mvn -B -ntp clean verify
+# Source builds run the same PostgreSQL tests as local/CI verification.
+# Supply connection configuration as BuildKit secrets, which are not retained in image layers.
+RUN --mount=type=secret,id=database_url,env=QUARKUS_DATASOURCE_JDBC_URL,required=true \
+    --mount=type=secret,id=database_user,env=QUARKUS_DATASOURCE_USERNAME,required=true \
+    --mount=type=secret,id=database_password,env=QUARKUS_DATASOURCE_PASSWORD,required=true \
+    mvn -B -ntp clean verify
 
 FROM eclipse-temurin:25-jre AS runtime
 WORKDIR /app

README.md

@@ -1,3 +1,18 @@
+# Landscape and shared engineering
+
+Architecture decisions, specifications and project onboarding are maintained in
+[landscape](http://192.168.2.28:3000/wanjakrah/landscape). Shared agent skills are maintained in landscape/skills/. Reusable tooling,
+standards and the project generator are maintained in
+[engineering](http://192.168.2.28:3000/wanjakrah/engineering).
+
+This project commits the engineering version recorded in `engineering.lock.json`
+under `generated/`. Ordinary builds need no other repository checkout. Regenerate
+with `mvn -N -Pregenerate-engineering validate`; CI checks the selected tag and
+commit with `python3 scripts/engineering.py --check`. To upgrade, update both tag
+and commit, follow engineering's UPGRADING.md, regenerate and review the diff.
+Project configuration in `engineering.properties`, workflows and `deploy/` remains
+application-owned. Read CODING_STANDARDS.md and AGENTS.md for project guidance.
+
 # agiledancers
 
 To map dance groups to performance days. The backend runs on Quarkus with Java 25.
@@ -19,14 +34,19 @@ mvn -pl agiledancers-be quarkus:dev
 Run the packaged application after building:
 
 ```sh
+# Set DATABASE_URL, DATABASE_USER and DATABASE_PASSWORD first.
 java -jar agiledancers-be/target/quarkus-app/quarkus-run.jar
 ```
 
-Build and run a Docker container from the repository root (only Docker is required):
+Build a Docker container against an isolated test database (see [connection setup](docs/persistent-storage.md)):
 
 ```sh
-docker build -t agiledancers .
+docker build --network=host \
-docker run --rm --name agiledancers -p 8080:8080 agiledancers
+  --secret id=database_url,env=TEST_DATABASE_URL \
+  --secret id=database_user,env=TEST_DATABASE_USER \
+  --secret id=database_password,env=TEST_DATABASE_PASSWORD -t agiledancers .
+docker run --rm --name agiledancers -p 8080:8080 \
+  -e DATABASE_URL -e DATABASE_USER -e DATABASE_PASSWORD agiledancers
 ```
 
 The Docker build compiles the application and runs the tests in a Maven build stage,
@@ -42,7 +62,13 @@ curl --fail http://localhost:8080/q/health/ready
 Quarkus configuration can be overridden with environment variables, for example
 `docker run --rm -e QUARKUS_HTTP_PORT=9090 -p 9090:9090 agiledancers`.
 
-The REST API uses shared in-memory storage; data is lost when the process stops.
+PostgreSQL stores all school data, planning state and the latest scheduling run
+through JPA/Hibernate ORM. Persistence entities remain in the repository layer.
+Flyway initializes and versions the schema. Production requires `DATABASE_URL`
+(a JDBC PostgreSQL URL), `DATABASE_USER` and `DATABASE_PASSWORD`; missing credentials,
+connection failures and migration failures prevent startup. See
+[database setup and transition](docs/persistent-storage.md) before replacing an
+in-memory release: export every school before stopping it.
 
 Architecture checks run with the normal test suite, or separately with:
 
@@ -56,7 +82,7 @@ mvn -pl agiledancers-be -Dtest=ArchitectureTest test
 | --- | --- | --- |
 | `model` | Domain entities and specifications | Model |
 | `service` | Application use cases and future ports | Model, repositories |
-| `repository` | Current in-memory persistence | Model |
+| `repository` | JPA/Hibernate entities, repositories and transaction boundaries | Model |
 | `rest` | Future REST services | Services, model |
 | `solver` | Future OR-Tools calculations | Services (ports), model |
 
@@ -175,8 +201,9 @@ recover current state on reconnection rather than requiring event replay. The
 production proxy disables buffering. The UI shows phase, elapsed time, solution
 discovery and final objective scores, and reports completion in an application-wide
 snackbar. Reloading recovers the latest state without replaying old notifications.
-Run state currently shares the application's in-memory lifetime; durable restart
+The latest run and saved assignments survive restart. Startup marks formerly
-recovery requires the PostgreSQL integration specified in S16.
+running calculations `INTERRUPTED`, preserves the previous assignments, and allows
+a new run. Results and successful status commit in one database transaction.
 
 `PUT .../shows/{showId}/assignments` accepts `{"assignments":[[1,2],[3]]}`, an
 ordered list of group IDs per daypart. Incomplete or invalid drafts can be saved;
@@ -281,13 +308,13 @@ for the current operational status.
 Production releases and rollback use separate manual Gitea workflows. See the
 [deployment runbook](docs/production-deployment.md) for Synology provisioning,
 semantic version tags, release/retry/rollback and the accepted data-loss limitation
-until S16, and [S6 evidence](docs/s6-validation.md) for deployment readiness.
+during the one-time transition from an in-memory release, and [S6 evidence](docs/s6-validation.md) for deployment readiness.
 
 ### Java formatting (S8)
 
 Maven is the authoritative formatting path. The root build runs the actual
 Palantir Java Format **2.101.0**, Palantir style, through a custom OpenRewrite
-**8.63.4** text recipe in `tooling/format/Format.java`. The pinned
+**8.63.4** text recipe in `generated/tooling/format/Format.java`. The pinned
 `exec-maven-plugin` **3.6.3** launches that helper with JDK 25. Native import
 ordering and unused-import removal are enabled; extra Javadoc formatting is off.
 No OpenRewrite AutoFormat or additional refactoring recipes run.
@@ -332,9 +359,9 @@ format-on-save must not override Maven's result. Other editors can invoke the
 standalone Maven apply command as an external tool.
 
 Verification and measurements are recorded in
-[the S8 evidence](specs/S8-formatting-evidence.md). Reproduce the isolated failure,
+[the S8 evidence](docs/validation/S8-formatting-evidence.md). Reproduce the isolated failure,
 UTF-8, import, cache and idempotence checks with
-`python3 tooling/format/test.py`, and the sequential end-to-end build measurements
+the formatter integration test in engineering (`python3 tests/format_integration.py`), and the sequential end-to-end build measurements
 with `python3 tooling/format/benchmark.py` (requires the ordinary backend test
 prerequisites). Results are written under `target/`.
 
@@ -345,4 +372,19 @@ It defines the agreed rules, exact metric limits, manual review duties, pinned
 analysis tools, coverage policy and standalone commands. `mvn verify` runs standards
 checks and requires at least 80% module-wide backend line coverage. CI also collects
 and merges coverage from Playwright before publication. Reports are retained with
-CI diagnostics. See [S7 validation](specs/S7-validation.md) for current migration status.
+CI diagnostics. See [S7 validation](docs/validation/S7-validation.md) for current migration status.
+
+
+Existing-school mutations require `X-School-Revision` with the revision loaded by
+the editor. `GET /api/dance-schools/{id}/data` returns the school and all its editor
+data from one consistent snapshot; `school.revision` identifies that snapshot.
+Missing or stale revisions receive `409` with a reload instruction. The import
+preview returns `existingRevision` for replacement confirmation. Creation of a
+new school does not need a revision. The frontend never automatically retries a
+conflicting edit with a newer revision.
+
+
+Domain-to-view projection is generated by MapStruct in `rest.mapping.DomainViewMapper`.
+It is a CDI bean with `unmappedTargetPolicy = ERROR`, so unmatched target fields fail
+compilation. REST resources supply calculated validation results explicitly. The
+entity-to-domain graph mappings remain handwritten in the repository layer.

agiledancers-be/pom.xml

@@ -14,6 +14,11 @@
     <packaging>jar</packaging>
 
     <dependencies>
+        <dependency><groupId>org.mapstruct</groupId><artifactId>mapstruct</artifactId><version>${mapstruct.version}</version></dependency>
+        <dependency><groupId>io.quarkus</groupId><artifactId>quarkus-hibernate-orm</artifactId></dependency>
+        <dependency><groupId>io.quarkus</groupId><artifactId>quarkus-jdbc-postgresql</artifactId></dependency>
+        <dependency><groupId>io.quarkus</groupId><artifactId>quarkus-flyway</artifactId></dependency>
+        <dependency><groupId>org.flywaydb</groupId><artifactId>flyway-database-postgresql</artifactId></dependency>
         <dependency>
             <groupId>io.quarkus</groupId>
             <artifactId>quarkus-rest-jackson</artifactId>
@@ -64,44 +69,54 @@
     <build>
         <plugins>
             <plugin>
-                <groupId>org.apache.maven.plugins</groupId><artifactId>maven-dependency-plugin</artifactId><version>3.8.1</version>
+                <groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId>
+                <configuration>
+                    <annotationProcessorPaths combine.children="append">
+                        <path><groupId>org.mapstruct</groupId><artifactId>mapstruct-processor</artifactId><version>${mapstruct.version}</version></path>
+                        <path><groupId>org.projectlombok</groupId><artifactId>lombok-mapstruct-binding</artifactId><version>${lombok-mapstruct-binding.version}</version></path>
+                    </annotationProcessorPaths>
+                    <compilerArgs><arg>-Amapstruct.suppressGeneratorTimestamp=true</arg></compilerArgs>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId><artifactId>maven-dependency-plugin</artifactId><version>3.11.0</version>
                 <executions><execution><id>standards-classpath</id><phase>prepare-package</phase><goals><goal>build-classpath</goal></goals>
                     <configuration><outputFile>${project.build.directory}/standards-classpath.txt</outputFile></configuration>
                 </execution>
                 <execution><id>coverage-tools</id><phase>prepare-package</phase><goals><goal>copy</goal></goals>
                     <configuration><artifactItems>
-                        <artifactItem><groupId>org.jacoco</groupId><artifactId>org.jacoco.agent</artifactId><version>0.8.14</version><classifier>runtime</classifier><destFileName>agent.jar</destFileName></artifactItem>
+                        <artifactItem><groupId>org.jacoco</groupId><artifactId>org.jacoco.agent</artifactId><version>0.8.16</version><classifier>runtime</classifier><destFileName>agent.jar</destFileName></artifactItem>
-                        <artifactItem><groupId>org.jacoco</groupId><artifactId>org.jacoco.cli</artifactId><version>0.8.14</version><classifier>nodeps</classifier><destFileName>cli.jar</destFileName></artifactItem>
+                        <artifactItem><groupId>org.jacoco</groupId><artifactId>org.jacoco.cli</artifactId><version>0.8.16</version><classifier>nodeps</classifier><destFileName>cli.jar</destFileName></artifactItem>
                     </artifactItems><outputDirectory>${project.build.directory}/coverage-tools</outputDirectory></configuration>
                 </execution></executions>
             </plugin>
             <plugin>
-                <groupId>org.codehaus.mojo</groupId><artifactId>exec-maven-plugin</artifactId><version>3.6.3</version>
+                <groupId>org.codehaus.mojo</groupId><artifactId>exec-maven-plugin</artifactId><version>3.6.4</version>
                 <executions><execution><id>standards</id><phase>verify</phase><goals><goal>exec</goal></goals>
                     <configuration>
                         <executable>${maven.home}/bin/mvn</executable>
                         <workingDirectory>${maven.multiModuleProjectDirectory}</workingDirectory>
                         <arguments><argument>-B</argument><argument>-ntp</argument><argument>-f</argument>
-                            <argument>${maven.multiModuleProjectDirectory}/tooling/standards/pom.xml</argument>
+                            <argument>${maven.multiModuleProjectDirectory}/generated/tooling/standards/pom.xml</argument>
                             <argument>test</argument><argument>exec:java</argument>
                         </arguments>
                     </configuration>
                 </execution>
                 <execution><id>coverage</id><phase>verify</phase><goals><goal>exec</goal></goals>
                     <configuration><executable>${java.home}/bin/java</executable><arguments>
-                        <argument>${maven.multiModuleProjectDirectory}/tooling/coverage/Coverage.java</argument>
+                        <argument>${maven.multiModuleProjectDirectory}/generated/tooling/coverage/Coverage.java</argument>
                         <argument>${project.build.directory}/site/jacoco/jacoco.xml</argument>
                     </arguments></configuration>
                 </execution>
                 <execution><id>combined-coverage</id><phase>none</phase><goals><goal>exec</goal></goals>
                     <configuration><executable>${java.home}/bin/java</executable><arguments>
-                        <argument>${maven.multiModuleProjectDirectory}/tooling/coverage/Coverage.java</argument>
+                        <argument>${maven.multiModuleProjectDirectory}/generated/tooling/coverage/Coverage.java</argument>
                         <argument>${project.build.directory}/site/jacoco-combined/jacoco.xml</argument>
                     </arguments></configuration>
                 </execution></executions>
             </plugin>
             <plugin>
-                <groupId>org.jacoco</groupId><artifactId>jacoco-maven-plugin</artifactId><version>0.8.14</version>
+                <groupId>org.jacoco</groupId><artifactId>jacoco-maven-plugin</artifactId><version>0.8.16</version>
                 <executions>
                     <execution><id>agent</id><goals><goal>prepare-agent</goal></goals><configuration>
                         <exclClassLoaders>*QuarkusClassLoader</exclClassLoaders><destFile>${project.build.directory}/jacoco.exec</destFile><append>true</append>

agiledancers-be/src/main/java/nl/agilecc/agiledancers/model/DanceSchool.java

@@ -20,6 +20,9 @@ public class DanceSchool extends AbstractEntity {
     @Setter
     private String name;
 
+    @Setter
+    private long revision;
+
     @Builder.Default
     private final Set<Dancer> dancers = new LinkedHashSet<>();
 

agiledancers-be/src/main/java/nl/agilecc/agiledancers/model/scheduling/SchedulingRun.java

@@ -1,10 +1,7 @@
-package nl.agilecc.agiledancers.service.model;
+package nl.agilecc.agiledancers.model.scheduling;
 
 import java.time.Instant;
 import java.util.UUID;
-import nl.agilecc.agiledancers.model.scheduling.SchedulingPhase;
-import nl.agilecc.agiledancers.model.scheduling.SchedulingProgress;
-import nl.agilecc.agiledancers.model.scheduling.SchedulingSummary;
 
 /** Latest immutable state for one show's calculation; runId identifies notifications across reconnects. */
 public record SchedulingRun(
@@ -24,7 +21,7 @@ public record SchedulingRun(
                 schoolId,
                 showId,
                 name,
-                Instant.now(),
+                Instant.now().truncatedTo(java.time.temporal.ChronoUnit.MICROS),
                 null,
                 SchedulingState.RUNNING,
                 new SchedulingProgress(SchedulingPhase.PREPARING, false),
@@ -54,7 +51,7 @@ public record SchedulingRun(
                 showId,
                 showName,
                 startedAt,
-                Instant.now(),
+                Instant.now().truncatedTo(java.time.temporal.ChronoUnit.MICROS),
                 outcome,
                 new SchedulingProgress(progress.phase(), progress.feasible() || scores != null),
                 explanation,

agiledancers-be/src/main/java/nl/agilecc/agiledancers/model/scheduling/SchedulingState.java

@@ -1,7 +1,8 @@
-package nl.agilecc.agiledancers.service.model;
+package nl.agilecc.agiledancers.model.scheduling;
 
 public enum SchedulingState {
     RUNNING,
+    INTERRUPTED,
     OPTIMAL,
     VALID,
     STALE,

agiledancers-be/src/main/java/nl/agilecc/agiledancers/repository/AbstractRepository.java

@@ -7,11 +7,19 @@ import nl.agilecc.agiledancers.model.AbstractEntity;
 
 public abstract class AbstractRepository<T extends AbstractEntity> {
     private long sequence = 0L;
+    private java.util.function.LongSupplier identifiers;
 
     protected final Map<Long, T> entities = new LinkedHashMap<>();
 
     public long nextId() {
-        return sequence++;
+        return identifiers == null ? sequence++ : identifiers.getAsLong();
+    }
+
+    /** Replaces detached transaction state; production identifiers come from PostgreSQL. */
+    public void load(final java.util.Collection<T> values, final java.util.function.LongSupplier identifiers) {
+        entities.clear();
+        values.forEach((final T entity) -> entities.put(entity.getId(), entity));
+        this.identifiers = identifiers;
     }
 
     public T add(final T entity) {

agiledancers-be/src/main/java/nl/agilecc/agiledancers/repository/Database.java

@@ -0,0 +1,113 @@
+package nl.agilecc.agiledancers.repository;
+
+import jakarta.inject.Inject;
+import jakarta.inject.Singleton;
+import jakarta.persistence.EntityManager;
+import jakarta.persistence.LockModeType;
+import jakarta.persistence.OptimisticLockException;
+import jakarta.persistence.PersistenceException;
+import jakarta.transaction.Status;
+import jakarta.transaction.TransactionManager;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.concurrent.Callable;
+import nl.agilecc.agiledancers.repository.entity.EntityIdentifiers;
+
+/** Owns short JTA units of work; Hibernate flushes before commit and publication follows durable commit. */
+@Singleton
+public class Database {
+    private final EntityManager entities;
+    private final TransactionManager manager;
+    private final ThreadLocal<List<Runnable>> committed = new ThreadLocal<>();
+    private final ThreadLocal<List<Runnable>> rolledBack = new ThreadLocal<>();
+
+    @Inject
+    public Database(final EntityManager entities, final TransactionManager manager) {
+        this.entities = entities;
+        this.manager = manager;
+    }
+
+    /**
+     * Runs work in a new transaction, or joins the current JTA transaction. Callback registration is supported only
+     * inside transactions started by this instance. Commit callbacks run in registration order after durable commit;
+     * their exceptions propagate to the caller without rolling back committed work or running remaining callbacks.
+     * Rollback callbacks run before the original failure is rethrown; a callback exception replaces that failure.
+     */
+    public <T> T transaction(final Callable<T> work) throws Exception {
+        try {
+            if (manager.getStatus() != Status.STATUS_NO_TRANSACTION) {
+                return work.call();
+            }
+            return outerTransaction(work);
+        } catch (final OptimisticLockException failure) {
+            throw new RevisionConflictException();
+        } catch (final PersistenceException
+                | jakarta.transaction.SystemException
+                | jakarta.transaction.RollbackException
+                | jakarta.transaction.HeuristicMixedException
+                | jakarta.transaction.HeuristicRollbackException
+                | jakarta.transaction.NotSupportedException failure) {
+            if (optimisticConflict(failure)) {
+                throw new RevisionConflictException();
+            }
+            System.getLogger(Database.class.getName())
+                    .log(System.Logger.Level.WARNING, "JPA transaction failed", failure);
+            throw new StorageException(failure);
+        }
+    }
+
+    private static boolean optimisticConflict(final Throwable failure) {
+        for (Throwable cause = failure; cause != null; cause = cause.getCause()) {
+            if (cause instanceof OptimisticLockException) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    private <T> T outerTransaction(final Callable<T> work) throws Exception {
+        final List<Runnable> publications = new ArrayList<>();
+        manager.begin();
+        committed.set(publications);
+        rolledBack.set(new ArrayList<>());
+        final T result;
+        try {
+            result = work.call();
+            manager.commit();
+        } catch (final Exception | Error failure) {
+            rollback(failure);
+            rolledBack.get().forEach(Runnable::run);
+            throw failure;
+        } finally {
+            committed.remove();
+            rolledBack.remove();
+        }
+        publications.forEach(Runnable::run);
+        return result;
+    }
+
+    private void rollback(final Throwable failure) {
+        try {
+            if (manager.getStatus() != Status.STATUS_NO_TRANSACTION) {
+                manager.rollback();
+            }
+        } catch (final jakarta.transaction.SystemException rollbackFailure) {
+            failure.addSuppressed(rollbackFailure);
+        }
+    }
+
+    /** Registers a callback on this thread's transaction owned by this instance; see {@link #transaction(Callable)}. */
+    public void afterCommit(final Runnable action) {
+        committed.get().add(action);
+    }
+
+    /** Registers a rollback callback under the same ownership requirement as {@link #afterCommit(Runnable)}. */
+    public void afterRollback(final Runnable action) {
+        rolledBack.get().add(action);
+    }
+
+    public long nextId() {
+        return entities.find(EntityIdentifiers.class, 1, LockModeType.PESSIMISTIC_WRITE)
+                .claim();
+    }
+}

agiledancers-be/src/main/java/nl/agilecc/agiledancers/repository/GroupMapping.java

@@ -0,0 +1,62 @@
+package nl.agilecc.agiledancers.repository;
+
+import java.util.LinkedHashMap;
+import java.util.LinkedHashSet;
+import java.util.Map;
+import nl.agilecc.agiledancers.model.Coach;
+import nl.agilecc.agiledancers.model.DanceGroup;
+import nl.agilecc.agiledancers.model.DanceSchool;
+import nl.agilecc.agiledancers.model.Dancer;
+import nl.agilecc.agiledancers.repository.entity.CoachEntity;
+import nl.agilecc.agiledancers.repository.entity.GroupEntity;
+import nl.agilecc.agiledancers.repository.entity.SchoolEntity;
+import nl.agilecc.agiledancers.repository.entity.SchoolMemberId;
+
+public class GroupMapping {
+    public static Map<Long, DanceGroup> groups(
+            final SchoolEntity stored,
+            final DanceSchool school,
+            final Map<Long, Coach> coaches,
+            final Map<Long, Dancer> dancers) {
+        final Map<Long, DanceGroup> result = new LinkedHashMap<>();
+        for (final GroupEntity entity : stored.getGroups()) {
+            final DanceGroup group = DanceGroup.builder()
+                    .category(entity.getCategory())
+                    .type(entity.getType())
+                    .startAge(entity.getStartAge())
+                    .endAge(entity.getEndAge())
+                    .coach(
+                            entity.getCoach() == null
+                                    ? null
+                                    : coaches.get(entity.getCoach().getId().getLocalId()))
+                    .styles(new LinkedHashSet<>(entity.getStyles()))
+                    .build();
+            group.setId(entity.getId().getLocalId());
+            entity.getDancerIds().stream().sorted().forEach((final Long id) -> group.addDancer(dancers.get(id)));
+            school.addDanceGroup(group);
+            result.put(group.getId(), group);
+        }
+        return result;
+    }
+
+    public static GroupEntity group(final SchoolEntity school, final DanceGroup group) {
+        final GroupEntity entity = new GroupEntity();
+        entity.setId(new SchoolMemberId(school.getId(), group.getId()));
+        entity.setSchool(school);
+        entity.setCategory(group.getCategory());
+        entity.setType(group.getType());
+        entity.setStartAge(group.getStartAge());
+        entity.setEndAge(group.getEndAge());
+        if (group.getCoach() != null) {
+            entity.setCoach(school.getCoaches().stream()
+                    .filter((final CoachEntity coach) ->
+                            coach.getId().getLocalId() == group.getCoach().getId())
+                    .findFirst()
+                    .orElseThrow());
+        }
+        entity.setStyles(new LinkedHashSet<>(group.getStyles()));
+        group.getDancers()
+                .forEach((final Dancer dancer) -> entity.getDancerIds().add(dancer.getId()));
+        return entity;
+    }
+}

agiledancers-be/src/main/java/nl/agilecc/agiledancers/repository/PeopleMapping.java

@@ -0,0 +1,70 @@
+package nl.agilecc.agiledancers.repository;
+
+import java.util.LinkedHashMap;
+import java.util.Map;
+import nl.agilecc.agiledancers.model.Coach;
+import nl.agilecc.agiledancers.model.DanceSchool;
+import nl.agilecc.agiledancers.model.Dancer;
+import nl.agilecc.agiledancers.repository.entity.CoachEntity;
+import nl.agilecc.agiledancers.repository.entity.DancerEntity;
+import nl.agilecc.agiledancers.repository.entity.SchoolEntity;
+import nl.agilecc.agiledancers.repository.entity.SchoolMemberId;
+
+/** Converts people while preserving the shared dancer identity used by coach links. */
+public class PeopleMapping {
+    public static Map<Long, Dancer> dancers(final SchoolEntity stored, final DanceSchool school) {
+        final Map<Long, Dancer> result = new LinkedHashMap<>();
+        for (final DancerEntity person : stored.getDancers()) {
+            final Dancer dancer = Dancer.builder()
+                    .name(person.getName())
+                    .birthDate(person.getBirthDate())
+                    .build();
+            dancer.setId(person.getId().getLocalId());
+            school.addDancer(dancer);
+            result.put(dancer.getId(), dancer);
+        }
+        return result;
+    }
+
+    public static Map<Long, Coach> coaches(
+            final SchoolEntity stored, final DanceSchool school, final Map<Long, Dancer> dancers) {
+        final Map<Long, Coach> result = new LinkedHashMap<>();
+        for (final CoachEntity trainer : stored.getCoaches()) {
+            final Coach coach = Coach.builder()
+                    .name(trainer.getName())
+                    .dancer(
+                            trainer.getDancer() == null
+                                    ? null
+                                    : dancers.get(trainer.getDancer().getId().getLocalId()))
+                    .build();
+            coach.setId(trainer.getId().getLocalId());
+            school.addCoach(coach);
+            result.put(coach.getId(), coach);
+        }
+        return result;
+    }
+
+    public static DancerEntity dancer(final SchoolEntity school, final Dancer dancer) {
+        final DancerEntity entity = new DancerEntity();
+        entity.setId(new SchoolMemberId(school.getId(), dancer.getId()));
+        entity.setSchool(school);
+        entity.setName(dancer.getName());
+        entity.setBirthDate(dancer.getBirthDate());
+        return entity;
+    }
+
+    public static CoachEntity coach(final SchoolEntity school, final Coach coach) {
+        final CoachEntity entity = new CoachEntity();
+        entity.setId(new SchoolMemberId(school.getId(), coach.getId()));
+        entity.setSchool(school);
+        entity.setName(coach.getName());
+        if (coach.getDancer() != null) {
+            entity.setDancer(school.getDancers().stream()
+                    .filter((final DancerEntity dancer) ->
+                            dancer.getId().getLocalId() == coach.getDancer().getId())
+                    .findFirst()
+                    .orElseThrow());
+        }
+        return entity;
+    }
+}

agiledancers-be/src/main/java/nl/agilecc/agiledancers/repository/RevisionConflictException.java

@@ -0,0 +1,8 @@
+package nl.agilecc.agiledancers.repository;
+
+/** An optimistic persistence conflict requires a new editor snapshot, never an automatic retry. */
+public class RevisionConflictException extends RuntimeException {
+    public RevisionConflictException() {
+        super("Deze school is gewijzigd. Herlaad de gegevens en probeer opnieuw.");
+    }
+}

agiledancers-be/src/main/java/nl/agilecc/agiledancers/repository/RunRepository.java

@@ -0,0 +1,78 @@
+package nl.agilecc.agiledancers.repository;
+
+import jakarta.inject.Inject;
+import jakarta.inject.Singleton;
+import jakarta.persistence.EntityManager;
+import java.util.List;
+import nl.agilecc.agiledancers.model.scheduling.SchedulingProgress;
+import nl.agilecc.agiledancers.model.scheduling.SchedulingRun;
+import nl.agilecc.agiledancers.model.scheduling.SchedulingState;
+import nl.agilecc.agiledancers.model.scheduling.SchedulingSummary;
+import nl.agilecc.agiledancers.repository.entity.RunEntity;
+import nl.agilecc.agiledancers.repository.entity.SchoolMemberId;
+
+@Singleton
+public class RunRepository {
+    private final EntityManager entities;
+
+    @Inject
+    public RunRepository(final EntityManager entities) {
+        this.entities = entities;
+    }
+
+    public List<SchedulingRun> load() {
+        return entities
+                .createQuery("from StoredRun run order by run.id.schoolId,run.id.localId", RunEntity.class)
+                .getResultList()
+                .stream()
+                .map(this::read)
+                .toList();
+    }
+
+    public void recover() {
+        load().stream()
+                .filter((final SchedulingRun run) -> run.state() == SchedulingState.RUNNING)
+                .forEach((final SchedulingRun run) -> save(run.completed(
+                        SchedulingState.INTERRUPTED,
+                        "Berekening onderbroken door een backendherstart. Geen nieuw resultaat toegepast; bestaande"
+                                + " indeling behouden. Start de berekening opnieuw.",
+                        null)));
+    }
+
+    public void save(final SchedulingRun run) {
+        final RunEntity entity = new RunEntity();
+        entity.setId(new SchoolMemberId(run.schoolId(), run.showId()));
+        entity.setRunId(run.runId());
+        entity.setShowName(run.showName());
+        entity.setStartedAt(run.startedAt());
+        entity.setFinishedAt(run.finishedAt());
+        entity.setState(run.state());
+        entity.setPhase(run.progress().phase());
+        entity.setFeasible(run.progress().feasible());
+        entity.setMessage(run.message());
+        if (run.summary() != null) {
+            entity.setAttendanceExcess(run.summary().attendanceExcess());
+            entity.setPerformanceSpread(run.summary().performanceSpread());
+            entity.setVarietyPenalty(run.summary().varietyPenalty());
+        }
+        entities.merge(entity);
+    }
+
+    private SchedulingRun read(final RunEntity entity) {
+        final SchedulingSummary summary = entity.getAttendanceExcess() == null
+                ? null
+                : new SchedulingSummary(
+                        entity.getAttendanceExcess(), entity.getPerformanceSpread(), entity.getVarietyPenalty());
+        return new SchedulingRun(
+                entity.getRunId(),
+                entity.getId().getSchoolId(),
+                entity.getId().getLocalId(),
+                entity.getShowName(),
+                entity.getStartedAt(),
+                entity.getFinishedAt(),
+                entity.getState(),
+                new SchedulingProgress(entity.getPhase(), entity.isFeasible()),
+                entity.getMessage(),
+                summary);
+    }
+}

agiledancers-be/src/main/java/nl/agilecc/agiledancers/repository/SchoolReader.java

@@ -0,0 +1,47 @@
+package nl.agilecc.agiledancers.repository;
+
+import jakarta.inject.Inject;
+import jakarta.inject.Singleton;
+import jakarta.persistence.EntityManager;
+import java.util.List;
+import java.util.Map;
+import nl.agilecc.agiledancers.model.Coach;
+import nl.agilecc.agiledancers.model.DanceGroup;
+import nl.agilecc.agiledancers.model.DanceSchool;
+import nl.agilecc.agiledancers.model.Dancer;
+import nl.agilecc.agiledancers.repository.entity.SchoolEntity;
+import nl.agilecc.agiledancers.repository.entity.ShowEntity;
+
+/** Exposes detached domain snapshots, keeping Hibernate sessions and lazy collections inside the adapter. */
+@Singleton
+public class SchoolReader {
+    private final EntityManager entities;
+
+    @Inject
+    public SchoolReader(final EntityManager entities) {
+        this.entities = entities;
+    }
+
+    public List<DanceSchool> load() {
+        return entities
+                .createQuery("from StoredSchool school order by school.id", SchoolEntity.class)
+                .getResultList()
+                .stream()
+                .map(this::school)
+                .toList();
+    }
+
+    private DanceSchool school(final SchoolEntity entity) {
+        final DanceSchool school = DanceSchool.builder()
+                .key(entity.getKey())
+                .name(entity.getName())
+                .revision(entity.getRevision())
+                .build();
+        school.setId(entity.getId());
+        final Map<Long, Dancer> dancers = PeopleMapping.dancers(entity, school);
+        final Map<Long, Coach> coaches = PeopleMapping.coaches(entity, school, dancers);
+        final Map<Long, DanceGroup> groups = GroupMapping.groups(entity, school, coaches, dancers);
+        entity.getShows().forEach((final ShowEntity show) -> school.addShow(ShowMapping.show(show, groups)));
+        return school;
+    }
+}

agiledancers-be/src/main/java/nl/agilecc/agiledancers/repository/SchoolWriter.java

@@ -0,0 +1,82 @@
+package nl.agilecc.agiledancers.repository;
+
+import jakarta.inject.Inject;
+import jakarta.inject.Singleton;
+import jakarta.persistence.EntityManager;
+import jakarta.persistence.LockModeType;
+import java.util.List;
+import nl.agilecc.agiledancers.model.Coach;
+import nl.agilecc.agiledancers.model.DanceGroup;
+import nl.agilecc.agiledancers.model.DanceSchool;
+import nl.agilecc.agiledancers.model.Dancer;
+import nl.agilecc.agiledancers.model.Show;
+import nl.agilecc.agiledancers.repository.entity.RunEntity;
+import nl.agilecc.agiledancers.repository.entity.SchoolEntity;
+
+/** Hibernate merges the aggregate graph and handles child differences, orphan removal and optimistic versioning. */
+@Singleton
+public class SchoolWriter {
+    private final EntityManager entities;
+
+    @Inject
+    public SchoolWriter(final EntityManager entities) {
+        this.entities = entities;
+    }
+
+    public void checkRevision(final long schoolId, final long expected) {
+        final SchoolEntity school = entities.find(SchoolEntity.class, schoolId, LockModeType.OPTIMISTIC);
+        if (school == null || school.getRevision() != expected) {
+            throw new RevisionConflictException();
+        }
+    }
+
+    public void save(final DanceSchool school) {
+        final SchoolEntity existing = entities.find(SchoolEntity.class, school.getId());
+        final SchoolEntity graph = graph(school);
+        if (existing == null) {
+            entities.persist(graph);
+        } else {
+            removeDeletedRuns(school);
+            graph.setRevision(existing.getRevision());
+            graph.setChangeStamp(existing.getChangeStamp() + 1);
+            entities.merge(graph);
+        }
+        entities.flush();
+    }
+
+    private SchoolEntity graph(final DanceSchool school) {
+        final SchoolEntity graph = new SchoolEntity();
+        graph.setId(school.getId());
+        graph.setKey(school.getKey());
+        graph.setName(school.getName());
+        school.getDancers()
+                .forEach((final Dancer dancer) -> graph.getDancers().add(PeopleMapping.dancer(graph, dancer)));
+        school.getCoaches().forEach((final Coach coach) -> graph.getCoaches().add(PeopleMapping.coach(graph, coach)));
+        school.getDanceGroups()
+                .forEach((final DanceGroup group) -> graph.getGroups().add(GroupMapping.group(graph, group)));
+        school.getShows().forEach((final Show show) -> graph.getShows().add(ShowMapping.show(graph, show)));
+        return graph;
+    }
+
+    private void removeDeletedRuns(final DanceSchool school) {
+        final List<Long> shows = school.getShows().stream().map(Show::getId).toList();
+        entities
+                .createQuery("from StoredRun run where run.id.schoolId=:school", RunEntity.class)
+                .setParameter("school", school.getId())
+                .getResultList()
+                .stream()
+                .filter((final RunEntity run) -> !shows.contains(run.getId().getLocalId()))
+                .forEach(entities::remove);
+    }
+
+    public void delete(final long schoolId) {
+        entities.createQuery("from StoredRun run where run.id.schoolId=:school", RunEntity.class)
+                .setParameter("school", schoolId)
+                .getResultList()
+                .forEach(entities::remove);
+        final SchoolEntity school = entities.find(SchoolEntity.class, schoolId);
+        if (school != null) {
+            entities.remove(school);
+        }
+    }
+}

agiledancers-be/src/main/java/nl/agilecc/agiledancers/repository/ShowMapping.java

@@ -0,0 +1,59 @@
+package nl.agilecc.agiledancers.repository;
+
+import java.util.LinkedHashMap;
+import java.util.Map;
+import nl.agilecc.agiledancers.model.DanceGroup;
+import nl.agilecc.agiledancers.model.DayPart;
+import nl.agilecc.agiledancers.model.Show;
+import nl.agilecc.agiledancers.repository.entity.DayPartEntity;
+import nl.agilecc.agiledancers.repository.entity.DayPartId;
+import nl.agilecc.agiledancers.repository.entity.SchoolEntity;
+import nl.agilecc.agiledancers.repository.entity.SchoolMemberId;
+import nl.agilecc.agiledancers.repository.entity.ShowEntity;
+
+public class ShowMapping {
+    public static Show show(final ShowEntity entity, final Map<Long, DanceGroup> groups) {
+        final Show show = Show.builder()
+                .name(entity.getName())
+                .preferredDayParts(entity.getPreferredDayParts())
+                .finalized(entity.isFinalized())
+                .appearances(Map.copyOf(entity.getAppearances()))
+                .dayParts(entity.getDayParts().stream()
+                        .map((final DayPartEntity part) -> DayPart.builder()
+                                .date(part.getDate())
+                                .type(part.getType())
+                                .danceGroups(part.getGroupIds().stream()
+                                        .map(groups::get)
+                                        .toList())
+                                .build())
+                        .toList())
+                .build();
+        show.setId(entity.getId().getLocalId());
+        return show;
+    }
+
+    public static ShowEntity show(final SchoolEntity school, final Show show) {
+        final ShowEntity entity = new ShowEntity();
+        entity.setId(new SchoolMemberId(school.getId(), show.getId()));
+        entity.setSchool(school);
+        entity.setName(show.getName());
+        entity.setPreferredDayParts(show.getPreferredDayParts());
+        entity.setFinalized(show.isFinalized());
+        entity.setAppearances(new LinkedHashMap<>(show.getAppearances()));
+        for (int index = 0; index < show.getDayParts().size(); index++) {
+            entity.getDayParts().add(part(entity, index, show.getDayParts().get(index)));
+        }
+        return entity;
+    }
+
+    private static DayPartEntity part(final ShowEntity show, final int position, final DayPart part) {
+        final DayPartEntity entity = new DayPartEntity();
+        entity.setId(new DayPartId(show.getId().getSchoolId(), show.getId().getLocalId(), position));
+        entity.setShow(show);
+        entity.setDate(part.getDate());
+        entity.setType(part.getType());
+        part.getDanceGroups()
+                .forEach((final DanceGroup group) -> entity.getGroupIds().add(group.getId()));
+        return entity;
+    }
+}

agiledancers-be/src/main/java/nl/agilecc/agiledancers/repository/StorageException.java

@@ -0,0 +1,8 @@
+package nl.agilecc.agiledancers.repository;
+
+/** Storage failures never authorize an in-memory fallback. */
+public class StorageException extends RuntimeException {
+    public StorageException(final Exception cause) {
+        super("Database niet beschikbaar. De wijziging is niet opgeslagen; herlaad en probeer opnieuw.", cause);
+    }
+}

agiledancers-be/src/main/java/nl/agilecc/agiledancers/repository/entity/CoachEntity.java

@@ -0,0 +1,33 @@
+package nl.agilecc.agiledancers.repository.entity;
+
+import jakarta.persistence.CascadeType;
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.FetchType;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.ManyToOne;
+import jakarta.persistence.Table;
+import lombok.Getter;
+import lombok.Setter;
+
+@Getter
+@Setter
+@Entity(name = "StoredCoach")
+@Table(name = "coach")
+public class CoachEntity extends SchoolMemberEntity {
+    @Column(nullable = false)
+    private String name;
+
+    // The shared school key is read from the owning row; only the linked member ID is writable.
+    @ManyToOne(
+            fetch = FetchType.LAZY,
+            cascade = {CascadeType.MERGE, CascadeType.PERSIST})
+    @org.hibernate.annotations.JoinColumnsOrFormulas({
+        @org.hibernate.annotations.JoinColumnOrFormula(
+                column = @JoinColumn(name = "dancer_id", referencedColumnName = "id")),
+        @org.hibernate.annotations.JoinColumnOrFormula(
+                formula =
+                        @org.hibernate.annotations.JoinFormula(value = "school_id", referencedColumnName = "school_id"))
+    })
+    private DancerEntity dancer;
+}

agiledancers-be/src/main/java/nl/agilecc/agiledancers/repository/entity/DancerEntity.java

@@ -0,0 +1,20 @@
+package nl.agilecc.agiledancers.repository.entity;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.Table;
+import java.time.LocalDate;
+import lombok.Getter;
+import lombok.Setter;
+
+@Getter
+@Setter
+@Entity(name = "StoredDancer")
+@Table(name = "dancer")
+public class DancerEntity extends SchoolMemberEntity {
+    @Column(nullable = false)
+    private String name;
+
+    @Column(name = "birth_date", nullable = false)
+    private LocalDate birthDate;
+}

agiledancers-be/src/main/java/nl/agilecc/agiledancers/repository/entity/DayPartEntity.java

@@ -0,0 +1,56 @@
+package nl.agilecc.agiledancers.repository.entity;
+
+import jakarta.persistence.CollectionTable;
+import jakarta.persistence.Column;
+import jakarta.persistence.ElementCollection;
+import jakarta.persistence.EmbeddedId;
+import jakarta.persistence.Entity;
+import jakarta.persistence.EnumType;
+import jakarta.persistence.Enumerated;
+import jakarta.persistence.FetchType;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.JoinColumns;
+import jakarta.persistence.ManyToOne;
+import jakarta.persistence.OrderColumn;
+import jakarta.persistence.Table;
+import java.time.LocalDate;
+import java.util.ArrayList;
+import java.util.List;
+import lombok.Getter;
+import lombok.Setter;
+import nl.agilecc.agiledancers.model.specifications.DayPartType;
+
+@Getter
+@Setter
+@Entity(name = "StoredDayPart")
+@Table(name = "day_part")
+public class DayPartEntity {
+    @EmbeddedId
+    private DayPartId id;
+
+    @ManyToOne(fetch = FetchType.LAZY)
+    @JoinColumns({
+        @JoinColumn(name = "school_id", referencedColumnName = "school_id", insertable = false, updatable = false),
+        @JoinColumn(name = "show_id", referencedColumnName = "id", insertable = false, updatable = false)
+    })
+    private ShowEntity show;
+
+    @Column(name = "day", nullable = false)
+    private LocalDate date;
+
+    @Enumerated(EnumType.STRING)
+    @Column(name = "part_type", nullable = false)
+    private DayPartType type;
+
+    @ElementCollection
+    @CollectionTable(
+            name = "assignment",
+            joinColumns = {
+                @JoinColumn(name = "school_id", referencedColumnName = "school_id"),
+                @JoinColumn(name = "show_id", referencedColumnName = "show_id"),
+                @JoinColumn(name = "part_position", referencedColumnName = "position")
+            })
+    @OrderColumn(name = "position")
+    @Column(name = "group_id", nullable = false)
+    private List<Long> groupIds = new ArrayList<>();
+}

agiledancers-be/src/main/java/nl/agilecc/agiledancers/repository/entity/DayPartId.java

@@ -0,0 +1,26 @@
+package nl.agilecc.agiledancers.repository.entity;
+
+import jakarta.persistence.Embeddable;
+import java.io.Serializable;
+import lombok.AllArgsConstructor;
+import lombok.EqualsAndHashCode;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+
+@Getter
+@Setter
+@Embeddable
+@AllArgsConstructor
+@NoArgsConstructor
+@EqualsAndHashCode
+public class DayPartId implements Serializable {
+    @jakarta.persistence.Column(name = "school_id")
+    private long schoolId;
+
+    @jakarta.persistence.Column(name = "show_id")
+    private long showId;
+
+    @jakarta.persistence.Column(name = "position")
+    private int position;
+}

agiledancers-be/src/main/java/nl/agilecc/agiledancers/repository/entity/EntityIdentifiers.java

@@ -0,0 +1,24 @@
+package nl.agilecc.agiledancers.repository.entity;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.Id;
+import jakarta.persistence.Table;
+import lombok.Getter;
+import lombok.Setter;
+
+@Getter
+@Setter
+@Entity(name = "EntityIdentifiers")
+@Table(name = "entity_identifiers")
+public class EntityIdentifiers {
+    @Id
+    private int id;
+
+    @Column(name = "next_value", nullable = false)
+    private long nextValue;
+
+    public long claim() {
+        return nextValue++;
+    }
+}

agiledancers-be/src/main/java/nl/agilecc/agiledancers/repository/entity/GroupEntity.java

@@ -0,0 +1,72 @@
+package nl.agilecc.agiledancers.repository.entity;
+
+import jakarta.persistence.CascadeType;
+import jakarta.persistence.CollectionTable;
+import jakarta.persistence.Column;
+import jakarta.persistence.ElementCollection;
+import jakarta.persistence.Entity;
+import jakarta.persistence.EnumType;
+import jakarta.persistence.Enumerated;
+import jakarta.persistence.FetchType;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.ManyToOne;
+import jakarta.persistence.Table;
+import java.util.LinkedHashSet;
+import java.util.Set;
+import lombok.Getter;
+import lombok.Setter;
+import nl.agilecc.agiledancers.model.specifications.DanceGroupStyle;
+import nl.agilecc.agiledancers.model.specifications.DanceGroupType;
+
+@Getter
+@Setter
+@Entity(name = "StoredGroup")
+@Table(name = "dance_group")
+public class GroupEntity extends SchoolMemberEntity {
+    @Column(nullable = false)
+    private String category;
+
+    @Enumerated(EnumType.STRING)
+    @Column(name = "group_type", nullable = false)
+    private DanceGroupType type;
+
+    @Column(name = "start_age", nullable = false)
+    private int startAge;
+
+    @Column(name = "end_age", nullable = false)
+    private int endAge;
+
+    // The shared school key is read from the owning row; only the linked member ID is writable.
+    @ManyToOne(
+            fetch = FetchType.LAZY,
+            cascade = {CascadeType.MERGE, CascadeType.PERSIST})
+    @org.hibernate.annotations.JoinColumnsOrFormulas({
+        @org.hibernate.annotations.JoinColumnOrFormula(
+                column = @JoinColumn(name = "coach_id", referencedColumnName = "id")),
+        @org.hibernate.annotations.JoinColumnOrFormula(
+                formula =
+                        @org.hibernate.annotations.JoinFormula(value = "school_id", referencedColumnName = "school_id"))
+    })
+    private CoachEntity coach;
+
+    @ElementCollection
+    @CollectionTable(
+            name = "group_style",
+            joinColumns = {
+                @JoinColumn(name = "school_id", referencedColumnName = "school_id"),
+                @JoinColumn(name = "group_id", referencedColumnName = "id")
+            })
+    @Enumerated(EnumType.STRING)
+    @Column(name = "style", nullable = false)
+    private Set<DanceGroupStyle> styles = new LinkedHashSet<>();
+
+    @ElementCollection
+    @CollectionTable(
+            name = "group_dancer",
+            joinColumns = {
+                @JoinColumn(name = "school_id", referencedColumnName = "school_id"),
+                @JoinColumn(name = "group_id", referencedColumnName = "id")
+            })
+    @Column(name = "dancer_id", nullable = false)
+    private Set<Long> dancerIds = new LinkedHashSet<>();
+}

agiledancers-be/src/main/java/nl/agilecc/agiledancers/repository/entity/RunEntity.java

@@ -0,0 +1,59 @@
+package nl.agilecc.agiledancers.repository.entity;
+
+import jakarta.persistence.AttributeOverride;
+import jakarta.persistence.Column;
+import jakarta.persistence.EmbeddedId;
+import jakarta.persistence.Entity;
+import jakarta.persistence.EnumType;
+import jakarta.persistence.Enumerated;
+import jakarta.persistence.Table;
+import java.time.Instant;
+import java.util.UUID;
+import lombok.Getter;
+import lombok.Setter;
+import nl.agilecc.agiledancers.model.scheduling.SchedulingPhase;
+import nl.agilecc.agiledancers.model.scheduling.SchedulingState;
+
+@Getter
+@Setter
+@Entity(name = "StoredRun")
+@Table(name = "scheduling_run")
+public class RunEntity {
+    @EmbeddedId
+    @AttributeOverride(name = "localId", column = @Column(name = "show_id"))
+    private SchoolMemberId id;
+
+    @Column(name = "run_id", nullable = false)
+    private UUID runId;
+
+    @Column(name = "show_name", nullable = false)
+    private String showName;
+
+    @Column(name = "started_at", nullable = false)
+    private Instant startedAt;
+
+    @Column(name = "finished_at")
+    private Instant finishedAt;
+
+    @Enumerated(EnumType.STRING)
+    @Column(nullable = false)
+    private SchedulingState state;
+
+    @Enumerated(EnumType.STRING)
+    @Column(nullable = false)
+    private SchedulingPhase phase;
+
+    private boolean feasible;
+
+    @Column(nullable = false)
+    private String message;
+
+    @Column(name = "attendance_excess")
+    private Long attendanceExcess;
+
+    @Column(name = "performance_spread")
+    private Integer performanceSpread;
+
+    @Column(name = "variety_penalty")
+    private Long varietyPenalty;
+}

agiledancers-be/src/main/java/nl/agilecc/agiledancers/repository/entity/SchoolEntity.java

@@ -0,0 +1,52 @@
+package nl.agilecc.agiledancers.repository.entity;
+
+import jakarta.persistence.CascadeType;
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.Id;
+import jakarta.persistence.OneToMany;
+import jakarta.persistence.OrderBy;
+import jakarta.persistence.Table;
+import jakarta.persistence.Version;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.UUID;
+import lombok.Getter;
+import lombok.Setter;
+
+@Getter
+@Setter
+@Entity(name = "StoredSchool")
+@Table(name = "school")
+public class SchoolEntity {
+    @Id
+    private long id;
+
+    @Column(name = "school_key", nullable = false)
+    private UUID key;
+
+    @Column(nullable = false)
+    private String name;
+
+    @Version
+    private long revision;
+    // Marks child-only changes so Hibernate advances the aggregate version exactly once.
+    @Column(name = "change_stamp", nullable = false)
+    private long changeStamp;
+
+    @OneToMany(mappedBy = "school", cascade = CascadeType.ALL, orphanRemoval = true)
+    @OrderBy("id.localId")
+    private List<DancerEntity> dancers = new ArrayList<>();
+
+    @OneToMany(mappedBy = "school", cascade = CascadeType.ALL, orphanRemoval = true)
+    @OrderBy("id.localId")
+    private List<CoachEntity> coaches = new ArrayList<>();
+
+    @OneToMany(mappedBy = "school", cascade = CascadeType.ALL, orphanRemoval = true)
+    @OrderBy("id.localId")
+    private List<GroupEntity> groups = new ArrayList<>();
+
+    @OneToMany(mappedBy = "school", cascade = CascadeType.ALL, orphanRemoval = true)
+    @OrderBy("id.localId")
+    private List<ShowEntity> shows = new ArrayList<>();
+}

agiledancers-be/src/main/java/nl/agilecc/agiledancers/repository/entity/SchoolMemberEntity.java

@@ -0,0 +1,21 @@
+package nl.agilecc.agiledancers.repository.entity;
+
+import jakarta.persistence.EmbeddedId;
+import jakarta.persistence.FetchType;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.ManyToOne;
+import jakarta.persistence.MappedSuperclass;
+import lombok.Getter;
+import lombok.Setter;
+
+@Getter
+@Setter
+@MappedSuperclass
+public abstract class SchoolMemberEntity {
+    @EmbeddedId
+    private SchoolMemberId id;
+
+    @ManyToOne(fetch = FetchType.LAZY)
+    @JoinColumn(name = "school_id", insertable = false, updatable = false)
+    private SchoolEntity school;
+}

agiledancers-be/src/main/java/nl/agilecc/agiledancers/repository/entity/SchoolMemberId.java

@@ -0,0 +1,23 @@
+package nl.agilecc.agiledancers.repository.entity;
+
+import jakarta.persistence.Embeddable;
+import java.io.Serializable;
+import lombok.AllArgsConstructor;
+import lombok.EqualsAndHashCode;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+
+@Getter
+@Setter
+@Embeddable
+@AllArgsConstructor
+@NoArgsConstructor
+@EqualsAndHashCode
+public class SchoolMemberId implements Serializable {
+    @jakarta.persistence.Column(name = "school_id")
+    private long schoolId;
+
+    @jakarta.persistence.Column(name = "id")
+    private long localId;
+}

agiledancers-be/src/main/java/nl/agilecc/agiledancers/repository/entity/ShowEntity.java

@@ -0,0 +1,51 @@
+package nl.agilecc.agiledancers.repository.entity;
+
+import jakarta.persistence.CascadeType;
+import jakarta.persistence.CollectionTable;
+import jakarta.persistence.Column;
+import jakarta.persistence.ElementCollection;
+import jakarta.persistence.Entity;
+import jakarta.persistence.EnumType;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.MapKeyColumn;
+import jakarta.persistence.MapKeyEnumerated;
+import jakarta.persistence.OneToMany;
+import jakarta.persistence.OrderBy;
+import jakarta.persistence.Table;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import lombok.Getter;
+import lombok.Setter;
+import nl.agilecc.agiledancers.model.specifications.DanceGroupType;
+
+@Getter
+@Setter
+@Entity(name = "StoredShow")
+@Table(name = "show")
+public class ShowEntity extends SchoolMemberEntity {
+    @Column(nullable = false)
+    private String name;
+
+    @Column(name = "preferred_day_parts", nullable = false)
+    private int preferredDayParts;
+
+    private boolean finalized;
+
+    @ElementCollection
+    @CollectionTable(
+            name = "show_appearance",
+            joinColumns = {
+                @JoinColumn(name = "school_id", referencedColumnName = "school_id"),
+                @JoinColumn(name = "show_id", referencedColumnName = "id")
+            })
+    @MapKeyEnumerated(EnumType.STRING)
+    @MapKeyColumn(name = "group_type")
+    @Column(name = "appearances", nullable = false)
+    private Map<DanceGroupType, Integer> appearances = new LinkedHashMap<>();
+
+    @OneToMany(mappedBy = "show", cascade = CascadeType.ALL, orphanRemoval = true)
+    @OrderBy("id.position")
+    private List<DayPartEntity> dayParts = new ArrayList<>();
+}

agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/CoachResource.java

@@ -15,29 +15,33 @@ import jakarta.ws.rs.core.MediaType;
 import java.util.List;
 import nl.agilecc.agiledancers.rest.apimodel.CoachRequest;
 import nl.agilecc.agiledancers.rest.apimodel.CoachView;
+import nl.agilecc.agiledancers.rest.mapping.DomainViewMapper;
 import nl.agilecc.agiledancers.service.CoachLinks;
 
+@SchoolTransactionBoundary
 @Path("/api/dance-schools/{schoolId}/coaches")
 @Produces(MediaType.APPLICATION_JSON)
 @Consumes(MediaType.APPLICATION_JSON)
 public class CoachResource {
+    private @Inject DomainViewMapper views;
+
     private @Inject CoachLinks links;
     private @PathParam("schoolId") long schoolId;
 
     @GET
     public List<CoachView> list() {
-        return links.list(schoolId).stream().map(CoachView::of).toList();
+        return links.list(schoolId).stream().map(views::coach).toList();
     }
 
     @POST
     public CoachView create(final @NotNull @Valid CoachRequest request) {
-        return CoachView.of(links.link(schoolId, null, request.dancerId()));
+        return views.coach(links.link(schoolId, null, request.dancerId()));
     }
 
     @PUT
     @Path("/{id}")
     public CoachView link(final @PathParam("id") long id, final @NotNull @Valid CoachRequest request) {
-        return CoachView.of(links.link(schoolId, id, request.dancerId()));
+        return views.coach(links.link(schoolId, id, request.dancerId()));
     }
 
     @DELETE

agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/DanceGroupResource.java

@@ -19,26 +19,30 @@ import java.util.List;
 import nl.agilecc.agiledancers.model.DanceGroup;
 import nl.agilecc.agiledancers.rest.apimodel.GroupRequest;
 import nl.agilecc.agiledancers.rest.apimodel.GroupView;
+import nl.agilecc.agiledancers.rest.mapping.DomainViewMapper;
 import nl.agilecc.agiledancers.service.SchoolManagementService;
 import nl.agilecc.agiledancers.service.model.GroupDetails;
 
+@SchoolTransactionBoundary
 @Path("/api/dance-schools/{schoolId}/dance-groups")
 @Produces(MediaType.APPLICATION_JSON)
 @Consumes(MediaType.APPLICATION_JSON)
 public class DanceGroupResource {
+    private @Inject DomainViewMapper views;
+
     private @Inject SchoolManagementService service;
 
     private @PathParam("schoolId") long schoolId;
 
     @GET
     public List<GroupView> list() {
-        return service.groups(schoolId).stream().map(GroupView::of).toList();
+        return service.groups(schoolId).stream().map(views::group).toList();
     }
 
     @GET
     @Path("/{id}")
     public GroupView get(final @PathParam("id") long id) {
-        return GroupView.of(service.group(schoolId, id));
+        return views.group(service.group(schoolId, id));
     }
 
     @POST
@@ -50,14 +54,14 @@ public class DanceGroupResource {
         return Response.created(uriInfo.getAbsolutePathBuilder()
                         .path(entity.getId().toString())
                         .build())
-                .entity(GroupView.of(entity))
+                .entity(views.group(entity))
                 .build();
     }
 
     @PUT
     @Path("/{id}")
     public GroupView update(final @PathParam("id") long id, final @NotNull @Valid GroupRequest request) {
-        return GroupView.of(service.updateGroup(
+        return views.group(service.updateGroup(
                 schoolId,
                 id,
                 new GroupDetails(

agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/DanceSchoolResource.java

@@ -19,23 +19,44 @@ import java.util.List;
 import nl.agilecc.agiledancers.model.DanceSchool;
 import nl.agilecc.agiledancers.rest.apimodel.SchoolRequest;
 import nl.agilecc.agiledancers.rest.apimodel.SchoolView;
+import nl.agilecc.agiledancers.rest.mapping.DomainViewMapper;
 import nl.agilecc.agiledancers.service.SchoolManagementService;
 
+@SchoolTransactionBoundary
 @Path("/api/dance-schools")
 @Produces(MediaType.APPLICATION_JSON)
 @Consumes(MediaType.APPLICATION_JSON)
 public class DanceSchoolResource {
+    private @Inject DomainViewMapper views;
+
     private @Inject SchoolManagementService service;
 
+    private @Inject nl.agilecc.agiledancers.service.ShowSchedules schedules;
+
+    @GET
+    @Path("/{id}/data")
+    public nl.agilecc.agiledancers.rest.apimodel.SchoolDataView data(final @PathParam("id") long id) {
+        final DanceSchool school = service.school(id);
+        return new nl.agilecc.agiledancers.rest.apimodel.SchoolDataView(
+                views.school(school),
+                school.getDancers().stream().map(views::dancer).toList(),
+                school.getDanceGroups().stream().map(views::group).toList(),
+                school.getShows().stream()
+                        .map((final nl.agilecc.agiledancers.model.Show show) ->
+                                views.show(show, schedules.violations(id, show.getId())))
+                        .toList(),
+                school.getCoaches().stream().map(views::coach).toList());
+    }
+
     @GET
     public List<SchoolView> list() {
-        return service.schools().stream().map(SchoolView::of).toList();
+        return service.schools().stream().map(views::school).toList();
     }
 
     @GET
     @Path("/{id}")
     public SchoolView get(final @PathParam("id") long id) {
-        return SchoolView.of(service.school(id));
+        return views.school(service.school(id));
     }
 
     @POST
@@ -44,14 +65,14 @@ public class DanceSchoolResource {
         return Response.created(uriInfo.getAbsolutePathBuilder()
                         .path(entity.getId().toString())
                         .build())
-                .entity(SchoolView.of(entity))
+                .entity(views.school(entity))
                 .build();
     }
 
     @PUT
     @Path("/{id}")
     public SchoolView update(final @PathParam("id") long id, final @NotNull @Valid SchoolRequest request) {
-        return SchoolView.of(service.updateSchool(id, request.name()));
+        return views.school(service.updateSchool(id, request.name()));
     }
 
     @DELETE

agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/DancerResource.java

@@ -19,25 +19,29 @@ import java.util.List;
 import nl.agilecc.agiledancers.model.Dancer;
 import nl.agilecc.agiledancers.rest.apimodel.DancerRequest;
 import nl.agilecc.agiledancers.rest.apimodel.DancerView;
+import nl.agilecc.agiledancers.rest.mapping.DomainViewMapper;
 import nl.agilecc.agiledancers.service.SchoolManagementService;
 
+@SchoolTransactionBoundary
 @Path("/api/dance-schools/{schoolId}/dancers")
 @Produces(MediaType.APPLICATION_JSON)
 @Consumes(MediaType.APPLICATION_JSON)
 public class DancerResource {
+    private @Inject DomainViewMapper views;
+
     private @Inject SchoolManagementService service;
 
     private @PathParam("schoolId") long schoolId;
 
     @GET
     public List<DancerView> list() {
-        return service.dancers(schoolId).stream().map(DancerView::of).toList();
+        return service.dancers(schoolId).stream().map(views::dancer).toList();
     }
 
     @GET
     @Path("/{id}")
     public DancerView get(final @PathParam("id") long id) {
-        return DancerView.of(service.dancer(schoolId, id));
+        return views.dancer(service.dancer(schoolId, id));
     }
 
     @POST
@@ -46,14 +50,14 @@ public class DancerResource {
         return Response.created(uriInfo.getAbsolutePathBuilder()
                         .path(entity.getId().toString())
                         .build())
-                .entity(DancerView.of(entity))
+                .entity(views.dancer(entity))
                 .build();
     }
 
     @PUT
     @Path("/{id}")
     public DancerView update(final @PathParam("id") long id, final @NotNull @Valid DancerRequest request) {
-        return DancerView.of(service.updateDancer(schoolId, id, request.name(), request.birthDate()));
+        return views.dancer(service.updateDancer(schoolId, id, request.name(), request.birthDate()));
     }
 
     @DELETE

agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/ManagementExceptionMapper.java

@@ -13,6 +13,7 @@ public class ManagementExceptionMapper implements ExceptionMapper<ManagementExce
     public Response toResponse(final ManagementException exception) {
         final int status = switch (exception.getKind()) {
             case NOT_FOUND -> 404;
+            case STORAGE_UNAVAILABLE -> 503;
             case INVALID_INPUT -> 400;
             case CONFLICT -> 409;
         };

agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/SchedulingEventsResource.java

@@ -9,9 +9,9 @@ import jakarta.ws.rs.Produces;
 import jakarta.ws.rs.core.MediaType;
 import java.time.Duration;
 import java.util.List;
+import nl.agilecc.agiledancers.model.scheduling.SchedulingRun;
 import nl.agilecc.agiledancers.rest.apimodel.SchedulingEventView;
 import nl.agilecc.agiledancers.service.SchedulingRuns;
-import nl.agilecc.agiledancers.service.model.SchedulingRun;
 import org.jboss.resteasy.reactive.RestStreamElementType;
 
 @Path("/api/scheduling/events")
@@ -36,6 +36,9 @@ public class SchedulingEventsResource {
                 .every(Duration.ofSeconds(15))
                 .onItem()
                 .transform((final Long tick) -> new SchedulingEventView(null));
-        return Multi.createBy().merging().streams(updates, heartbeat);
+        return Multi.createBy()
+                .merging()
+                .streams(updates, heartbeat)
+                .runSubscriptionOn(io.smallrye.mutiny.infrastructure.Infrastructure.getDefaultWorkerPool());
     }
 }

agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/SchoolRequestInterceptor.java

@@ -0,0 +1,50 @@
+package nl.agilecc.agiledancers.rest;
+
+import io.vertx.ext.web.RoutingContext;
+import jakarta.annotation.Priority;
+import jakarta.inject.Inject;
+import jakarta.interceptor.AroundInvoke;
+import jakarta.interceptor.Interceptor;
+import jakarta.interceptor.InvocationContext;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+import nl.agilecc.agiledancers.service.ManagementException;
+import nl.agilecc.agiledancers.service.ManagementExceptionKind;
+import nl.agilecc.agiledancers.service.SchoolTransactions;
+import nl.agilecc.agiledancers.service.model.SchoolChange;
+
+@SchoolTransactionBoundary
+@Interceptor
+@Priority(Interceptor.Priority.APPLICATION)
+public class SchoolRequestInterceptor {
+    private static final Pattern SCHOOL_PATH = Pattern.compile("/api/dance-schools/(\\d+)(?:/|$)");
+    private @Inject RoutingContext context;
+    private @Inject SchoolTransactions transactions;
+
+    @AroundInvoke
+    public Object invoke(final InvocationContext invocation) throws Exception {
+        final String path = context.request().path();
+        final String method = context.request().method().name();
+        final boolean mutation = !method.equals("GET") && !path.endsWith("/preview");
+        final Matcher matcher = SCHOOL_PATH.matcher(path);
+        final Long schoolId = matcher.find()
+                ? Long.valueOf(matcher.group(1))
+                : number(context.request().getParam("replaceId"));
+        final Long revision = mutation ? number(context.request().getHeader("X-School-Revision")) : null;
+        return transactions.request(
+                new SchoolChange(schoolId, revision, mutation, mutation && !path.endsWith("/schedule")),
+                invocation::proceed);
+    }
+
+    private static Long number(final String value) {
+        if (value == null) {
+            return null;
+        }
+        try {
+            return Long.valueOf(value);
+        } catch (final NumberFormatException failure) {
+            throw new ManagementException(
+                    ManagementExceptionKind.INVALID_INPUT, "Ongeldige schoolversie of school-ID.");
+        }
+    }
+}

agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/SchoolSnapshotResource.java

@@ -15,15 +15,19 @@ import jakarta.ws.rs.QueryParam;
 import jakarta.ws.rs.core.MediaType;
 import jakarta.ws.rs.core.Response;
 import nl.agilecc.agiledancers.rest.apimodel.SchoolView;
+import nl.agilecc.agiledancers.rest.mapping.DomainViewMapper;
 import nl.agilecc.agiledancers.service.ManagementException;
 import nl.agilecc.agiledancers.service.ManagementExceptionKind;
 import nl.agilecc.agiledancers.service.SchoolManagementService;
 import nl.agilecc.agiledancers.service.model.ImportPreview;
 import nl.agilecc.agiledancers.service.model.SchoolSnapshot;
 
+@SchoolTransactionBoundary
 @Path("/api/dance-schools")
 @Produces(MediaType.APPLICATION_JSON)
 public class SchoolSnapshotResource {
+    private @Inject DomainViewMapper views;
+
     private @Inject SchoolManagementService service;
 
     private @Inject ObjectMapper mapper;
@@ -48,7 +52,7 @@ public class SchoolSnapshotResource {
     @Path("/import")
     @Consumes(MediaType.APPLICATION_JSON)
     public SchoolView apply(final String json, final @QueryParam("replaceId") Long replaceId) {
-        return SchoolView.of(service.importSchool(parse(json), replaceId));
+        return views.school(service.importSchool(parse(json), replaceId));
     }
 
     private SchoolSnapshot parse(final String json) {

agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/SchoolTransactionBoundary.java

@@ -0,0 +1,13 @@
+package nl.agilecc.agiledancers.rest;
+
+import jakarta.interceptor.InterceptorBinding;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/** Bounds school HTTP operations to one durable transaction and optimistic revision check. */
+@InterceptorBinding
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.TYPE, ElementType.METHOD})
+public @interface SchoolTransactionBoundary {}

agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/ShowResource.java

@@ -18,19 +18,23 @@ import jakarta.ws.rs.core.UriInfo;
 import java.util.List;
 import nl.agilecc.agiledancers.model.DayPart;
 import nl.agilecc.agiledancers.model.Show;
+import nl.agilecc.agiledancers.model.scheduling.SchedulingRun;
 import nl.agilecc.agiledancers.rest.apimodel.DayPartRequest;
 import nl.agilecc.agiledancers.rest.apimodel.ScheduleRequest;
 import nl.agilecc.agiledancers.rest.apimodel.ShowRequest;
 import nl.agilecc.agiledancers.rest.apimodel.ShowView;
+import nl.agilecc.agiledancers.rest.mapping.DomainViewMapper;
 import nl.agilecc.agiledancers.service.SchedulingRuns;
 import nl.agilecc.agiledancers.service.SchoolManagementService;
 import nl.agilecc.agiledancers.service.ShowSchedules;
-import nl.agilecc.agiledancers.service.model.SchedulingRun;
 
+@SchoolTransactionBoundary
 @Path("/api/dance-schools/{schoolId}/shows")
 @Produces(MediaType.APPLICATION_JSON)
 @Consumes(MediaType.APPLICATION_JSON)
 public class ShowResource {
+    private @Inject DomainViewMapper views;
+
     private @Inject SchoolManagementService service;
 
     private @Inject SchedulingRuns scheduling;
@@ -67,7 +71,7 @@ public class ShowResource {
     }
 
     private ShowView view(final Show show) {
-        return ShowView.of(show, schedules.violations(schoolId, show.getId()));
+        return views.show(show, schedules.violations(schoolId, show.getId()));
     }
 
     private static Show settings(final ShowRequest request) {

agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/apimodel/CoachView.java

@@ -1,12 +1,3 @@
 package nl.agilecc.agiledancers.rest.apimodel;
 
-import nl.agilecc.agiledancers.model.Coach;
+public record CoachView(long id, String name, Long dancerId) {}
-
-public record CoachView(long id, String name, Long dancerId) {
-    public static CoachView of(final Coach coach) {
-        return new CoachView(
-                coach.getId(),
-                coach.getName(),
-                coach.getDancer() == null ? null : coach.getDancer().getId());
-    }
-}

agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/apimodel/DancerView.java

@@ -1,10 +1,5 @@
 package nl.agilecc.agiledancers.rest.apimodel;
 
 import java.time.LocalDate;
-import nl.agilecc.agiledancers.model.Dancer;
 
-public record DancerView(long id, String name, LocalDate birthDate) {
+public record DancerView(long id, String name, LocalDate birthDate) {}
-    public static DancerView of(final Dancer dancer) {
-        return new DancerView(dancer.getId(), dancer.getName(), dancer.getBirthDate());
-    }
-}

agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/apimodel/GroupView.java

@@ -5,8 +5,6 @@ import java.util.Collections;
 import java.util.LinkedHashSet;
 import java.util.List;
 import java.util.Set;
-import nl.agilecc.agiledancers.model.DanceGroup;
-import nl.agilecc.agiledancers.model.Dancer;
 import nl.agilecc.agiledancers.model.specifications.DanceGroupStyle;
 import nl.agilecc.agiledancers.model.specifications.DanceGroupType;
 
@@ -22,15 +20,4 @@ public record GroupView(
         styles = styles == null ? null : Collections.unmodifiableSet(new LinkedHashSet<>(styles));
         dancerIds = dancerIds == null ? null : Collections.unmodifiableList(new ArrayList<>(dancerIds));
     }
-
-    public static GroupView of(final DanceGroup group) {
-        return new GroupView(
-                group.getId(),
-                group.getCategory(),
-                group.getType(),
-                group.getStartAge(),
-                group.getEndAge(),
-                Set.copyOf(group.getStyles()),
-                group.getDancers().stream().map(Dancer::getId).toList());
-    }
 }

agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/apimodel/SchedulingEventView.java

@@ -1,7 +1,7 @@
 package nl.agilecc.agiledancers.rest.apimodel;
 
 import java.util.List;
-import nl.agilecc.agiledancers.service.model.SchedulingRun;
+import nl.agilecc.agiledancers.model.scheduling.SchedulingRun;
 
 /** A null runs field is a heartbeat, not a replacement of the current snapshot. */
 public record SchedulingEventView(List<SchedulingRun> runs) {

agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/apimodel/SchoolDataView.java

@@ -0,0 +1,18 @@
+package nl.agilecc.agiledancers.rest.apimodel;
+
+import java.util.List;
+
+/** One school and all editor data from the same revision and database snapshot. */
+public record SchoolDataView(
+        SchoolView school,
+        List<DancerView> dancers,
+        List<GroupView> groups,
+        List<ShowView> shows,
+        List<CoachView> coaches) {
+    public SchoolDataView {
+        dancers = List.copyOf(dancers);
+        groups = List.copyOf(groups);
+        shows = List.copyOf(shows);
+        coaches = List.copyOf(coaches);
+    }
+}

agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/apimodel/SchoolView.java

@@ -3,24 +3,12 @@ package nl.agilecc.agiledancers.rest.apimodel;
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
-import nl.agilecc.agiledancers.model.DanceGroup;
-import nl.agilecc.agiledancers.model.DanceSchool;
-import nl.agilecc.agiledancers.model.Dancer;
-import nl.agilecc.agiledancers.model.Show;
 
-public record SchoolView(long id, String name, List<Long> dancerIds, List<Long> danceGroupIds, List<Long> showIds) {
+public record SchoolView(
+        long id, long revision, String name, List<Long> dancerIds, List<Long> danceGroupIds, List<Long> showIds) {
     public SchoolView {
         dancerIds = dancerIds == null ? null : Collections.unmodifiableList(new ArrayList<>(dancerIds));
         danceGroupIds = danceGroupIds == null ? null : Collections.unmodifiableList(new ArrayList<>(danceGroupIds));
         showIds = showIds == null ? null : Collections.unmodifiableList(new ArrayList<>(showIds));
     }
-
-    public static SchoolView of(final DanceSchool school) {
-        return new SchoolView(
-                school.getId(),
-                school.getName(),
-                school.getDancers().stream().map(Dancer::getId).toList(),
-                school.getDanceGroups().stream().map(DanceGroup::getId).toList(),
-                school.getShows().stream().map(Show::getId).toList());
-    }
 }

agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/apimodel/ShowView.java

@@ -5,9 +5,6 @@ import java.util.Collections;
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
-import nl.agilecc.agiledancers.model.DanceGroup;
-import nl.agilecc.agiledancers.model.DayPart;
-import nl.agilecc.agiledancers.model.Show;
 import nl.agilecc.agiledancers.model.specifications.DanceGroupType;
 
 public record ShowView(
@@ -23,26 +20,4 @@ public record ShowView(
         dayParts = dayParts == null ? null : Collections.unmodifiableList(new ArrayList<>(dayParts));
         appearances = appearances == null ? null : Collections.unmodifiableMap(new LinkedHashMap<>(appearances));
     }
-
-    public static ShowView of(final Show show) {
-        return of(show, List.of());
-    }
-
-    public static ShowView of(final Show show, final List<String> violations) {
-        return new ShowView(
-                show.getId(),
-                show.getName(),
-                show.getDayParts().stream()
-                        .map((final DayPart p) -> new DayPartView(
-                                p.getDate(),
-                                p.getType(),
-                                p.getDanceGroups().stream()
-                                        .map(DanceGroup::getId)
-                                        .toList()))
-                        .toList(),
-                show.getAppearances(),
-                nl.agilecc.agiledancers.service.SchedulingInputs.preferred(show),
-                show.isFinalized(),
-                violations);
-    }
 }

agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/mapping/DomainViewMapper.java

@@ -0,0 +1,59 @@
+package nl.agilecc.agiledancers.rest.mapping;
+
+import java.util.List;
+import nl.agilecc.agiledancers.model.AbstractEntity;
+import nl.agilecc.agiledancers.model.Coach;
+import nl.agilecc.agiledancers.model.DanceGroup;
+import nl.agilecc.agiledancers.model.DanceSchool;
+import nl.agilecc.agiledancers.model.Dancer;
+import nl.agilecc.agiledancers.model.DayPart;
+import nl.agilecc.agiledancers.model.Show;
+import nl.agilecc.agiledancers.rest.apimodel.CoachView;
+import nl.agilecc.agiledancers.rest.apimodel.DancerView;
+import nl.agilecc.agiledancers.rest.apimodel.DayPartView;
+import nl.agilecc.agiledancers.rest.apimodel.GroupView;
+import nl.agilecc.agiledancers.rest.apimodel.SchoolView;
+import nl.agilecc.agiledancers.rest.apimodel.ShowView;
+import nl.agilecc.agiledancers.service.SchedulingInputs;
+import org.mapstruct.AnnotateWith;
+import org.mapstruct.Mapper;
+import org.mapstruct.Mapping;
+import org.mapstruct.MappingConstants;
+import org.mapstruct.Named;
+import org.mapstruct.ReportingPolicy;
+
+/** Generates API projections only; domain graph identity and validation remain application-owned. */
+// Mark generated implementations so coverage and architecture checks retain their handwritten-code scope.
+@AnnotateWith(lombok.Generated.class)
+@Mapper(componentModel = MappingConstants.ComponentModel.JAKARTA_CDI, unmappedTargetPolicy = ReportingPolicy.ERROR)
+public interface DomainViewMapper {
+    @Mapping(target = "dancerIds", source = "dancers")
+    @Mapping(target = "danceGroupIds", source = "danceGroups")
+    @Mapping(target = "showIds", source = "shows")
+    public SchoolView school(final DanceSchool school);
+
+    public DancerView dancer(final Dancer dancer);
+
+    @Mapping(target = "dancerIds", source = "dancers")
+    public GroupView group(final DanceGroup group);
+
+    @Mapping(target = "dancerId", source = "dancer")
+    public CoachView coach(final Coach coach);
+
+    @Mapping(target = "danceGroupIds", source = "danceGroups")
+    public DayPartView dayPart(final DayPart part);
+
+    /** Violations are calculated by the use case, never inferred by the mapper. */
+    @Mapping(target = "violations", source = "violations")
+    @Mapping(target = "preferredDayParts", source = "show", qualifiedByName = "preferredDayParts")
+    public ShowView show(final Show show, final List<String> violations);
+
+    public default Long id(final AbstractEntity entity) {
+        return entity == null ? null : entity.getId();
+    }
+
+    @Named("preferredDayParts")
+    public default int preferredDayParts(final Show show) {
+        return SchedulingInputs.preferred(show);
+    }
+}

agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/ManagementExceptionKind.java

@@ -2,6 +2,7 @@ package nl.agilecc.agiledancers.service;
 
 public enum ManagementExceptionKind {
     NOT_FOUND,
+    STORAGE_UNAVAILABLE,
     INVALID_INPUT,
     CONFLICT
 }

agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/SchedulingPersistence.java

@@ -0,0 +1,54 @@
+package nl.agilecc.agiledancers.service;
+
+import jakarta.inject.Inject;
+import jakarta.inject.Singleton;
+import java.util.List;
+import java.util.concurrent.Callable;
+import nl.agilecc.agiledancers.model.scheduling.SchedulingRun;
+import nl.agilecc.agiledancers.repository.Database;
+import nl.agilecc.agiledancers.repository.RunRepository;
+
+/** Coordinates scheduling status with the same unit of work as domain changes. */
+@Singleton
+public class SchedulingPersistence {
+    private final SchoolTransactions transactions;
+    private final Database database;
+    private final RunRepository runs;
+
+    @Inject
+    public SchedulingPersistence(
+            final SchoolTransactions transactions, final Database database, final RunRepository runs) {
+        this.transactions = transactions;
+        this.database = database;
+        this.runs = runs;
+    }
+
+    public List<SchedulingRun> recover() {
+        return transactions.background(() -> {
+            runs.recover();
+            return runs.load();
+        });
+    }
+
+    public List<SchedulingRun> load() {
+        return transactions.background(runs::load);
+    }
+
+    public <T> T work(final Callable<T> action) {
+        return transactions.background(action);
+    }
+
+    public void save(final SchedulingRun run, final Runnable publication) {
+        runs.save(run);
+        database.afterCommit(publication);
+    }
+
+    public void accepted(final SchedulingRun run, final Runnable launch, final Runnable rollback) {
+        database.afterRollback(rollback);
+        save(run, launch);
+    }
+
+    public void result(final long schoolId) {
+        transactions.saveResult(schoolId);
+    }
+}

agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/SchedulingRuns.java

@@ -1,23 +1,28 @@
 package nl.agilecc.agiledancers.service;
 
+import io.quarkus.runtime.Startup;
+import jakarta.annotation.PostConstruct;
 import jakarta.annotation.PreDestroy;
 import jakarta.inject.Inject;
 import jakarta.inject.Singleton;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.concurrent.Callable;
 import java.util.concurrent.ExecutorService;
 import java.util.concurrent.Executors;
 import java.util.function.Consumer;
 import nl.agilecc.agiledancers.model.scheduling.SchedulingInput;
 import nl.agilecc.agiledancers.model.scheduling.SchedulingProgress;
 import nl.agilecc.agiledancers.model.scheduling.SchedulingResult;
+import nl.agilecc.agiledancers.model.scheduling.SchedulingRun;
+import nl.agilecc.agiledancers.model.scheduling.SchedulingState;
 import nl.agilecc.agiledancers.model.scheduling.SchedulingSummary;
-import nl.agilecc.agiledancers.service.model.SchedulingRun;
+import nl.agilecc.agiledancers.repository.StorageException;
-import nl.agilecc.agiledancers.service.model.SchedulingState;
 import nl.agilecc.agiledancers.service.port.SchedulingEngine;
 
-/** Owns background tasks and publishes current state independently of any HTTP connection. */
+/** Owns background tasks; the school monitor orders short commits and publication, never solver computation. */
+@Startup
 @Singleton
 public class SchedulingRuns {
     private final SchoolManagementService schools;
@@ -25,6 +30,7 @@ public class SchedulingRuns {
     private final ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor();
     private final Map<Long, SchedulingRun> runs = new HashMap<>();
     private final Map<Object, Consumer<List<SchedulingRun>>> listeners = new HashMap<>();
+    private @Inject SchedulingPersistence persistence;
 
     @Inject
     public SchedulingRuns(final SchoolManagementService schools, final SchedulingEngine engine) {
@@ -32,74 +38,119 @@ public class SchedulingRuns {
         this.engine = engine;
     }
 
-    public synchronized SchedulingRun start(final long schoolId, final long showId) {
+    @PostConstruct
-        final SchedulingInput input;
+    public void recover() {
-        final SchedulingRun run;
+        persistence.recover().forEach((final SchedulingRun run) -> runs.put(run.showId(), run));
+    }
+
+    public SchedulingRun start(final long schoolId, final long showId) {
         synchronized (schools) {
-            final String name = schools.show(schoolId, showId).getName();
+            final SchedulingInput input = schools.beginScheduling(schoolId, showId);
-            input = schools.beginScheduling(schoolId, showId);
+            final SchedulingRun run = SchedulingRun.started(
-            run = SchedulingRun.started(schoolId, showId, name);
+                    schoolId, showId, schools.show(schoolId, showId).getName());
+            final Runnable launch = () -> launch(run, input);
+            if (persistence == null) {
+                launch.run();
+            } else {
+                persistence.accepted(run, launch, () -> schools.endScheduling(showId));
+            }
+            return run;
         }
+    }
+
+    private void launch(final SchedulingRun run, final SchedulingInput input) {
         publish(run);
         try {
             executor.submit(() -> calculate(run, input));
         } catch (final RuntimeException failure) {
-            schools.endScheduling(showId);
+            finish(run.completed(
-            publish(run.completed(
                     SchedulingState.SOLVER_FAILED, "Berekening kon niet starten. Bestaande indeling behouden.", null));
-            throw failure;
+            if (persistence == null) {
+                throw failure;
+            }
         }
-        return run;
     }
 
-    public synchronized SchedulingRun status(final long schoolId, final long showId) {
+    public SchedulingRun status(final long schoolId, final long showId) {
-        schools.show(schoolId, showId);
+        synchronized (schools) {
-        return runs.get(showId);
+            schools.show(schoolId, showId);
+            return runs.get(showId);
+        }
     }
 
     /** Registration and initial snapshot share the publication lock, preventing a missed update. */
-    public synchronized Runnable subscribe(final Consumer<List<SchedulingRun>> listener) {
+    public Runnable subscribe(final Consumer<List<SchedulingRun>> listener) {
-        final Object key = new Object();
+        synchronized (schools) {
-        listeners.put(key, listener);
+            if (persistence != null) {
-        listener.accept(List.copyOf(runs.values()));
+                runs.clear();
-        return () -> unsubscribe(key);
+                persistence.load().forEach((final SchedulingRun run) -> runs.put(run.showId(), run));
+            }
+            final Object key = new Object();
+            listeners.put(key, listener);
+            listener.accept(List.copyOf(runs.values()));
+            return () -> unsubscribe(key);
+        }
     }
 
-    private synchronized void unsubscribe(final Object key) {
+    private void unsubscribe(final Object key) {
-        listeners.remove(key);
+        synchronized (schools) {
+            listeners.remove(key);
+        }
     }
 
-    private synchronized void publish(final SchedulingRun run) {
+    private void publish(final SchedulingRun run) {
-        runs.put(run.showId(), run);
+        synchronized (schools) {
-        final List<SchedulingRun> snapshot = List.copyOf(runs.values());
+            runs.put(run.showId(), run);
-        listeners.values().forEach((final Consumer<List<SchedulingRun>> listener) -> listener.accept(snapshot));
+            final List<SchedulingRun> snapshot = List.copyOf(runs.values());
+            for (final Consumer<List<SchedulingRun>> listener : List.copyOf(listeners.values())) {
+                notifyListener(listener, snapshot);
+            }
+        }
     }
 
-    private synchronized void progress(final SchedulingRun run, final SchedulingProgress update) {
+    private void notifyListener(final Consumer<List<SchedulingRun>> listener, final List<SchedulingRun> snapshot) {
-        publish(runs.get(run.showId()).progressed(update));
+        try {
+            listener.accept(snapshot);
+        } catch (final RuntimeException disconnected) {
+            // A disconnected transport must not turn a committed solver outcome into a failure.
+            listeners.values().remove(listener);
+        }
+    }
+
+    private void progress(final SchedulingRun run, final SchedulingProgress update) {
+        work(() -> {
+            save(latest(run).progressed(update));
+            return null;
+        });
     }
 
     private void calculate(final SchedulingRun run, final SchedulingInput input) {
-        SchedulingRun completed;
         try {
             final SchedulingResult result =
                     engine.solve(input, (final SchedulingProgress update) -> progress(run, update));
             final SchedulingSummary summary = SchedulingSummary.of(input, result);
-            schools.finishScheduling(run.schoolId(), input, result);
+            work(() -> {
-            completed = latest(run)
+                schools.finishScheduling(run.schoolId(), input, result);
-                    .completed(
+                if (persistence != null) {
-                            result.optimal() ? SchedulingState.OPTIMAL : SchedulingState.VALID,
+                    persistence.result(run.schoolId());
-                            result.optimal()
+                }
-                                    ? "Optimaal conceptrooster."
+                save(latest(run)
-                                    : "Geldig conceptrooster; optimaliteit niet bewezen.",
+                        .completed(
-                            summary);
+                                result.optimal() ? SchedulingState.OPTIMAL : SchedulingState.VALID,
+                                result.optimal()
+                                        ? "Optimaal conceptrooster."
+                                        : "Geldig conceptrooster; optimaliteit niet bewezen.",
+                                summary));
+                return null;
+            });
+            schools.endScheduling(run.showId());
         } catch (final ManagementException failure) {
-            completed = failed(run, failure);
+            finish(failed(run, failure));
         } catch (final RuntimeException | LinkageError failure) {
-            completed = latest(run)
+            finish(latest(run)
-                    .completed(SchedulingState.SOLVER_FAILED, "Berekening mislukt. Bestaande indeling behouden.", null);
+                    .completed(
+                            SchedulingState.SOLVER_FAILED, "Berekening mislukt. Bestaande indeling behouden.", null));
         }
-        finish(completed);
     }
 
     private SchedulingRun failed(final SchedulingRun run, final ManagementException failure) {
@@ -115,13 +166,71 @@ public class SchedulingRuns {
         return latest(run).completed(outcome, failure.getMessage() + " Bestaande indeling behouden.", null);
     }
 
-    private synchronized SchedulingRun latest(final SchedulingRun run) {
+    private SchedulingRun latest(final SchedulingRun run) {
-        return runs.get(run.showId());
+        synchronized (schools) {
+            return runs.get(run.showId());
+        }
     }
 
-    private synchronized void finish(final SchedulingRun completed) {
+    private void finish(final SchedulingRun completed) {
-        schools.endScheduling(completed.showId());
+        try {
-        publish(completed);
+            while (true) {
+                try {
+                    work(() -> {
+                        schools.show(completed.schoolId(), completed.showId());
+                        save(completed);
+                        return null;
+                    });
+                    return;
+                } catch (final StorageException unavailable) {
+                    // Keep the run guard and terminal outcome until storage recovers; never publish an uncommitted
+                    // status.
+                    if (executor.isShutdown() || !waitForStorage()) {
+                        return;
+                    }
+                } catch (final ManagementException removed) {
+                    if (removed.getKind() != ManagementExceptionKind.NOT_FOUND) {
+                        throw removed;
+                    }
+                    return;
+                }
+            }
+        } finally {
+            schools.endScheduling(completed.showId());
+        }
+    }
+
+    private boolean waitForStorage() {
+        try {
+            Thread.sleep(1000);
+            return true;
+        } catch (final InterruptedException stopping) {
+            Thread.currentThread().interrupt();
+            return false;
+        }
+    }
+
+    private void save(final SchedulingRun run) {
+        if (persistence == null) {
+            publish(run);
+        } else {
+            persistence.save(run, () -> publish(run));
+        }
+    }
+
+    private <T> T work(final Callable<T> action) {
+        synchronized (schools) {
+            if (persistence != null) {
+                return persistence.work(action);
+            }
+            try {
+                return action.call();
+            } catch (final RuntimeException failure) {
+                throw failure;
+            } catch (final Exception failure) {
+                throw new IllegalStateException(failure);
+            }
+        }
     }
 
     @PreDestroy

agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/SchoolManagementService.java

@@ -30,7 +30,7 @@ import nl.agilecc.agiledancers.service.model.GroupDetails;
 import nl.agilecc.agiledancers.service.model.ImportPreview;
 import nl.agilecc.agiledancers.service.model.SchoolSnapshot;
 
-/** Owns the in-memory school aggregates; all writes go through this shared service. */
+/** Owns detached school aggregates within the shared transaction monitor; all domain writes pass through here. */
 @Singleton
 public class SchoolManagementService {
     private final DanceSchoolRepository schools = new DanceSchoolRepository();
@@ -41,6 +41,27 @@ public class SchoolManagementService {
     private final Map<Long, Long> revisions = new HashMap<>();
     private final Set<Long> running = new HashSet<>();
 
+    /** Installs a detached relational snapshot under the service's existing aggregate lock. */
+    public synchronized void load(final List<DanceSchool> state, final java.util.function.LongSupplier identifiers) {
+        revisions.clear();
+        schools.load(state, identifiers);
+        dancers.load(
+                state.stream()
+                        .flatMap((final DanceSchool school) -> school.getDancers().stream())
+                        .toList(),
+                identifiers);
+        groups.load(
+                state.stream()
+                        .flatMap((final DanceSchool school) -> school.getDanceGroups().stream())
+                        .toList(),
+                identifiers);
+        shows.load(
+                state.stream()
+                        .flatMap((final DanceSchool school) -> school.getShows().stream())
+                        .toList(),
+                identifiers);
+    }
+
     public synchronized void touch(final Show show) {
         show.setFinalized(false);
         revisions.merge(show.getId(), 1L, Long::sum);
@@ -64,7 +85,8 @@ public class SchoolManagementService {
                     ManagementExceptionKind.INVALID_INPUT, "Correct preferredDayParts before scheduling.");
         }
         running.add(showId);
-        return SchedulingInputs.of(school(schoolId), show, revisions.getOrDefault(showId, 0L));
+        return SchedulingInputs.of(
+                school(schoolId), show, school(schoolId).getRevision() + revisions.getOrDefault(showId, 0L));
     }
 
     /** Validates the complete result and input revision before replacing any saved assignments. */
@@ -77,7 +99,7 @@ public class SchoolManagementService {
             throw new ManagementException(
                     ManagementExceptionKind.CONFLICT, "Scheduling inputs changed. Run scheduling again.");
         }
-        if (revisions.getOrDefault(input.showId(), 0L) != input.revision()) {
+        if (school(schoolId).getRevision() + revisions.getOrDefault(input.showId(), 0L) != input.revision()) {
             throw new ManagementException(
                     ManagementExceptionKind.CONFLICT, "Scheduling inputs changed. Run scheduling again.");
         }
@@ -320,12 +342,14 @@ public class SchoolManagementService {
                 snapshot.groups().size(),
                 snapshot.shows().size(),
                 existing == null ? null : existing.getId(),
-                existing == null ? null : existing.getName());
+                existing == null ? null : existing.getName(),
+                existing == null ? null : existing.getRevision());
     }
 
     /** Validates and stages the complete graph before replacing repositories; file IDs become runtime IDs. */
     public synchronized DanceSchool importSchool(final SchoolSnapshot snapshot, final Long replaceId) {
         final DanceSchool staged = snapshot.restore();
+        final long revision = replaceId == null ? 0 : school(replaceId).getRevision();
         final ImportPreview preview = preview(snapshot);
         if (!Objects.equals(preview.existingId(), replaceId)) {
             throw new ManagementException(
@@ -347,6 +371,7 @@ public class SchoolManagementService {
         final List<DanceGroup> rebuiltGroups = rebuildGroups(importedGroups, memberships, replacements);
         final List<Show> rebuiltShows = rebuildShows(importedShows, replacements);
         final DanceSchool imported = DanceSchool.builder()
+                .revision(revision)
                 .key(staged.getKey())
                 .name(staged.getName())
                 .dancers(new LinkedHashSet<>(importedDancers))

agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/SchoolTransactions.java

@@ -0,0 +1,118 @@
+package nl.agilecc.agiledancers.service;
+
+import jakarta.inject.Inject;
+import jakarta.inject.Singleton;
+import java.util.List;
+import java.util.concurrent.Callable;
+import nl.agilecc.agiledancers.model.DanceSchool;
+import nl.agilecc.agiledancers.repository.Database;
+import nl.agilecc.agiledancers.repository.RevisionConflictException;
+import nl.agilecc.agiledancers.repository.SchoolReader;
+import nl.agilecc.agiledancers.repository.SchoolWriter;
+import nl.agilecc.agiledancers.repository.StorageException;
+import nl.agilecc.agiledancers.service.model.SchoolChange;
+
+/** Serializes short domain units of work; solver computation never holds this lock or a database connection. */
+@Singleton
+public class SchoolTransactions {
+    private final SchoolManagementService schools;
+    private final Database database;
+    private final SchoolReader reader;
+    private final SchoolWriter writer;
+
+    @Inject
+    public SchoolTransactions(
+            final SchoolManagementService schools,
+            final Database database,
+            final SchoolReader reader,
+            final SchoolWriter writer) {
+        this.schools = schools;
+        this.database = database;
+        this.reader = reader;
+        this.writer = writer;
+    }
+
+    /** An expected revision is mandatory for existing-school writes; null school identifies a new-school operation. */
+    public Object request(final Long schoolId, final Long revision, final boolean mutation, final Callable<Object> work)
+            throws Exception {
+        return request(new SchoolChange(schoolId, revision, mutation, mutation), work);
+    }
+
+    public Object request(final SchoolChange change, final Callable<Object> work) throws Exception {
+        synchronized (schools) {
+            try {
+                return database.transaction(() -> {
+                    final List<DanceSchool> before = reader.load();
+                    schools.load(before, database::nextId);
+                    if (change.mutation() && change.schoolId() != null) {
+                        check(change);
+                        schools.school(change.schoolId())
+                                .setRevision(change.revision() + (change.changesInputs() ? 1 : 0));
+                    }
+                    final Object result = work.call();
+                    if (change.changesInputs()) {
+                        store(before, change.schoolId());
+                    }
+                    return result;
+                });
+            } catch (final RevisionConflictException failure) {
+                throw new ManagementException(ManagementExceptionKind.CONFLICT, failure.getMessage());
+            } catch (final StorageException failure) {
+                throw new ManagementException(ManagementExceptionKind.STORAGE_UNAVAILABLE, failure.getMessage());
+            }
+        }
+    }
+
+    private void check(final SchoolChange change) {
+        final long schoolId = change.schoolId();
+        final Long expected = change.revision();
+        final long actual = schools.school(schoolId).getRevision();
+        if (expected == null || actual != expected) {
+            throw new ManagementException(
+                    ManagementExceptionKind.CONFLICT,
+                    "Deze school is gewijzigd of de schoolversie ontbreekt. Herlaad de gegevens en probeer opnieuw.");
+        }
+        writer.checkRevision(schoolId, expected);
+    }
+
+    private void store(final List<DanceSchool> before, final Long schoolId) {
+        final List<DanceSchool> after = schools.schools();
+        if (schoolId != null) {
+            final DanceSchool retained = after.stream()
+                    .filter((final DanceSchool school) -> school.getId().equals(schoolId))
+                    .findFirst()
+                    .orElse(null);
+            if (retained == null) {
+                writer.delete(schoolId);
+            } else {
+                writer.save(retained);
+            }
+        }
+        final List<Long> known = before.stream().map(DanceSchool::getId).toList();
+        after.stream()
+                .filter((final DanceSchool school) -> !known.contains(school.getId()))
+                .forEach(writer::save);
+    }
+
+    /** Refreshes current domain state and commits a worker's atomic result/status operation. */
+    public <T> T background(final Callable<T> work) {
+        synchronized (schools) {
+            try {
+                return database.transaction(() -> {
+                    schools.load(reader.load(), database::nextId);
+                    return work.call();
+                });
+            } catch (final RuntimeException failure) {
+                throw failure;
+            } catch (final Exception failure) {
+                throw new IllegalStateException(failure);
+            }
+        }
+    }
+
+    public void saveResult(final long schoolId) {
+        final DanceSchool school = schools.school(schoolId);
+        school.setRevision(school.getRevision() + 1);
+        writer.save(school);
+    }
+}

agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/model/ImportPreview.java

@@ -1,3 +1,4 @@
 package nl.agilecc.agiledancers.service.model;
 
-public record ImportPreview(String name, int dancers, int groups, int shows, Long existingId, String existingName) {}
+public record ImportPreview(
+        String name, int dancers, int groups, int shows, Long existingId, String existingName, Long existingRevision) {}

agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/model/SchoolChange.java

@@ -0,0 +1,4 @@
+package nl.agilecc.agiledancers.service.model;
+
+/** Run acceptance checks the loaded revision but does not itself change scheduling inputs. */
+public record SchoolChange(Long schoolId, Long revision, boolean mutation, boolean changesInputs) {}

agiledancers-be/src/main/resources/application.properties

@@ -1,7 +1,7 @@
 quarkus.application.name=agiledancers
 quarkus.http.host=0.0.0.0
 
-# Scheduling is synchronous with a 30-minute solver limit.
+# Keep idle SSE connections alive alongside the 30-minute solver limit.
 quarkus.http.idle-timeout=31M
 quarkus.jackson.fail-on-unknown-properties=true
 
@@ -9,3 +9,17 @@ quarkus.jackson.fail-on-unknown-properties=true
 %test.quarkus.jacoco.data-file=target/jacoco.exec
 %test.quarkus.jacoco.reuse-data-file=true
 %test.quarkus.jacoco.report=false
+
+# Production requires an explicitly configured database; initialization failures prevent startup.
+quarkus.datasource.db-kind=postgresql
+%prod.quarkus.datasource.jdbc.url=${DATABASE_URL}
+%prod.quarkus.datasource.username=${DATABASE_USER}
+%prod.quarkus.datasource.password=${DATABASE_PASSWORD}
+quarkus.datasource.jdbc.acquisition-timeout=5S
+quarkus.flyway.migrate-at-start=true
+quarkus.datasource.devservices.image-name=postgres:17.6
+
+# Flyway owns DDL; Hibernate validates its JPA mappings against the migrated schema.
+quarkus.hibernate-orm.schema-management.strategy=validate
+quarkus.hibernate-orm.request-scoped.enabled=false
+quarkus.datasource.jdbc.transaction-isolation-level=repeatable-read

agiledancers-be/src/main/resources/db/migration/V1__persistent_schools.sql

@@ -0,0 +1,71 @@
+CREATE SEQUENCE entity_id START 1;
+CREATE TABLE school (
+ id bigint PRIMARY KEY, school_key uuid NOT NULL UNIQUE, name text NOT NULL,
+ revision bigint NOT NULL DEFAULT 0 CHECK (revision >= 0)
+);
+CREATE TABLE dancer (
+ school_id bigint NOT NULL REFERENCES school ON DELETE CASCADE,
+ id bigint NOT NULL, name text NOT NULL, birth_date date NOT NULL,
+ PRIMARY KEY (school_id, id)
+);
+CREATE TABLE coach (
+ school_id bigint NOT NULL REFERENCES school ON DELETE CASCADE,
+ id bigint NOT NULL, name text NOT NULL, dancer_id bigint,
+ PRIMARY KEY (school_id, id),
+ FOREIGN KEY (school_id, dancer_id) REFERENCES dancer DEFERRABLE INITIALLY DEFERRED
+);
+CREATE TABLE dance_group (
+ school_id bigint NOT NULL REFERENCES school ON DELETE CASCADE,
+ id bigint NOT NULL, category text NOT NULL, group_type text NOT NULL,
+ start_age integer NOT NULL CHECK (start_age >= 0), end_age integer NOT NULL CHECK (end_age >= start_age),
+ coach_id bigint, PRIMARY KEY (school_id, id),
+ FOREIGN KEY (school_id, coach_id) REFERENCES coach DEFERRABLE INITIALLY DEFERRED
+);
+CREATE TABLE group_style (
+ school_id bigint NOT NULL, group_id bigint NOT NULL, style text NOT NULL,
+ PRIMARY KEY (school_id, group_id, style),
+ FOREIGN KEY (school_id, group_id) REFERENCES dance_group ON DELETE CASCADE
+);
+CREATE TABLE group_dancer (
+ school_id bigint NOT NULL, group_id bigint NOT NULL, dancer_id bigint NOT NULL,
+ PRIMARY KEY (school_id, group_id, dancer_id),
+ FOREIGN KEY (school_id, group_id) REFERENCES dance_group ON DELETE CASCADE,
+ FOREIGN KEY (school_id, dancer_id) REFERENCES dancer DEFERRABLE INITIALLY DEFERRED
+);
+CREATE TABLE show (
+ school_id bigint NOT NULL REFERENCES school ON DELETE CASCADE,
+ id bigint NOT NULL, name text NOT NULL, preferred_day_parts integer NOT NULL CHECK (preferred_day_parts BETWEEN 1 AND 6),
+ finalized boolean NOT NULL, PRIMARY KEY (school_id, id)
+);
+CREATE TABLE show_appearance (
+ school_id bigint NOT NULL, show_id bigint NOT NULL, group_type text NOT NULL, appearances integer NOT NULL CHECK (appearances >= 0),
+ PRIMARY KEY (school_id, show_id, group_type),
+ FOREIGN KEY (school_id, show_id) REFERENCES show ON DELETE CASCADE
+);
+CREATE TABLE day_part (
+ school_id bigint NOT NULL, show_id bigint NOT NULL, position integer NOT NULL CHECK (position >= 0),
+ day date NOT NULL, part_type text NOT NULL,
+ PRIMARY KEY (school_id, show_id, position), UNIQUE (school_id, show_id, day, part_type),
+ FOREIGN KEY (school_id, show_id) REFERENCES show ON DELETE CASCADE
+);
+CREATE TABLE assignment (
+ school_id bigint NOT NULL, show_id bigint NOT NULL, part_position integer NOT NULL,
+ position integer NOT NULL CHECK (position >= 0), group_id bigint NOT NULL,
+ PRIMARY KEY (school_id, show_id, part_position, position),
+ FOREIGN KEY (school_id, show_id, part_position) REFERENCES day_part ON DELETE CASCADE,
+ FOREIGN KEY (school_id, group_id) REFERENCES dance_group DEFERRABLE INITIALLY DEFERRED
+);
+CREATE TABLE scheduling_run (
+ school_id bigint NOT NULL REFERENCES school ON DELETE CASCADE,
+ show_id bigint NOT NULL, run_id uuid NOT NULL UNIQUE, show_name text NOT NULL,
+ started_at timestamptz NOT NULL, finished_at timestamptz,
+ state text NOT NULL CHECK (state IN ('RUNNING','OPTIMAL','VALID','STALE','INVALID_INPUT','INFEASIBLE','NO_SOLUTION','SOLVER_FAILED','INTERRUPTED')),
+ phase text NOT NULL CHECK (phase IN ('PREPARING','ATTENDANCE','SPREAD','VARIETY')),
+ feasible boolean NOT NULL, message text NOT NULL,
+ attendance_excess bigint, performance_spread integer, variety_penalty bigint,
+ PRIMARY KEY (school_id, show_id),
+ FOREIGN KEY (school_id, show_id) REFERENCES show DEFERRABLE INITIALLY DEFERRED,
+ CHECK ((state = 'RUNNING') = (finished_at IS NULL)),
+ CHECK ((attendance_excess IS NULL AND performance_spread IS NULL AND variety_penalty IS NULL)
+     OR (attendance_excess IS NOT NULL AND performance_spread IS NOT NULL AND variety_penalty IS NOT NULL))
+);

agiledancers-be/src/main/resources/db/migration/V2__jpa_aggregate_versioning.sql

@@ -0,0 +1,15 @@
+-- Child-only edits must dirty the school entity so @Version advances exactly once.
+ALTER TABLE school ADD COLUMN change_stamp bigint NOT NULL DEFAULT 0;
+
+-- Keep existing identifiers and start above every value already allocated by V1.
+-- JPA allocates identifiers under a row lock, including when a transaction creates a whole import graph.
+CREATE TABLE entity_identifiers (
+ id integer PRIMARY KEY CHECK (id = 1),
+ next_value bigint NOT NULL CHECK (next_value > 0)
+);
+INSERT INTO entity_identifiers (id, next_value) VALUES (1, nextval('entity_id'));
+
+-- Hibernate updates retained positions in place; date/type swaps must be checked on the final graph.
+ALTER TABLE day_part DROP CONSTRAINT day_part_school_id_show_id_day_part_type_key;
+ALTER TABLE day_part ADD CONSTRAINT day_part_date_type_unique
+ UNIQUE (school_id, show_id, day, part_type) DEFERRABLE INITIALLY DEFERRED;

agiledancers-be/src/test/java/nl/agilecc/agiledancers/DomainViewMapperTest.java

@@ -0,0 +1,119 @@
+package nl.agilecc.agiledancers;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+import io.quarkus.test.junit.QuarkusTest;
+import jakarta.inject.Inject;
+import java.time.LocalDate;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import nl.agilecc.agiledancers.model.Coach;
+import nl.agilecc.agiledancers.model.DanceGroup;
+import nl.agilecc.agiledancers.model.DanceSchool;
+import nl.agilecc.agiledancers.model.Dancer;
+import nl.agilecc.agiledancers.model.DayPart;
+import nl.agilecc.agiledancers.model.Show;
+import nl.agilecc.agiledancers.model.specifications.DanceGroupStyle;
+import nl.agilecc.agiledancers.model.specifications.DayPartType;
+import nl.agilecc.agiledancers.rest.apimodel.GroupView;
+import nl.agilecc.agiledancers.rest.apimodel.SchoolView;
+import nl.agilecc.agiledancers.rest.apimodel.ShowView;
+import nl.agilecc.agiledancers.rest.mapping.DomainViewMapper;
+import org.junit.jupiter.api.Test;
+
+@QuarkusTest
+class DomainViewMapperTest {
+    private @Inject DomainViewMapper views;
+
+    public @Test void relationshipsBecomeOrderedIdsAndUnlinkedCoachesRetainNull() {
+        final DanceSchool school =
+                DanceSchool.builder().name("School").revision(4).build();
+        school.setId(7L);
+        final Dancer first = dancer(9L);
+        final Dancer second = dancer(3L);
+        school.addDancer(first);
+        school.addDancer(second);
+        final SchoolView mapped = views.school(school);
+        assertEquals(List.of(9L, 3L), mapped.dancerIds());
+        assertEquals(4, mapped.revision());
+        final Coach coach = Coach.builder().name("Coach").dancer(first).build();
+        coach.setId(2L);
+        assertEquals(9L, views.coach(coach).dancerId());
+        coach.setDancer(null);
+        assertNull(views.coach(coach).dancerId());
+        school.removeDancer(first);
+        assertEquals(List.of(9L, 3L), mapped.dancerIds());
+        assertThrows(
+                UnsupportedOperationException.class, () -> mapped.dancerIds().clear());
+    }
+
+    public @Test void nestedViewsKeepAssignmentOrderAndExplicitValidationWithoutSharingCollections() {
+        final DanceGroup first = DanceGroup.builder().category("First").build();
+        first.setId(8L);
+        final DanceGroup second = DanceGroup.builder().category("Second").build();
+        second.setId(2L);
+        final List<DanceGroup> assigned = new ArrayList<>(List.of(first, second));
+        final DayPart part = DayPart.builder()
+                .date(LocalDate.of(2027, 1, 1))
+                .type(DayPartType.MORNING)
+                .danceGroups(assigned)
+                .build();
+        final List<String> violations = new ArrayList<>(List.of("Draft validation"));
+        final Show show = Show.builder()
+                .name("Show")
+                .dayParts(new ArrayList<>(List.of(part)))
+                .appearances(Map.of())
+                .build();
+        show.setId(1L);
+        final ShowView mapped = views.show(show, violations);
+        assertEquals(1, mapped.preferredDayParts());
+        assertEquals(List.of(8L, 2L), mapped.dayParts().getFirst().danceGroupIds());
+        assigned.clear();
+        violations.clear();
+        show.getDayParts().clear();
+        assertEquals(List.of(8L, 2L), mapped.dayParts().getFirst().danceGroupIds());
+        assertEquals(List.of("Draft validation"), mapped.violations());
+        assertThrows(
+                UnsupportedOperationException.class,
+                () -> mapped.dayParts().getFirst().danceGroupIds().clear());
+    }
+
+    public @Test void preferredDefaultsUseTheExistingRuleAndStylesAreSnapshotValues() {
+        final DayPart part = DayPart.builder()
+                .date(LocalDate.of(2027, 1, 1))
+                .type(DayPartType.MORNING)
+                .danceGroups(List.of())
+                .build();
+        final Show show = Show.builder()
+                .dayParts(List.of(part, part))
+                .appearances(Map.of())
+                .build();
+        show.setId(1L);
+        assertEquals(2, views.show(show, List.of()).preferredDayParts());
+        show.setPreferredDayParts(1);
+        assertEquals(1, views.show(show, List.of()).preferredDayParts());
+        final DanceGroup group = DanceGroup.builder().category("Group").build();
+        group.setId(1L);
+        group.addStyle(DanceGroupStyle.JAZZ);
+        final Dancer dancer = dancer(4L);
+        group.addDancer(dancer);
+        final GroupView mapped = views.group(group);
+        group.replaceStyles(Set.of(DanceGroupStyle.MODERN));
+        group.removeDancer(dancer);
+        assertEquals(Set.of(DanceGroupStyle.JAZZ), mapped.styles());
+        assertEquals(List.of(4L), mapped.dancerIds());
+    }
+
+    private static Dancer dancer(final long id) {
+        final Dancer dancer = Dancer.builder()
+                .name("Dancer")
+                .birthDate(LocalDate.of(2000, 1, 1))
+                .build();
+        dancer.setId(id);
+        return dancer;
+    }
+}

agiledancers-be/src/test/java/nl/agilecc/agiledancers/PersistenceTest.java

@@ -0,0 +1,386 @@
+package nl.agilecc.agiledancers;
+
+import static io.restassured.RestAssured.given;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import io.quarkus.test.junit.QuarkusTest;
+import jakarta.inject.Inject;
+import java.time.LocalDate;
+import java.util.List;
+import java.util.Set;
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeUnit;
+import nl.agilecc.agiledancers.model.DanceSchool;
+import nl.agilecc.agiledancers.model.DayPart;
+import nl.agilecc.agiledancers.model.Show;
+import nl.agilecc.agiledancers.model.scheduling.SchedulingPhase;
+import nl.agilecc.agiledancers.model.scheduling.SchedulingProgress;
+import nl.agilecc.agiledancers.model.scheduling.SchedulingRun;
+import nl.agilecc.agiledancers.model.scheduling.SchedulingState;
+import nl.agilecc.agiledancers.model.scheduling.SchedulingSummary;
+import nl.agilecc.agiledancers.model.specifications.DanceGroupStyle;
+import nl.agilecc.agiledancers.model.specifications.DanceGroupType;
+import nl.agilecc.agiledancers.model.specifications.DayPartType;
+import nl.agilecc.agiledancers.repository.Database;
+import nl.agilecc.agiledancers.repository.RunRepository;
+import nl.agilecc.agiledancers.repository.SchoolReader;
+import nl.agilecc.agiledancers.repository.SchoolWriter;
+import nl.agilecc.agiledancers.repository.StorageException;
+import nl.agilecc.agiledancers.service.SchoolManagementService;
+import nl.agilecc.agiledancers.service.SchoolTransactions;
+import nl.agilecc.agiledancers.service.model.GroupDetails;
+import org.junit.jupiter.api.Test;
+
+@QuarkusTest
+class PersistenceTest {
+    private @Inject SchoolTransactions transactions;
+    private @Inject SchoolManagementService schools;
+    private @Inject Database database;
+    private @Inject SchoolReader reader;
+    private @Inject SchoolWriter writer;
+    private @Inject RunRepository runs;
+    private @Inject jakarta.persistence.EntityManager entities;
+
+    public @Test void simultaneousEditsRequireTheLoadedRevision() throws Exception {
+        final long id = create();
+        final String path = "/api/dance-schools/" + id;
+        try (final java.util.concurrent.ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor()) {
+            final java.util.concurrent.Future<Integer> first = executor.submit(() -> rename(path, "First", 0));
+            final java.util.concurrent.Future<Integer> second = executor.submit(() -> rename(path, "Second", 0));
+            final List<Integer> statuses = List.of(first.get(10, TimeUnit.SECONDS), second.get(10, TimeUnit.SECONDS));
+            assertTrue(statuses.containsAll(List.of(200, 409)));
+            given().contentType("application/json")
+                    .body("{\"name\":\"Missing revision\"}")
+                    .put(path)
+                    .then()
+                    .statusCode(409);
+            given().get(path + "/data").then().statusCode(200);
+            assertEquals(1, given().get(path).jsonPath().getInt("revision"));
+        } finally {
+            delete(id);
+        }
+    }
+
+    public @Test void detachedRelationalGraphRetainsIdsReferencesDraftAndFinalState() throws Exception {
+        final long id = create();
+        try {
+            final Show show = fixture(id);
+            transactions.background(() -> {
+                final DanceSchool loaded = schools.school(id);
+                assertEquals(1, loaded.getDancers().size());
+                assertEquals(
+                        Set.of(DanceGroupStyle.JAZZ),
+                        loaded.getDanceGroups().iterator().next().getStyles());
+                assertEquals(show.getId(), loaded.getShows().iterator().next().getId());
+                assertTrue(loaded.getShows().iterator().next().isFinalized());
+                assertEquals(
+                        loaded.getDanceGroups().iterator().next(),
+                        loaded.getShows()
+                                .iterator()
+                                .next()
+                                .getDayParts()
+                                .getFirst()
+                                .getDanceGroups()
+                                .getFirst());
+                return null;
+            });
+            given().get("/api/dance-schools/" + id + "/export").then().statusCode(200);
+        } finally {
+            delete(id);
+        }
+    }
+
+    public @Test void deferredConstraintFailureRollsBackDomainAndCompletedStatusTogether() throws Exception {
+        final long id = create();
+        try {
+            final Show show = fixture(id);
+            final SchedulingRun run = SchedulingRun.started(id, show.getId(), show.getName());
+            database.transaction(() -> {
+                runs.save(run);
+                return null;
+            });
+            final java.util.concurrent.atomic.AtomicBoolean published = new java.util.concurrent.atomic.AtomicBoolean();
+            assertThrows(StorageException.class, () -> damageResult(id, show, run, published));
+            assertFalse(published.get());
+            database.transaction(() -> {
+                assertEquals(
+                        "Persistent school",
+                        reader.load().stream()
+                                .filter((final DanceSchool school) -> school.getId() == id)
+                                .findFirst()
+                                .orElseThrow()
+                                .getName());
+                assertEquals(
+                        1,
+                        entities.find(
+                                        nl.agilecc.agiledancers.repository.entity.DayPartEntity.class,
+                                        new nl.agilecc.agiledancers.repository.entity.DayPartId(id, show.getId(), 0))
+                                .getGroupIds()
+                                .size());
+                assertEquals(
+                        SchedulingState.RUNNING,
+                        runs.load().stream()
+                                .filter((final SchedulingRun item) ->
+                                        item.runId().equals(run.runId()))
+                                .findFirst()
+                                .orElseThrow()
+                                .state());
+                return null;
+            });
+        } finally {
+            delete(id);
+        }
+    }
+
+    public @Test void recoveryRetainsRunIdentityProgressAndExistingAssignments() throws Exception {
+        final long id = create();
+        try {
+            final Show show = fixture(id);
+            final SchedulingRun run = SchedulingRun.started(id, show.getId(), show.getName())
+                    .progressed(new SchedulingProgress(SchedulingPhase.SPREAD, true));
+            database.transaction(() -> {
+                runs.save(run);
+                return null;
+            });
+            database.transaction(() -> {
+                runs.recover();
+                return null;
+            });
+            database.transaction(() -> {
+                final SchedulingRun recovered = runs.load().stream()
+                        .filter((final SchedulingRun item) -> item.runId().equals(run.runId()))
+                        .findFirst()
+                        .orElseThrow();
+                assertEquals(SchedulingState.INTERRUPTED, recovered.state());
+                assertEquals(run.progress(), recovered.progress());
+                assertTrue(recovered.finishedAt() != null);
+                assertTrue(recovered.message().contains("behouden"));
+                return null;
+            });
+        } finally {
+            delete(id);
+        }
+    }
+
+    public @Test void aFailedReplacementImportRetainsThePreviousGraphAndRevision() throws Exception {
+        final long id = create();
+        try {
+            fixture(id);
+            final nl.agilecc.agiledancers.service.model.SchoolSnapshot before =
+                    transactions.background(() -> schools.exportSchool(id));
+            assertThrows(
+                    nl.agilecc.agiledancers.service.ManagementException.class,
+                    () -> transactions.request(id, 1L, true, () -> {
+                        final DanceSchool imported = schools.importSchool(before, id);
+                        imported.getDancers().iterator().next().setBirthDate(null);
+                        return imported;
+                    }));
+            transactions.background(() -> {
+                assertEquals(before, schools.exportSchool(id));
+                assertEquals(1, schools.school(id).getRevision());
+                return null;
+            });
+        } finally {
+            delete(id);
+        }
+    }
+
+    public @Test void changedSchoolInputsRejectAnOlderSolverSnapshot() throws Exception {
+        final long id = create();
+        try {
+            final Show show = fixture(id);
+            final nl.agilecc.agiledancers.model.scheduling.SchedulingInput input =
+                    transactions.background(() -> schools.beginScheduling(id, show.getId()));
+            transactions.request(id, 1L, true, () -> schools.updateSchool(id, "Changed"));
+            final nl.agilecc.agiledancers.service.ManagementException failure = assertThrows(
+                    nl.agilecc.agiledancers.service.ManagementException.class,
+                    () -> transactions.background(() -> {
+                        schools.finishScheduling(
+                                id,
+                                input,
+                                new nl.agilecc.agiledancers.model.scheduling.SchedulingResult(
+                                        true, List.of(List.of())));
+                        return null;
+                    }));
+            assertEquals(nl.agilecc.agiledancers.service.ManagementExceptionKind.CONFLICT, failure.getKind());
+            transactions.background(() -> {
+                assertEquals(
+                        1,
+                        schools.show(id, show.getId())
+                                .getDayParts()
+                                .getFirst()
+                                .getDanceGroups()
+                                .size());
+                schools.endScheduling(show.getId());
+                return null;
+            });
+        } finally {
+            delete(id);
+        }
+    }
+
+    public @Test void hibernateVersionRejectsDetachedStaleEntities() throws Exception {
+        final long id = create();
+        try {
+            final nl.agilecc.agiledancers.repository.entity.SchoolEntity stale = database.transaction(
+                    () -> entities.find(nl.agilecc.agiledancers.repository.entity.SchoolEntity.class, id));
+            database.transaction(() -> {
+                entities.find(nl.agilecc.agiledancers.repository.entity.SchoolEntity.class, id)
+                        .setName("Confirmed");
+                return null;
+            });
+            stale.setName("Stale");
+            assertThrows(
+                    nl.agilecc.agiledancers.repository.RevisionConflictException.class,
+                    () -> database.transaction(() -> entities.merge(stale)));
+            transactions.background(() -> {
+                assertEquals("Confirmed", schools.school(id).getName());
+                assertEquals(1, schools.school(id).getRevision());
+                return null;
+            });
+        } finally {
+            delete(id);
+        }
+    }
+
+    public @Test void childOnlyEditsAdvanceTheAggregateVersionOnce() throws Exception {
+        final long id = create();
+        try {
+            fixture(id);
+            transactions.request(id, 1L, true, () -> {
+                final long dancerId = schools.dancers(id).getFirst().getId();
+                return schools.updateDancer(id, dancerId, "Updated dancer", LocalDate.of(2000, 1, 1));
+            });
+            transactions.background(() -> {
+                assertEquals(2, schools.school(id).getRevision());
+                assertEquals("Updated dancer", schools.dancers(id).getFirst().getName());
+                return null;
+            });
+        } finally {
+            delete(id);
+        }
+    }
+
+    public @Test void hibernateRetainsAssignmentsWhenDayPartsAreReordered() throws Exception {
+        final long id = create();
+        try {
+            final Show show = fixture(id);
+            final DayPart added = DayPart.builder()
+                    .date(LocalDate.of(2027, 1, 2))
+                    .type(DayPartType.EVENING)
+                    .danceGroups(List.of())
+                    .build();
+            transactions.request(
+                    id,
+                    1L,
+                    true,
+                    () -> schools.updateShow(
+                            id,
+                            show.getId(),
+                            "Two parts",
+                            List.of(show.getDayParts().getFirst(), added),
+                            null));
+            transactions.request(id, 2L, true, () -> {
+                final Show current = schools.show(id, show.getId());
+                return schools.updateShow(
+                        id,
+                        show.getId(),
+                        "Swapped",
+                        List.of(
+                                current.getDayParts().getLast(),
+                                current.getDayParts().getFirst()),
+                        null);
+            });
+            transactions.background(() -> {
+                final Show restored = schools.show(id, show.getId());
+                assertEquals(added.getDate(), restored.getDayParts().getFirst().getDate());
+                assertEquals(
+                        1, restored.getDayParts().getLast().getDanceGroups().size());
+                assertEquals(3, schools.school(id).getRevision());
+                return null;
+            });
+        } finally {
+            delete(id);
+        }
+    }
+
+    private void damageResult(
+            final long id,
+            final Show show,
+            final SchedulingRun run,
+            final java.util.concurrent.atomic.AtomicBoolean published)
+            throws Exception {
+        database.transaction(() -> {
+            entities.find(nl.agilecc.agiledancers.repository.entity.SchoolEntity.class, id)
+                    .setName("Uncommitted");
+            entities.find(
+                            nl.agilecc.agiledancers.repository.entity.DayPartEntity.class,
+                            new nl.agilecc.agiledancers.repository.entity.DayPartId(id, show.getId(), 0))
+                    .getGroupIds()
+                    .clear();
+            runs.save(run.completed(SchedulingState.OPTIMAL, "Uncommitted", new SchedulingSummary(0, 0, 0)));
+            database.afterCommit(() -> published.set(true));
+            // This dancer FK is deferred: work returns normally, and commit itself must fail.
+            entities.find(
+                            nl.agilecc.agiledancers.repository.entity.GroupEntity.class,
+                            new nl.agilecc.agiledancers.repository.entity.SchoolMemberId(
+                                    id,
+                                    show.getDayParts()
+                                            .getFirst()
+                                            .getDanceGroups()
+                                            .getFirst()
+                                            .getId()))
+                    .getDancerIds()
+                    .add(999999L);
+            return null;
+        });
+    }
+
+    private long create() throws Exception {
+        return (Long) transactions.request(
+                null,
+                null,
+                true,
+                () -> schools.createSchool("Persistent school").getId());
+    }
+
+    private Show fixture(final long id) throws Exception {
+        return (Show) transactions.request(id, 0L, true, () -> {
+            final long dancer =
+                    schools.createDancer(id, "Dancer", LocalDate.of(2000, 1, 1)).getId();
+            final long group = schools.createGroup(
+                            id, new GroupDetails("Group", DanceGroupType.REGULAR, 0, 99, Set.of(DanceGroupStyle.JAZZ)))
+                    .getId();
+            schools.addGroupDancer(id, group, dancer);
+            final Show show = schools.createShow(
+                    id,
+                    "Saved show",
+                    List.of(DayPart.builder()
+                            .date(LocalDate.of(2027, 1, 1))
+                            .type(DayPartType.MORNING)
+                            .danceGroups(List.of(schools.group(id, group)))
+                            .build()),
+                    null);
+            show.setFinalized(true);
+            return show;
+        });
+    }
+
+    private int rename(final String path, final String name, final long revision) {
+        return given().header("X-School-Revision", revision)
+                .contentType("application/json")
+                .body(java.util.Map.of("name", name))
+                .put(path)
+                .statusCode();
+    }
+
+    private void delete(final long id) {
+        transactions.background(() -> {
+            writer.delete(id);
+            return null;
+        });
+    }
+}

agiledancers-be/src/test/java/nl/agilecc/agiledancers/RevisionRequests.java

@@ -0,0 +1,50 @@
+package nl.agilecc.agiledancers;
+
+import io.restassured.RestAssured;
+import io.restassured.response.Response;
+import io.restassured.specification.FilterableRequestSpecification;
+import io.restassured.specification.RequestSpecification;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+/** Existing endpoint scenarios use fresh revisions; concurrency tests deliberately send explicit stale revisions. */
+public class RevisionRequests {
+    private static final Pattern SCHOOL = Pattern.compile("/api/dance-schools/(\\d+)(?:/|$)");
+    private static final Pattern REPLACEMENT = Pattern.compile("[?&]replaceId=(\\d+)");
+
+    public static RequestSpecification given() {
+        return RestAssured.given()
+                .filter(
+                        (final FilterableRequestSpecification request,
+                                final io.restassured.specification.FilterableResponseSpecification response,
+                                final io.restassured.filter.FilterContext context) -> {
+                            addRevision(request);
+                            return context.next(request, response);
+                        });
+    }
+
+    private static void addRevision(final FilterableRequestSpecification request) {
+        final String id = schoolId(request);
+        if (!request.getMethod().equals("GET")
+                && id != null
+                && !request.getHeaders().hasHeaderWithName("X-School-Revision")) {
+            final Response school = RestAssured.given().get("/api/dance-schools/" + id);
+            if (school.statusCode() == 200) {
+                request.header("X-School-Revision", school.jsonPath().getLong("revision"));
+            }
+        }
+    }
+
+    private static String schoolId(final FilterableRequestSpecification request) {
+        final Matcher school = SCHOOL.matcher(request.getURI());
+        if (school.find()) {
+            return school.group(1);
+        }
+        final Matcher replacement = REPLACEMENT.matcher(request.getURI());
+        if (replacement.find()) {
+            return replacement.group(1);
+        }
+        final Object parameter = request.getQueryParams().get("replaceId");
+        return parameter == null ? null : parameter.toString();
+    }
+}

agiledancers-be/src/test/java/nl/agilecc/agiledancers/S18ResourceTest.java

@@ -1,6 +1,6 @@
 package nl.agilecc.agiledancers;
 
-import static io.restassured.RestAssured.given;
+import static nl.agilecc.agiledancers.RevisionRequests.given;
 import static org.hamcrest.Matchers.empty;
 import static org.hamcrest.Matchers.equalTo;
 import static org.hamcrest.Matchers.hasSize;

agiledancers-be/src/test/java/nl/agilecc/agiledancers/SchedulingEventsTest.java

@@ -1,6 +1,6 @@
 package nl.agilecc.agiledancers;
 
-import static io.restassured.RestAssured.given;
+import static nl.agilecc.agiledancers.RevisionRequests.given;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
 import static org.junit.jupiter.api.Assertions.assertTrue;
@@ -36,12 +36,14 @@ import org.junit.jupiter.api.Test;
 class SchedulingEventsTest {
     private @Inject SchoolManagementService schools;
     private @Inject ObjectMapper json;
+    private @Inject nl.agilecc.agiledancers.service.SchoolTransactions transactions;
     private @TestHTTPResource URI base;
 
     public @Test void streamStartsWithSnapshotAndPushesCompletionAndReconnectSnapshot() throws Exception {
-        final long school = schools.createSchool("SSE school").getId();
+        final long school = (Long) transactions.request(
+                null, null, true, () -> schools.createSchool("SSE school").getId());
         try {
-            final Show show = show(school);
+            final Show show = (Show) transactions.request(school, 0L, true, () -> show(school));
             final String path = "/api/dance-schools/" + school + "/shows/" + show.getId() + "/schedule";
             given().get(path).then().statusCode(204);
             try (final HttpClient client = HttpClient.newHttpClient();
@@ -64,7 +66,7 @@ class SchedulingEventsTest {
             }
             assertReconnectContains(show.getId());
         } finally {
-            schools.deleteSchool(school);
+            given().delete("/api/dance-schools/" + school);
         }
     }
 

agiledancers-be/src/test/java/nl/agilecc/agiledancers/SchoolManagementResourceTest.java

@@ -1,6 +1,6 @@
 package nl.agilecc.agiledancers;
 
-import static io.restassured.RestAssured.given;
+import static nl.agilecc.agiledancers.RevisionRequests.given;
 import static org.hamcrest.Matchers.contains;
 import static org.hamcrest.Matchers.containsInAnyOrder;
 import static org.hamcrest.Matchers.empty;

agiledancers-be/src/test/java/nl/agilecc/agiledancers/SchoolSnapshotResourceTest.java

@@ -1,6 +1,6 @@
 package nl.agilecc.agiledancers;
 
-import static io.restassured.RestAssured.given;
+import static nl.agilecc.agiledancers.RevisionRequests.given;
 import static org.hamcrest.Matchers.containsString;
 import static org.hamcrest.Matchers.emptyOrNullString;
 import static org.hamcrest.Matchers.equalTo;

agiledancers-be/src/test/java/nl/agilecc/agiledancers/service/SchedulingRunsTest.java

@@ -19,11 +19,11 @@ import nl.agilecc.agiledancers.model.Show;
 import nl.agilecc.agiledancers.model.scheduling.SchedulingFailureKind;
 import nl.agilecc.agiledancers.model.scheduling.SchedulingInput;
 import nl.agilecc.agiledancers.model.scheduling.SchedulingResult;
+import nl.agilecc.agiledancers.model.scheduling.SchedulingRun;
+import nl.agilecc.agiledancers.model.scheduling.SchedulingState;
 import nl.agilecc.agiledancers.model.specifications.DanceGroupType;
 import nl.agilecc.agiledancers.model.specifications.DayPartType;
 import nl.agilecc.agiledancers.service.model.GroupDetails;
-import nl.agilecc.agiledancers.service.model.SchedulingRun;
-import nl.agilecc.agiledancers.service.model.SchedulingState;
 import nl.agilecc.agiledancers.service.port.SchedulingEngine;
 import nl.agilecc.agiledancers.solver.OrToolsSchedulingEngine;
 import org.junit.jupiter.api.Test;
@@ -136,6 +136,71 @@ class SchedulingRunsTest {
         schools.endScheduling(schools.beginScheduling(school, show.getId()).showId());
     }
 
+    public @Test void databaseRecoveryPersistsPendingFailureWithoutRestart() throws Exception {
+        final Show show = show();
+        final var entered = new CountDownLatch(1);
+        final var release = new CountDownLatch(1);
+        final var persistence = new OutagePersistence();
+        final var runs = new SchedulingRuns(schools, blocking(entered, release));
+        final java.lang.reflect.Field field = SchedulingRuns.class.getDeclaredField("persistence");
+        field.setAccessible(true);
+        field.set(runs, persistence);
+        try {
+            final SchedulingRun started = runs.start(school, show.getId());
+            assertTrue(entered.await(10, TimeUnit.SECONDS));
+            persistence.available.set(false);
+            release.countDown();
+            assertTrue(persistence.unavailable.await(10, TimeUnit.SECONDS));
+            assertEquals(started, persistence.stored.get());
+            assertEquals(started, runs.status(school, show.getId()));
+            assertThrows(ManagementException.class, () -> runs.start(school, show.getId()));
+            persistence.available.set(true);
+            final SchedulingRun completed = await(runs, show);
+            assertEquals(SchedulingState.SOLVER_FAILED, completed.state());
+            assertEquals(started.runId(), completed.runId());
+            assertEquals(completed, persistence.stored.get());
+            schools.endScheduling(schools.beginScheduling(school, show.getId()).showId());
+        } finally {
+            persistence.available.set(true);
+            release.countDown();
+            runs.close();
+        }
+    }
+
+    private static class OutagePersistence extends SchedulingPersistence {
+        private final CountDownLatch unavailable = new CountDownLatch(2);
+        private final java.util.concurrent.atomic.AtomicBoolean available =
+                new java.util.concurrent.atomic.AtomicBoolean(true);
+        private final AtomicReference<SchedulingRun> stored = new AtomicReference<>();
+
+        private OutagePersistence() {
+            super(null, null, null);
+        }
+
+        public @Override <T> T work(final java.util.concurrent.Callable<T> action) {
+            if (!available.get()) {
+                unavailable.countDown();
+                throw new nl.agilecc.agiledancers.repository.StorageException(new IllegalStateException("offline"));
+            }
+            try {
+                return action.call();
+            } catch (final RuntimeException failure) {
+                throw failure;
+            } catch (final Exception failure) {
+                throw new IllegalStateException(failure);
+            }
+        }
+
+        public @Override void accepted(final SchedulingRun run, final Runnable launch, final Runnable rollback) {
+            save(run, launch);
+        }
+
+        public @Override void save(final SchedulingRun run, final Runnable publication) {
+            stored.set(run);
+            publication.run();
+        }
+    }
+
     private Show show() {
         final long group = schools.createGroup(
                         school, new GroupDetails("Group", DanceGroupType.REGULAR, 0, 99, Set.of()))

agiledancers-fe/e2e/school-management.spec.ts

@@ -1,4 +1,4 @@
-import { test, expect, Page } from '@playwright/test';
+import { test, expect, Page, APIRequestContext } from '@playwright/test';
 import type { School } from '../src/app/core/api-models';
 
 const backend = process.env['PLAYWRIGHT_BASE_URL'] || 'http://127.0.0.1:8080';
@@ -6,11 +6,23 @@ let schoolToDelete: number | undefined;
 
 test.afterEach(async ({ request }) => {
   if (schoolToDelete !== undefined) {
-    await request.delete(`${backend}/api/dance-schools/${schoolToDelete}`);
+    await request.delete(`${backend}/api/dance-schools/${schoolToDelete}`, {
+      headers: await revision(request, schoolToDelete),
+    });
     schoolToDelete = undefined;
   }
 });
 
+async function revision(
+  request: APIRequestContext,
+  schoolId: number,
+): Promise<Record<string, string>> {
+  const school = (await (
+    await request.get(`${backend}/api/dance-schools/${schoolId}`)
+  ).json()) as School;
+  return { 'X-School-Revision': String(school.revision) };
+}
+
 async function tab(page: Page, label: string) {
   await page
     .getByRole('navigation', { name: 'Dansschool onderdelen' })
@@ -113,6 +125,7 @@ test('manages a school, shared memberships and shows through the real REST API',
     const dancerResponse = await request.post(
       `${backend}/api/dance-schools/${schoolToDelete}/dancers`,
       {
+        headers: await revision(request, schoolToDelete),
         data: { name, birthDate: '1990-01-01' },
       },
     );
@@ -120,14 +133,17 @@ test('manages a school, shared memberships and shows through the real REST API',
     const groupResponse = await request.post(
       `${backend}/api/dance-schools/${schoolToDelete}/dance-groups`,
       {
+        headers: await revision(request, schoolToDelete),
         data: { category: name, type: 'REGULAR', startAge: 0, endAge: 99, styles: ['MODERN'] },
       },
     );
     const group = (await groupResponse.json()) as { id: number };
     await request.put(
       `${backend}/api/dance-schools/${schoolToDelete}/dance-groups/${group.id}/dancers/${dancer.id}`,
+      { headers: await revision(request, schoolToDelete) },
     );
   }
+  await page.reload();
   await tab(page, 'Shows');
   await page.getByRole('button', { name: 'Show toevoegen' }).click();
   await page.getByRole('dialog').getByLabel('Naam', { exact: true }).fill('Zomershow');
@@ -214,12 +230,14 @@ test('links a coach and finalizes performances spread across multiple dates', as
   schoolToDelete = school.id;
   const base = `${backend}/api/dance-schools/${school.id}`;
   const dancerResponse = await request.post(`${base}/dancers`, {
+    headers: await revision(request, school.id),
     data: { name: 'Dancing coach', birthDate: '1990-01-01' },
   });
   const dancer = (await dancerResponse.json()) as { id: number };
   const groupIds: number[] = [];
   for (const name of ['Preschool', 'Adults']) {
     const response = await request.post(`${base}/dance-groups`, {
+      headers: await revision(request, school.id),
       data: {
         category: name,
         type: name === 'Preschool' ? 'PRE_SCHOOLER' : 'REGULAR',
@@ -230,9 +248,12 @@ test('links a coach and finalizes performances spread across multiple dates', as
     });
     const group = (await response.json()) as { id: number };
     groupIds.push(group.id);
-    await request.put(`${base}/dance-groups/${group.id}/dancers/${dancer.id}`);
+    await request.put(`${base}/dance-groups/${group.id}/dancers/${dancer.id}`, {
+      headers: await revision(request, school.id),
+    });
   }
   const showResponse = await request.post(`${base}/shows`, {
+    headers: await revision(request, school.id),
     data: {
       name: 'Coach across dates',
       preferredDayParts: 1,
@@ -244,6 +265,7 @@ test('links a coach and finalizes performances spread across multiple dates', as
   });
   const show = (await showResponse.json()) as { id: number };
   await request.put(`${base}/shows/${show.id}/assignments`, {
+    headers: await revision(request, school.id),
     data: { assignments: groupIds.map((id) => [id]) },
   });
   await page.goto(`/schools/${school.id}/shows`);
@@ -271,3 +293,39 @@ test('shows a useful connection error and recovers on retry', async ({ page }) =
   await page.getByRole('button', { name: 'Opnieuw proberen' }).click();
   await expect(page.getByRole('heading', { name: /Mijn dansscholen/ })).toBeVisible();
 });
+
+test('rejects a stale editor in another screen and allows reload and retry', async ({
+  page,
+  request,
+}) => {
+  const response = await request.post(`${backend}/api/dance-schools`, {
+    data: { name: `Concurrent school ${Date.now()}` },
+  });
+  const school = (await response.json()) as School;
+  schoolToDelete = school.id;
+  const other = await page.context().newPage();
+  try {
+    for (const screen of [page, other]) {
+      await screen.goto(`/schools/${school.id}/overview`);
+      await screen.getByRole('button', { name: 'School bewerken' }).click();
+    }
+    await page.getByRole('dialog').getByLabel('Naam', { exact: true }).fill('First confirmed edit');
+    await other.getByRole('dialog').getByLabel('Naam', { exact: true }).fill('Stale edit');
+    await save(page);
+    await other.getByRole('dialog').getByRole('button', { name: 'Opslaan', exact: true }).click();
+    await expect(other.getByRole('dialog').getByRole('alert')).toContainText('Herlaad');
+    await expect(other.getByRole('dialog').getByLabel('Naam', { exact: true })).toHaveValue(
+      'Stale edit',
+    );
+    await other.reload();
+    await expect(
+      other.getByRole('heading', { name: 'First confirmed edit', exact: true }),
+    ).toBeVisible();
+    await other.getByRole('button', { name: 'School bewerken' }).click();
+    await other.getByRole('dialog').getByLabel('Naam', { exact: true }).fill('Reloaded edit');
+    await save(other);
+    await expect(other.getByRole('heading', { name: 'Reloaded edit', exact: true })).toBeVisible();
+  } finally {
+    await other.close();
+  }
+});

agiledancers-fe/package.json

@@ -14,24 +14,24 @@
   },
   "private": true,
   "dependencies": {
-    "@angular/common": "22.2.3",
+    "@angular/common": "22.2.4",
-    "@angular/compiler": "22.2.3",
+    "@angular/compiler": "22.2.4",
-    "@angular/core": "22.2.3",
+    "@angular/core": "22.2.4",
-    "@angular/forms": "22.2.3",
+    "@angular/forms": "22.2.4",
-    "@angular/platform-browser": "22.2.3",
+    "@angular/platform-browser": "22.2.4",
-    "@angular/router": "22.2.3",
+    "@angular/router": "22.2.4",
     "rxjs": "7.8.2",
     "tslib": "2.8.1"
   },
   "devDependencies": {
-    "@angular/build": "22.2.4",
+    "@angular/build": "22.2.6",
-    "@angular/cli": "22.2.4",
+    "@angular/cli": "22.2.6",
-    "@angular/compiler-cli": "22.2.3",
+    "@angular/compiler-cli": "22.2.4",
     "@eslint/js": "10.0.1",
     "@playwright/test": "1.64.1",
     "@types/node": "22.20.5",
     "angular-eslint": "22.6.0",
-    "eslint": "10.13.0",
+    "eslint": "10.14.0",
     "eslint-config-prettier": "10.1.8",
     "globals": "17.13.0",
     "husky": "9.1.7",

agiledancers-fe/src/app/core/api-models.ts

@@ -1,5 +1,6 @@
 export interface School {
   id: number;
+  revision: number;
   name: string;
   dancerIds: number[];
   danceGroupIds: number[];

agiledancers-fe/src/app/core/scheduling-status.ts

@@ -2,6 +2,7 @@ import { DestroyRef, inject, Injectable, signal } from '@angular/core';
 
 export type SchedulingState =
   | 'RUNNING'
+  | 'INTERRUPTED'
   | 'OPTIMAL'
   | 'VALID'
   | 'STALE'

agiledancers-fe/src/app/core/school-api.spec.ts

@@ -18,13 +18,17 @@ describe('SchoolApi contract', () => {
   it('loads all resources from the same school', () => {
     const received = vi.fn();
     api.schoolData(7).subscribe(received);
-    const school = { id: 7, name: 'Studio', dancerIds: [], danceGroupIds: [], showIds: [] };
+    const school = {
-    http.expectOne('/api/dance-schools/7').flush(school);
+      id: 7,
-    http.expectOne('/api/dance-schools/7/dancers').flush([]);
+      name: 'Studio',
-    http.expectOne('/api/dance-schools/7/dance-groups').flush([]);
+      revision: 0,
-    expect(received).not.toHaveBeenCalled();
+      dancerIds: [],
-    http.expectOne('/api/dance-schools/7/shows').flush([]);
+      danceGroupIds: [],
-    http.expectOne('/api/dance-schools/7/coaches').flush([]);
+      showIds: [],
+    };
+    http
+      .expectOne('/api/dance-schools/7/data')
+      .flush({ school, dancers: [], groups: [], shows: [], coaches: [] });
     expect(received).toHaveBeenCalledWith({
       school,
       dancers: [],
@@ -34,12 +38,32 @@ describe('SchoolApi contract', () => {
     });
   });
 
+  it('sends the loaded school revision without retrying a stale mutation', () => {
+    api.schoolData(7).subscribe();
+    http
+      .expectOne('/api/dance-schools/7/data')
+      .flush({ school: { id: 7, revision: 4 }, dancers: [], groups: [], shows: [], coaches: [] });
+    const failure = vi.fn();
+    api.saveDancer(7, { name: 'Sam', birthDate: '2010-05-12' }).subscribe({ error: failure });
+    const request = http.expectOne('/api/dance-schools/7/dancers');
+    expect(request.request.headers.get('X-School-Revision')).toBe('4');
+    request.flush({ message: 'Herlaad de gegevens' }, { status: 409, statusText: 'Conflict' });
+    expect(failure).toHaveBeenCalledOnce();
+  });
+
   it('updates an existing entity even when its id is zero', () => {
     api.saveSchool({ name: 'Renamed' }, 0).subscribe();
     const request = http.expectOne('/api/dance-schools/0');
     expect(request.request.method).toBe('PUT');
     expect(request.request.body).toEqual({ name: 'Renamed' });
-    request.flush({ id: 0, name: 'Renamed', dancerIds: [], danceGroupIds: [], showIds: [] });
+    request.flush({
+      id: 0,
+      name: 'Renamed',
+      revision: 0,
+      dancerIds: [],
+      danceGroupIds: [],
+      showIds: [],
+    });
   });
 
   it('keeps group details separate from memberships', () => {

agiledancers-fe/src/app/core/school-api.ts

@@ -1,7 +1,7 @@
 import { SchedulingRun } from './scheduling-status';
 import { inject, Injectable } from '@angular/core';
 import { HttpClient } from '@angular/common/http';
-import { forkJoin, Observable } from 'rxjs';
+import { Observable, tap } from 'rxjs';
 import {
   Coach,
   DanceGroup,
@@ -20,64 +20,114 @@ import {
 export class SchoolApi {
   private readonly http = inject(HttpClient);
   private readonly base = '/api/dance-schools';
+  private readonly revisions = new Map<number, number>();
 
   schools(): Observable<School[]> {
-    return this.http.get<School[]>(this.base);
+    return this.http.get<School[]>(this.base).pipe(
+      tap((schools) => {
+        for (const school of schools) this.revisions.set(school.id, school.revision);
+      }),
+    );
   }
   schoolData(schoolId: number): Observable<SchoolData> {
-    const base = `${this.base}/${schoolId}`;
+    return this.http
-    return forkJoin({
+      .get<SchoolData>(`${this.base}/${schoolId}/data`)
-      school: this.http.get<School>(base),
+      .pipe(tap((data) => this.revisions.set(schoolId, data.school.revision)));
-      dancers: this.http.get<Dancer[]>(`${base}/dancers`),
-      groups: this.http.get<DanceGroup[]>(`${base}/dance-groups`),
-      shows: this.http.get<Show[]>(`${base}/shows`),
-      coaches: this.http.get<Coach[]>(`${base}/coaches`),
-    });
   }
-  saveSchool(body: SchoolRequest, id?: number): Observable<School> {
+  private options(schoolId: number, expected?: number): { headers: Record<string, string> } {
+    const revision = expected ?? this.revisions.get(schoolId);
+    return { headers: revision === undefined ? {} : { 'X-School-Revision': String(revision) } };
+  }
+  saveSchool(body: SchoolRequest, id?: number, revision?: number): Observable<School> {
     return id === undefined
       ? this.http.post<School>(this.base, body)
-      : this.http.put<School>(`${this.base}/${id}`, body);
+      : this.http.put<School>(`${this.base}/${id}`, body, this.options(id, revision));
   }
-  saveDancer(schoolId: number, body: DancerRequest, id?: number): Observable<Dancer> {
+  saveDancer(
-    return this.save(`${this.base}/${schoolId}/dancers`, body, id);
+    schoolId: number,
+    body: DancerRequest,
+    id?: number,
+    revision?: number,
+  ): Observable<Dancer> {
+    return this.save(`${this.base}/${schoolId}/dancers`, body, schoolId, id, revision);
   }
-  saveGroup(schoolId: number, body: GroupRequest, id?: number): Observable<DanceGroup> {
+  saveGroup(
-    return this.save(`${this.base}/${schoolId}/dance-groups`, body, id);
+    schoolId: number,
+    body: GroupRequest,
+    id?: number,
+    revision?: number,
+  ): Observable<DanceGroup> {
+    return this.save(`${this.base}/${schoolId}/dance-groups`, body, schoolId, id, revision);
   }
-  saveShow(schoolId: number, body: ShowRequest, id?: number): Observable<Show> {
+  saveShow(schoolId: number, body: ShowRequest, id?: number, revision?: number): Observable<Show> {
-    return this.save(`${this.base}/${schoolId}/shows`, body, id);
+    return this.save(`${this.base}/${schoolId}/shows`, body, schoolId, id, revision);
   }
   schedule(schoolId: number, showId: number): Observable<SchedulingRun> {
-    return this.http.post<SchedulingRun>(`${this.base}/${schoolId}/shows/${showId}/schedule`, null);
+    return this.http.post<SchedulingRun>(
+      `${this.base}/${schoolId}/shows/${showId}/schedule`,
+      null,
+      this.options(schoolId),
+    );
   }
-  saveAssignments(schoolId: number, showId: number, assignments: number[][]): Observable<Show> {
+  saveAssignments(
-    return this.http.put<Show>(`${this.base}/${schoolId}/shows/${showId}/assignments`, {
+    schoolId: number,
-      assignments,
+    showId: number,
-    });
+    assignments: number[][],
+    revision?: number,
+  ): Observable<Show> {
+    return this.http.put<Show>(
+      `${this.base}/${schoolId}/shows/${showId}/assignments`,
+      {
+        assignments,
+      },
+      this.options(schoolId, revision),
+    );
   }
-  finalize(schoolId: number, showId: number): Observable<Show> {
+  finalize(schoolId: number, showId: number, revision?: number): Observable<Show> {
-    return this.http.post<Show>(`${this.base}/${schoolId}/shows/${showId}/finalize`, null);
+    return this.http.post<Show>(
+      `${this.base}/${schoolId}/shows/${showId}/finalize`,
+      null,
+      this.options(schoolId, revision),
+    );
   }
   linkCoach(schoolId: number, dancerId: number, coachId?: number): Observable<Coach> {
-    return this.save<Coach>(`${this.base}/${schoolId}/coaches`, { dancerId }, coachId);
+    return this.save<Coach>(`${this.base}/${schoolId}/coaches`, { dancerId }, schoolId, coachId);
   }
   unlinkCoach(schoolId: number, coachId: number): Observable<void> {
-    return this.http.delete<void>(`${this.base}/${schoolId}/coaches/${coachId}/dancer`);
+    return this.http.delete<void>(
+      `${this.base}/${schoolId}/coaches/${coachId}/dancer`,
+      this.options(schoolId),
+    );
   }
-  delete(kind: ResourceKind, schoolId: number, id: number): Observable<void> {
+  delete(kind: ResourceKind, schoolId: number, id: number, revision?: number): Observable<void> {
     const collection = { school: '', dancer: '/dancers', group: '/dance-groups', show: '/shows' }[
       kind
     ];
     const url =
       kind === 'school' ? `${this.base}/${id}` : `${this.base}/${schoolId}${collection}/${id}`;
-    return this.http.delete<void>(url);
+    return this.http.delete<void>(url, this.options(schoolId, revision));
   }
-  membership(schoolId: number, groupId: number, dancerId: number, add: boolean): Observable<void> {
+  membership(
+    schoolId: number,
+    groupId: number,
+    dancerId: number,
+    add: boolean,
+    revision?: number,
+  ): Observable<void> {
     const url = `${this.base}/${schoolId}/dance-groups/${groupId}/dancers/${dancerId}`;
-    return add ? this.http.put<void>(url, null) : this.http.delete<void>(url);
+    return add
+      ? this.http.put<void>(url, null, this.options(schoolId, revision))
+      : this.http.delete<void>(url, this.options(schoolId, revision));
   }
-  private save<T>(url: string, body: unknown, id?: number): Observable<T> {
+  private save<T>(
-    return id === undefined ? this.http.post<T>(url, body) : this.http.put<T>(`${url}/${id}`, body);
+    url: string,
+    body: unknown,
+    schoolId: number,
+    id?: number,
+    revision?: number,
+  ): Observable<T> {
+    return id === undefined
+      ? this.http.post<T>(url, body, this.options(schoolId, revision))
+      : this.http.put<T>(`${url}/${id}`, body, this.options(schoolId, revision));
   }
 }

agiledancers-fe/src/app/schools/school-page.html

@@ -477,6 +477,7 @@
     <app-entity-editor
       [target]="target"
       [schoolId]="context.school.id"
+      [revision]="context.school.revision"
       [shows]="context.shows"
       (closed)="editor.set(null)"
       (saved)="saved()"
@@ -487,6 +488,7 @@
       [show]="show"
       [groups]="context.groups"
       [schoolId]="context.school.id"
+      [revision]="context.school.revision"
       (closed)="scheduleEditing.set(null)"
       (saved)="reload()"
     />
@@ -495,6 +497,7 @@
     <app-group-members
       [group]="group"
       [schoolId]="context.school.id"
+      [revision]="context.school.revision"
       [dancers]="context.dancers"
       (closed)="members.set(null)"
       (changed)="membershipChanged($event)"

agiledancers-fe/src/app/schools/school-page.ts

@@ -219,7 +219,10 @@ export class SchoolPage implements OnInit {
         .join(', ') || 'Nog geen groep'
     );
   }
+  private deletionRevision?: number;
+
   askDelete(target: DeleteTarget): void {
+    this.deletionRevision = this.data()?.school.revision;
     this.deleteError.set('');
     if (target.kind === 'group') {
       const names =
@@ -255,7 +258,9 @@ export class SchoolPage implements OnInit {
     this.deleteBusy.set(true);
     this.deleteError.set('');
     try {
-      await firstValueFrom(this.api.delete(target.kind, schoolId, target.id));
+      await firstValueFrom(
+        this.api.delete(target.kind, schoolId, target.id, this.deletionRevision),
+      );
       this.deleting.set(null);
       if (target.kind === 'school') await this.router.navigate(['/schools']);
       else {

agiledancers-fe/src/app/shared/entity-editor.spec.ts

@@ -50,11 +50,33 @@ describe('EntityEditor', () => {
     const saved = vi.fn();
     component.saved.subscribe(saved);
     await component.save();
-    expect(api.saveSchool).toHaveBeenCalledWith({ name: 'Studio' }, undefined);
+    expect(api.saveSchool).toHaveBeenCalledWith({ name: 'Studio' }, undefined, undefined);
     expect(saved).toHaveBeenCalledOnce();
     expect(component.busy()).toBe(false);
   });
 
+  it('retains the revision from opening the editor across background refreshes', async () => {
+    api.saveDancer.mockReturnValue(of({ id: 3 }));
+    const fixture = TestBed.createComponent(EntityEditor);
+    fixture.componentRef.setInput('target', {
+      kind: 'dancer',
+      value: { id: 3, name: 'Sam', birthDate: '2010-01-01' },
+    });
+    fixture.componentRef.setInput('schoolId', 7);
+    fixture.componentRef.setInput('revision', 4);
+    const component = fixture.componentInstance;
+    component.ngOnInit();
+    fixture.componentRef.setInput('revision', 5);
+    component.name = 'Sam edited';
+    await component.save();
+    expect(api.saveDancer).toHaveBeenCalledWith(
+      7,
+      { name: 'Sam edited', birthDate: '2010-01-01' },
+      3,
+      4,
+    );
+  });
+
   it('keeps the editor open and preserves input when saving fails', async () => {
     api.saveSchool.mockReturnValue(throwError(() => new HttpErrorResponse({ status: 0 })));
     const component = editor({ kind: 'school' });
@@ -116,6 +138,7 @@ describe('EntityEditor', () => {
       7,
       expect.objectContaining({ preferredDayParts: 1 }),
       undefined,
+      undefined,
     );
   });
 

agiledancers-fe/src/app/shared/entity-editor.ts

@@ -174,6 +174,8 @@ import { DialogFrame } from './dialog-frame';
 })
 export class EntityEditor implements OnInit {
   readonly target = input.required<EditorTarget>();
+  readonly revision = input<number>();
+  private originalRevision?: number;
   readonly schoolId = input<number>();
   readonly shows = input<Show[]>([]);
   readonly closed = output<void>();
@@ -207,6 +209,7 @@ export class EntityEditor implements OnInit {
     return `${labels[this.target().kind]} ${this.target().value ? 'bewerken' : 'toevoegen'}`;
   }
   ngOnInit(): void {
+    this.originalRevision = this.revision();
     const target = this.target();
     if (!target.value) return;
     if (target.kind === 'group') {
@@ -298,13 +301,14 @@ export class EntityEditor implements OnInit {
     let request: Observable<unknown>;
     switch (target.kind) {
       case 'school':
-        request = this.api.saveSchool({ name: this.name.trim() }, id);
+        request = this.api.saveSchool({ name: this.name.trim() }, id, this.originalRevision);
         break;
       case 'dancer':
         request = this.api.saveDancer(
           schoolId!,
           { name: this.name.trim(), birthDate: this.date },
           id,
+          this.originalRevision,
         );
         break;
       case 'group':
@@ -318,6 +322,7 @@ export class EntityEditor implements OnInit {
             styles: this.selectedStyles,
           },
           id,
+          this.originalRevision,
         );
         break;
       case 'show':
@@ -329,6 +334,7 @@ export class EntityEditor implements OnInit {
             preferredDayParts: this.preferredDayParts,
           },
           id,
+          this.originalRevision,
         );
         break;
     }

agiledancers-fe/src/app/shared/group-members.ts

@@ -57,6 +57,8 @@ import { DialogFrame } from './dialog-frame';
   `,
 })
 export class GroupMembers implements OnInit {
+  readonly revision = input<number>();
+  private originalRevision?: number;
   readonly schoolId = input.required<number>();
   readonly group = input.required<DanceGroup>();
   readonly dancers = input.required<Dancer[]>();
@@ -70,6 +72,7 @@ export class GroupMembers implements OnInit {
   );
   private readonly api = inject(SchoolApi);
   ngOnInit(): void {
+    this.originalRevision = this.revision();
     this.memberIds.set([...this.group().dancerIds]);
   }
   async toggle(dancerId: number, event: Event): Promise<void> {
@@ -82,7 +85,10 @@ export class GroupMembers implements OnInit {
     this.busy.set(true);
     this.error.set('');
     try {
-      await firstValueFrom(this.api.membership(this.schoolId(), this.group().id, dancerId, add));
+      await firstValueFrom(
+        this.api.membership(this.schoolId(), this.group().id, dancerId, add, this.originalRevision),
+      );
+      if (this.originalRevision !== undefined) this.originalRevision++;
       this.memberIds.update((ids) =>
         add ? [...ids, dancerId] : ids.filter((id) => id !== dancerId),
       );

agiledancers-fe/src/app/shared/schedule-editor.spec.ts

@@ -57,7 +57,7 @@ describe('ScheduleEditor', () => {
     const draft = { ...show, finalized: false, violations: ['Group 1 requires 1 dayparts.'] };
     api.saveAssignments.mockReturnValue(of(draft));
     await component.save();
-    expect(api.saveAssignments).toHaveBeenCalledWith(7, 4, [[2], [3]]);
+    expect(api.saveAssignments).toHaveBeenCalledWith(7, 4, [[2], [3]], undefined);
     expect(component.current()).toEqual(draft);
     expect(component.dirty()).toBe(false);
     expect(api.finalize).not.toHaveBeenCalled();

agiledancers-fe/src/app/shared/schedule-editor.ts

@@ -113,6 +113,8 @@ import { DialogFrame } from './dialog-frame';
 export class ScheduleEditor implements OnInit {
   readonly show = input.required<Show>();
   readonly groups = input.required<DanceGroup[]>();
+  readonly revision = input<number>();
+  private originalRevision?: number;
   readonly schoolId = input.required<number>();
   readonly closed = output<void>();
   readonly saved = output<void>();
@@ -124,6 +126,7 @@ export class ScheduleEditor implements OnInit {
   assignments: number[][] = [];
 
   ngOnInit(): void {
+    this.originalRevision = this.revision();
     this.current.set(this.show());
     this.assignments = this.show().dayParts.map((p) => [...p.danceGroupIds]);
   }
@@ -162,9 +165,15 @@ export class ScheduleEditor implements OnInit {
     try {
       const result = await firstValueFrom(
         finalize
-          ? this.api.finalize(this.schoolId(), this.show().id)
+          ? this.api.finalize(this.schoolId(), this.show().id, this.originalRevision)
-          : this.api.saveAssignments(this.schoolId(), this.show().id, this.assignments),
+          : this.api.saveAssignments(
+              this.schoolId(),
+              this.show().id,
+              this.assignments,
+              this.originalRevision,
+            ),
       );
+      if (this.originalRevision !== undefined) this.originalRevision++;
       this.current.set(result);
       this.assignments = result.dayParts.map((p) => [...p.danceGroupIds]);
       this.dirty.set(false);

agiledancers-fe/src/app/shared/school-transfer.ts

@@ -10,6 +10,7 @@ interface Preview {
   shows: number;
   existingId: number | null;
   existingName: string | null;
+  existingRevision: number | null;
 }
 @Component({
   selector: 'app-school-transfer',
@@ -117,7 +118,12 @@ export class SchoolTransfer {
       const query = p.existingId === null ? '' : `?replaceId=${p.existingId}`;
       await firstValueFrom(
         this.http.post(`${this.base}/import${query}`, this.json, {
-          headers: { 'Content-Type': 'application/json' },
+          headers: {
+            'Content-Type': 'application/json',
+            ...(p.existingRevision === null
+              ? {}
+              : { 'X-School-Revision': String(p.existingRevision) }),
+          },
         }),
       );
       this.cancel();

ci/runner/agiledancers-runner.service

@@ -1,19 +0,0 @@
-[Unit]
-Description=Agiledancers Gitea Actions runner
-After=network-online.target
-Wants=network-online.target
-
-[Service]
-Type=simple
-WorkingDirectory=%h/.local/share/agiledancers-runner
-EnvironmentFile=%h/.config/agiledancers-runner/environment
-ExecStartPre=/usr/bin/env java %h/.local/share/agiledancers-runner/WaitForDocker.java 120
-TimeoutStartSec=150
-ExecStart=%h/.local/bin/act_runner daemon --config %h/.local/share/agiledancers-runner/config.yaml
-Restart=on-failure
-RestartSec=10
-KillSignal=SIGTERM
-TimeoutStopSec=150
-
-[Install]
-WantedBy=default.target

ci/runner/config.yaml

@@ -6,6 +6,6 @@ runner:
   timeout: 2h
   shutdown_timeout: 2m
   labels:
-    - agiledancers-mini-pc:host
+    - mini-pc:host
 cache:
   enabled: false

ci/runner/runner.service

@@ -0,0 +1,19 @@
+[Unit]
+Description=mini-pc Gitea Actions runner
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+WorkingDirectory=%h/.local/share/mini-pc-runner
+EnvironmentFile=%h/.config/mini-pc-runner/environment
+ExecStartPre=/usr/bin/env java %h/.local/share/mini-pc-runner/WaitForDocker.java 120
+TimeoutStartSec=150
+ExecStart=%h/.local/bin/act_runner daemon --config %h/.local/share/mini-pc-runner/config.yaml
+Restart=on-failure
+RestartSec=10
+KillSignal=SIGTERM
+TimeoutStopSec=150
+
+[Install]
+WantedBy=default.target

deploy/compose.yaml

@@ -1,6 +1,27 @@
 # Images are resolved to registry digests before replacement. Never use :main here.
 services:
+  database:
+    image: postgres:17.6
+    restart: unless-stopped
+    environment:
+      POSTGRES_DB: agiledancers
+      POSTGRES_USER: agiledancers
+      POSTGRES_PASSWORD: ${DATABASE_PASSWORD:?Required database password}
+    volumes:
+      - database-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ['CMD-SHELL', 'pg_isready -U agiledancers -d agiledancers']
+      interval: 5s
+      timeout: 3s
+      retries: 12
   backend:
+    depends_on:
+      database:
+        condition: service_healthy
+    environment:
+      DATABASE_URL: jdbc:postgresql://database:5432/agiledancers
+      DATABASE_USER: agiledancers
+      DATABASE_PASSWORD: ${DATABASE_PASSWORD:?Required database password}
     image: ${BACKEND_IMAGE:?Required verified backend digest}
     platform: linux/amd64
     restart: unless-stopped
@@ -32,3 +53,7 @@ services:
       options:
         max-size: '10m'
         max-file: '3'
+
+volumes:
+  database-data:
+    name: agiledancers-production-database

deploy/health.sh

@@ -0,0 +1,7 @@
+# Application-specific readiness, retained with each release by engineering.
+application_health() {
+    frontend=$(compose ps -q frontend)
+    docker_cmd exec "$frontend" wget -q -T 5 -O /dev/null http://backend:8080/q/health/ready || return 1
+    curl --noproxy '*' --fail --silent --show-error --max-time 5 "http://$BIND_IP:$FRONTEND_PORT/" -o /dev/null || return 1
+    curl --noproxy '*' --fail --silent --show-error --max-time 5 "http://$BIND_IP:$FRONTEND_PORT/api/dance-schools" -o /dev/null
+}

deploy/production.env.example

@@ -7,3 +7,6 @@ DOCKER_BIN=/usr/local/bin/docker
 DOCKER_SUDO=1
 # The pull-only registry login is provisioned separately using docker login.
 DOCKER_CONFIG=/volume1/docker/agiledancers-production/docker-auth
+
+# Set a long random password before the first S16 deployment. Never commit its real value.
+DATABASE_PASSWORD=replace-with-a-long-random-password

docs/S19-classification.md

@@ -0,0 +1,3 @@
+# S19 resource ownership
+
+The complete [migration inventory](http://192.168.2.28:3000/wanjakrah/landscape/src/branch/main/S19-classification.md) records every source resource and its destination.

docs/S19-followup-validation.md

@@ -0,0 +1,12 @@
+# S19 review follow-up — 2026-11-10
+
+Engineering v2.0.0 at `46df72f008113d0ed683a6c7344b1d7309564d84` is pinned and committed.
+Regeneration and bootstrap --check passed against the published tag and full commit.
+Shared engineering tests passed: 8 bootstrap/generator, 21 CI and 34 release tests;
+formatter integration passed. Java launcher documentation, varargs and console API updated.
+
+Workflows use the shared user-scoped mini-pc runner for wanjakrah. It serves current
+and future repositories without per-project registration. Skills are maintained in
+landscape/skills/ and project agent instructions reference those workflows.
+Project deployment credentials and runtime configuration remain application-owned.
+No production deployment was performed.

docs/S19-validation.md

@@ -0,0 +1,36 @@
+# S19 validation
+
+The [landscape specification](http://192.168.2.28:3000/wanjakrah/landscape/src/branch/main/specs/S19.md)
+and [resource inventory](http://192.168.2.28:3000/wanjakrah/landscape/src/branch/main/S19-classification.md)
+describe the repository split. Engineering owns the shared source; this project
+consumes its selected tag and commit through engineering.lock.json.
+
+Validated on 2026-11-08:
+
+- Full Maven verification: 73 backend tests and 19 standards regression tests.
+  Existing approved waiver retained; no new waiver or threshold change.
+- Full shared pipeline: frontend lint/build, 32 frontend tests, 4 Playwright
+  tests, both prebuilt Docker images and combined backend coverage
+  1771/1841 (96.20%).
+- Standalone backend and frontend Docker source builds passed. The backend used
+  a disposable PostgreSQL container and BuildKit secrets for test configuration.
+- Shared CI/release regression suites: 19 and 34 tests respectively.
+- Engineering bootstrap/generator suite: 7 tests, covering all component choices,
+  actual Maven regeneration with generated/ absent, drift including new files,
+  obsolete-file removal, moved tags and preservation of project-owned files.
+- Formatter integration checks passed. Upstream skills and attribution files
+  match their source snapshot byte for byte; only the skills index was adapted.
+- A separate generated example passed its common pipeline and a real isolated
+  deployment of two synthetic revisions followed by rollback. Production was
+  not used. See engineering's VALIDATION.md and tests/acceptance.py.
+
+Gitea build-run evidence for the migrated application commit is recorded with
+S19 in landscape. Its workflow checks the pinned release before invoking the
+same shared pipeline. Checkout and committed generated resources require no
+sibling repository checkout.
+
+Production deployment is a separate action. Live NAS SSH authentication,
+production credentials and rollback against pre-S19 retained releases were not
+exercised. The existing Compose project, database volume and release-state schema
+remain compatible. Legacy releases without retained health.sh use the current
+application health function; review that compatibility before production rollback.

docs/backend-review.md

@@ -1,16 +1,10 @@
-# Backend review companion
+# Agile Dancers backend review companion
 
-Use alongside `skills/code-review/SKILL.md` and `CODING_STANDARDS.md`.
+Use [the shared review guidance](../generated/docs/backend-review.md),
+[code-review skill](http://192.168.2.28:3000/wanjakrah/landscape/src/branch/main/skills/code-review/SKILL.md), and
+[project standards](../CODING_STANDARDS.md).
 
-Review changed code for intent-revealing comments, missing public-contract Javadoc,
+The backend module is agiledancers-be. The approved Group constructor waiver
-appropriate record use, defensive copying of mutable record components, and
+remains application-owned in tooling/standards/waivers.tsv. Assess retained
-compatibility with APIs, JSON and persistence. Assess ambiguous `var` initializers
+signals against the implementation evidence in docs/validation and the change
-and framework/lifecycle exceptions to field finality. Confirm architecture and
+description. S19 introduces no standards waiver.
-injection decisions make sense for production and tests.
-
-Read standards reports even when verification passes. Assess every review signal
-in changed code, including fan-out, public methods and record component counts.
-Record a rationale for retained signals in the S7 evidence or change description.
-Check narrowly scoped waivers against recorded maintainer agreement and reason.
-Never introduce blanket exclusions or weaken thresholds to pass a build.
-Do not repeat mechanical checks already enforced by tooling; verify their result.

docs/gitea-ci.md

@@ -12,7 +12,7 @@ zoals `[skip ci]`; dit is expliciet toegestaan.
 ## Java-bronbestanden uitvoeren
 
 De CI- en setuphulpmiddelen zijn Java 25-bronbestanden. Start ze direct met
-`java ci/Ci.java <opdracht>` vanuit de repositoryroot. De Java-launcher compileert
+`java generated/ci/Ci.java <opdracht>` vanuit de repositoryroot. De Java-launcher compileert
 de benodigde bronbestanden in het geheugen. Er is geen aparte `javac`-stap,
 Maven-module, Python-installatie of scriptingframework nodig. De helper gebruikt
 alleen de JDK, inclusief de HTTP-client, process builder en bestandsloten.
@@ -36,7 +36,7 @@ Gitea 1.25.4 en de registry staan op de bestaande Synology,
 Linux x86_64 mini-pc. Er is geen extra hardware nodig. De mini-pc moet aanstaan en
 wakker blijven; Docker en de runner moeten draaien. Anders blijven jobs wachten.
 Een host-runner voert repositorycode uit als de ontwikkelgebruiker: gebruik deze
-runner alleen voor deze vertrouwde repository.
+runner alleen voor de vertrouwde repositories van deze eigenaar.
 
 De runner heeft Git, Bash, JDK 25, Maven 3.9+, Node 22.22.3+/24.15.0+/26+, npm
 en een werkende Docker-daemon
@@ -76,7 +76,7 @@ Je kunt de instelling ook samenvoegen met behoud van bestaande instellingen en
 backup via:
 
 ```sh
-java ci/Ci.java configure-docker "$HOME/.docker/daemon.json"
+java generated/ci/Ci.java configure-docker "$HOME/.docker/daemon.json"
 ```
 
 Voor Docker Engine op Linux is dat dezelfde toevoeging aan
@@ -87,7 +87,7 @@ Docker-clients die images van deze interne HTTP-registry moeten ophalen.
 
 Gebruik de Docker Desktop-context of zet `DOCKER_HOST` expliciet. De installer
 neemt de geselecteerde socket over in de gebruikersservice. Als de socket later
-wijzigt, pas dan `~/.config/agiledancers-runner/environment` aan en herstart de
+wijzigt, pas dan `~/.config/mini-pc-runner/environment` aan en herstart de
 runner. Bij Docker Desktop blijft de Desktop-VM eveneens nodig voor builds.
 Runner en containers moeten de Synology en internetdownloads kunnen bereiken.
 
@@ -109,12 +109,13 @@ Stel bij repository **Settings → Actions** in:
 | Secret | `REGISTRY_TOKEN` | PAT met `write:package` en `read:repository` voor imagepublicatie en controle van de huidige hoofdbranch |
 
 Het gewone jobtoken van Gitea 1.25 biedt geen packagepublicatie; gebruik een PAT.
-Gebruik een repository-runnerregistratietoken, geen instancebrede registratie.
+Gebruik de gedeelde user-scoped runner `mini-pc` voor `wanjakrah`; een nieuwe
+repository heeft geen eigen runnerregistratie nodig.
 Sla tokenwaarden buiten Git op en plaats ze niet in opdrachten, screenshots of logs.
 
-Voor reproduceerbare configuratie bestaat `java ci/Ci.java configure-gitea`. Maak twee
+Voor reproduceerbare configuratie bestaat `java generated/ci/Ci.java configure-gitea`. Maak twee
 bestanden buiten de repository met mode `600`: één voor een PAT met voldoende
-repositorybeheerrechten (repository Actions, secrets, variabelen en runnerregistratie),
+repositorybeheerrechten (repository Actions, secrets en variabelen),
 en één voor de publicatie-PAT. De beheer-PAT hoeft niet als workflowsecret te worden
 bewaard. Vul die bestanden via een lokale editor of verborgen terminalinvoer.
 Voer daarna uit met de werkelijke platformwaarde:
@@ -124,14 +125,12 @@ export GITEA_ADMIN_TOKEN_FILE="$HOME/.config/agiledancers-runner/admin-token"
 export REGISTRY_TOKEN_FILE="$HOME/.config/agiledancers-runner/registry-token"
 export REGISTRY_USER=wanjakrah
 export TARGET_PLATFORM=linux/amd64  # alleen als dit op de Synology is vastgesteld
-java ci/Ci.java configure-gitea
+java generated/ci/Ci.java configure-gitea
 ```
 
-Het script stelt de repository-instellingen in via de API en schrijft het
+Het script stelt alleen de applicatie-instellingen, registrysecrets en platformwaarde
-runnerregistratietoken naar
+in. De gedeelde runnerregistratie wordt eenmalig beheerd vanuit engineering.
-`~/.config/agiledancers-runner/registration-token` met mode `600`. Het toont geen
+Applicatiespecifieke deploymentcredentials blijven onder ~/.config/agiledancers-runner/.
-tokenwaarden. Voor handmatige inrichting kun je dat registratietoken uit de
-repository-instellingen halen en in hetzelfde bestand plaatsen.
 
 De bevestigde Gitea 1.25.4-configuratie heeft geen `[actions]`-sectie: de defaults
 zijn negentig dagen voor artifacts en 365 dagen voor logs. Een workflow vraagt veertien dagen
@@ -139,43 +138,30 @@ via `retention-days: 14`. Een kortere serverlimiet of het vroegtijdig verwijdere
 van workflowruns mag die periode niet inkorten. Artifactretentie geldt voor
 testdiagnostiek; gepubliceerde containerimages worden niet automatisch verwijderd.
 
-## Runner installeren en starten
+## Gedeelde runner gebruiken
+
+De fysieke mini-pc draait `mini-pc-runner.service` met label `mini-pc:host`,
+geregistreerd op gebruikersniveau voor `wanjakrah`. Daardoor kunnen bestaande en
+nieuwe repositories van deze eigenaar dezelfde runner gebruiken. De gedeelde
+capaciteit is één job tegelijk. De workflowbestanden gebruiken `runs-on: mini-pc`.
+
+Voor eenmalige registratie, installatie en migratie volg je de
+[engineering-instructies](http://192.168.2.28:3000/wanjakrah/engineering/src/tag/v2.0.0/README.md).
+Controleer dit project met `java generated/ci/Ci.java check-runner`; gebruik daarbij
+het in engineering beschreven owner-only tokenbestand voor de gedeelde setup.
 
 ```sh
-export JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64
+systemctl --user status mini-pc-runner
-java ci/Ci.java install-runner --prepare-only
+journalctl --user -u mini-pc-runner -f
-# Na Dockerconfiguratie en het opslaan van het registratietoken:
+systemctl --user restart mini-pc-runner
-java ci/Ci.java install-runner
-systemctl --user status agiledancers-runner
-journalctl --user -u agiledancers-runner -f
 ```
 
-De installer controleert tools, installeert checksum-gecontroleerde runner
+Runnerstate staat onder ~/.local/share/mini-pc-runner/ en serviceconfiguratie onder
-`v0.2.13`, neemt label `agiledancers-mini-pc:host` over en registreert de runner.
+~/.config/mini-pc-runner/. De runner start samen met Docker Desktop na grafisch
-Configuratie en `.runner`-credentials staan in
+aanmelden, wacht maximaal 120 seconden op Docker en probeert een mislukte start
-`~/.local/share/agiledancers-runner`, de service in
+opnieuw. User lingering staat uit: vóór aanmelden of bij een uitgeschakelde mini-pc
-`~/.config/systemd/user/agiledancers-runner.service` en de expliciete Java-, PATH-
+is de runner niet beschikbaar. De oude agiledancers-runnerstate blijft voor herstel
-en Docker-socketinstellingen in `~/.config/agiledancers-runner/environment`.
+bewaard; applicatiespecifieke deploymenttokens en SSH-sleutels blijven op hun eigen paden.
-Een bestaande registratie wordt hergebruikt. Er worden geen secrets in de
-repository geschreven. Bewaar het tokenbestand alleen zolang registratie/herstel
-dat nodig heeft en behandel `.runner` als credential.
-
-Op de mini-pc starten Docker Desktop en de runner automatisch na grafisch
-aanmelden. Bij een Docker Desktop-socket installeert de installer hiervoor
-`~/.config/systemd/user/agiledancers-runner.service.d/10-agiledancers-docker-desktop.conf`
-en schakelt beide services in voor `graphical-session.target`. De runner wacht
-via `~/.local/share/agiledancers-runner/WaitForDocker.java` maximaal 120 seconden
-tot de ingestelde Docker-engine bereikbaar is. Bij een mislukte start probeert
-systemd het na tien seconden opnieuw. De runner volgt stoppen en herstarten van
-Docker Desktop en stopt bij afmelden.
-
-User lingering staat op deze pc uit: vóór aanmelden starten deze services niet.
-S4 belooft geen beschikbaarheid wanneer de mini-pc uitstaat. Herstarten/stoppen:
-
-```sh
-systemctl --user restart agiledancers-runner
-systemctl --user stop agiledancers-runner
-```
 
 ## Images en publicatie
 
@@ -200,8 +186,8 @@ De frontend luistert op containerpoort 8080, ondersteunt SPA-routes en proxy't
 8080. Voorbeelden voor eventueel handmatig starten staan los van de pipeline;
 de pipeline start geen blijvende applicatie op de NAS.
 
-`java ci/Ci.java verify` maakt een succesmarker pas na alle builds en tests.
+`java generated/ci/Ci.java verify` maakt een succesmarker pas na alle builds en tests.
-`java ci/Ci.java publish` vereist die marker en hoofdbranchref. Onder een gedeeld Java-bestandslot (`FileChannel`)
+`java generated/ci/Ci.java publish` vereist die marker en hoofdbranchref. Onder een gedeeld Java-bestandslot (`FileChannel`)
 buiten de checkout worden bestaande commitimages hergebruikt en ontbrekende
 images geüpload. Iedere image wordt teruggehaald, op revisielabel gecontroleerd en
 met digest vastgelegd in de diagnostiek. Authenticatie- of netwerkfouten tellen
@@ -238,7 +224,7 @@ blijven de committags bruikbaar en worden de oude `main`-updates overgeslagen.
 Lokale controle van publicatie-/foutgedrag zonder registrywijzigingen:
 
 ```sh
-java ci/Ci.java test
+java generated/ci/Ci.java test
 ```
 
 Volledige lokale verificatie met Docker en de vastgestelde platformwaarde:
@@ -246,7 +232,7 @@ Volledige lokale verificatie met Docker en de vastgestelde platformwaarde:
 ```sh
 export JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64
 export TARGET_PLATFORM=linux/amd64  # eerst de Synology controleren
-java ci/Ci.java verify
+java generated/ci/Ci.java verify
 ```
 
 ## Operationele oplevering

docs/persistent-storage.md

@@ -0,0 +1,154 @@
+# PostgreSQL storage (S16)
+
+The backend requires PostgreSQL 17. Flyway applies the versioned SQL under
+`agiledancers-be/src/main/resources/db/migration` before startup recovery and
+readiness. Never edit an already deployed migration; add the next version instead.
+The database owns domain identifiers and a monotonically increasing school
+revision. Application persistence uses JPA/Hibernate ORM: mapped entities and
+collections live in `repository.entity`, and repositories use `EntityManager`.
+The existing domain objects remain independent of JPA. Database constraints enforce
+school ownership of every relationship.
+
+Production uses `deploy/compose.yaml`: PostgreSQL has no published port and keeps
+its data in the named volume `agiledancers-production-database`. Set a long random
+`DATABASE_PASSWORD` in the mode-600 `production.env` on the NAS before the first
+S16 deployment. Compose reads it directly from this file, including when Docker runs through
+`sudo`; exporting it in the SSH shell does not survive the default sudo environment
+filter. The password is never written to release metadata. Deployment preflight
+rejects a missing password before pulling images or replacing containers. The backend receives:
+
+- `DATABASE_URL=jdbc:postgresql://database:5432/agiledancers`
+- `DATABASE_USER=agiledancers`
+- `DATABASE_PASSWORD` from `production.env`
+
+Database health gates backend startup, and the backend readiness check includes
+the datasource. Acquisition failures reject requests with `503` and a message that
+the mutation was not stored. There is no volatile fallback. PostgreSQL's normal
+WAL, fsync and synchronous-commit defaults must remain enabled. Application writes
+are acknowledged only after commit. A network loss during acknowledgement can
+leave the client uncertain; reload current data before deciding to retry.
+
+## Deployment failure before the first S16 release
+
+A missing `DATABASE_PASSWORD` can make `compose config --quiet` exit with status
+15. Configure the password in the existing NAS `production.env` (trusted shell
+configuration, mode `600`), for example `DATABASE_PASSWORD='<long random value>'`.
+Keep the same password after PostgreSQL initializes its volume: changing only this
+file does not change the database account password. Use Compose v2.17 or newer;
+the deployment reads `production.env` and then the retained `release.env` through
+two `--env-file` options, so sudo cannot discard the credential. Do not print
+expanded Compose configuration because it contains the password; use `config --quiet`.
+
+If the attempt was rejected before container replacement, no pending journal or
+lock remains and the old release continues running. After merging the deployment
+fix and completing the export below, run a new deployment. Use retry only if the
+failed attempt already created a version tag. Do not remove a lock or pending
+journal if one does remain; follow the production recovery runbook.
+
+## Transition from the previous release
+
+1. Export **every school** through JSON while the old backend is still running.
+   Its data exists only in memory and cannot be recovered after it stops.
+2. Keep those exports, configure the database password, then deploy S16. The
+   first startup creates an empty relational database through Flyway.
+3. Import the JSON files through the existing preview and confirmation workflow.
+   School keys and file-local relationship semantics remain unchanged; runtime
+   IDs are assigned by PostgreSQL. A replacement retains the target school ID.
+4. Verify schools and saved assignments after a restart before removing exports.
+   Import retains the existing behavior of importing schedules as drafts.
+
+Deployments recreate only the application containers. Never run `compose down -v`
+or delete the named database volume. Rollback replaces application images, not
+schema migrations; only roll back to a database-compatible release. An image from
+before S16 cannot read the new database. Database/volume loss recovery and backup
+operations are deferred to S17.
+
+## Local development and verification
+
+Quarkus Dev Services starts disposable PostgreSQL for development and tests when
+no datasource URL is configured; Docker must be accessible. For a durable local
+instance, create a PostgreSQL service with a persistent volume and pass
+`QUARKUS_DATASOURCE_JDBC_URL`, `QUARKUS_DATASOURCE_USERNAME`, and
+`QUARKUS_DATASOURCE_PASSWORD` to dev/test execution. Production uses the three
+`DATABASE_*` variables above. Never reuse a production database for tests.
+
+```sh
+JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64 mvn -Dformat.mode=check clean verify
+cd agiledancers-fe
+npm test
+npm run lint
+npm run build
+```
+
+Standalone Docker builds run the complete backend tests against a reachable test
+database. Supply its configuration through BuildKit secrets (not image build
+arguments), for example with shell variables `TEST_DATABASE_URL`,
+`TEST_DATABASE_USER` and `TEST_DATABASE_PASSWORD` already set:
+
+```sh
+docker build --network=host \
+  --secret id=database_url,env=TEST_DATABASE_URL \
+  --secret id=database_user,env=TEST_DATABASE_USER \
+  --secret id=database_password,env=TEST_DATABASE_PASSWORD \
+  -t agiledancers .
+```
+
+CI runs verification against disposable PostgreSQL, packages the exact verified
+output using the `prebuilt` Docker target, and starts a separate database on its
+isolated browser-test network. Cleanup removes those test containers only.
+
+The packaged-process regression test below checks graceful and abrupt backend
+termination, stable recovered run IDs through HTTP and SSE, committed results,
+interrupted calculations, database outages, and failed startup/migrations. It
+requires a built backend and an **isolated disposable database container**: the
+test deliberately stops and restarts the named container. It does not remove its
+volume. Pass matching connection options if they differ from the defaults.
+
+```sh
+python3 tooling/persistence/restart_test.py --database-container agiledancers-s16-test
+```
+
+S16 targets one active backend. The existing domain monitor serializes short
+snapshot/mutation/commit units of work; solver work runs outside that monitor and
+outside database transactions. Results use the school revision captured at start.
+Changes elsewhere in the same school may invalidate a run. Latest progress and
+outcome are durable; calculations left Running at startup become Interrupted and
+retain earlier saved assignments. There is no automatic resumption or run history.
+
+
+## JPA mapping and schema upgrades
+
+Hibernate manages relationships, element collections, ordered assignments and
+orphan removal through mapped entities. Its `@Version` on the school entity
+implements optimistic concurrency. A child-only change marks the aggregate dirty,
+so the school version advances exactly once without manual version-update SQL.
+JTA owns the transaction boundary; run acceptance and completion are published only
+after commit. Detached domain snapshots do not expose Hibernate proxies through the
+API or to solver threads.
+
+Flyway remains the only schema writer. Hibernate runs in `validate` mode and never
+creates or alters application tables. V1 is retained unchanged. V2 adds the aggregate
+change stamp, a JPA-managed identifier counter seeded above the existing sequence,
+and a deferred date/type uniqueness check for reordering dayparts. Existing school
+keys, entity IDs, assignments and scheduling status are preserved. The counter is
+locked while allocating IDs within a transaction. Rollback requires a release that
+understands V2's identifier allocation; the earlier JDBC implementation is not a
+compatible rollback target.
+
+
+## API projections
+
+MapStruct 1.6.3 generates the REST-layer `DomainViewMapper` for domain objects to
+view records. REST resources inject the generated CDI bean. Relationship collections
+map to ID lists through one shared helper; validation remains a use-case result
+passed explicitly to the mapper. Preferred-daypart defaults call the existing
+application rule. View constructors preserve immutable snapshots.
+
+The mapper sets `unmappedTargetPolicy = ERROR`: every target component must have a
+mapping, whether inferred from a matching property or declared explicitly. A newly
+added unmatched component therefore fails compilation. The backend compiler runs
+MapStruct together with Lombok and its pinned MapStruct binding. Generated classes
+stay under `target/generated-sources/annotations`; they are not maintained source.
+
+Persistence entities and shared domain graph identity continue to use PeopleMapping,
+GroupMapping and ShowMapping. MapStruct does not construct or update that graph.

docs/production-deployment.md

@@ -4,10 +4,11 @@ De buildworkflow bouwt, test en publiceert automatisch. Productie verandert
 alleen via **Actions → Deploy production → Run workflow** of **Rollback
 production**. Start beide vanaf `main`; de workflows verschijnen na de merge.
 
-**Tot S16 is geïmplementeerd kan iedere deployment, retry, rollback of automatisch
+**Voor de eerste S16-deployment: exporteer alle scholen voordat de oude backend
-herstel alle applicatiegegevens wissen.** Informeer de launching partner vooraf.
+stopt.** De oude release bewaart gegevens alleen in geheugen. Configureer ook
-Een onderbroken berekening moet opnieuw worden gestart. Een herstelde
+`DATABASE_PASSWORD` in `production.env`. Zie [database-inrichting en overgang](persistent-storage.md).
-applicatieversie herstelt geen verloren gegevens.
+Nieuwe releases gebruiken een apart PostgreSQL-volume; verwijder dit volume niet.
+Onderbroken berekeningen worden als Interrupted hersteld en starten niet vanzelf.
 
 ## Eenmalige DSM-inrichting
 
@@ -29,7 +30,7 @@ Gebruik je bestaande beheeraccount voor deze stappen:
 5. Schakel **Terminal en SNMP → Terminal → SSH-service inschakelen** in. De
    maintainer heeft SSH-poort **22** bevestigd. Beperk toegang tot mini-pc/LAN/VPN;
    configureer geen internet-portforwarding.
-6. Controleer dat Container Manager/Docker draait, dat Docker Compose **v2**,
+6. Controleer dat Container Manager/Docker draait, dat Docker Compose **v2.17 of nieuwer**,
    `curl`, `timeout` met `-k` en `sh` beschikbaar zijn. Op de NAS is geen Java,
    Python of Git nodig. Controleer het Docker-pad, doorgaans `/usr/local/bin/docker`.
 
@@ -135,8 +136,9 @@ sudo -n /usr/local/bin/docker compose version
 sudo -n /usr/local/bin/docker info --format '{{.OSType}}/{{.Architecture}}'
 ```
 
-Als DSM geen `visudo` bevat, is `deploy/enable-docker.sh` het eenmalige alternatief.
+Als DSM geen `visudo` bevat, is `generated/deploy/enable-docker.sh` het eenmalige alternatief.
-Kopieer het naar de eigen NAS-thuismap en voer het daar met sudo uit. Het maakt
+Kopieer het naar de eigen NAS-thuismap en voer daar
+`sudo sh enable-docker.sh agiledancers-deploy /usr/local/bin/docker` uit. Het maakt
 uitsluitend de bovengenoemde regel, controleert die door als deploymentaccount
 Docker te starten en verwijdert een nieuwe regel als die controle faalt. Een
 afwijkende bestaande regel wordt niet overschreven. De implementatiesessie heeft
@@ -176,7 +178,7 @@ inrichten. Bewaar `admin-token`, `s6-release-token`, `s6-pull-token` en de priva
 `~/.ssh/known_hosts` en voer uit:
 
 ```sh
-java ci/Ci.java configure-deployment
+java generated/ci/Ci.java configure-deployment
 ```
 
 Defaults zijn de bevestigde NAS/account/SSH-poort, repository
@@ -268,8 +270,9 @@ nieuwe release door te drukken.
    controlescript uitvoeren met bestaande lockowner en gekozen release-directory:
 
    ```sh
-   ssh -i <private-key-path> -p <ssh-port> <deploy-user>@<nas> \
+   cat deploy/health.sh generated/deploy/remote.sh | \
-     'timeout -k 5 300 sh -s -- apply <production-directory> <lock-owner> <release-directory-id>' < deploy/remote.sh
+     ssh -i <private-key-path> -p <ssh-port> <deploy-user>@<nas> \
+     'COMPOSE_PROJECT=agiledancers-production DEPLOY_ROLES="backend frontend" DEPENDENCY_SERVICES=database REQUIRED_SECRETS=DATABASE_PASSWORD TARGET_PLATFORM=linux/amd64 timeout -k 5 300 sh -s -- apply <production-directory> <lock-owner> <release-directory-id>'
    ```
 
    Gebruik de eerder gepinde hostkey en gecontroleerde waarden uit het journal.
@@ -285,16 +288,17 @@ nieuwe release door te drukken.
 
 ## Na S16 en lokale verificatie
 
-S16 blokkeert S6 niet. Zodra S16 is ingevoerd, moeten database/volumes buiten de
+De databaseservice en het volume `agiledancers-production-database` blijven buiten
-vervangbare containers blijven en saved data zowel deployment als rollback
+de vervanging van backend en frontend. Compose leest `production.env` rechtstreeks via `--env-file`, zodat het
-overleven. De gewone procedure vereist dan databasecompatibiliteit met de vorige
+databasewachtwoord ook via sudo en bij retry en rollback beschikbaar is; het staat niet in releasebestanden. De procedure vereist
-applicatieversie. Plan incompatibele migraties apart: imageherstel maakt geen
+databasecompatibiliteit met de vorige applicatieversie. Plan incompatibele migraties
-migratie ongedaan. Backup/restore blijven S17-werk.
+apart: imageherstel maakt geen migratie ongedaan. Rollback naar een oude release
+van vóór S16 kan de database niet lezen. Backup/restore blijven S17-werk.
 
 ```sh
-java ci/Ci.java test
+java generated/ci/Ci.java test
-java ci/Ci.java release-test
+java generated/ci/Ci.java release-test
-sh -n deploy/remote.sh
+sh -n generated/deploy/remote.sh
 mvn -N -Dformat.mode=check exec:exec@format
 ```
 

docs/s18-validation.md

@@ -1,3 +1,5 @@
+> Historical validation evidence from application commit `bd898e92d22f6c412e671908770f4d89c8ae12bc`. Commands retain their original paths; current tooling is documented in README.md.
+
 # S18 implementation validation
 
 Validated on 2026-11-03 against the confirmed S18 specification.

docs/s2-validation.md

@@ -1,3 +1,5 @@
+> Historical validation evidence from application commit `bd898e92d22f6c412e671908770f4d89c8ae12bc`. Commands retain their original paths; current tooling is documented in README.md.
+
 # S2 implementation evidence
 
 Validated on the development mini-PC on 2026-10-29: AMD Ryzen 7 7730U (8 cores,
@@ -58,7 +60,7 @@ Prettier. The selected configuration uses only Prettier. Staged scopes are:
 - All: all 52 maintained frontend files, including non-applicable files that the
   hook must skip, plus a small TS preservation-test fixture; generated lockfile
   excluded. Exact paths and raw measurements are in
-  [the timing report](s2-hook-timings.json).
+  [the timing report](http://192.168.2.28:3000/wanjakrah/agiledancers/src/commit/bd898e92d22f6c412e671908770f4d89c8ae12bc/docs/s2-hook-timings.json).
 
 | Candidate | Staged scope | Run 1 | Run 2 | Run 3 |
 | --- | --- | --- | --- | --- |

docs/s4-validation.md

@@ -1,3 +1,5 @@
+> Historical validation evidence from application commit `bd898e92d22f6c412e671908770f4d89c8ae12bc`. Commands retain their original paths; current tooling is documented in README.md.
+
 # S4 verification evidence
 
 Updated: 2026-10-29. S4 is **complete**. Main publication/pullback passed in run

docs/s6-validation.md

@@ -1,3 +1,5 @@
+> Historical validation evidence from application commit `bd898e92d22f6c412e671908770f4d89c8ae12bc`. Commands retain their original paths; current tooling is documented in README.md.
+
 # S6 implementation and operational evidence
 
 Status: IN_REVIEW. Production `v1.0.0` is running on the Synology at