schema.graphql

"""
Directs the executor to defer this fragment when the `if` argument is true or undefined.
"""
directive @defer(
  """Deferred when true or undefined."""
  if: Boolean = true

  """Unique name"""
  label: String
) on FRAGMENT_SPREAD | INLINE_FRAGMENT

"""
Indicates exactly one field must be supplied and this field must not be `null`.
"""
directive @oneOf on INPUT_OBJECT

"""Exposes a URL that specifies the behavior of this scalar."""
directive @specifiedBy(
  """The URL that specifies the behavior of this scalar."""
  url: String!
) on SCALAR

"""
Aktivitäts-Kennzahlen aus dem Audit-Log (bezogen auf das aktive Semester).
"""
type ActivitySummary {
  """Anzahl mutierender Operationen der letzten 24 Stunden."""
  last24h: Int!

  """Anzahl mutierender Operationen der letzten 7 Tage."""
  last7d: Int!

  """Anzahl fehlgeschlagener Operationen in den letzten 7 Tagen."""
  errors7d: Int!

  """Anzahl unterschiedlicher handelnder Nutzer in den letzten 7 Tagen."""
  distinctUsers7d: Int!

  """Die häufigsten Operationen der letzten 7 Tage (absteigend), gekappt."""
  topOperations: [OperationCount!]!
}

type AdditionalExam {
  ancode: Int!

  """date in dd.mm.yyyy."""
  date: String!

  """time in HH:MM."""
  time: String!
  rooms: [AdditionalExamRoom!]!
}

input AdditionalExamInput {
  ancode: Int!
  date: String!
  time: String!
  rooms: [AdditionalExamRoomInput!]!
}

type AdditionalExamRoom {
  roomName: String!
  invigilatorID: Int!
  duration: Int!
  isReserve: Boolean!
  studentCount: Int!
  isHandicap: Boolean!
}

input AdditionalExamRoomInput {
  roomName: String!
  invigilatorID: Int!
  duration: Int!
  isReserve: Boolean!
  studentCount: Int!
  isHandicap: Boolean!
}

"""Plattform-Überblick für Admins."""
type AdminOverview {
  """Zeitpunkt, zu dem diese Übersicht erhoben wurde."""
  generatedAt: Time!

  """Build-Version und verbundene MongoDB des laufenden Servers."""
  server: ServerInfo!

  """Das aktuell aktive Semester (Workspace), z. B. "2026 SS"."""
  activeSemester: String!

  """
  Alle bekannten Workspaces (Semester-Datenbanken) mit Read-only-/Schema-Stand.
  """
  workspaces: [Semester!]!

  """Die Zugriffsliste (alle bekannten Login-Identitäten)."""
  users: [User!]!

  """Anzahl der Nutzer je Rolle."""
  roleCounts: RoleCounts!

  """Zustand des Auto-Syncs und des Admin-Digests."""
  scheduler: SchedulerStatus!

  """
  Backup-Fälligkeit des aktiven Workspace (Änderungen seit dem letzten Dump).
  """
  backup: BackupStatus!

  """
  Laufzeit-Status: ob gerade geschrieben werden darf und ob der Workspace schreibgeschützt ist.
  """
  live: LiveStatus!

  """
  Aktivitäts-Kennzahlen aus dem Audit-Log des aktiven Workspace (24h/7d/Fehler/aktive Nutzer + Top-Operationen).
  """
  activity: ActivitySummary!

  """Die jüngsten Audit-Einträge (neueste zuerst) des aktiven Workspace."""
  recentActivity: [MutationLogEntry!]!

  """
  Die jüngsten fehlgeschlagenen Operationen (neueste zuerst) des aktiven Workspace.
  """
  recentErrors: [MutationLogEntry!]!

  """Die jüngsten externen Transfers (ZPA/Anny) des aktiven Workspace."""
  recentSyncs: [SyncLogEntry!]!
}

type AnCode {
  zpaAncode: Int!
}

"""
Ancodes bundles an exam's internal (ZPA) ancode with its external Primuss identities.
Internal use → zpaAncode; external communication (Primuss/MUC.DAI) → primussAncodes.
For FK07 exams they are normally equal; for MUC.DAI/external exams they differ.
"""
type Ancodes {
  zpaAncode: Int!
  primussAncodes: [ZPAPrimussAncodes!]!
}

type AnnyBooking {
  number: String!
  startDate: Time!
  endDate: Time!
  blockerStartDate: Time!
  blockerEndDate: Time!
  chargedDuration: Int!
  description: String!
  createdAt: Time!
  updatedAt: Time!
  canceledAt: Time
  status: String!
  isBlocker: Boolean!
  canEdit: Boolean!
  isEditable: Boolean!
  manuallyCreated: Boolean!
  note: String!
  room: String
  self: String!
  personalizationName: String!
  bookingGroupIdentifier: String
  cancelableUntil: Time
  hasCustomDescription: Boolean!

  """
  true when the booking's personalization name is one of ours (annyConfig.personalizationNames).
  """
  mine: Boolean!
}

type AnnyConfig {
  """names whose bookings are flagged as ours (mine=true)."""
  personalizationNames: [String!]!
}

input ArgFilterInput {
  key: String!
  value: String!
}

type AssembledExam {
  ancode: Int!

  """
  internal/external ancode identity of the exam (zpaAncode + program-scoped primussAncodes)
  """
  ancodes: Ancodes!
  zpaExam: ZPAExam!
  mainExamer: Teacher!
  primussExams: [EnhancedPrimussExam!]!
  constraints: Constraints
  conflicts: [ZPAConflict!]!
  studentRegsCount: Int!
  ntas: [NTA!]!
  maxDuration: Int!
}

type AssembledExamsChange {
  ancode: Int!
  module: String!

  """added | removed | changed"""
  kind: String!

  """human-readable change descriptions, e.g. 'Anmeldungen 42 → 43'."""
  details: [String!]!
}

type AssembledExamsState {
  """true when the assembled exams are stale relative to their inputs."""
  dirty: Boolean!

  """
  the operation that last marked them stale (mutation/subscription name).
  """
  reason: String

  """when they were last marked stale or (re)generated."""
  changedAt: Time
}

type BackupStatus {
  """
  True when there were mutations after the last dump (or a dump was never taken).
  """
  hasUnsavedChanges: Boolean!

  """When the last full semester ZIP dump was downloaded; null if never."""
  lastDumpAt: Time

  """
  Timestamp of the most recent change (mutation log); null if nothing changed yet.
  """
  lastChangeAt: Time
}

"""
BalanceReport: are all invigilators within ±tolerance of their target minutes.
"""
type BalanceReport {
  satisfied: Boolean!
  invigilators: Int!
  toleranceMin: Int!
  withinTolerance: Int!
  over: Int!
  under: Int!
  maxOver: Int!
  maxUnder: Int!
}

"""A room blocked at one exam time (not usable for planning there)."""
type BlockedRoom {
  """Absolute start time of the blocked slot."""
  starttime: Time
  room: String!
  reason: String
}

type Conflict {
  ancode: Int!
  numberOfStuds: Int!
}

"""
ConflictDecision is an explicit per-student override of the automatic handling:
ACCEPT drops that student's proximity penalty; VETO forces it to count at full weight
(overriding an automatic repeat down-weighting).
"""
enum ConflictDecision {
  ACCEPT
  VETO
}

type ConflictPerProgram {
  program: String!
  conflicts: [Conflict!]!
}

type Conflicts {
  ancode: Int!
  module: String!
  mainExamer: String!
  conflicts: [Conflict!]!
}

type ConflictsPerProgramAncode {
  program: String!
  ancode: Int!
  conflicts: Conflicts
}

type ConflictStudent {
  mtknr: String!
  name: String!

  """the student's study program, e.g. "IF"."""
  program: String!

  """the student's cohort/group, e.g. "IF4B"."""
  group: String!

  """
  true if this is (heuristically) a repeat for this student (repeater exam or
  the student's semester is above the exam's) — auto down-weighted and accepted by default.
  """
  autoAccepted: Boolean!

  """
  explicit decision for this student, if any (overrides the automatic handling).
  """
  decision: ConflictDecision

  """
  effective: penalty dropped for this student (explicit ACCEPT, or autoAccepted and not vetoed).
  """
  accepted: Boolean!
}

type ConnectedExam {
  zpaExam: ZPAExam!
  primussExams: [PrimussExam!]!
  otherPrimussExams: [PrimussExam!]!

  """Findings from connecting ZPA and Primuss data, graded by level."""
  warnings: [ConnectedExamWarning!]!
}

"""A finding from connecting a ZPA exam to its Primuss registrations."""
type ConnectedExamWarning {
  """info | warning | error"""
  level: String!
  message: String!

  """
  The Primuss program this finding refers to (for an add/fix/remove action), if any.
  """
  program: String

  """The Primuss ancode this finding refers to, if any."""
  ancode: Int

  """The module/exam name of the referenced Primuss exam, if known."""
  module: String

  """The examer of the referenced Primuss exam, if known."""
  examer: String
}

type ConstraintCost {
  name: String!
  cost: Float!
}

type Constraints {
  ancode: Int!
  notPlannedByMe: Boolean!

  """do not upload this exam to the ZPA when publishing the plan."""
  doNotPublish: Boolean!
  excludeDays: [Time!]
  possibleDays: [Time!]
  fixedDay: Time
  fixedTime: Time
  sameSlot: [Int!]
  online: Boolean!

  """
  fixed exam location/campus, e.g. "Campus Pasing"; empty = default campus
  (Lothstraße). Used for a minimum travel gap between exams at different campuses.
  """
  location: String

  """
  the faculty that plans this exam when notPlannedByMe (e.g. "FK10" for Pasing ZPA exams).
  """
  notPlannedByMeInFK: String
  roomConstraints: RoomConstraints
}

input ConstraintsInput {
  allowedRooms: [String!]
  notPlannedByMe: Boolean
  doNotPublish: Boolean
  excludeDays: [Time!]
  possibleDays: [Time!]
  fixedDay: Time
  fixedTime: Time
  sameSlot: [Int!]
  online: Boolean
  location: String

  """the faculty that plans this exam when notPlannedByMe (e.g. "FK10")."""
  notPlannedByMeInFK: String
  placesWithSocket: Boolean
  lab: Boolean
  exahm: Boolean
  seb: Boolean
  kdpJiraURL: String
  maxStudents: Int
  additionalSeats: Int

  """
  Lead time (Vorlauf) in minutes before the exam; total that replaces the default 15.
  """
  preExamMinutes: Int

  """
  Trailing time (Nachlauf) in minutes after the exam; total that replaces the default 15.
  """
  postExamMinutes: Int
  comments: String
}

type CountBucket {
  """
  Number of exams; the top bucket uses this as its lower bound (label carries the '+').
  """
  examCount: Int!
  label: String!
  students: Int!
  share: Float!
}

"""CoverageReport: how many positions are filled."""
type CoverageReport {
  positions: Int!
  unfilled: Int!
}

type DistributionBucket {
  count: Int!
  invigilators: Int!
}

"""
Status of the per-session dry-run recipient override shown on the Probeläufe page.
"""
type DryRunTestMailStatus {
  """
  The active session override, or null when none is set (the configured default is used).
  """
  override: String

  """
  The address dry-run mails currently go to (override, or the configured default).
  """
  current: String!

  """
  The configured default (effective testMail) that a reset falls back to.
  """
  default: String!

  """
  True when an override is active and deviates from the default — the GUI should show a warning banner.
  """
  overridden: Boolean!
}

"""
EmailAttachmentInfo describes one uploaded attachment (without its binary data).
kind is e.g. "cover-page" or "invigilation-image"; key is the teacher /
invigilator id the attachment belongs to. The binaries themselves are uploaded
via the REST endpoints /upload/email-attachment and /upload/email-attachments-zip.
"""
type EmailAttachmentInfo {
  kind: String!
  key: String!
  filename: String!
  contentType: String!
  size: Int!
  uploadedAt: Time!
}

type Emails {
  profs: String!
  lbas: String!
  lbasLastSemester: String!
  additionalExamer: [String!]!
  fs: String!
  sekr: String!

  """Recipient for building-management room requests (Gebäudemanagement)."""
  roomManagement: String!

  """Recipient for the EXaHM/SEB room overview (KDP)."""
  kdp: String!

  """
  Recipient for the overview of LBAs' repeat exams (Lehrbeauftragten-Beauftragte:r).
  """
  lbaba: String!
}

input EmailsInput {
  profs: String!
  lbas: String!
  lbasLastSemester: String!
  additionalExamer: [String!]!
  fs: String!
  sekr: String!
  roomManagement: String!
  kdp: String!
  lbaba: String!
}

"""
EmailTemplate is one editable email body template (a Markdown *.md.tmpl). The built-in
embedded template is the default; a stored override replaces it. The layout templates
(emailBaseHTML/jiraOnHTML) are not editable here.
"""
type EmailTemplate {
  """the template's file name, e.g. "exahmEmail.md.tmpl"."""
  name: String!

  """
  a short human-readable purpose of this email (for the GUI list; not part of the mail).
  """
  description: String!

  """
  the effective Markdown: the stored override if any, otherwise the built-in default.
  """
  markdown: String!

  """true when no override is stored (the built-in default is in use)."""
  isDefault: Boolean!

  """the built-in default Markdown (for preview and reset-to-default)."""
  defaultMarkdown: String!

  """
  the variables (placeholders) this template may use, with a description and an example.
  """
  variables: [EmailTemplateVariable!]!
}

"""
EmailTemplateFunction documents a helper function callable in every email template, e.g.
`jiraURL` or `plural`. The list is global (all functions are available in all templates).
"""
type EmailTemplateFunction {
  """the function name, e.g. "plural"."""
  name: String!

  """how to call it, e.g. "{{ plural .N \"Platz\" \"Plätze\" }}"."""
  usage: String!

  """what it does, in plain language."""
  description: String!
}

"""
EmailTemplatePreview is the rendered result of a (possibly not-yet-saved) template against
representative sample data. On a template error, `error` holds the message and html/text
are empty — so the GUI can show parse/exec mistakes live while editing.
"""
type EmailTemplatePreview {
  """
  the rendered HTML part (the shared layout is applied), for an in-GUI preview.
  """
  html: String!

  """the rendered plain-text part."""
  text: String!

  """
  the error message if the template does not parse/execute; null on success.
  """
  error: String
}

"""
EmailTemplateVariable documents one placeholder available in a template, e.g.
`.Teacher.Fullname`. Meant to be shown next to the editor so a non-technical user knows
which values exist and how to write them.
"""
type EmailTemplateVariable {
  """how to write it in the template, e.g. "{{ .Teacher.Fullname }}"."""
  name: String!

  """what the value is, in plain language."""
  description: String!

  """the value used for this placeholder in the live preview."""
  example: String!
}

type EnhancedPrimussExam {
  exam: PrimussExam!
  studentRegs: [EnhancedStudentReg!]!
  conflicts: [Conflict!]!
  ntas: [NTA!]!
}

type EnhancedStudentReg {
  mtknr: String!

  """
  Primuss ancode (per-program namespace); == the ZPA ancode only for FK07 exams
  """
  primussAncode: Int!
  program: String!
  group: String!
  name: String!
  presence: String!
  zpaStudent: ZPAStudent
}

type ExamDay {
  date: Time!
}

type ExamDurationOverride {
  ancode: Int!
  duration: Int!
}

type ExamerInPlan {
  mainExamer: String!
  mainExamerID: Int!
}

"""
ExamPair is a pair of exams with display info (for canShareSlot lists/suggestions).
"""
type ExamPair {
  ancode1: Int!
  module1: String!
  mainExamer1: String!
  ancode2: Int!
  module2: String!
  mainExamer2: String!
}

"""
One exam I plan for an examer, for the planning info email (no slot/date).
"""
type ExamPlanningMailExam {
  ancode: Int!
  module: String!

  """Human-readable exam type (ZPA full name)."""
  examType: String!
  constraints: Constraints
}

type ExamPlanningMailRecipient {
  teacher: Teacher!

  """
  withExams = I plan at least one of their exams; fk07NoExams = FK07 examer I plan nothing for.
  """
  category: String!

  """The exams I plan for this examer (empty for fk07NoExams)."""
  exams: [ExamPlanningMailExam!]!
}

"""State of the EXaHM/SEB room phase (phase A) relative to phase B."""
type ExamRoomsPhaseState {
  """
  planned EXaHM/SEB exams (have a plan entry — the set the room phase freezes).
  """
  planned: Int!

  """
  of those, how many are frozen (phaseFixed) so phase B leaves them untouched.
  """
  fixed: Int!

  """
  planned > 0 and every planned EXaHM/SEB exam is frozen — safe to run phase B.
  """
  allFixed: Boolean!
}

"""
ExamScheduleConflict is a conflict in the CURRENT plan: two exams a student is
registered in that ended up close in time, aggregated over all affected students. A
conflict is only meaningful per student — the per-student acceptance lives on
affectedStudents.
"""
type ExamScheduleConflict {
  ancode1: Int!
  module1: String!
  mainExamer1: String!

  """the study groups exam 1 is offered for (e.g. ["IF2A"])."""
  groups1: [String!]!

  """true if exam 1 is a repeater exam."""
  isRepeaterExam1: Boolean!

  """exam 1's campus/location (empty = default campus Lothstraße)."""
  location1: String!

  """the planned slot of exam 1."""
  slot1: Slot!
  ancode2: Int!
  module2: String!
  mainExamer2: String!
  groups2: [String!]!
  isRepeaterExam2: Boolean!
  location2: String!
  slot2: Slot!

  """number of students registered in both, in the plan."""
  studentCount: Int!

  """
  worst time proximity across affected students: OVERLAP | TOO_CLOSE | SAME_DAY.
  """
  proximity: String!

  """true if the pair is declared can-share-slot."""
  canShareSlot: Boolean!

  """
  true if BOTH exams are external (planned by another faculty): information only.
  """
  infoOnly: Boolean!

  """
  the affected students (registered in both); acceptance is set per student here.
  """
  affectedStudents: [ConflictStudent!]!

  """
  status relative to the currently saved plan, only set in a generation report: "new"
  (not in the saved plan), "worse"/"better" (proximity changed), "unchanged", or
  "resolved" (was in the saved plan, gone now). Empty outside a diff context.
  """
  diffStatus: String!
}

"""Quality report of a generated (or current) exam schedule."""
type ExamScheduleDiagnostics {
  students: Int!
  pairs: Int!

  """
  Two of a student's exams overlap in time (a hard violation — should be 0).
  """
  overlaps: Int!

  """Two of a student's exams are directly consecutive / too close in time."""
  tooClose: Int!
  sameDay: Int!
  nextDay: Int!
  within3: Int!
  further: Int!
  studentsWithTooClose: Int!
  studentsWithSameDay: Int!
  worstStudentPenalty: Float!

  """Peak concurrent seats across all start times."""
  maxSeatsAt: Int!

  """Distinct start times holding at least one of our exams."""
  starttimesUsed: Int!
  slotsOverThreshold: Int!

  """Peak number of exams sharing a single start time."""
  maxExamsAt: Int!
}

type ExamScheduleReport {
  units: Int!
  fixed: Int!
  placed: Int!
  unplaced: Int!
  unplacedAncodes: [Int!]!
  hardViolations: [String!]!
  cost: Float!
  costByConstraint: [ConstraintCost!]!
  iterations: Int!

  """the seed used — pass it back to reproduce this exact plan."""
  seed: Int!
  stoppedEarly: Boolean!
  written: Boolean!
  diagnostics: ExamScheduleDiagnostics!

  """
  conflicts of the generated schedule (to review/rate, also on a dry run). Each
  carries a diffStatus relative to the saved plan (new/worse/better/unchanged).
  """
  conflicts: [ExamScheduleConflict!]!

  """
  conflicts that were in the saved plan but are gone in the generated one (diffStatus "resolved").
  """
  resolvedConflicts: [ExamScheduleConflict!]!

  """
  EXaHM/SEB exams (ancodes) that carry an NTA. Their NTA time extension is not
  gated against the Anny booking window (the NTA student is seated in a separate
  NTA room booked later at room planning) — this is the reminder to book that room.
  """
  exahmNtaAncodes: [Int!]!

  """
  why each unplaced exam could not be scheduled (empty when everything was placed).
  """
  unplacedReasons: [UnplacedExamReason!]!
}

type ExamSpreadStatistics {
  """
  Students in scope with at least one exam placed within the exam period.
  """
  studentCount: Int!

  """
  Students with at least one ratable gap (>= 2 exams, after dropping spurious
  foreign-foreign / same-slot pairs); denominator of the shares.
  """
  multiExamStudentCount: Int!

  """Total placed exam registrations counted across all students in scope."""
  totalPlannedExams: Int!

  """
  Students who still have at least one not-yet-placed exam (coverage caveat).
  """
  studentsWithUnplannedExams: Int!
  avgExamsPerStudent: Float!
  maxExamsPerStudent: Int!

  """
  Share (%) of multi-exam students who have >= 1 free day between ALL consecutive exams.
  """
  freeDayShare: Float!

  """Share (%) of multi-exam students who have two exams on the same day."""
  sameDayShare: Float!

  """
  Share (%) of multi-exam students whose tightest gap is two consecutive days (0 free days).
  """
  adjacentDayShare: Float!

  """
  Share (%) of multi-exam students with a real overlap/too-close conflict (should be 0).
  """
  conflictShare: Float!

  """Number of students with three or more exam sittings on a single day."""
  threeExamsOneDayCount: Int!

  """
  Average, over multi-exam students, of their SMALLEST free-days-between-exams (same day = -1, overlap = -2).
  """
  avgMinFreeDays: Float!
  medianMinFreeDays: Float!

  """
  Carter-style proximity index averaged per multi-exam student (lower = better); the objective the solver minimizes.
  """
  avgProximityCost: Float!

  """Students grouped by their WORST (tightest) consecutive-exam gap."""
  studentBuckets: [SpreadBucket!]!

  """All consecutive-exam gaps grouped by proximity class."""
  pairBuckets: [SpreadBucket!]!

  """Students grouped by how many exams they have."""
  examCountBuckets: [CountBucket!]!

  """Per study program breakdown, most students first."""
  byProgram: [ProgramSpread!]!

  """
  The most tightly-scheduled students, for GUI drill-down (not part of the aggregate PDF).
  """
  worstStudents: [WorstStudent!]!

  """
  The non-repeat-exam cap for the in-scope population (6 = the most possible in a normal semester).
  """
  maxRegularNonRepeatExams: Int!

  """
  Students excluded here because they have more than maxRegularNonRepeatExams non-repeat exams (repeat-heavy outliers).
  """
  excludedStudentCount: Int!

  """
  freeDayShare over ALL students incl. the excluded outliers — for a 'barely
  differs' note; equals freeDayShare when there are no outliers.
  """
  allFreeDayShare: Float!

  """
  The travel/break buffer (minutes) below which two exams count as an overlap.
  """
  examGapMinutes: Int!

  """
  The same-day start-to-start threshold (minutes) below which two exams count as too close.
  """
  notTooCloseMinutes: Int!
}

"""
ExamTime is the time span of one exam an invigilator is the main examer of:
from the start time of the slot until the end time (start + maxDuration of the
exam, i.e. the longest exam in the slot including NTA extensions).
"""
type ExamTime {
  from: Time!
  until: Time!
}

type ExamWithRegsAndRooms {
  exam: PlannedExam!
  normalRegsMtknr: [String!]!
  ntasInNormalRooms: [NTA!]!
  ntasInAloneRooms: [NTA!]!
  rooms: [PlannedRoom!]!
}

"""
FairnessDistribution: per-invigilator count histogram for one kind (reserve/nta).
buckets reads as "count:invigilators", e.g. count 1 / invigilators 48.
"""
type FairnessDistribution {
  kind: String!
  total: Int!
  max: Int!
  buckets: [DistributionBucket!]!
}

type FK07Program {
  name: String!
}

type GenerateAssembledExamsResult {
  """the new state (dirty=false)."""
  state: AssembledExamsState!

  """
  what changed vs the previously cached assembled exams (empty = nothing changed).
  """
  changes: [AssembledExamsChange!]!
}

type GeneratePreparationResult {
  assembledExams: GenerateAssembledExamsResult!
  studentRegs: GenerateStudentRegsResult!
}

type GenerateStudentRegsResult {
  state: StudentRegsState!

  """
  number of students with planned registrations after the (re)generation.
  """
  studentCount: Int!
}

type GenerationConfig {
  iterations: Int!
  startTemp: Float!
  endTemp: Float!

  """allowed deviation (minutes) from an invigilator's target workload."""
  toleranceMin: Int!
  maxSpanHours: Float!
  weightMinuteBalance: Float!
  weightBeyondTolerance: Float!
  weightOverTargetFactor: Float!
  weightCoverage: Float!
  weightMaxDays: Float!
  weightPreferExamDays: Float!
  weightDistribution: Float!
  weightDaySpan: Float!

  """
  Terminplan: whether/how the start-time window applies (default AUTO by semester).
  """
  slotTimeMode: SlotTimeConstraintMode!

  """
  Terminplan: how strictly the window is enforced — HARD (domain restriction, default) or SOFT (penalty).
  """
  slotTimeEnforcement: SlotTimeConstraintEnforcement!

  """
  Terminplan: SOFT-mode window penalty (per registration, per hour outside the
  window). Unused in HARD mode. 0 = use default.
  """
  slotTimeWeight: Float!

  """
  Terminplan (winter): exams must not start before this (HH:MM), e.g. 10:00.
  """
  slotTimeWinterEarliest: String!

  """
  Terminplan (summer): exams must not start after this (HH:MM), e.g. 14:00
  (non-climatised rooms get too hot in the afternoon).
  """
  slotTimeSummerLatest: String!

  """
  Terminplan (summer): mild 'earlier is better' pull below the cutoff (per
  registration, per hour later than the day's first slot). 0 = use default.
  """
  slotTimeGradientWeight: Float!

  """
  spread: two exams of a student directly consecutive on the same day (very bad).
  """
  examAdjacent: Float!

  """spread: two exams of a student on the same day but not consecutive."""
  examSameDay: Float!

  """spread across days: DayFactor · 24 / hours between the two exams."""
  examDayFactor: Float!

  """
  convex term protecting the least well-spread student (+ WorstCase · P²).
  """
  examWorstCase: Float!

  """down-weight applied to (likely) repeat-exam conflict pairs (0..1)."""
  examRepeatFactor: Float!

  """
  attract: pull parallel sections / small same-examer exams close together.
  """
  examAttract: Float!

  """even distribution: convex penalty on the seat load per start time."""
  examSlotLoad: Float!

  """soft seat threshold per start time for the slot-load term."""
  examLoadThreshold: Int!

  """
  penalty per unplaced exam (dominant — keep very high so all exams get placed).
  """
  examUnplaced: Float!

  """
  extra penalty for a same-day student pair across campuses (travel gap).
  """
  examCrossCampus: Float!

  """
  per unused booked T-building seat in the EXaHM/SEB room phase (phase A only).
  """
  examTbauFill: Float!

  """
  per empty start time between two occupied ones on the same day (bad for invigilation).
  """
  examHole: Float!

  """
  0 = tiered/grid-equivalent same-day cost; >0 = continuous falloff time constant (minutes) for finer start times.
  """
  examClosenessFalloffMin: Float!

  """
  Pre-plan (SEB/EXaHM): usable fraction of a slot's booked Anny seats (1.0 = fill completely).
  """
  preplanCapacityFactor: Float!

  """
  Room plan: whether/how the summer heat constraints apply (default AUTO by semester).
  """
  roomHeatMode: RoomHeatConstraintMode!

  """
  Room plan: penalty per unplaced seat (dominant — keep very high so everyone gets a room).
  """
  roomUnplaced: Float!

  """
  Room plan: penalty per seat an exam's free-seat buffer falls short (do not pack rooms full).
  """
  roomBuffer: Float!

  """
  Room plan: penalty per extra room an exam is split across (keep an exam together).
  """
  roomSplit: Float!

  """
  Room plan: penalty per distinct room used overall (compaction — request/open fewer rooms).
  """
  roomCompaction: Float!

  """
  Room plan (summer): penalty per (floor × lateness × seat) in own rooms — later = lower floor.
  """
  roomHeatFloor: Float!

  """
  Room plan: penalty per seat whose room differs from the saved plan on a re-run (warm start).
  """
  roomChurn: Float!

  """
  Room plan (summer): clock hour up to which a slot start is 'cool' (lateness
  0); later starts get lateness = start − baseline.
  """
  roomHeatBaselineHour: Float!
}

input GenerationConfigInput {
  iterations: Int!
  startTemp: Float!
  endTemp: Float!
  toleranceMin: Int!
  maxSpanHours: Float!
  weightMinuteBalance: Float!
  weightBeyondTolerance: Float!
  weightOverTargetFactor: Float!
  weightCoverage: Float!
  weightMaxDays: Float!
  weightPreferExamDays: Float!
  weightDistribution: Float!
  weightDaySpan: Float!
  slotTimeMode: SlotTimeConstraintMode!
  slotTimeEnforcement: SlotTimeConstraintEnforcement!
  slotTimeWeight: Float!
  slotTimeWinterEarliest: String!
  slotTimeSummerLatest: String!
  slotTimeGradientWeight: Float!
  examAdjacent: Float!
  examSameDay: Float!
  examDayFactor: Float!
  examWorstCase: Float!
  examRepeatFactor: Float!
  examAttract: Float!
  examSlotLoad: Float!
  examLoadThreshold: Int!
  examUnplaced: Float!
  examCrossCampus: Float!
  examTbauFill: Float!
  examHole: Float!
  examClosenessFalloffMin: Float!
  preplanCapacityFactor: Float!
  roomHeatMode: RoomHeatConstraintMode!
  roomUnplaced: Float!
  roomBuffer: Float!
  roomSplit: Float!
  roomCompaction: Float!
  roomHeatFloor: Float!
  roomChurn: Float!
  roomHeatBaselineHour: Float!
}

type ImportJointResult {
  """programs (Studiengruppen) found in the CSV."""
  programs: [String!]!

  """total exam rows imported into the joint_<program> collections."""
  examsImported: Int!

  """new non-ZPA exams created (non-FK07, not existing yet)."""
  examsCreated: Int!

  """non-FK07 exams that already existed (kept with their ancode)."""
  examsExisting: Int!

  """FK07 exams skipped (they exist as ZPA exams, only linked)."""
  examsSkippedFK07: Int!

  """
  assembled exams of the imported programs removed because they are no longer in the CSV (or flipped to FK07).
  """
  examsRemoved: Int!
}

type Invigilation {
  roomName: String
  duration: Int!
  invigilatorID: Int!
  slot: Slot!
  isReserve: Boolean!
  isSelfInvigilation: Boolean!
  prePlanned: Boolean!
}

"""
InvigilationReport is the structured outcome of an invigilation generation run,
mirroring the textual report. It is delivered once on the final RESULT line of
the assignInvigilations subscription (also for dryRun, where nothing is
written to the database).
"""
type InvigilationReport {
  seed: Int!
  iterations: Int!
  iterationsRun: Int!
  stoppedEarly: Boolean!
  balance: BalanceReport!
  coverage: CoverageReport!
  minutes: MinutesReport!
  outliers: [InvigilatorOutlier!]!
  fairness: [FairnessDistribution!]!
  softCost: SoftCostReport!
}

type InvigilationSlot {
  reserve: Teacher

  """true if the reserve invigilation in this slot is pre-planned (fixed)."""
  reservePrePlanned: Boolean!
  roomsWithInvigilators: [RoomWithInvigilator!]!
}

"""
InvigilationTimeWindow restricts, for one calendar date, the times an
invigilator may invigilate. An assigned invigilation must start no earlier than
from (if set) and end no later than until (if set). The check is sub-slot
granular and NTA-aware, since the end time includes the room's (possibly
NTA-extended) duration.
"""
type InvigilationTimeWindow {
  date: Time!
  from: Time
  until: Time
}

"""
date is the calendar day; from/until are clock times on that day (at least one of from/until must be set).
"""
input InvigilationTimeWindowInput {
  date: Time!
  from: Time
  until: Time
}

type InvigilationTodos {
  sumExamRooms: Int!
  sumReserve: Int!
  sumOtherContributions: Int!
  sumOtherContributionsOvertimeCutted: Int!
  invigilatorCount: Int!
  todoPerInvigilator: Int!
  todoPerInvigilatorOvertimeCutted: Int!
  invigilators: [Invigilator!]!
}

type Invigilator {
  teacher: Teacher!
  requirements: InvigilatorRequirements
  todos: InvigilatorTodos
}

"""
InvigilatorConstraints are the per-invigilator constraints kept in the DB and
edited via the GUI (separate from the ZPA-sourced invigilator_requirements,
which is overwritten on every ZPA pull). They are merged on top of the ZPA
requirements: isNotInvigilator removes the person from invigilation duty,
excludedDates add whole blocked days, and timeWindows block parts of a day.
"""
type InvigilatorConstraints {
  teacherID: Int!
  isNotInvigilator: Boolean!
  excludedDates: [Time!]!
  timeWindows: [InvigilationTimeWindow!]!
}

input InvigilatorConstraintsInput {
  teacherID: Int!
  isNotInvigilator: Boolean!
  excludedDates: [Time!]!
  timeWindows: [InvigilationTimeWindowInput!]!
}

"""
InvigilatorOutlier: a person whose assigned minutes are furthest from target.
"""
type InvigilatorOutlier {
  invigilatorID: Int!
  doing: Int!
  target: Int!
  open: Int!
  percent: Float!
}

type InvigilatorRequirements {
  excludedDates: [Time!]!
  excludedDays: [Int!]!
  examTimes: [ExamTime!]!
  examDays: [Int!]!
  partTime: Float!
  oralExamsContribution: Int!
  liveCodingContribution: Int!
  masterContribution: Int!
  freeSemester: Float!
  overtimeLastSemester: Float!
  overtimeThisSemester: Float!
  allContributions: Int!
  factor: Float!

  """
  fromZpa is false if the invigilator has not yet entered their requirements in
  the ZPA. In that case default requirements (full time, no contributions) are
  used and the invigilator still has to provide their real requirements.
  """
  fromZpa: Boolean!
  timeWindows: [InvigilationTimeWindow!]!
}

type InvigilatorsForDay {
  want: [Invigilator!]!
  can: [Invigilator!]!
}

type InvigilatorTodos {
  totalMinutes: Int!
  doingMinutes: Int!
  enough: Boolean!
  invigilationDays: [Int!]
  invigilations: [Invigilation!]
}

"""A single comment on a Jira issue."""
type JiraComment {
  author: JiraUser
  body: String!
  created: Time
}

"""A Jira issue (the subset plexams reads/writes)."""
type JiraIssue {
  key: String!
  summary: String!
  description: String
  status: String
  issueType: String

  """The reporter/author. Populated in list and detail views."""
  reporter: JiraUser

  """Creation time, when known."""
  created: Time

  """
  The issue's comments, oldest first. Only populated by jiraIssue(key); empty in list views.
  """
  comments: [JiraComment!]!

  """Browse URL, e.g. https://jira.cc.hm.edu/browse/PLEX-42."""
  url: String!
}

"""
Open issues of one issue type — the grouping returned by jiraOpenIssuesByType.
"""
type JiraIssueGroup {
  issueType: String!
  issues: [JiraIssue!]!
}

"""
Open issues of one JSM customer request type — returned by jiraOpenIssuesByRequestType (FK07PP is a service desk project).
"""
type JiraRequestTypeGroup {
  """
  Customer request type name, or "(kein Anfragetyp)" for issues raised without one.
  """
  requestType: String!
  issues: [JiraIssue!]!
}

"""
A workflow transition currently available on an issue; ids are workflow- and status-specific.
"""
type JiraTransition {
  id: String!
  name: String!
}

"""
Authenticated Jira user — returned by jiraConnection to verify the configured PAT.
"""
type JiraUser {
  name: String!
  displayName: String!
  emailAddress: String!
}

type JointExam {
  primussAncode: Int!
  module: String!
  mainExamer: String!
  mainExamerID: Int
  examType: String!
  duration: Int!
  isRepeaterExam: Boolean!
  program: String!

  """
  the responsible faculty (Prüfungsplanung), e.g. FK07 / FK03 / FK08 / FK12.
  """
  plannedBy: String!

  """
  Ancode of the created/linked exam: our ZPA ancode for FK07-planned exams, the
  auto-assigned ancode for exams planned by other faculties. null if not yet
  created/linked.
  """
  ancode: Int

  """
  Link status to our data: "external" (auto-created external exam, linked), "zpa"
  (linked to a ZPA exam), or "unresolved" (FK07 exam with no clear ZPA match — needs
  manual linking).
  """
  linkStatus: String!

  """
  The plan entry, if planned: dayNumber/slotNumber = my time, externalTime = the other faculty's time.
  """
  planEntry: PlanEntry
}

"""
The reserved grid slots (matching the allowed times) for one joint study program.
"""
type JointProgramSlots {
  program: String!
  slots: [Slot!]!
}

"""Absolute start times reserved for one joint study program's exams."""
type JointProgramTimes {
  """Study program shortname (Kürzel), e.g. "DE"."""
  program: String!
  allowedTimes: [Time!]!
}

input JointProgramTimesInput {
  program: String!
  allowedTimes: [Time!]!
}

"""Laufzeit-Status der Schreibsperren."""
type LiveStatus {
  """
  Ob Schreiboperationen aktuell erlaubt sind (keine Validierung/kein exklusiver Transfer läuft).
  """
  writesAllowed: Boolean!

  """Ob der aktive Workspace schreibgeschützt ist (read-only)."""
  readOnly: Boolean!
}

"""
LogLevel classifies a streamed LogLine. PROGRESS lines are throttled optimizer
snapshots and should be rendered in-place (like a spinner) instead of appended.
DONE marks the final line of a stream.
"""
enum LogLevel {
  INFO
  WARN
  ERROR
  PROGRESS
  RESULT
  DONE
}

"""
LogLine is one streamed line of output. text carries the rendered line including
ANSI color codes, so a terminal-like frontend can display it verbatim. progress
is only set when level is PROGRESS; report is only set on the final RESULT line
of an invigilation generation and carries the structured outcome.
"""
type LogLine {
  level: LogLevel!
  text: String!
  progress: OptimizerProgress
  report: InvigilationReport
  validation: ValidationReport
  examReport: ExamScheduleReport
  roomReport: RoomPlanReport
}

"""
MinutesReport: distribution of assigned vs. target minutes around the tolerance band.
"""
type MinutesReport {
  withinTolerance: Int!
  over: Int!
  under: Int!
  toleranceMin: Int!
}

type Mutation {
  """
  Set the current user's Kürzel override. An empty string resets to the ZPA default.
  """
  setMyShortname(shortname: String!): MyAccount!

  """
  Store the current user's Jira Personal Access Token, AES-256-GCM encrypted in the
  DB. Write-only: the token is never returned by any query. Requires secrets.key to
  be configured on the server.
  """
  setMyJiraToken(token: String!): MyAccount!

  """Remove the current user's stored Jira PAT."""
  removeMyJiraToken: MyAccount!

  """Create or update an additional exam (key: ancode)."""
  upsertAdditionalExam(input: AdditionalExamInput!): AdditionalExam!

  """Delete an additional exam by ancode. Returns false if there was none."""
  deleteAdditionalExam(ancode: Int!): Boolean!

  """
  Set the personalization names that mark 'our' Anny bookings (mine=true). Does
  not filter; all bookings are still fetched and shown.
  """
  setAnnyPersonalizationNames(names: [String!]!): AnnyConfig!

  """
  Regenerate the cached assembled exams from the current data and clear the stale
  flag. Fast (~100ms); returns the new state plus the list of changes vs the
  previously cached assembled exams.
  """
  generateAssembledExams: GenerateAssembledExamsResult!

  """
  Delete the cached assembled exams and their state, undoing a generation; they can be
  rebuilt with generateAssembledExams. Returns how many assembled exams were removed.
  Blocked while a validation or transfer/email is running.
  """
  resetAssembledExams: Int!

  """
  Create or update a user (upsert by email). Admin surface for opening access to a
  wider circle with restricted rights (seed VIEWER users here). Requires role ADMIN.
  """
  setUser(email: String!, name: String!, role: Role!): User!

  """
  Remove a user from the allow-list, so they can no longer log in. Requires role ADMIN.
  """
  removeUser(email: String!): Boolean!

  """
  Mark an exam as planned by another faculty; inFK is that faculty (e.g. "FK10").
  """
  notPlannedByMe(ancode: Int!, inFK: String): Boolean!
  lab(ancode: Int!): Boolean!
  exahm(ancode: Int!): Boolean!
  seb(ancode: Int!): Boolean!
  online(ancode: Int!): Boolean!
  addConstraints(ancode: Int!, constraints: ConstraintsInput!): Constraints!
  clearEmailAttachments(kind: String!): Int!

  """
  Store a Markdown override for an email template. The Markdown is validated (must parse
  with the template functions) before it is saved. Returns the updated template.
  """
  setEmailTemplate(name: String!, markdown: String!): EmailTemplate!

  """
  Remove a template's override, reverting to the built-in default. False if there was none.
  """
  resetEmailTemplate(name: String!): Boolean!

  """
  Add a Primuss ancode mapping to a ZPA exam.
  Returns the (live computed) connected exam.
  """
  addPrimussAncode(zpaAncode: Int!, program: String!, primussAncode: Int!): ConnectedExam!

  """
  Remove a (manually added) Primuss ancode mapping of a program from a ZPA exam.
  Returns the (live computed) connected exam.
  """
  removePrimussAncode(zpaAncode: Int!, program: String!): ConnectedExam!

  """
  Renumber a Primuss exam (exam + student regs + conflicts) from fromAncode to
  toAncode within a program. Returns the (live computed) connected exam.
  """
  fixPrimussAncode(zpaAncode: Int!, program: String!, fromAncode: Int!, toAncode: Int!): ConnectedExam!

  """
  Set an explicit decision for a student's conflict (ACCEPT drops the penalty;
  VETO forces it to count despite an automatic repeat down-weighting).
  """
  setStudentConflictDecision(ancode1: Int!, ancode2: Int!, mtknr: String!, decision: ConflictDecision!): Boolean!

  """Remove the explicit decision (back to automatic handling)."""
  removeStudentConflictDecision(ancode1: Int!, ancode2: Int!, mtknr: String!): Boolean!

  """Declare / undeclare that two exams may share a slot."""
  setExamsCanShareSlot(ancode1: Int!, ancode2: Int!): Boolean!
  removeExamsCanShareSlot(ancode1: Int!, ancode2: Int!): Boolean!

  """
  Set the duration override (minutes) for an ancode. Applied only when the ZPA duration is 0.
  """
  setExamDuration(ancode: Int!, duration: Int!): ExamDurationOverride!

  """
  Remove the duration override for an ancode. Returns false if there was none.
  """
  removeExamDuration(ancode: Int!): Boolean!

  """
  fixExamRoomsPhase freezes the phase-A EXaHM/SEB placement (sets PhaseFixed, distinct
  from the manual Locked). Returns the number of exams fixed. Phase B then treats them
  as immovable obstacles.
  """
  fixExamRoomsPhase: Int!

  """
  unfixExamRoomsPhase clears the phase-A freeze on all exams (manual Locked stays).
  """
  unfixExamRoomsPhase: Boolean!

  """
  resetExamSchedule removes the generated exam schedule (phase B): all placements that
  are not manually locked, not external / not-planned-by-me and not frozen by the
  EXaHM/SEB room phase (phaseFixed). Returns the number of entries removed. A full reset
  (incl. phase A) = unfixExamRoomsPhase then resetExamSchedule. Blocked while published.
  """
  resetExamSchedule: Int!

  """Store the generation config (global). Returns the saved config."""
  setGenerationConfig(input: GenerationConfigInput!): GenerationConfig!

  """
  Pre-plan (fix) an invigilator for a room (roomName) or the reserve (roomName == null) at an exam time.
  """
  prePlanInvigilation(invigilatorID: Int!, starttime: Time!, roomName: String): Boolean!

  """
  Remove a pre-planned invigilation (key: starttime/roomName; roomName null = the reserve).
  """
  removePrePlannedInvigilation(starttime: Time!, roomName: String): Boolean!

  """
  prePlanInvigilationAt promotes the invigilation currently planned for a room
  (roomName) or the reserve (roomName == null) at an exam time to a pre-planned,
  fixed assignment, so it survives a re-run of the automatic planning.
  """
  prePlanInvigilationAt(starttime: Time!, roomName: String): Boolean!

  """
  Reset the assigned invigilations (invigilations_other) so only the
  pre-planning remains; self-invigilations are refreshed on the next generation.
  Blocked while the invigilation plan is published.
  """
  resetInvigilations: Boolean!

  """
  Create or replace the whole constraints record of one invigilator (key: teacherID).
  """
  setInvigilatorConstraints(input: InvigilatorConstraintsInput!): InvigilatorConstraints!

  """
  Remove the constraints record of one invigilator (key: teacherID). Returns false if there was none.
  """
  deleteInvigilatorConstraints(teacherID: Int!): Boolean!

  """
  Add or update a permanent (cross-semester) non-invigilator (key: teacherID),
  e.g. someone retired. name is the display name (pass the candidate's name; if
  empty the backend tries to resolve it). validFrom/validUntil (semester labels
  like "2026-SS", either omitted for an open bound) limit the semesters the
  exemption applies to; leave both empty for a truly permanent exemption, or set
  validUntil to retire it without deleting the record (so past semesters stay correct).
  """
  setPermanentNonInvigilator(teacherID: Int!, name: String!, reason: String!, validFrom: String, validUntil: String): PermanentNonInvigilator!

  """
  Remove a permanent non-invigilator (key: teacherID). Returns false if there was none.
  """
  removePermanentNonInvigilator(teacherID: Int!): Boolean!

  """
  Create a Jira issue. project/issueType fall back to the jira.project config /
  "Task" when omitted. Returns the created issue.
  """
  createJiraIssue(project: String, issueType: String, summary: String!, description: String): JiraIssue!

  """Add a plain-text comment to an issue. Returns true on success."""
  addJiraComment(key: String!, body: String!): Boolean!

  """
  Move an issue through a workflow transition (id from jiraTransitions). Returns true on success.
  """
  transitionJiraIssue(key: String!, transitionId: String!): Boolean!

  """
  Import MUC.DAI exams from a CSV (the file you get from MUC.DAI; columns Nr,
  Modulname, Prüfungsform, Bewertung, Dauer, Erstpruefender, Zweitpruefender,
  IstWiederholung, Studiengruppe, Prüfungsplanung). Replaces the joint_<program>
  data and generates the non-ZPA exams for everything not planned by FK07 (FK07
  exams already exist as ZPA exams and are only linked). The GUI sends the file
  content as text.
  """
  importJointExams(csv: String!): ImportJointResult!

  """
  Set the external date/time of an exam (e.g. a MUC.DAI exam planned by another
  faculty). The matching slot is computed and stored as the plan entry's
  externalTime. date: dd.mm.yyyy, time: HH:MM.
  """
  setExternalExamTime(ancode: Int!, date: String!, time: String!): Boolean!

  """
  Manually link a MUC.DAI exam (program + primussAncode) to a ZPA exam (zpaAncode),
  for the unresolved/wrong FK07 cases. Stored as a manual link that survives re-imports.
  """
  setJointZpaLink(program: String!, primussAncode: Int!, zpaAncode: Int!): JointExam!

  """
  Remove the (manual) link of a MUC.DAI exam and fall back to automatic detection.
  """
  removeJointLink(program: String!, primussAncode: Int!): JointExam!
  addNTA(input: NTAInput!): NTA!

  """
  Update the editable fields of an existing NTA (key: mtknr). Errors if it does not exist.
  """
  updateNTA(input: NTAInput!): NTA!

  """
  Activate/deactivate an NTA (key: mtknr). A deactivated NTA is not applied to exams.
  """
  setNTAActive(mtknr: String!, active: Boolean!): NTA!

  """
  Accept that an NTA gives up the room-alone right for one exam (key:
  mtknr/ancode), with a reason. Downgrades the rooms validation to a warning and
  is added to the NTA email.
  """
  addNtaRoomAloneWaiver(mtknr: String!, ancode: Int!, reason: String!): NtaRoomAloneWaiver!

  """Remove an NTA room-alone waiver (key: mtknr/ancode)."""
  removeNtaRoomAloneWaiver(mtknr: String!, ancode: Int!): Boolean!

  """
  Place an exam at an absolute start time (the source of truth). Any time is accepted;
  the GUI should warn — but still allow — when the time is not one of the semester's
  standard start times (semesterConfig.starttimes).
  """
  setExamTime(ancode: Int!, starttime: Time!): Boolean!

  """
  Set the planner, stored in the global DB. name + email are required; the remaining
  fields are optional sender-identity overrides — pass null/empty to fall back to the
  derived default (testMail/cc = email with +plexams, noreplyMail = noreply+plexams@hm.edu,
  noreplyName = "Prüfungsplanung FK07 (NOREPLY)").
  """
  setPlaner(name: String!, email: String!, testMail: String, cc: String, noreplyMail: String, noreplyName: String): Planer!

  """
  Override the dry-run recipient for this session only (Probeläufe page). Empty string resets to the default.
  """
  setDryRunTestMail(email: String!): DryRunTestMailStatus!

  """
  Reset the session dry-run recipient override back to the configured default.
  """
  resetDryRunTestMail: DryRunTestMailStatus!

  """
  Set or clear a planning condition by hand (e.g. mark/unmark a plan as published). Returns the new state.
  """
  setPlanningCondition(key: String!, done: Boolean!): PlanningState!

  """
  Regenerate both the cached assembled exams and the per-student planned
  registrations in one step. They share the same inputs (connected exams + Primuss
  data) and are independent of each other, so they are always (re)generated together.
  Clears both stale flags and reports both results.
  """
  generatePreparation: GeneratePreparationResult!

  """
  Generate a slot assignment for the pre-exams, distributing them only over the
  MUC.DAI slots that already have Anny rooms booked (up to ~90% of each slot's
  booked seats). Exams of the same study program never share a slot and are spread
  across days; the most important exams (EXaHM, then large SEB) are placed first.
  Uses a DSATUR constructive pass with a simulated-annealing repair for the hard
  residue. Fixed pre-exams keep their slot; all non-fixed exams are re-planned
  (with keepAssigned, currently-slotted non-fixed exams are kept too). The new
  assignment is persisted; the result is its validation.
  """
  generatePreplanAssignment(keepAssigned: Boolean): PreplanValidation!
  addPreplanExam(input: PreplanExamInput!): PreplanExam!
  updatePreplanExam(id: Int!, input: PreplanExamInput!): PreplanExam!
  deletePreplanExam(id: Int!): Boolean!

  """
  Reset the Vorplanung: clear the planned time of every NON-fixed pre-exam
  (fixed ones and the pre-exams themselves are kept). Returns how many were reset.
  """
  resetPreplanTimes: Int!

  """
  Assign the pre-exam to a start time, or clear it (pass starttime or null). The time
  must be a real slot start of this semester.
  """
  setPreplanExamTime(id: Int!, starttime: Time): PreplanExam!

  """
  Link the pre-exam to a real ZPA exam (its ancode). The ancode must exist and
  must not already be linked by another pre-exam.
  """
  connectPreplanExamToAncode(id: Int!, ancode: Int!): PreplanExam!

  """Remove the ZPA link from a pre-exam."""
  disconnectPreplanExam(id: Int!): PreplanExam!

  """
  Pin/unpin the pre-exam's current slot. A fixed pre-exam keeps its slot when the
  automatic assignment is (re-)generated; all non-fixed exams are re-planned.
  """
  setPreplanExamFixed(id: Int!, fixed: Boolean!): PreplanExam!

  """
  Mark (conflict=true) or unmark (false) another pre-exam as "must not run at the same
  time" as this one (same students). The link is kept symmetric. Soft: the automatic
  assignment then spreads the two apart (different days, else max slot distance).
  """
  setPreplanExamNotSameSlot(id: Int!, otherID: Int!, conflict: Boolean!): PreplanExam!

  """
  Mark (canShare=true) or unmark (false) another pre-exam as "may run at the same time /
  right after" this one despite a shared study program (no common students). The link is
  kept symmetric and cancels the program-based spreading for that pair.
  """
  setPreplanExamCanShareSlot(id: Int!, otherID: Int!, canShare: Boolean!): PreplanExam!

  """
  Set the constraints of a pre-exam (room restrictions, same-slot, …). Reuses the
  normal ConstraintsInput, but its `sameSlot` references other PRE-EXAM ids (not
  ancodes) — they are kept symmetric. On connectPreplanExamToAncode these
  constraints are carried over to the ZPA exam (sameSlot translated to ancodes).
  """
  setPreplanExamConstraints(id: Int!, constraints: ConstraintsInput!): PreplanExam!

  """
  resetPrimussData deletes all imported Primuss Sammellisten collections (the
  per-program studentregs/exams/count/conflicts written by the ZIP import), undoing an
  import. The manually maintained ancode overlay is kept. Returns the programs whose
  data was removed. Blocked while a validation or transfer/email is running.
  """
  resetPrimussData: [String!]!

  """
  addStudentReg manually adds a single student registration (mtknr) to a Primuss exam
  (program + ancode), e.g. to correct a missing registration. Returns true on success.
  Blocked while a validation or transfer/email is running.
  """
  addStudentReg(program: String!, ancode: Int!, mtknr: String!): Boolean!

  """
  removeStudentReg manually removes a single student registration (mtknr) from a Primuss
  exam (program + ancode). Returns the number of registrations removed (0 or 1). Blocked
  while a validation or transfer/email is running.
  """
  removeStudentReg(program: String!, ancode: Int!, mtknr: String!): Int!
  prePlanRoom(
    ancode: Int!
    roomName: String!
    reserve: Boolean!
    mtknr: String

    """
    Optional exact number of students for this room; taken verbatim when generating.
    """
    seats: Int
  ): Boolean!

  """
  Remove a pre-planned room from an exam (key: ancode/roomName/mtknr). mtknr null = the room for normal students.
  """
  removePrePlannedRoom(ancode: Int!, roomName: String!, mtknr: String): Boolean!

  """
  Block a room at an exam time so it is not used for planning there (e.g. otherwise occupied). reason is an optional note.
  """
  blockRoomAt(room: String!, starttime: Time!, reason: String): BlockedRoom!

  """Remove a room block (key: room + starttime)."""
  unblockRoomAt(room: String!, starttime: Time!): Boolean!

  """
  Block a room at several times at once (e.g. a whole day or a time range). Returns the stored blocks.
  """
  blockRoomAtTimes(room: String!, starttimes: [Time!]!, reason: String): [BlockedRoom!]!

  """
  Remove the room blocks at several times at once. Returns how many blocks were removed.
  """
  unblockRoomAtTimes(room: String!, starttimes: [Time!]!): Int!

  """
  Activate/deactivate a room (key: name). A deactivated room is not used for planning.
  """
  setRoomActive(name: String!, active: Boolean!): Room!

  """
  Create a new room (key: name). Errors if a room with that name already exists.
  """
  addRoom(input: RoomInput!): Room!

  """
  Update an existing room (key: name). Errors if it does not exist; keeps the active state.
  """
  updateRoom(input: RoomInput!): Room!

  """
  Reset the assigned room plan (planned_rooms) so only the pre-planning remains;
  re-assignment re-applies it. Blocked while the room plan is published.
  """
  resetRoomsForExams: Boolean!

  """Set the approved flag of a room request (key: room + starttime)."""
  setRoomRequestApproved(room: String!, starttime: Time!, approved: Boolean!): RoomRequest!

  """
  Activate/deactivate a room request; inactive requests are not used for room planning.
  """
  setRoomRequestActive(room: String!, starttime: Time!, active: Boolean!): RoomRequest!

  """
  Generate room requests from the current plan and REPLACE all existing ones
  (one-shot, no merge). Generated requests start active and not approved. Errors
  if requests already exist unless force is true (force discards them, including
  approved flags). Returns the number written.
  """
  applyRoomRequestsPreview(force: Boolean!): Int!

  """
  Manually add a single room request (key: room + starttime). Errors if one already exists. Starts active and not approved.
  """
  addRoomRequest(room: String!, starttime: Time!, from: Time!, until: Time!): RoomRequest!

  """
  Change the time range of an existing room request, e.g. extend it for an NTA
  (key: room + starttime). Errors if it does not exist.
  """
  updateRoomRequestTime(room: String!, starttime: Time!, from: Time!, until: Time!): RoomRequest!

  """
  Replace the raw per-semester config. The derived semesterConfig (days, slots,
  go-slots) is recomputed and stored. Returns warnings for changes that may
  invalidate an existing plan (the change is still applied).
  """
  setSemesterConfigInput(input: SemesterConfigInputData!): SaveSemesterConfigResult!

  """
  Create a new semester (in its own database) with the given config. The
  semester must match YYYY-SS / YYYY-WS and must not already have a config.
  Use setSemester to switch the running server to it afterwards.
  """
  createSemester(semester: String!, input: SemesterConfigInputData!): SaveSemesterConfigResult!

  """
  Switch the running server to another database (workspace) at runtime. `name` is
  the database name from allSemesterNames (id), e.g. "2026-SS" or "test-v2". The
  logical semester used against external systems (ZPA) is the database's own stored
  semester — independent of the database name. `semester` is an optional override,
  only needed for a database that has no stored semester yet (then it is
  remembered). The target may be empty (config null until created/imported).
  Refused while an operation is running. The GUI must refetch all data afterwards.
  """
  setSemester(name: String!, semester: String): Semester!

  """
  Create a new, independent database (workspace) for the logical semester of
  `fromSemester` (e.g. "2026-SS"), copying that semester's config (dates/slots/
  emails) so it matches. `database` is the new database name (e.g. "test-v2"); it
  must not exist yet. The data stays empty — switch to it and import (e.g. from ZPA,
  which uses the logical semester). Returns the new workspace.
  """
  createWorkspace(database: String!, fromSemester: String!): Semester!

  """
  Protect or unprotect the current database: when read-only, all data-changing
  operations (mutations and imports/generation/uploads) are rejected, but the
  semester can still be viewed and validated, and you can switch away. Useful to
  guard the real semester while replaying in a clone.
  """
  setSemesterReadOnly(readOnly: Boolean!): Semester!

  """Create or update a special-interest group (key: name)."""
  upsertSpecialInterest(input: SpecialInterestInput!): SpecialInterest!

  """
  Delete a special-interest group by name. Returns false if there was none.
  """
  deleteSpecialInterest(name: String!): Boolean!

  """
  Regenerate the per-student planned registrations from the current data and clear
  the stale flag. Returns the new state plus the number of students.
  """
  generateStudentRegs: GenerateStudentRegsResult!

  """Create or update a study program (key: shortname/Kürzel)."""
  upsertStudyProgram(input: StudyProgramInput!): StudyProgram!

  """
  Delete a study program by its shortname. Returns false if there was none.
  """
  deleteStudyProgram(shortname: String!): Boolean!

  """
  Seed study programs from the configured lists (fk07programs, joint faculties,
  miscprograms) without overwriting existing ones. Returns the number created.
  """
  seedStudyProgramsFromConfig: Int!
  addZpaExamToPlan(ancode: Int!): Boolean!
  rmZpaExamFromPlan(ancode: Int!): Boolean!
}

type MutationLogArg {
  key: String!
  value: String!
}

type MutationLogEntry {
  time: Time!

  """GraphQL operation/field name, e.g. addPreplanExam."""
  name: String!

  """mutation | subscription | upload"""
  type: String!

  """
  The operator (Prüfungsplaner) who triggered the operation; from the local
  operator.* config (empty for entries written before this was configured).
  """
  user: String

  """
  The call arguments, flattened to key/value pairs (nested input objects included).
  """
  args: [MutationLogArg!]!

  """
  Ancodes referenced by the arguments (ancode / zpaAncode / primussAncode / …).
  """
  ancodes: [Int!]!

  """
  Set when the operation returned an error (for subscriptions only the start error, if any).
  """
  error: String
  durationMs: Int!
}

"""
The current user's own account: identity (from the IdP via the auth proxy,
read-only) plus editable self-service settings — the Kürzel (shortname) and the
per-user Jira Personal Access Token (stored encrypted in the DB, never returned).
"""
type MyAccount {
  email: String!
  name: String!
  role: Role!

  """
  Effective Kürzel: the user's own override if set, otherwise the ZPA default.
  """
  shortname: String!

  """
  The Kürzel from the matching ZPA teacher record (for display / reset), empty if none.
  """
  shortnameFromZpa: String!

  """Whether an (encrypted) Jira PAT is stored for this user."""
  jiraTokenSet: Boolean!

  """When the Jira PAT was last set (null if none)."""
  jiraTokenUpdatedAt: Time
}

type NTA {
  name: String!
  email: String
  mtknr: String!
  compensation: String!
  deltaDurationPercent: Int!
  needsRoomAlone: Boolean!
  needsHardware: Boolean!
  program: String!
  from: String!
  until: String!
  lastSemester: String
  deactivated: Boolean!
}

input NTAInput {
  name: String!
  email: String
  mtknr: String!
  compensation: String!
  deltaDurationPercent: Int!
  needsRoomAlone: Boolean!
  needsHardware: Boolean!
  program: String!
  from: String!
  until: String!
}

type NtaRoomAloneWaiver {
  mtknr: String!
  ancode: Int!
  reason: String!
}

type NTAWithRegs {
  nta: NTA!
  regs: StudentRegsPerStudent
}

type NTAWithRegsByExam {
  exam: ZPAExam!
  ntas: [NTAWithRegs!]
}

type NTAWithRegsByExamAndTeacher {
  teacher: Teacher!
  exams: [NTAWithRegsByExam!]
}

"""Eine Operation mit ihrer Häufigkeit."""
type OperationCount {
  name: String!
  count: Int!
}

"""
OptimizerConstraint describes one applied constraint (for the read-only view).
"""
type OptimizerConstraint {
  name: String!
  title: String!
  description: String!

  """hard | soft"""
  kind: String!

  """soft-constraint weight (0 for hard)."""
  weight: Float!

  """display priority (lower = more important)."""
  tier: Int!
}

"""
OptimizerProgress is the structured payload of a PROGRESS LogLine, mirroring the
simulated-annealing optimizer snapshot.
"""
type OptimizerProgress {
  iteration: Int!
  total: Int!
  bestCost: Float!
  balance: Boolean!
  unfilled: Int!
}

"""
PermanentNonInvigilator is a teacher who does no invigilation duty (e.g.
retired, or a role/leave-bound exemption). It lives in the global plexams
database and therefore carries over between semesters; it implies
isNotInvigilator for the semesters it applies to.
"""
type PermanentNonInvigilator {
  teacherID: Int!

  """
  Denormalized display name, kept so the entry stays readable even after the teacher has left the FK07 invigilator pool.
  """
  name: String!
  reason: String!

  """
  First semester the exemption applies to (inclusive, label like "2026-SS");
  null = open (applies to all earlier semesters too).
  """
  validFrom: String

  """
  Last semester the exemption applies to (inclusive, label like "2026-SS"); null
  = open (never retires). Set this to retire an exemption without deleting the record.
  """
  validUntil: String
}

type PlanEntry {
  """The absolute start time — the source of truth for the placement."""
  starttime: Time!
  ancode: Int!
  locked: Boolean!

  """
  fixed by the EXaHM/SEB room phase (phase A), distinct from the manual lock.
  """
  phaseFixed: Boolean!

  """
  true for an exam placed by another faculty (kept when the generated plan is reset).
  """
  external: Boolean!
}

type Planer {
  name: String!
  email: String!

  """Override for the dry-run recipient; null/empty => defaultMail."""
  testMail: String

  """
  Override for the Cc added to every real send; null/empty => defaultMail.
  """
  cc: String

  """
  Override for the noreply From/Reply-To address of JIRA-answered mails; null/empty => noreply+plexams@hm.edu.
  """
  noreplyMail: String

  """
  Override for the noreply display name; null/empty => "Prüfungsplanung FK07 (NOREPLY)".
  """
  noreplyName: String

  """
  Derived default for testMail/cc: the planner email with +plexams (e.g. x+plexams@hm.edu).
  """
  defaultMail: String!

  """
  The address dry-run mails actually go to (override → config → defaultMail).
  """
  effectiveTestMail: String!

  """The Cc actually added to real sends (override → config → defaultMail)."""
  effectiveCc: String!

  """
  The noreply address actually used (override → config → noreply+plexams@hm.edu).
  """
  effectiveNoreplyMail: String!

  """The noreply display name actually used (override → config → default)."""
  effectiveNoreplyName: String!
}

type PlannedExam {
  ancode: Int!

  """
  internal/external ancode identity of the exam (zpaAncode + program-scoped primussAncodes)
  """
  ancodes: Ancodes!
  zpaExam: ZPAExam!
  mainExamer: Teacher!
  primussExams: [EnhancedPrimussExam!]!
  constraints: Constraints
  conflicts: [ZPAConflict!]!
  studentRegsCount: Int!
  ntas: [NTA!]!
  maxDuration: Int!
  planEntry: PlanEntry
  plannedRooms: [PlannedRoom!]
}

type PlannedRoom {
  """Absolute start time of the exam using this room."""
  starttime: Time
  room: Room!
  ancode: Int!
  duration: Int!
  handicap: Boolean!
  handicapRoomAlone: Boolean!
  reserve: Boolean!
  studentsInRoom: [String!]!
  ntaMtknr: String
  prePlanned: Boolean!
}

type PlanningCondition {
  key: String!
  title: String!
  phase: String!

  """true when the condition (milestone) is reached."""
  done: Boolean!

  """
  true when the condition is computed automatically from the underlying data
  (read-only: it cannot be toggled by hand, done follows the data).
  """
  auto: Boolean!

  """
  If set, the area this condition gates while done (e.g. ROOMS, INVIGILATIONS); null if it is not a gate.
  """
  gate: PlanningGate
}

"""Areas that can be locked by a published gate."""
enum PlanningGate {
  EXAMS
  ROOMS
  INVIGILATIONS
}

type PlanningPhase {
  key: String!
  title: String!
  conditions: [PlanningCondition!]!
}

type PlanningState {
  phases: [PlanningPhase!]!

  """
  Areas whose generation is currently locked because a gate condition is set.
  """
  blockedAreas: [PlanningGate!]!
}

type PreExam {
  zpaExam: ZPAExam!
  constraints: Constraints
  planEntry: PlanEntry
}

"""
A manually entered pseudo-exam for the SEB/EXaHM pre-planning, captured before the
ZPA exam list / Primuss data exist. Linked to a ZPA ancode later (phase 4).
"""
type PreplanExam {
  id: Int!

  """EXaHM | SEB"""
  examKind: String!
  examerID: Int!

  """Snapshot of the examer's name."""
  examerName: String!
  module: String!

  """StudyProgram shortnames."""
  programs: [String!]!
  expectedStudents: Int!
  duration: Int

  """
  Absolute start time the pre-exam is assigned to (null = not yet assigned).
  """
  plannedStarttime: Time

  """
  True when the slot is pinned and survives a re-run of the automatic assignment.
  """
  isFixed: Boolean!

  """
  PRE-EXAM ids that should not run at the same time as this one (same students). Soft:
  the assignment spreads them apart (different days, else maximum slot distance).
  """
  notSameSlot: [Int!]

  """
  PRE-EXAM ids that may run at the same time / right after this one despite sharing a
  study program (no common students). Cancels the spreading for that pair.
  """
  canShareSlot: [Int!]

  """Set once linked to a real ZPA exam."""
  ancode: Int
  notes: String

  """
  Constraints captured during pre-planning (room restrictions, same-slot, …),
  carried over to the ZPA exam on linking. In sameSlot the ints are PRE-EXAM ids.
  """
  constraints: Constraints
}

input PreplanExamInput {
  examKind: String!
  examerID: Int!
  module: String!
  programs: [String!]!
  expectedStudents: Int!
  duration: Int
  notes: String
}

"""
One graded finding of the pre-plan validation (same levels as ValidationFinding).
"""
type PreplanFinding {
  level: ValidationLevel!
  message: String!
}

type PreplanKindNeed {
  examCount: Int!
  seatsNeeded: Int!

  """Greedily suggested number of rooms of this kind to cover the seats."""
  roomsSuggested: Int!

  """Names of the suggested rooms (largest first)."""
  rooms: [String!]!

  """
  Total seats available across all rooms of this kind (per slot ceiling).
  """
  seatsAvailable: Int!

  """
  Seats already booked in Anny for this slot (0 for the unslotted bucket).
  """
  seatsBooked: Int!

  """
  Rooms still to book in Anny to cover the demand (largest first); empty when enough is booked.
  """
  roomsToBook: [String!]!
}

"""
PrePlannedInvigilation fixes an invigilator for a room (or the reserve) in a
slot before the automatic invigilation planning runs. roomName is null for a
reserve invigilation.
"""
type PrePlannedInvigilation {
  """Absolute start time."""
  starttime: Time
  invigilatorID: Int!
  roomName: String
  isReserve: Boolean!
}

type PrePlannedRoom {
  ancode: Int!
  roomName: String!
  mtknr: String
  reserve: Boolean!

  """
  Optional exact number of students planned for this room; taken verbatim when generating.
  """
  seats: Int
}

type PreplanOverview {
  slots: [PreplanSlotNeed!]!
}

type PreplanProgramConflict {
  program: String!
  preplanExamIDs: [Int!]!
  modules: [String!]!
}

type PreplanRule {
  kind: PreplanRuleKind!

  """Short German title."""
  title: String!

  """
  One- or two-sentence German explanation, including the relevant values.
  """
  description: String!
}

enum PreplanRuleKind {
  """Must always hold; a plan violating it is invalid."""
  HARD

  """Optimization goal; the solver trades these off (weighted)."""
  SOFT
}

type PreplanSameSlotGroup {
  members: [PreplanSameSlotMember!]!

  """
  true when every member is connected (the same-slot is fully carried over to the ZPA exams).
  """
  complete: Boolean!
}

type PreplanSameSlotMember {
  id: Int!
  module: String!
  examKind: String!

  """true when this member is linked to a ZPA ancode."""
  connected: Boolean!
  ancode: Int
}

type PreplanSlotNeed {
  """null starttime = the bucket of pre-exams without a slot yet."""
  starttime: Time
  exahm: PreplanKindNeed!
  seb: PreplanKindNeed!

  """
  Programs that appear in more than one pre-exam of this slot (possible clash).
  """
  conflicts: [PreplanProgramConflict!]!
}

type PreplanValidation {
  """
  True when there are no error-level findings; warnings and infos do not fail the validation.
  """
  ok: Boolean!

  """
  True when the validation did not run because there are no SEB/EXaHM pre-exams yet.
  Not a failure — render neutrally ("übersprungen"), not as a green pass.
  """
  skipped: Boolean!

  """Why the validation was skipped, if skipped."""
  skipReason: String
  assignedCount: Int!

  """ids of pre-exams without a slot."""
  unassignedIDs: [Int!]!

  """
  Human-readable findings (German), flat text at all levels (kept for backward compatibility; prefer findings).
  """
  messages: [String!]!

  """
  Graded findings. Small SEB exams that fit the R-building (no Anny booking needed)
  are warnings, real capacity shortfalls are errors.
  """
  findings: [PreplanFinding!]!
}

type PrimussExam {
  ancode: Int!
  module: String!
  mainExamer: String!
  program: String!
  examType: String!
  presence: String!
}

type PrimussExamAncode {
  ancode: Int!
  program: String!
  numberOfStuds: Int!
}

type PrimussExamByProgram {
  program: String!
  exams: [PrimussExamWithCount!]!
}

input PrimussExamInput {
  ancode: Int!
  program: String!
}

type PrimussExamWithCount {
  ancode: Int!
  module: String!
  mainExamer: String!
  program: String!
  examType: String!
  presence: String!
  studentRegsCount: Int!

  """
  true if this Primuss exam is connected to a ZPA or external (MUC.DAI) exam.
  """
  connected: Boolean!

  """
  true if connected to a ZPA exam selected to be planned by us (a subset of
  connected; false for external/MUC.DAI links or not-to-plan ZPA exams).
  """
  plannedZPA: Boolean!
}

type ProgramSpread {
  program: String!
  studentCount: Int!
  multiExamStudentCount: Int!
  avgExamsPerStudent: Float!
  freeDayShare: Float!
  sameDayShare: Float!
  avgMinFreeDays: Float!

  """
  True when too few multi-exam students back the shares to be meaningful (read them with care).
  """
  lowSampleSize: Boolean!
}

type Query {
  allSemesterNames: [Semester!]!
  semester: Semester!

  """
  null when the semester has no config yet (fresh/empty DB) — create it via createSemester / init.
  """
  semesterConfig: SemesterConfig

  """
  The raw, editable per-semester config (source of truth for the derived semesterConfig).
  """
  semesterConfigInput: SemesterConfigInput

  """
  A template for creating a new semester, seeded from the current semester's
  config (slots/emails/go-slots carry over; the planner adjusts the dates).
  """
  newSemesterConfigDefaults: SemesterConfigInput!

  """The current user's account (identity + Kürzel + Jira-token status)."""
  myAccount: MyAccount!

  """
  Additional exams: fully specified entries that are appended to the ZPA upload
  but are not part of the normal plan (replaces publish.additionalExams).
  """
  additionalExams: [AdditionalExam!]!

  """
  Plattform-Überblick für Admins (Zugriff/Rollen, Auto-Sync, Aktivität/Audit, Backup, Workspaces). Erfordert Rolle ADMIN.
  """
  adminOverview: AdminOverview!

  """
  Zustand des nächtlichen Auto-Syncs und des Admin-Digest-Versands. Erfordert Rolle ADMIN.
  """
  schedulerStatus: SchedulerStatus!
  annyBookings(room: String): [AnnyBooking!]!
  allAnnyBookings: [AnnyBooking!]!

  """
  The Anny settings stored in the DB (the token stays in the config file).
  """
  annyConfig: AnnyConfig!

  """
  State of the cached assembled exams. dirty=true means an input changed since the
  last generation (connected exams, zpa-exams-to-plan, constraints, NTAs, imports),
  so the assembled exams — and everything derived from them (planned exams) — are
  stale and should be regenerated.
  """
  assembledExamsState: AssembledExamsState!

  """
  The currently authenticated user — from the auth-proxy header, or the local dev
  fallback when auth is disabled. The GUI uses it to show identity/role and adapt
  the UI cosmetically; it is NEVER a security boundary (enforcement is in the backend).
  """
  me: User!

  """
  All known users (the authorization allow-list). Admin view for managing who may log in.
  """
  users: [User!]!

  """
  Whether the current semester has changes that are not yet captured in a
  downloaded full ZIP dump, plus the relevant timestamps. Used by the GUI to
  prominently offer the semester-dump download once something changed since the
  last backup.
  """
  backupStatus: BackupStatus!
  constraintForAncode(ancode: Int!): Constraints
  zpaExamsToPlanWithConstraints: [ZPAExamWithConstraints!]!
  emailAttachments(kind: String!): [EmailAttachmentInfo!]!

  """
  Candidates for the consolidated exam-planning info email (replacing the separate
  constraints + prepared emails): one entry per examer — every examer with at least one
  exam I plan (toPlan and not notPlannedByMe, any faculty), plus the FK07 examers who do
  have ZPA exam(s) this semester but none that I plan. Examers without any ZPA exam, and
  non-FK07 examers without a planned exam, are excluded. For selecting/deselecting
  recipients before sending. No slot/date is included.
  """
  examPlanningMailRecipients: [ExamPlanningMailRecipient!]!

  """
  All editable email templates with their effective Markdown, description and variables.
  """
  emailTemplates: [EmailTemplate!]!

  """
  The helper functions available in every email template (jiraURL, plural, …).
  """
  emailTemplateFunctions: [EmailTemplateFunction!]!

  """
  Render the given Markdown for the named template against representative sample data and
  return the HTML/text preview. Does not save. Used for the live preview + validation while
  editing; a template error is returned in the preview's `error` field, not as a GraphQL error.
  """
  renderEmailTemplatePreview(name: String!, markdown: String!): EmailTemplatePreview!
  connectedExam(ancode: Int!): ConnectedExam
  connectedExams: [ConnectedExam!]!
  assembledExams: [AssembledExam!]!
  assembledExam(ancode: Int!): AssembledExam
  plannedExams: [PlannedExam!]!
  plannedExam(ancode: Int!): PlannedExam
  jointExams: [JointExam!]!
  conflictingAncodes(ancode: Int!): [Conflict!]

  """Conflicts of the current plan, to review (accept per student)."""
  examScheduleConflicts: [ExamScheduleConflict!]!

  """All explicit per-student conflict decisions currently stored."""
  studentConflictDecisions: [StudentConflictDecision!]!

  """
  Exam pairs declared as allowed to share a slot (no student legitimately sits both).
  """
  examsCanShareSlot: [ExamPair!]!

  """
  Auto-detected canShareSlot candidates (same module+program, different examer) not yet declared.
  """
  canShareSlotSuggestions: [ExamPair!]!

  """
  Per-ancode exam duration overrides. They are only applied to exams whose ZPA
  duration is 0 (i.e. not set in the ZPA); they feed the assembled exams.
  """
  examDurationOverrides: [ExamDurationOverride!]!

  """
  The read-only list of hard/soft constraints the exam-schedule generator applies.
  """
  examScheduleConstraints: [OptimizerConstraint!]!

  """
  Summary of the EXaHM/SEB room phase for the GUI: how many EXaHM/SEB exams are planned and
  how many of those are frozen (phaseFixed) for phase B. Use allFixed to decide whether to
  warn before running generateExamSchedule (phase B), and planned/fixed to show the state
  next to the fix/unfix buttons.
  """
  examRoomsPhaseState: ExamRoomsPhaseState!

  """
  Global generation tuning: the invigilation optimizer (simulated annealing)
  parameters. Stored in the global plexams database; the config file is only a
  seed/fallback. Steers invigilation generation. (The room/invigilation turnaround
  moved to the per-semester config as timelagMin.)
  """
  generationConfig: GenerationConfig!
  invigilatorTodos: InvigilationTodos
  invigilatorsWithReq: [Invigilator!]!

  """
  invigilatorsExcludedByConfig returns the invigilators who would do invigilation
  duty (factor > 0) but are excluded only because isNotInvigilator is set in their
  DB constraints (see invigilatorConstraints). People who are out anyway are not
  listed. (The field name is kept for backwards compatibility.)
  """
  invigilatorsExcludedByConfig: [Invigilator!]!
  roomsWithInvigilationsAt(starttime: Time!): InvigilationSlot
  invigilatorsForDay(date: Time!): InvigilatorsForDay
  invigilator(room: String!, starttime: Time!): Teacher
  prePlannedInvigilations: [PrePlannedInvigilation!]!

  """
  Per-invigilator constraints stored in the DB (managed via the GUI): whether
  they do no invigilation at all, additional excluded whole days and time
  windows when they cannot invigilate. These are merged on top of the ZPA requirements.
  """
  invigilatorConstraints: [InvigilatorConstraints!]!

  """
  Teachers who never do invigilation duty again (e.g. retired). Global (plexams
  DB), carries over between semesters; always implies isNotInvigilator.
  """
  permanentNonInvigilators: [PermanentNonInvigilator!]!

  """
  All teachers in the invigilator pool, including the ones currently excluded
  (isNotInvigilator / permanent). Use this to manage constraints for everyone —
  invigilatorsWithReq only returns the ones who actually invigilate.
  """
  invigilatorCandidates: [Teacher!]!

  """Verify the configured Jira connection (GET /rest/api/2/myself)."""
  jiraConnection: JiraUser!

  """Fetch a single Jira issue by key (e.g. "PLEX-42")."""
  jiraIssue(key: String!): JiraIssue!

  """
  List the workflow transitions currently available for an issue in its current status.
  """
  jiraTransitions(key: String!): [JiraTransition!]!

  """
  All open (not-done) issues, newest first. project falls back to the
  jira.project config; omit both to span all visible projects.
  """
  jiraOpenIssues(project: String): [JiraIssue!]!

  """
  The open issues grouped by issue type (groups sorted by type, empty groups omitted).
  """
  jiraOpenIssuesByType(project: String): [JiraIssueGroup!]!

  """
  The open issues grouped by JSM customer request type (Anfragetyp), groups
  sorted by name. Only for service desk projects like FK07PP.
  """
  jiraOpenIssuesByRequestType(project: String): [JiraRequestTypeGroup!]!

  """
  Suggested ZPA exams for linking an (unresolved) MUC.DAI exam, ranked: ZPA exams that
  carry the program with a missing number (0/-1) first, then same-examer + similar
  module, then either. For the GUI to confirm/correct the link.
  """
  jointZpaCandidates(program: String!, primussAncode: Int!): [ZPAExam!]!

  """
  Audit log of mutating operations (mutations + data-changing subscriptions),
  newest first. Filter by operation name, by an ancode referenced in the
  arguments, by arbitrary argument key/value pairs, and/or a time range.
  """
  mutationLog(
    """filter by operation type: mutation | subscription | upload"""
    type: String
    name: String
    ancode: Int
    args: [ArgFilterInput!]

    """filter by the operator (Prüfungsplaner) who triggered the operation."""
    user: String
    since: Time
    until: Time
    limit: Int
  ): [MutationLogEntry!]!

  """
  Distinct operation names present in the mutation log (for a filter dropdown).
  """
  mutationLogNames: [String!]!
  ntas: [NTA!]
  ntasWithRegs: [Student!]
  nta(mtknr: String!): NTAWithRegs
  examsWithNtas: [PlannedExam!]!

  """All accepted NTA room-alone waivers of the semester."""
  ntaRoomAloneWaivers: [NtaRoomAloneWaiver!]!
  allProgramsInPlan: [String!]
  ancodesInPlan: [Int!]
  examerInPlan: [ExamerInPlan!]

  """
  examersWithExamsPlannedByMe returns the main examers of all planned exams that
  are planned by me (not flagged NotPlannedByMe).
  """
  examersWithExamsPlannedByMe: [Teacher!]!
  preExamsAt(starttime: Time!): [PreExam!]
  examsAt(starttime: Time!): [PlannedExam!]
  examsWithoutSlot: [PlannedExam!]!

  """
  examsNotOnSlotGrid returns the planned exams whose absolute start time is NOT one of the
  semester's standard slot start times (e.g. another faculty's exam placed at 11:00). They
  are invisible in a purely slot-by-slot grid, so the GUI must surface them separately —
  e.g. rendered in the slot whose time window they overlap, with the real start time shown.
  """
  examsNotOnSlotGrid: [PlannedExam!]!
  allowedSlots(ancode: Int!): [Slot!]
  awkwardSlots(ancode: Int!): [Slot!]!

  """
  The planner (name + email + sender-identity overrides). Stored globally in the DB; the config is only a fallback.
  """
  planer: Planer!

  """
  The current dry-run recipient status (session override vs. configured default) for the Probeläufe page.
  """
  dryRunTestMail: DryRunTestMailStatus!

  """The planning state (phases, conditions, currently locked areas)."""
  planningState: PlanningState!

  """
  Validate the current slot assignment of the pre-exams (unassigned, capacity, program overlaps).
  """
  validatePreplanAssignment: PreplanValidation!

  """
  The hard and soft rules the SEB/EXaHM pre-planning uses, as a human-readable list
  for a read-only display in the GUI. Derived from the solver so it stays in sync.
  """
  preplanConstraints: [PreplanRule!]!

  """SEB/EXaHM pre-planning pseudo-exams of this semester."""
  preplanExams: [PreplanExam!]!
  preplanExam(id: Int!): PreplanExam

  """
  Candidate ZPA exams for linking the given pre-exam, ranked by examer (same
  teacher) and module-name similarity. Empty before the ZPA exams are imported.
  """
  preplanExamAncodeSuggestions(id: Int!): [ZPAExam!]!

  """
  Same-slot groups of pre-exams (>= 2 members) with each member's connection status, so
  the GUI can show which members are still pending. The same-slot is only carried over to
  the ZPA exams once every member of a group is connected (complete = true).
  """
  preplanSameSlotGroups: [PreplanSameSlotGroup!]!

  """
  Room-need and program-overlap overview for the SEB/EXaHM pre-planning: per slot
  (plus one entry with null day/slot for not-yet-slotted pre-exams) the seat demand
  and a suggested set of rooms per kind, and the program overlaps within the slot.
  """
  preplanOverview: PreplanOverview!
  primussExams: [PrimussExamByProgram]
  primussExam(program: String!, ancode: Int!): PrimussExam!
  primussExamsForAnCode(ancode: Int!): [PrimussExam!]
  studentRegsForProgram(program: String!): [StudentReg!]
  rooms: [Room!]!
  prePlannedRooms: [PrePlannedRoom!]!
  roomsAt(starttime: Time!): RoomsForSlot
  roomsForSlots: [RoomsForSlot!]!
  plannedRooms: [PlannedRoom!]!
  plannedRoomNames: [String!]
  plannedRoomNamesAt(starttime: Time!): [String!]
  plannedRoomsAt(starttime: Time!): [PlannedRoom!]
  plannedRoomForStudent(ancode: Int!, mtknr: String!): PlannedRoom

  """
  All rooms blocked for a specific slot (not usable there, e.g. otherwise occupied).
  """
  blockedRooms: [BlockedRoom!]!

  """
  All rooms allowed at a time with their free seats and which exams already use
  them — for sharing a room (e.g. as a reserve).
  """
  roomsWithFreeSeatsAt(starttime: Time!): [RoomWithFreeSeats!]!

  """
  Students that could not be assigned a real room in their slot during the last
  room generation (the replacement for the old 'No Room' placeholder).
  """
  unplacedExams: [UnplacedExam!]!

  """
  The read-only list of hard/soft constraints the room-plan generator (solver) applies.
  """
  roomPlanConstraints: [OptimizerConstraint!]!

  """All building-management room requests of the semester."""
  roomRequests: [RoomRequest!]!

  """
  Dry-run: which management rooms would be requested for which exams (read-only, changes nothing).
  """
  roomRequestsPreview: [RoomRequestPreview!]!

  """
  Runtime information about the running plexams.go server: its build version
  and the MongoDB it is connected to. Used e.g. for the GUI footer.
  """
  serverInfo: ServerInfo!

  """
  Special-interest groups (named ancode lists) used for the Studierenden-Info PDFs.
  """
  specialInterests: [SpecialInterest!]!

  """
  Student-centric quality statistics of the current plan: how well the exams are
  spread out in time for the individual students. Covers our OWN students (enrolled in
  an FK07 or MUC.DAI program) with at most `maxRegularNonRepeatExams` non-repeat exams —
  the most anyone can have in a normal course of study; students beyond that (many
  repeat registrations) are excluded from the figures and only summarized via
  `excludedStudentCount` / `allFreeDayShare`, since including them barely moves the
  aggregate.
  
  Aggregates the gaps between each student's consecutive exams (NTA-aware, absolute
  times, calendar-day gaps) into human-readable shares (e.g. "share of students with at
  least one exam-free day between all their exams"), a distribution histogram, a
  per-program breakdown and a Carter-style proximity index.
  
  Spurious pairs are dropped from the gap statistics (as ValidateConflicts does):
  two exams of other faculties (not ours to resolve) and two exams declared same-slot
  or can-share-slot (a student may not sit both, so the registration is invalid). Only
  registrations that appear in the plan are counted (to-plan ZPA exams and external
  exams); not-to-plan ZPA exams (e.g. Modularbeiten) and orphan MUC.DAI Primuss
  registrations are already excluded upstream.
  
  Same data feeds the GUI and the printable PDF (/download/pdf/spread-statistics).
  """
  examSpreadStatistics: ExamSpreadStatistics!

  """
  State of the prepared student registrations (the per-student planned regs shown
  via `students`). dirty=true means an input changed since the last generation
  (connected exams, which exams are planned, NTAs, ZPA imports), so they should be
  regenerated.
  """
  studentRegsState: StudentRegsState!
  studentByMtknr(mtknr: String!): Student
  studentsByName(regex: String!): [Student!]!
  students: [Student!]!

  """All study programs (Studiengänge), global/cross-semester."""
  studyPrograms: [StudyProgram!]!
  teacher(id: Int!): Teacher
  teachers(fromZPA: Boolean): [Teacher!]!
  invigilators: [ZPAInvigilator!]!
  fk07programs: [FK07Program!]!
  zpaExams(fromZPA: Boolean): [ZPAExam!]!
  zpaExamsByType: [ZPAExamsForType!]!
  zpaExamsNotToPlan: [ZPAExam!]!
  zpaExamsPlaningStatusUnknown: [ZPAExam!]!
  zpaExam(ancode: Int!): ZPAExam
  zpaAnCodes: [AnCode]
  studentRegsImportErrors: [RegWithError!]!

  """
  Transfer history (imports from / uploads to ZPA, Anny, …), newest first.
  The whole history since the start of the semester is kept; pass limit to cap it.
  """
  syncLog(limit: Int): [SyncLogEntry!]!
}

type RegWithError {
  registration: ZPAStudentReg!
  error: ZPAStudentRegError!
}

"""
RegWithProgram is one student's registration for one exam in one study program — the
per-program projection of an exam's Ancodes: the external primussAncode plus the
internal zpaAncode (equal for FK07, different for MUC.DAI/external exams).
"""
type RegWithProgram {
  program: String!
  primussAncode: Int!
  zpaAncode: Int!
}

"""
A role governs what a logged-in user may do. A user has exactly one role; the roles
form a hierarchy ADMIN ⊇ PLANER ⊇ VIEWER:
- VIEWER: read-only (queries + validations, no mutations/data-changing subscriptions).
- PLANER: full planning access (everything VIEWER can, plus all data-changing ops).
- ADMIN:  everything PLANER can, plus user administration (setUser/removeUser).
The enum is intentionally extensible for finer-grained roles later.
"""
enum Role {
  ADMIN
  PLANER
  VIEWER
}

"""Anzahl der Nutzer je Rolle."""
type RoleCounts {
  admin: Int!
  planer: Int!
  viewer: Int!
  total: Int!
}

type Room {
  name: String!
  seats: Int!
  handicap: Boolean!
  lab: Boolean!
  placesWithSocket: Boolean!

  """needsRequest is derived: true when requestWith is not NONE."""
  needsRequest: Boolean!
  requestWith: RoomRequestType!

  """
  Lower number = preferred when generating room requests (e.g. R1.006/R1.046 = 1, R1.049 = 2).
  """
  requestPriority: Int!
  exahm: Boolean!
  seb: Boolean!
  sebSeats: Int
  hmebSeats: Int
  deactivated: Boolean!

  """
  Optional summer heat override (higher = hotter). Null = derive from the
  R-building floor in the name. Only used for own (non-booked) rooms.
  """
  hitzewert: Int
}

type RoomAndExam {
  room: PlannedRoom!
  exam: ZPAExam!
}

type RoomConstraints {
  allowedRooms: [String!]
  placesWithSocket: Boolean!
  lab: Boolean!
  exahm: Boolean!
  seb: Boolean!
  kdpJiraURL: String
  maxStudents: Int

  """
  extra seats to reserve on top of the registered students (capacity buffer).
  """
  additionalSeats: Int

  """
  Lead time (Vorlauf) in minutes the rooms must be free BEFORE this exam starts, as a
  total that REPLACES the default 15 min (null = default). Used for setup that exceeds the
  ordinary turnaround, e.g. an EXaHM exam in the T-building.
  """
  preExamMinutes: Int

  """
  Trailing time (Nachlauf) in minutes the rooms stay occupied AFTER this exam ends, total
  that REPLACES the default 15 min (null = default).
  """
  postExamMinutes: Int
  comments: String
}

"""
When the room-plan generator applies the summer heat constraints (heat-floor soft + summer
cooldown hard). AUTO follows the semester (active only in summer/SS); SUMMER forces them on
(for testing); OFF disables them. Only own (non-booked) rooms are ever affected. Default AUTO.
"""
enum RoomHeatConstraintMode {
  AUTO
  SUMMER
  OFF
}

input RoomInput {
  name: String!
  seats: Int!
  handicap: Boolean!
  lab: Boolean!
  placesWithSocket: Boolean!
  requestWith: RoomRequestType!

  """
  Lower number = preferred when generating room requests. Optional; defaults to 0 (irrelevant when requestWith is NONE).
  """
  requestPriority: Int! = 0
  exahm: Boolean!
  seb: Boolean!
  sebSeats: Int
  hmebSeats: Int

  """
  Optional summer heat override (higher = hotter). Null = derive from the
  R-building floor in the name. Only used for own (non-booked) rooms.
  """
  hitzewert: Int
}

"""One exam's use of a room in a slot."""
type RoomInSlotUsage {
  ancode: Int!
  module: String!
  examer: String!
  studentCount: Int!
}

"""
Structured outcome of a solver-based room-generation run (assignRoomsForExams),
delivered once on the final RESULT line (also for dryRun).
"""
type RoomPlanReport {
  exams: Int!
  placedSeats: Int!
  unplacedSeats: Int!

  """distinct rooms used."""
  rooms: Int!
  hardViolations: [String!]!
  cost: Float!
  costByConstraint: [ConstraintCost!]!
  iterations: Int!

  """the seed used — pass it back to reproduce this exact plan."""
  seed: Int!
  stoppedEarly: Boolean!
  written: Boolean!

  """exams with students that got no room (grouped)."""
  unplacedExams: [UnplacedExam!]!
}

type RoomRequest {
  room: String!

  """Absolute start time of the exam the room is requested for."""
  starttime: Time!
  from: Time!
  until: Time!
  approved: Boolean!
  active: Boolean!
}

"""
RoomRequestPreview is one entry of the dry-run room-request generation: a
management room that would be requested for an exam in a slot. It carries the
triggering exam and the other (simultaneous) exams in that slot so the result can
be eyeballed in the GUI. The preview is read-only and changes nothing.
"""
type RoomRequestPreview {
  room: String!

  """Absolute start time of the exam the room would be requested for."""
  starttime: Time!
  from: Time!
  until: Time!
  students: Int!
  seats: Int!
  exam: PlannedExam!
  simultaneousExams: [PlannedExam!]!
}

"""
RoomRequestType says how a room that needs requesting must be requested:
NONE = no request needed, ANNY = via the Anny website (T-building), MANAGEMENT =
via the building management (Gebäudemanagement).
"""
enum RoomRequestType {
  NONE
  ANNY
  MANAGEMENT
}

type RoomsForSlot {
  starttime: Time!
  rooms: [Room!]!
}

"""
A room allowed in a slot, with its free seats and the exams already using it.
"""
type RoomWithFreeSeats {
  roomName: String!
  seats: Int!
  usedSeats: Int!
  freeSeats: Int!

  """
  handicap = true: NTA room, only for NTAs (not for normal students / non-NTA reserve).
  """
  handicap: Boolean!
  exahm: Boolean!
  lab: Boolean!
  seb: Boolean!

  """
  The exams already using this room in the slot (empty if the room is still free).
  """
  usedBy: [RoomInSlotUsage!]!
}

type RoomWithInvigilator {
  name: String!
  maxDuration: Int!
  studentCount: Int!
  roomAndExams: [RoomAndExam!]!
  invigilator: Teacher

  """
  true if the invigilation for this room in this slot is pre-planned (fixed).
  """
  prePlanned: Boolean!
}

type SaveSemesterConfigResult {
  ok: Boolean!

  """Non-fatal warnings, e.g. changes that may invalidate an existing plan."""
  warnings: [String!]!
}

"""
Zustand der beiden serverinternen Zeitpläne (nächtlicher Auto-Sync, täglicher Admin-Digest).
"""
type SchedulerStatus {
  """Ob der nächtliche Auto-Sync aktiviert ist (scheduler.enabled)."""
  autoSyncEnabled: Boolean!

  """Geplante Uhrzeit des Auto-Syncs (HH:MM, lokal)."""
  autoSyncTime: String!

  """Ob der Auto-Sync noch nie gelaufen ist (kein persistierter Zustand)."""
  neverRan: Boolean!

  """Beginn des letzten Auto-Sync-Laufs; null wenn nie gelaufen."""
  lastFireAt: Time

  """Ende des letzten Auto-Sync-Laufs; null wenn nie gelaufen."""
  lastFinished: Time

  """
  Ergebnis des letzten Laufs: ok | errors | skipped | panic (leer wenn nie gelaufen).
  """
  lastStatus: String!

  """
  Auslöser des letzten Laufs: nightly | catchup | manual (leer wenn nie gelaufen).
  """
  lastTrigger: String!

  """Workspace, den der letzte Lauf abgeglichen hat."""
  lastSemester: String!

  """Anzahl der im letzten Lauf gefundenen Änderungen."""
  lastTotalChanges: Int!

  """
  Ob der tägliche Admin-Digest aktiviert ist (scheduler.adminmail.enabled).
  """
  adminMailEnabled: Boolean!

  """Geplante Uhrzeit des Admin-Digests (HH:MM, lokal)."""
  adminMailTime: String!
}

type Semester {
  """
  the database label (e.g. '2026 SS' or a clone '2026 SS-Test'); selects the database.
  """
  id: String!

  """
  the logical semester used against external systems (ZPA), e.g. '2026 SS' — for
  a clone this stays the real semester, not the database name.
  """
  semester: String

  """
  false for databases that cannot be used with this code (no semester config).
  """
  compatible: Boolean!

  """
  true when the database is protected: it can be selected, but all mutations fail.
  """
  readOnly: Boolean!

  """data schema version of the database (null when unknown/never stamped)."""
  schemaVersion: Int
}

type SemesterConfig {
  days: [ExamDay!]!
  starttimes: [Starttime!]!
  slots: [Slot!]!

  """Reserved start times per joint study program (echo of the raw config)."""
  jointProgramAllowedTimes: [JointProgramTimes!]

  """
  Reserved grid slots per joint study program (derived from jointProgramAllowedTimes).
  """
  jointProgramSlots: [JointProgramSlots!]!
  forbiddenSlots: [Slot!]
  from: Time!
  until: Time!
  emails: Emails!

  """
  Effective travel/break buffer (minutes) between a student's consecutive exams.
  """
  examGapMinutes: Int!

  """
  Effective turnaround (minutes) between two uses of a room / between two invigilations.
  """
  timelagMin: Int!

  """
  Effective "too close" threshold (minutes, same day) for a student's two exams.
  """
  notTooCloseMinutes: Int!

  """
  Effective end-to-start travel buffer (minutes) between a student's two exams at different campuses.
  """
  crossCampusGapMinutes: Int!

  """Effective max students examined at the same start time (0 = no limit)."""
  maxSeatsPerSlot: Int!
}

"""
SemesterConfigInput is the raw, editable per-semester configuration — the values
that used to live in <semester>.yaml. The derived SemesterConfig is computed from
it.
"""
type SemesterConfigInput {
  """
  Start of the planning period; day 1 = from. Exams of other faculties may lie earlier (no check).
  """
  from: Time!
  until: Time!

  """Allowed daily exam start times as "HH:MM"."""
  startTimes: [String!]!
  forbiddenDays: [Time!]

  """
  Absolute start times reserved per joint study program (one entry per program, e.g. DE/GS/ID).
  """
  jointProgramAllowedTimes: [JointProgramTimes!]
  emails: Emails!

  """
  Travel/break buffer (minutes) a student needs between two consecutive exams (null = default).
  """
  examGapMinutes: Int

  """
  Minimum turnaround (minutes) between two uses of a room / between two invigilations (null = default).
  """
  timelagMin: Int

  """
  Two exams of a student closer than this (minutes, same day) are flagged as "too close" (null = default 120).
  """
  notTooCloseMinutes: Int

  """
  End-to-start travel buffer (minutes) a student needs between two exams at
  DIFFERENT campuses (null = default 120). Applied as a hard separation whenever
  the two exams' locations differ.
  """
  crossCampusGapMinutes: Int

  """
  Max students examined at the same start time (configurable per-time capacity
  for the Terminplan solver; null/0 = no limit).
  """
  maxSeatsPerSlot: Int
}

input SemesterConfigInputData {
  from: Time!
  until: Time!
  startTimes: [String!]!
  forbiddenDays: [Time!]

  """
  Absolute start times reserved per joint study program (one entry per program, e.g. DE/GS/ID).
  """
  jointProgramAllowedTimes: [JointProgramTimesInput!]
  emails: EmailsInput!

  """
  Travel/break buffer (minutes) a student needs between two consecutive exams (null = default).
  """
  examGapMinutes: Int

  """
  Minimum turnaround (minutes) between two uses of a room / between two invigilations (null = default).
  """
  timelagMin: Int

  """
  Two exams of a student closer than this (minutes, same day) are flagged as "too close" (null = default 120).
  """
  notTooCloseMinutes: Int

  """
  End-to-start travel buffer (minutes) a student needs between two exams at
  DIFFERENT campuses (null = default 120). Applied as a hard separation whenever
  the two exams' locations differ.
  """
  crossCampusGapMinutes: Int

  """
  Max students examined at the same start time (configurable per-time capacity
  for the Terminplan solver; null/0 = no limit).
  """
  maxSeatsPerSlot: Int
}

type ServerInfo {
  """plexams.go build version, e.g. "1.99.0" or "dev" for local builds."""
  version: String!

  """Git commit the binary was built from ("none" if unknown)."""
  commit: String!

  """Build date ("unknown" if not set)."""
  date: String!

  """Who built the binary ("unknown" if not set)."""
  builtBy: String!

  """
  Link to the GitHub release for this version, or null for dev/unreleased
  builds where no matching release exists.
  """
  releaseURL: String

  """
  The MongoDB host:port the server is connected to (credentials redacted).
  """
  mongoHost: String!

  """The MongoDB database (workspace) currently in use, e.g. "2026-SS"."""
  mongoDatabase: String!
}

type Slot {
  starttime: Time!
}

"""
How strictly the start-time window is enforced. HARD (default): a hard domain restriction —
a non-exempt exam is never placed outside its window; one that fits nowhere is left UNPLACED
with a clear reason (the rest of the plan is still written). SOFT: a strong penalty instead —
the exam may be placed outside the window (deliberate emergency deviation) but is reported as
a violation. EXaHM/SEB exams (booked T-building rooms) are exempt in both cases.
"""
enum SlotTimeConstraintEnforcement {
  HARD
  SOFT
}

"""
When the exam-schedule generator (Terminplan) applies the start-time window constraint, and
which way. AUTO follows the semester (winter → exams must not start before the morning limit,
e.g. 10:00; summer → exams must not start after the afternoon limit, e.g. 14:00, because the
non-climatised rooms get too hot); WINTER/SUMMER force one variant (for testing); OFF disables
it. Booked, climate-controlled T-building rooms (EXaHM/SEB) are always exempt. Default AUTO.
"""
enum SlotTimeConstraintMode {
  AUTO
  WINTER
  SUMMER
  OFF
}

type SoftCostItem {
  name: String!
  cost: Float!
}

"""
SoftCostReport: the weighted soft-constraint penalty score (lower is better).
"""
type SoftCostReport {
  total: Float!
  breakdown: [SoftCostItem!]!
}

type SpecialInterest {
  name: String!

  """output file name for the generated PDF."""
  filename: String!
  ancodes: [Int!]!
}

input SpecialInterestInput {
  name: String!
  filename: String!
  ancodes: [Int!]!
}

"""
A named distribution bucket with an absolute count and a percentage share.
"""
type SpreadBucket {
  """
  Stable machine key: OVERLAP | SAME_DAY | ADJACENT | ONE_FREE | TWO_FREE | THREE_PLUS_FREE.
  """
  key: String!
  label: String!
  count: Int!
  share: Float!
}

type Starttime {
  start: String!
}

type Student {
  mtknr: String!
  program: String!
  group: String!
  name: String!

  """
  internal ZPA ancodes the student is registered for (the conflict/plan key)
  """
  zpaAncodes: [Int!]!
  regsWithProgram: [RegWithProgram!]!
  zpaStudent: ZPAStudent
  nta: NTA
}

"""
StudentConflictDecision is a stored explicit decision for one student's conflict pair.
"""
type StudentConflictDecision {
  ancode1: Int!
  ancode2: Int!
  mtknr: String!
  decision: ConflictDecision!
}

type StudentReg {
  mtknr: String!

  """
  Primuss ancode (per-program namespace); == the ZPA ancode only for FK07 exams
  """
  primussAncode: Int!
  program: String!
  group: String!
  name: String!
  presence: String!
}

type StudentRegsPerAncode {
  ancode: Int!
  perProgram: [StudentRegsPerAncodeAndProgram!]!
}

type StudentRegsPerAncodeAndProgram {
  program: String!

  """internal ZPA ancode of the exam"""
  zpaAncode: Int!

  """
  external (Primuss/MUC.DAI) ancode of the exam in this program; == zpaAncode for FK07
  """
  primussAncode: Int!
  studentRegs: [StudentReg!]!
}

type StudentRegsPerStudent {
  student: Student!
  ancodes: [Int!]!
}

type StudentRegsState {
  dirty: Boolean!

  """
  the operation that last marked them stale (mutation/subscription name).
  """
  reason: String

  """when they were last marked stale or (re)generated."""
  changedAt: Time
}

"""A study program (Studiengang), e.g. IF / DE / GN."""
type StudyProgram {
  """
  Kürzel, e.g. IF (unique key). May be degree-suffixed, e.g. DC-B / DC-M.
  """
  shortname: String!
  name: String!

  """e.g. Bachelor / Master."""
  degree: String

  """
  The (still 2-letter, possibly non-unique) code this program has in the external
  ZPA system, e.g. "DC" for both DC-B and DC-M. Empty defaults to shortname.
  """
  zpaCode: String

  """Origin/grouping: fk07 | joint | misc."""
  category: String!
  active: Boolean!

  """A retired fk07 program counts as an "old program" (no longer planned)."""
  retired: Boolean!

  """
  Base ancode for external (e.g. joint-program) exams of this program: the local
  ZPA ancode is externalExamsBase + primussAncode. Only for externally imported
  programs (joint/misc).
  """
  externalExamsBase: Int

  """
  The joint Studienfakultät this program belongs to (e.g. "MUC.DAI" |
  "MUC.HEALTH"). Set exactly for category "joint" programs.
  """
  jointFaculty: String
}

input StudyProgramInput {
  shortname: String!
  name: String!
  degree: String
  zpaCode: String
  category: String!
  active: Boolean!
  retired: Boolean!
  externalExamsBase: Int
  jointFaculty: String
}

type Subscription {
  """
  assignInvigilations runs the automatic invigilation planning and streams its
  output line by line (terminal style). With dryRun the optimizer only reports;
  nothing is written to the database. seed and iterations override the config
  defaults (0/null = keep config/default). The stream ends with a DONE line.
  """
  assignInvigilations(dryRun: Boolean!, seed: Int, iterations: Int): LogLine!

  """
  Sendet den Admin-Digest sofort (statt zur geplanten Zeit) und streamt den Fortschritt.
  dryRun=true schickt die Vorschau an die Testadresse (smtp.testmail) statt an die Admins.
  Erfordert Rolle ADMIN. Endet mit DONE.
  """
  sendAdminDigestNow(dryRun: Boolean!): LogLine!
  sendEmailExaHM(run: Boolean!): LogLine!

  """
  Send the consolidated exam-planning info email to the selected examers (teacherIDs;
  null/empty = all candidates from examPlanningMailRecipients). Per examer: the exams I
  plan with their constraints (no slot/date) and a Jira link for (further) constraints,
  or — for FK07 examers I plan nothing for — a note that I plan none of their exams.
  """
  sendEmailExamPlanningInfo(run: Boolean!, teacherIDs: [Int!]): LogLine!
  sendEmailDraft(run: Boolean!): LogLine!
  sendEmailPublishedExams(run: Boolean!): LogLine!
  sendEmailPublishedRooms(run: Boolean!): LogLine!
  sendEmailInvigilations(run: Boolean!): LogLine!
  sendEmailInvigilationsMissing(run: Boolean!): LogLine!

  """
  Send an individual published-invigilations email (with the personal plan PNG) to each invigilator.
  """
  sendEmailPublishedInvigilations(run: Boolean!): LogLine!

  """Send cover-page emails to all examers with exams planned by me."""
  sendEmailCoverPages(run: Boolean!): LogLine!

  """Send the cover-page email to a single examer."""
  sendEmailCoverPage(teacherID: Int!, run: Boolean!): LogLine!

  """
  Send the request for the active building-management rooms to the Gebäudemanagement.
  """
  sendEmailRoomRequests(run: Boolean!): LogLine!

  """
  Send the secretariat the room occupancy (per non-request room, when it is used
  by an exam; overlapping NTA times merged) with a request to check it against
  ZPA. Send before publishing the room plan.
  """
  sendEmailRoomsSecretariat(run: Boolean!): LogLine!

  """
  Send the KDP the overview of the EXaHM/SEB room planning (by day/time and
  room, with per-exam seat counts and a room-oriented CSV attachment). Send
  after publishing the room plan.
  """
  sendEmailKdpExahm(run: Boolean!): LogLine!

  """
  Send the Lehrbeauftragten-Beauftragte:r (lbaba) an overview of all repeat
  exams of LBAs I planned (dates and invigilations only).
  """
  sendEmailLbaRepeaters(run: Boolean!): LogLine!

  """
  Send the secretariat a short note that the invigilation planning is finished,
  everything is in ZPA and the plan may be posted. Send after publishing the
  invigilation plan.
  """
  sendEmailInvigilationsSecretariat(run: Boolean!): LogLine!

  """Send the primuss-data email to every examer with exams planned by me."""
  sendEmailPrimussDataAll(run: Boolean!): LogLine!

  """
  Send the primuss-data email for a single exam (by ZPA ancode). updated marks it as an update.
  """
  sendEmailPrimussData(ancode: Int!, updated: Boolean!, run: Boolean!): LogLine!

  """Send primuss data for an exam not planned by us to a single address."""
  sendEmailPrimussDataUnplanned(program: String!, ancode: Int!, email: String!, run: Boolean!): LogLine!

  """Inform the examers about a new NTA (by Matrikelnummer)."""
  sendEmailNewNTA(mtknr: String!, run: Boolean!): LogLine!

  """Email NTAs with a claim to a room of their own (mtknr, or "all")."""
  sendEmailNTARoomAlone(mtknr: String!, run: Boolean!): LogLine!

  """Email all NTAs their planned rooms after room planning."""
  sendEmailNTAPlanned(run: Boolean!): LogLine!

  """
  generateExamSchedule runs the automatic exam-schedule (Terminplan) generation and
  streams its terminal-style output line by line. With dryRun nothing is written; the
  final RESULT line carries the structured examReport either way. A non-dry-run write
  is refused while the plan is gated (draft sent / published). With keepAssigned the
  current plan is used as the warm start (only improve, minimal churn) instead of
  building a fresh assignment from scratch.
  """
  generateExamSchedule(dryRun: Boolean!, seed: Int, iterations: Int, ignoreRatings: Boolean, keepAssigned: Boolean): LogLine!

  """
  generateExamRoomsPhase runs phase A: it schedules ONLY the EXaHM/SEB exams into the
  booked T-building slots, maximizing room usage, and streams its output line by line.
  With dryRun nothing is written. After a satisfactory run, fixExamRoomsPhase freezes
  the result so the regular generateExamSchedule (phase B) leaves those exams untouched.
  """
  generateExamRoomsPhase(dryRun: Boolean!, seed: Int, iterations: Int): LogLine!

  """
  Assign rooms to all exams with the constraint solver (simulated annealing) and stream the
  output line by line. The allowed rooms per slot are computed live from the current
  rooms/requests/bookings. With dryRun nothing is written; the final RESULT line carries the
  structured roomReport either way. seed and iterations override the defaults (0/null = keep
  default). With keepAssigned the current plan is used as the warm start (minimal churn).
  """
  assignRoomsForExams(dryRun: Boolean! = false, seed: Int, iterations: Int, keepAssigned: Boolean): LogLine!

  """
  Fetch the room bookings from anny.eu and store them (used for the EXaHM room slots). Streams its output.
  """
  importAnnyBookings: LogLine!
  validateInvigilatorRequirements: LogLine!
  validateInvigilationDuplicates: LogLine!
  validateInvigilatorSlots: LogLine!
  validateInvigilationsTimeDistance: LogLine!
  validateInvigilationConstraints: LogLine!
  validateRoomsPerSlot: LogLine!
  validateRoomsNeedRequest: LogLine!
  validateRoomsPerExam: LogLine!
  validateRoomsTimeDistance: LogLine!
  validateRoomsBlocked: LogLine!
  validateRoomsEnoughSeats: LogLine!
  validateZPADateTimes: LogLine!
  validateZPARooms: LogLine!
  validateZPAInvigilators: LogLine!
  validateConflicts(onlyPlannedByMe: Boolean!, ancode: Int!): LogLine!
  validateConstraints: LogLine!
  validateStudentRegs: LogLine!

  """
  validateSemesterTimes checks the generated Terminplan against the semester start-time
  window (winter: not before slotTimeWinterEarliest; summer: not after slotTimeSummerLatest).
  Our own non-exempt exams outside the window are graded by the configured enforcement
  (HARD → error, SOFT → warning); EXaHM/SEB (climate-controlled T-Bau) placements outside
  the window are reported as INFO only.
  """
  validateSemesterTimes: LogLine!
  validateDBPlanEntries: LogLine!
  validateDBConstraints: LogLine!
  validateDBRooms: LogLine!
  validateDBNtas: LogLine!
  validateDBReferences: LogLine!

  """
  Upload the planned exams to ZPA without rooms or invigilators (dryRun = build only, do not post).
  """
  uploadExamsToZPA(dryRun: Boolean!): LogLine!

  """Upload the planned exams to ZPA including planned rooms."""
  uploadExamsWithRoomsToZPA(dryRun: Boolean!): LogLine!

  """
  Upload the planned exams to ZPA including planned rooms and invigilators.
  """
  uploadExamsWithInvigilatorsToZPA(dryRun: Boolean!): LogLine!

  """Upload the student registrations to ZPA."""
  uploadStudentRegsToZPA: LogLine!

  """Fetch teachers from ZPA and cache them."""
  importTeachersFromZPA: LogLine!

  """Fetch exams from ZPA and cache them."""
  importExamsFromZPA: LogLine!

  """Fetch invigilator requirements from ZPA and cache them."""
  importInvigilatorRequirementsFromZPA: LogLine!

  """Fetch the ZPA infos of students with registrations and cache them."""
  importStudentsFromZPA: LogLine!

  """
  Run the nightly auto-sync now: pull ZPA (exams/teachers/invigilator
  requirements) and Anny bookings, record the diff and mail it. Streams
  progress; ends with DONE.
  """
  triggerScheduledSync: LogLine!
}

type SyncChangeEntry {
  """added | removed | changed"""
  type: String!
  name: String!

  """set only for changed entries"""
  fields: [SyncFieldChange!]
}

type SyncFieldChange {
  field: String!
  old: String!
  new: String!
}

"""
SyncLogEntry records one external transfer (import from / upload to ZPA, Anny, …).
For imports it also carries the diff against the DB state right before it.
"""
type SyncLogEntry {
  time: Time!

  """
  stable key, e.g. zpa-import-exams, zpa-upload-plan-exams-rooms, anny-import-bookings
  """
  operation: String!

  """human-readable label"""
  label: String!

  """import | upload"""
  direction: String!

  """ZPA | Anny | …"""
  system: String!
  ok: Boolean!
  summary: String!
  added: Int!
  changed: Int!
  removed: Int!

  """per-entry detail (imports only)"""
  entries: [SyncChangeEntry!]
}

type Teacher {
  shortname: String!
  fullname: String!
  isProf: Boolean!
  isLBA: Boolean!
  isProfHC: Boolean!
  isStaff: Boolean!
  lastSemester: String!
  fk: String!
  id: Int!
  email: String!
  isActive: Boolean!
}

scalar Time

"""
Students of an exam that could not be assigned a real room in their slot during
room generation (kept out of the planned rooms).
"""
type UnplacedExam {
  """Absolute start time of the exam."""
  starttime: Time
  ancode: Int!
  mtknrs: [String!]!

  """set if these are NTA students (then mtknrs has exactly one entry)."""
  ntaMtknr: String
}

"""
UnplacedExamReason is the reason a single exam ended up unplaced in a generation run.
"""
type UnplacedExamReason {
  ancode: Int!
  reason: String!
}

"""
A user is a login identity supplied by the auth proxy (Shibboleth/OIDC, matched by
email) together with a role. Users live in the global plexams DB and are the
authorization allow-list. Kept strictly separate from the planer (the shared email
sender identity).
"""
type User {
  email: String!
  name: String!
  role: Role!

  """
  Kürzel (shortname) override; empty when not set — the effective value then
  defaults to the ZPA teacher shortname (see myAccount).
  """
  shortname: String!
}

"""
ValidationFinding is one problem (or note) found by a validator. message is clean
text (no ANSI); the optional reference fields let the GUI link a finding to the
affected exam / room / slot / invigilator / student and render it as a row.
"""
type ValidationFinding {
  level: ValidationLevel!
  message: String!
  ancode: Int
  relatedAncodes: [Int!]
  room: String

  """
  Absolute start time of the affected slot (derived; null when not slot-related).
  """
  starttime: Time
  invigilatorID: Int
  studentMtknr: String
}

"""ValidationLevel classifies a single validation finding."""
enum ValidationLevel {
  INFO
  WARNING
  ERROR
}

"""
ValidationReport is the structured outcome of one validator. It is delivered on
the final RESULT line of the validator's subscription (in LogLine.validation),
while the human-readable lines stream before it.
"""
type ValidationReport {
  name: String!
  ok: Boolean!

  """
  True when the validator did not run because the data it checks does not exist yet
  (e.g. no exam plan, no rooms, no invigilations). Not a failure — render neutrally
  ("übersprungen"), not as a green pass.
  """
  skipped: Boolean!

  """Why the validator was skipped, if skipped."""
  skipReason: String
  errorCount: Int!
  warningCount: Int!
  infoCount: Int!
  findings: [ValidationFinding!]!
}

type WorstStudent {
  mtknr: String!
  name: String!
  program: String!
  group: String!
  examCount: Int!

  """
  Smallest free-days-between over the student's consecutive exams: -2 overlap, -1 same day, 0 adjacent, k = k free days.
  """
  minFreeDays: Int!
  worstLabel: String!
  exams: [WorstStudentExam!]!
}

type WorstStudentExam {
  ancode: Int!
  module: String!
  starttime: Time!
  durationMinutes: Int!
}

type ZPAConflict {
  ancode: Int!
  numberOfStuds: Int!
  primussAncodes: [PrimussExamAncode!]!
}

type ZPAExam {
  zpaID: Int!
  semester: String!
  ancode: Int!
  module: String!
  mainExamer: String!
  mainExamerID: Int!
  examType: String!
  examTypeFull: String!
  duration: Int!
  isRepeaterExam: Boolean!
  groups: [String!]!
  primussAncodes: [ZPAPrimussAncodes!]!

  """
  Responsible faculty (Prüfungsplanung), e.g. FK03/FK08/FK12 for external MUC.DAI
  exams. Empty for our own FK07 exams — the GUI can treat empty as FK07.
  """
  faculty: String!
}

type ZPAExamsForType {
  type: String!
  exams: [ZPAExam!]!
}

type ZPAExamWithConstraints {
  zpaExam: ZPAExam!
  constraints: Constraints
  planEntry: PlanEntry
}

type ZPAInvigilator {
  teacher: Teacher!
  hasSubmittedRequirements: Boolean!
}

type ZPAPrimussAncodes {
  program: String!
  ancode: Int!
}

type ZPAStudent {
  mtknr: String!
  greeting: String!
  firstName: String!
  lastName: String!
  email: String!
  gender: String!
  group: String!
}

type ZPAStudentReg {
  ancode: Int!
  mtknr: String!
  program: String!
}

type ZPAStudentRegError {
  semester: String!
  ancode: String!
  exam: String!
  mtknr: String!
  program: String!
}