openapi.yaml

openapi: "3.1.0"

# Copyright 2026 Chronos Ledger Contributors
# Licensed under the Apache License, Version 2.0
#
# This is the authoritative static OpenAPI contract for Chronos Ledger.
# FastAPI also generates a live version at runtime: GET /openapi.json, but
# only where DOCS_ENABLED allows it, which it does not under APP_ENV=production.
# The two should remain in sync. Update this file when adding or changing endpoints.

info:
  title: Chronos Ledger API
  version: "0.17.0" # x-release-please-version
  description: |
    Organization Schedule & Attendance Management REST API.

    **Authentication**: All endpoints except `/config`, `/auth/login` and
    `/guest/visit/{code}` require a Bearer JWT in the `Authorization` header. An API key in
    `X-API-Key` is accepted in place of one anywhere, which is how a lobby
    terminal with no one to sign in reaches `/guest/register-checkin` and
    `/guest/directory`. A key can be narrowed to part of the API and given
    an end date: see the `ApiKeyAuth` security scheme.

    **Roles**: `ORG_ADMIN` > `UNIT_ADMIN` > `STAFF` > `MEMBER`.
    Role requirements are noted on each endpoint.

    **Organizations**: every account belongs to one organization, and a
    caller reads and writes only that organization's data. The organization
    comes from the caller, never from the path or a header. A row in another
    organization answers `404 NOT_FOUND`, the same as a row that does not
    exist. A user id and an email address are unique across the whole
    deployment; a resource code is unique within an organization.
  contact:
    name: Chronos Ledger Contributors
    email: admin@org.internal
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0

servers:
  - url: http://localhost
    description: Local development (Docker Compose)
  - url: http://{server_ip}
    description: Organization intranet
    variables:
      server_ip:
        default: "192.168.1.100"

# ─────────────────────────────────────────────
# Reusable components
# ─────────────────────────────────────────────
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: |
        A machine credential bound to a service-account user. Accepted anywhere
        a Bearer token is, and acts as the bound user, so roles and unit scoping
        apply unchanged. This is how a lobby kiosk authenticates.

        A key can also be narrowed and given an end date, which a Bearer token
        cannot be. `scopes` is a comma separated list of `<area>:read` and
        `<area>:write`, where the area is the path segment after `/api/v1`:
        `schedule`, `resources`, `attendance`, `users`, `ingestion`, `guest`,
        `sync`, `config`, `auth`, `api-keys`, `audit`, `changes`, `webhooks`. `GET`, `HEAD` and `OPTIONS` are
        reads and everything else is a write, so `schedule:read` passes
        `GET /schedule/slots` and is refused `POST /schedule/slots` with a 403
        naming `schedule:write`. The single scope `*` is every area, which is
        what a key issued before scopes existed holds and what a key created
        without naming any gets. The one scope outside that grammar is
        `impersonate`, which `*` does not include: see below.

        A key holding `impersonate` may send `X-Chronos-Actor: <user id>` and
        the request then runs as that person, so their role and unit scoping
        apply, and the key's own scopes still apply on top. It only narrows:
        what the request may do is what both the key and the named person may
        do. The named person has to exist, be active and be in the key's
        organization; unknown and other-organization ids get the same answer.
        A Bearer token, or a key without the scope, that sends the header is
        refused with 403 `IMPERSONATION_NOT_ALLOWED` and a named person who
        cannot be acted for with 403 `IMPERSONATION_REFUSED`. The header is
        never ignored. Rate limits and idempotency keys stay with the API key,
        and the audit log records both the key's account and the person
        named. See `ActingFor`.

        `expires_at` is checked on the request, not by a sweep, so a key stops
        working the moment it runs out and answers 401 `API key expired`. A
        null expiry never runs out.

        The first-login gate does not apply to a key. It holds an admin
        account until the password it was handed is changed, and a key never
        uses that password, so a service account at an admin role works
        through its key without anyone signing in as it.

  schemas:
    # ── Enumerations ──────────────────────────
    InstitutionalRole:
      type: string
      enum: [ORG_ADMIN, UNIT_ADMIN, STAFF, MEMBER]
      description: Role assigned to a system user.

    AccessReadiness:
      type: string
      enum: [OPEN_AD_HOC, BUSY, CRITICAL_DO_NOT_DISTURB, VERY_FREE]
      description: Staff availability / occupancy index visible to members.

    DynamicState:
      type: string
      enum: [SCHEDULED, ON_LEAVE, PROXY_SUBSTITUTE, LUNCH, INTERNAL_MEETING, ADHOC_EVENT]
      description: Operational state of a daily ledger entry.

    ExecutionMode:
      type: string
      enum: [PHYSICAL, ONLINE_STREAM]
      description: Class delivery format.

    VerificationMetric:
      type: string
      enum: [PRESENT, ABSENT, LATE]
      description: Attendance marking status for a member.

    LogVerificationState:
      type: string
      enum: [PENDING_VERIFICATION, VERIFIED_APPROVED, VERIFIED_DENIED]
      description: Approval workflow state for absence requests and guest handshakes.

    # ── Auth ──────────────────────────────────
    LoginRequest:
      type: object
      required: [email_address, password]
      description: >
        `email` is accepted in place of `email_address` through 0.14 and
        removed in 0.15.
      properties:
        email_address:
          type: string
          format: email
          example: staff@org.internal
        password:
          type: string
          format: password
          example: "••••••••"

    Readiness:
      type: object
      properties:
        status:
          type: string
          enum: [ready, not ready]
        database:
          type: string
          enum: [ok, unavailable]
        redis:
          type: string
          enum: [ok, unavailable]

    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
          description: "Signed JWT. Include as `Authorization: Bearer <token>`."
        refresh_token:
          type: string
          description: Exchange at `POST /auth/refresh` for a new pair when the access token expires.
        token_type:
          type: string
          example: bearer
        user_id:
          type: string
          example: FAC001
        role:
          $ref: "#/components/schemas/InstitutionalRole"
        full_name:
          type: string
          example: Dr. Priya Sharma
        initial_login_state:
          type: boolean
          description: True on first login, client should prompt password change.

    ChangePasswordRequest:
      type: object
      required: [current_password, new_password]
      properties:
        current_password:
          type: string
          format: password
        new_password:
          type: string
          format: password
          minLength: 12
          description: >
            At least PASSWORD_MIN_LENGTH characters, 12 unless the deployment
            has raised it, and not a placeholder published in this repository.

    FederatedTokenRequest:
      type: object
      required: [token]
      properties:
        token:
          type: string
          description: >
            The note, exactly as its issuer minted it. A signed JWT whose
            `iss` names a registered issuer, whose header `kid` names one of
            that issuer's registered keys, and which carries `aud`, `sub`,
            `jti`, `iat` and `exp`. An `email` claim is what a first-time
            subject is provisioned from; `name` and `groups` are read if they
            are there.

    RefreshRequest:
      type: object
      required: [refresh_token]
      properties:
        refresh_token:
          type: string

    FeedToken:
      type: object
      properties:
        feed_token:
          type: string
          description: 256 bits out of the system random source, hex encoded.
        feed_path:
          type: string
          description: >
            The feed path this token opens, relative to the server root.
          example: /api/v1/sync/user-feed/1f4a9c2e.ics

    # ── Users ─────────────────────────────────
    UserCreate:
      type: object
      required: [id, full_name, email_address, password, role_type]
      properties:
        id:
          type: string
          example: FAC042
        full_name:
          type: string
          example: Dr. Rajan Mehta
        email_address:
          type: string
          format: email
        password:
          type: string
          format: password
          minLength: 12
          description: >
            Held to the same PASSWORD_MIN_LENGTH floor as a password the user
            chooses for themselves.
        role_type:
          $ref: "#/components/schemas/InstitutionalRole"
        unit_code:
          type: string
          nullable: true
          example: CSE
        assigned_base_station:
          type: string
          nullable: true
          example: Front Desk
        reporting_line_manager:
          type: string
          nullable: true
          example: HOD001

    UserUpdate:
      type: object
      description: >
        A field left out keeps its value and a null clears it, except
        full_name and email_address, which cannot be null (422).
      properties:
        full_name:
          type: string
        email_address:
          type: string
          format: email
        unit_code:
          type: string
          nullable: true
        assigned_base_station:
          type: string
          nullable: true
        reporting_line_manager:
          type: string
          nullable: true

    ProvisionedCredential:
      type: object
      description: >
        A password generated for a member the import created. Returned
        only in the upload response and never stored.
      properties:
        member_id:
          type: string
        email_address:
          type: string
        initial_password:
          type: string
      required: [member_id, email_address, initial_password]

    CsvImportResult:
      type: object
      properties:
        status:
          type: string
          enum: [SUCCESS, FAILED]
        rows_ingested:
          type: integer
          description: Present when status is SUCCESS.
        provisioned_credentials:
          type: array
          description: >
            One entry per member this import created, empty when the file
            only touched members who already existed. The single copy of
            these passwords: save them or reset the members individually.
          items:
            $ref: "#/components/schemas/ProvisionedCredential"
        slots_corrected:
          type: integer
          description: >
            Slots this file changed rather than created. Re-uploading a file
            with a corrected room or lead is how a timetable is edited in
            bulk; a slot whose start time moved does not match and arrives as
            a second slot instead, with the original reported in not_in_file.
        ledger_rows_updated:
          type: integer
          description: >
            Days already generated from a corrected slot that were still
            plans and now carry the new lead and room. A day whose room
            changed also has its geofence cleared, because the old one
            fenced members out of the room they have just been sent to.
        ledger_rows_kept:
          type: integer
          description: >
            Days left alone because attendance or a note has been recorded
            against them. They now disagree with the timetable on purpose:
            they record what happened. Days already past are never touched
            and are not counted here.
        kept_days:
          type: array
          description: >
            The days counted in ledger_rows_kept, earliest first, each with
            the room it still has. Present when status is SUCCESS.
          items:
            $ref: "#/components/schemas/KeptDay"
        requirements_unmet:
          type: array
          description: >
            One entry per requirement of a slot in the file, or of its
            activity or room, that the slot's next run cannot have. A
            report; the import is not refused for it.
          items:
            $ref: "#/components/schemas/SlotRequirementGap"
        not_in_file:
          $ref: "#/components/schemas/ImportOrphans"
        removed:
          $ref: "#/components/schemas/ImportRemoved"
        not_removed:
          $ref: "#/components/schemas/ImportNotRemoved"
        error_log:
          type: string
          description: Present when status is FAILED.
      required: [status]

    KeptDay:
      type: object
      description: >
        A day a re-import left as it was, because attendance or a note has
        been recorded against it. It keeps the room, lead and window it
        was held with.
      properties:
        id:
          type: integer
          description: The ledger entry, as GET /schedule/ledger returns it.
        date:
          type: string
          format: date
        activity_code:
          type: string
        master_slot_id:
          type: integer
          description: The slot the file corrected.
        time_window_start:
          type: string
          format: time
        room:
          type: string
          nullable: true
          description: The room the day still has, not the one the file names.
      required: [id, date, activity_code, master_slot_id, time_window_start, room]

    ImportOrphans:
      type: object
      description: >
        What the cycle holds that this file did not mention. A report, and
        an action only when the upload sets `remove_missing`: a file covering
        half a timetable cannot be told apart from a timetable that lost half
        its classes, so by default nothing here is removed and somebody
        decides.


        Scoped to the units named in the file, not to the whole cycle, so a
        file covering one unit does not report every class in every other
        unit each time it is uploaded.
      properties:
        slots:
          type: array
          items:
            $ref: "#/components/schemas/OrphanSlot"
        enrollments:
          type: array
          items:
            $ref: "#/components/schemas/OrphanEnrollment"
      required: [slots, enrollments]

    OrphanSlot:
      type: object
      properties:
        id:
          type: integer
          description: What DELETE /schedule/slots/{slot_id} takes, if it should go.
        activity_code:
          type: string
        rrule:
          type: string
          example: FREQ=WEEKLY;BYDAY=MO
        dtstart:
          type: string
          format: date
        time_window_start:
          type: string
          format: time
        room:
          type: string
          nullable: true
      required: [id, activity_code, rrule, dtstart, time_window_start]

    OrphanEnrollment:
      type: object
      properties:
        member_id:
          type: string
        activity_code:
          type: string
      required: [member_id, activity_code]

    ImportRemoved:
      type: object
      description: >
        What an upload with `remove_missing` set removed, from among the rows
        in `not_in_file`. Both lists are empty when the option is off.
      properties:
        slots:
          type: array
          items:
            $ref: "#/components/schemas/RemovedSlot"
        enrollments:
          type: array
          items:
            $ref: "#/components/schemas/OrphanEnrollment"
      required: [slots, enrollments]

    RemovedSlot:
      description: A slot the upload removed, as it was listed in `not_in_file`.
      allOf:
        - $ref: "#/components/schemas/OrphanSlot"
        - type: object
          properties:
            ledger_rows_removed:
              type: integer
              description: Days from today on that the slot had produced, now withdrawn.
            ledger_rows_detached:
              type: integer
              description: >
                Days already past, kept with everything recorded on them and
                no longer pointing at a slot.
          required: [ledger_rows_removed, ledger_rows_detached]

    ImportNotRemoved:
      type: object
      description: >
        What an upload with `remove_missing` set listed for removal and left
        in place. Empty when the option is off.
      properties:
        slots:
          type: array
          items:
            $ref: "#/components/schemas/NotRemovedSlot"
      required: [slots]

    NotRemovedSlot:
      description: >
        A slot the upload did not remove, as it was listed in `not_in_file`.
        It stays on the timetable with all its days.
      allOf:
        - $ref: "#/components/schemas/OrphanSlot"
        - type: object
          properties:
            reason:
              type: string
              description: >
                Why it was left, naming the dates of the days ahead that carry
                attendance or a note. Act on it with `POST /schedule/slots/{id}/retire`,
                which keeps those days.
          required: [reason]

    PasswordResetResponse:
      type: object
      properties:
        user_id:
          type: string
        initial_password:
          type: string
          description: >
            Plain text, returned only here. Never stored and never logged.
      required: [user_id, initial_password]

    UserStatusUpdate:
      type: object
      required: [status]
      properties:
        status:
          $ref: "#/components/schemas/AccessReadiness"

    UserResponse:
      type: object
      properties:
        id:
          type: string
        full_name:
          type: string
        email_address:
          type: string
        role_type:
          $ref: "#/components/schemas/InstitutionalRole"
        unit_code:
          type: string
          nullable: true
        assigned_base_station:
          type: string
          nullable: true
        current_occupancy_index:
          $ref: "#/components/schemas/AccessReadiness"
        reporting_line_manager:
          type: string
          nullable: true
        deactivated_at:
          type: string
          format: date-time
          nullable: true
          description: When the account was deactivated, or null while it is active.
        organization_id:
          type: string
          description: >
            The organization the account belongs to. Everything the account
            reads and writes is in this organization.

    OpenItems:
      type: object
      description: >
        What still names a deactivated account. Deactivating changes none of
        it and is never refused because of it; calling deactivate again
        counts afresh.
      required:
        - pending_absence_requests
        - direct_reports
        - slots_led
        - ledger_rows_ahead
      properties:
        pending_absence_requests:
          type: integer
          description: >
            Absence requests sent to the account that nobody has decided. An
            admin decides them from `GET /attendance/absence/pending`.
        direct_reports:
          type: integer
          description: Active accounts that name it as their manager.
        slots_led:
          type: integer
          description: Slots it leads in a cycle that has not ended, drafts included.
        ledger_rows_ahead:
          type: integer
          description: Ledger rows dated today or later that it leads or covers.

    DeactivatedUserResponse:
      allOf:
        - $ref: "#/components/schemas/UserResponse"
        - type: object
          required: [open_items]
          properties:
            open_items:
              $ref: "#/components/schemas/OpenItems"

    # ── API keys ─────────────────────────────
    ApiKeyCreate:
      type: object
      required: [label, user_id]
      properties:
        label:
          type: string
          minLength: 1
          maxLength: 100
          description: What this key is for, so it can be recognized in the list.
          example: Hospital information system
        user_id:
          type: string
          description: >
            The user this key acts as. The key can never do more than that
            user can, whatever its scopes say.
          example: SVC001
        scopes:
          type: array
          nullable: true
          minItems: 1
          items:
            type: string
            pattern: "^(\\*|impersonate|[a-z][a-z-]*:(read|write))$"
          description: >
            Areas this key may reach. Omit the field for an unrestricted key;
            an empty array is refused, since a key that can reach nothing is
            not a key anybody wants. Stored sorted and deduplicated. The
            scope `impersonate` lets the key act for a named person in its
            organization (header `X-Chronos-Actor`); it is granted only by
            naming it, and `*` does not include it.
          example: [schedule:read, resources:read]
        expires_at:
          type: string
          format: date-time
          nullable: true
          description: >
            When the key stops working. Omit for a key that never does. A time
            already past is refused at creation.
          example: "2027-01-01T00:00:00Z"

    ApiKeyResponse:
      type: object
      properties:
        id:
          type: integer
        key_prefix:
          type: string
          description: The first 12 characters, enough to tell two keys apart.
          example: ck_8Kd2mQ7x
        label:
          type: string
        user_id:
          type: string
        scopes:
          type: string
          description: >
            Comma separated, or `*` for a key that was never narrowed. May
            include `impersonate`, which `*` does not stand for.
          example: resources:read,schedule:read
        expires_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
          nullable: true

    ApiKeyCreated:
      allOf:
        - $ref: "#/components/schemas/ApiKeyResponse"
        - type: object
          required: [api_key]
          properties:
            api_key:
              type: string
              description: >
                The raw key. Returned exactly once, here. Only its hash is
                stored, so it cannot be shown again and a lost key has to be
                revoked and reissued.
              example: ck_8Kd2mQ7xR3nL9vB5tY1wZ0aC6eF4gH2jK8mN

    # ── Federation ────────────────────────────
    IssuerCreate:
      type: object
      required: [issuer, display_name, audience]
      properties:
        issuer:
          type: string
          maxLength: 255
          description: >
            The exact `iss` value notes will carry. Compared, never parsed:
            nothing here fetches it, so it is an identifier that happens to
            look like a URL.
          example: https://sso.example.internal
        display_name:
          type: string
          maxLength: 100
          description: What an administrator calls this issuer in a list.
          example: Campus SSO
        audience:
          type: string
          maxLength: 255
          description: >
            The `aud` this instance answers to. An issuer serving several
            relying parties should give each one its own value, so a note
            minted for another one is refused here.
          example: chronos-ledger
        enabled:
          type: boolean
          default: true
          description: >
            False is refused the same way an unknown issuer is, so turning an
            issuer off does not mean deleting what it was allowed to assert.

    IssuerUpdate:
      type: object
      description: >
        Every field is optional and one left out is unchanged. `issuer` cannot
        be changed: it is the value notes already in the wild carry, and
        editing it would retarget a registration rather than register another.
      properties:
        display_name:
          type: string
          maxLength: 100
        audience:
          type: string
          maxLength: 255
        enabled:
          type: boolean

    IssuerResponse:
      type: object
      properties:
        id:
          type: integer
          example: 3
        issuer:
          type: string
          example: https://sso.example.internal
        display_name:
          type: string
          example: Campus SSO
        audience:
          type: string
          example: chronos-ledger
        enabled:
          type: boolean
          example: true
        created_at:
          type: string
          format: date-time
          nullable: true

    IssuerKeyCreate:
      type: object
      required: [kid, public_key]
      properties:
        kid:
          type: string
          maxLength: 100
          description: >
            The `kid` the note header will carry. A note is verified against
            the key it names and no other, so an overlap during a rotation is
            two registered keys rather than two candidates per note.
          example: 2026-key-a
        public_key:
          type: string
          description: >
            An Ed25519 public key in PEM form. Loaded when it is registered, so
            a key that cannot be read is refused here rather than turning every
            note that names it into a 401 nobody can explain.
          example: |
            -----BEGIN PUBLIC KEY-----
            MCowBQYDK2VwAyEAWJyyHHtL1RwC53ABtyd229BalcSDxdE3P02wXuDoeV4=
            -----END PUBLIC KEY-----
        not_before:
          type: string
          format: date-time
          nullable: true
          description: When the key starts being accepted. Omitted means now.
        not_after:
          type: string
          format: date-time
          nullable: true
          description: >
            When it stops. Omitted is a key with no planned retirement, which
            is the ordinary case until a rotation gives it one.

    IssuerKeyRetire:
      type: object
      required: [not_after]
      properties:
        not_after:
          type: string
          format: date-time
          description: >
            The moment the key stops being accepted. A moment in the past stops
            it now, which is what a leaked key wants; a moment in the future is
            the overlap a planned rotation wants.

    IssuerKeyResponse:
      type: object
      properties:
        id:
          type: integer
        issuer_id:
          type: integer
        kid:
          type: string
        public_key:
          type: string
          description: >
            Read back in full. It is a public key, so there is nothing here a
            leak would cost anybody, and an integrator comparing what was
            registered against what is being signed with needs to see it.
        not_before:
          type: string
          format: date-time
        not_after:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
          nullable: true

    RoleMapEntryCreate:
      type: object
      required: [group_claim_value, role_type]
      properties:
        group_claim_value:
          type: string
          maxLength: 200
          description: >
            One value out of the note's `groups` claim, matched exactly. A group
            with no entry lands on `MEMBER`, so an issuer trusted to say who
            somebody is has not thereby been trusted to say what they may do.
          example: library-staff
        role_type:
          type: string
          enum: [STAFF, MEMBER]
          description: >
            `ORG_ADMIN` and `UNIT_ADMIN` are refused with a 422, and refused
            again by a check constraint. It is the one rule whose failure would
            hand an outside system this instance.
          example: STAFF
        unit_code:
          type: string
          maxLength: 50
          nullable: true
          description: The unit somebody in this group belongs to, if any.
          example: LIB

    RoleMapEntryResponse:
      type: object
      properties:
        id:
          type: integer
        issuer_id:
          type: integer
        group_claim_value:
          type: string
        role_type:
          type: string
          enum: [STAFF, MEMBER]
        unit_code:
          type: string
          nullable: true

    LinkCreate:
      type: object
      required: [issuer_id, subject, user_id]
      properties:
        issuer_id:
          type: integer
          description: The registration the subject belongs to.
          example: 3
        subject:
          type: string
          maxLength: 255
          description: >
            The `sub` notes for this person will carry. Opaque and scoped to its
            issuer: two issuers may use the same string for different people,
            which is why the pair is what has to be unique.
          example: u-4417
        user_id:
          type: string
          maxLength: 50
          description: >
            The account that subject signs in as. An `ORG_ADMIN` or `UNIT_ADMIN`
            account is refused: the role map cannot grant either role, and a
            link would be a way around that.
          example: EMP1042

    LinkResponse:
      type: object
      properties:
        id:
          type: integer
        issuer_id:
          type: integer
        subject:
          type: string
        user_id:
          type: string
        created_at:
          type: string
          format: date-time
          nullable: true
    # ── Resource classes ──────────────────────
    ResourceClassResponse:
      type: object
      required: [id, code, name, active, seeded, created_at]
      properties:
        id:
          type: integer
        code:
          type: string
          description: The stable identifier. Uppercase, unique in the organization, never changed.
          example: ROOM
        name:
          type: string
          description: What is shown. Free to change.
          example: Room
        active:
          type: boolean
          description: >
            Whether a new resource or requirement may name the class.
            Switching it off leaves the ones that already do as they are.
        seeded:
          type: boolean
          description: >
            True for `ROOM` and `PERSON`, which every organization has and
            which can be renamed but not removed or switched off. They are
            also where the engine's older behaviour is anchored: an import
            files rooms under `ROOM`. Any other class carries no behaviour,
            it is a label that resources are filed under and requirements
            can ask for.
        created_at:
          type: string
          format: date-time

    ResourceClassCreate:
      type: object
      required: [code, name]
      properties:
        code:
          type: string
          pattern: "^[A-Z][A-Z0-9_]*$"
          minLength: 1
          maxLength: 30
          description: Uppercase letters, digits and underscores, starting with a letter.
          example: EQUIPMENT_CART
        name:
          type: string
          minLength: 1
          maxLength: 120
          example: Equipment cart

    ResourceClassUpdate:
      type: object
      description: >
        Every field is optional and one left out is left alone. Neither can be
        null. code is absent on purpose: it never changes.
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 120
        active:
          type: boolean

    # ── Resources ─────────────────────────────
    ResourceResponse:
      type: object
      properties:
        id:
          type: integer
        code:
          type: string
          description: The importer's match key. Not editable.
          example: LH-3
        label:
          type: string
          example: Lecture Hall 3
        resource_type:
          type: string
          description: >
            The code of one of the organization's resource classes. `ROOM`
            and `PERSON` exist everywhere; see `GET /api/v1/resource-classes/`
            for the rest.
          example: ROOM
        unit_code:
          type: string
          nullable: true
        capacity:
          type: integer
          nullable: true
          description: >
            How many people a room holds, or on a POOLED resource how many
            units the pool has.
        mode:
          type: string
          enum: [EXCLUSIVE, POOLED, SHARED]
          description: >
            How a reservation takes the resource. EXCLUSIVE, the default, is
            one booking at a time. POOLED is capacity interchangeable units,
            of which a booking takes its quantity, refused with
            `RESOURCE_CAPACITY_EXCEEDED` when the bookings already there
            leave too few at some moment of the window. SHARED records who
            is there and refuses nobody. The mode governs reservations only:
            the timetable on any resource is one class at a time, and a
            class on a pooled resource takes the whole pool.
        user_id:
          type: string
          nullable: true
          description: Set when this resource is a person.
        latitude:
          type: number
          nullable: true
        longitude:
          type: number
          nullable: true
        altitude_target:
          type: number
          nullable: true
        active:
          type: boolean

    ResourceCreate:
      type: object
      required: [code]
      description: >
        A resource, a room unless `resource_type` says otherwise. Every
        string is trimmed first, code included, the same as the importer
        trims a room name, so this room and the same name in a later CSV are
        one row.
      properties:
        code:
          type: string
          minLength: 1
          maxLength: 30
          description: >
            The importer's match key, unique across every resource. Not
            editable afterwards.
          example: LH-3
        label:
          type: string
          minLength: 1
          maxLength: 120
          description: Defaults to the code, which is what an imported room gets.
          example: Lecture Hall 3
        resource_type:
          type: string
          pattern: "^[A-Z][A-Z0-9_]*$"
          maxLength: 30
          description: >
            The code of an active resource class of the organization. `ROOM`
            when left out. A class that is unknown, inactive or another
            organization's is a 422 with `UNKNOWN_RESOURCE_CLASS`.
          example: ROOM
        unit_code:
          type: string
          maxLength: 50
          nullable: true
        capacity:
          type: integer
          minimum: 0
          nullable: true
          description: Required, and at least 1, when mode is POOLED.
        mode:
          type: string
          enum: [EXCLUSIVE, POOLED, SHARED]
          description: See ResourceResponse.mode. EXCLUSIVE when left out.
        latitude:
          type: number
          minimum: -90
          maximum: 90
          nullable: true
          description: Set together with longitude, or not at all.
        longitude:
          type: number
          minimum: -180
          maximum: 180
          nullable: true
        altitude_target:
          type: number
          nullable: true

    ResourceUpdate:
      type: object
      description: >
        Every field is optional and a field left out is left alone. code,
        resource_type and user_id are absent on purpose: code is the importer's
        match key, and a room that becomes a person is a different resource,
        not an edit.
      properties:
        label:
          type: string
          minLength: 1
          maxLength: 120
        capacity:
          type: integer
          minimum: 0
          nullable: true
          description: >
            A POOLED resource keeps a capacity of at least 1. A cut the
            bookings still to come would no longer fit is a 409 with
            `RESOURCE_BOOKINGS_WOULD_NOT_FIT`.
        mode:
          type: string
          enum: [EXCLUSIVE, POOLED, SHARED]
          description: >
            See ResourceResponse.mode. Cannot be null. A change the bookings
            still to come would no longer fit is a 409 with
            `RESOURCE_BOOKINGS_WOULD_NOT_FIT` naming them; one that fits is
            written onto them.
        latitude:
          type: number
          minimum: -90
          maximum: 90
          nullable: true
          description: >
            Set or cleared together with longitude. Setting the pair is what
            switches geofencing on for sessions held here.
        longitude:
          type: number
          minimum: -180
          maximum: 180
          nullable: true
        altitude_target:
          type: number
          nullable: true
          description: Optional. Without it the fence is horizontal only.
        active:
          type: boolean

    BusyInterval:
      type: object
      description: >
        One window in which a resource is taken, by a weekly slot or by a
        reservation. Which kind it is can be read off the fields that are
        filled in: a slot carries the activity fields and a null
        reservation_id, and a reservation carries the reverse. What a booking
        is for is deliberately not here, because this is readable by anyone
        signed in.


        The date is the day the window opened on and end_date the day it
        finishes on. They differ when the window ran past midnight, and
        then the date can fall before the range that returned the
        interval: a booking dated Monday from 22:00 to 06:00 is on
        Tuesday's calendar.


        A generated day is a third kind and reads as a slot: it carries the
        activity fields and a null reservation_id, and its master_slot_id is
        the slot it came from, or null if that slot has since been deleted.
        Telling a day apart from the weekly slot that produced it is not
        possible from these fields alone and is not meant to be. What refused
        the request is in the message beside the list.
      properties:
        date:
          type: string
          format: date
          example: "2026-01-05"
        start:
          type: string
          format: time
          example: "09:00:00"
        end_date:
          type: string
          format: date
          description: >
            Always present, and the same as date for a window that
            finishes on the day it started. It is spelled out rather than
            left to be inferred, because inferring it wrong is silent: a
            reader that takes date with end and ignores this computes
            minus sixteen hours for a night shift running 22:00 to 06:00,
            and a plausible answer for every interval written before
            overnight windows existed.
          example: "2026-01-05"
        end:
          type: string
          format: time
          example: "10:00:00"
        activity_id:
          type: integer
          nullable: true
        activity_code:
          type: string
          nullable: true
        master_slot_id:
          type: integer
          nullable: true
        reservation_id:
          type: integer
          nullable: true

    AvailabilityResponse:
      type: object
      properties:
        resource_id:
          type: integer
        code:
          type: string
        from:
          type: string
          format: date
        to:
          type: string
          format: date
        busy:
          type: array
          description: >
            Busy intervals, not free ones. Times are naive wall clock in the
            organization's own timezone, with no offset and no Z.
          items:
            $ref: "#/components/schemas/BusyInterval"
        requirements_met:
          type: boolean
          nullable: true
          description: >
            Null unless `with_requirements` was asked for. Then true when the
            resource itself is free for the window and nothing it requires is
            missing, whatever the enforcement.
        unmet:
          type: array
          description: >
            Empty unless `with_requirements` was asked for. Then the
            requirements that could not be held for the window.
          items:
            $ref: "#/components/schemas/UnmetRequirement"

    ConflictItem:
      type: object
      description: >
        One of the rows taking part in a clash, with the window it holds.
        type is `slot` (a weekly slot on one date, id is the slot),
        `ledger_day` (a generated day, id is the ledger row) or `reservation`
        (a held booking, id is the reservation). It is a string rather than
        an enum so that a new kind of row can be added later; a reader should
        skip a type it does not know. date is the day the window opened on
        and end_date the day it finishes on, as in BusyInterval.
      required: [type, id, date, start, end_date, end, activity_id, resource_id]
      properties:
        type:
          type: string
          example: slot
        id:
          type: integer
        date:
          type: string
          format: date
          example: "2026-01-05"
        start:
          type: string
          format: time
          example: "09:00:00"
        end_date:
          type: string
          format: date
          example: "2026-01-05"
        end:
          type: string
          format: time
          example: "10:00:00"
        activity_id:
          type: integer
          nullable: true
          description: Null for a reservation.
        resource_id:
          type: integer
          nullable: true
          description: Null for a slot or a day that names no resource.

    Conflict:
      type: object
      description: >
        Two rows that hold the same resource, member or lead at the same
        moment. kind is `resource_overlap`, with resource_id set,
        `member_overlap`, with member_id set, or `lead_overlap`, with lead_id
        set: one person leading two different activities at once. The lead of
        a generated day is its substitute when it has one, so a substituted
        day does not clash for the lead it was taken from. Each of
        resource_id, member_id and lead_id is null on the kinds that do not
        use it. Like ConflictItem.type, kind is a string so that
        later kinds can be added; a reader should skip a kind it does not
        know. date, start, end_date and end are the part of the two windows
        they share. items is a list rather than a pair so that a later kind
        can name more than two rows.


        `resource_overbooked` is a POOLED resource whose reservations
        together hold more than its capacity. date to end is the whole
        stretch in which they do, items is every reservation open in it,
        and capacity and taken say by how much: taken is the most held at
        any moment of the stretch. capacity and taken are null on the other
        kinds. Two reservations on a pooled resource are never a
        `resource_overlap`, and reservations on a SHARED resource are never
        reported at all.


        `requirement_unmet` is a weekly slot or a generated day, its one
        item, whose activity or resource requires something the window
        cannot have. requirement_id names the requirement and message says
        what is missing; both are null on the other kinds. resource_id is
        the row's own resource. It is a report: nothing is refused for it.
      required: [kind, resource_id, member_id, date, start, end_date, end, items]
      properties:
        kind:
          type: string
          example: resource_overlap
        resource_id:
          type: integer
          nullable: true
        member_id:
          type: string
          nullable: true
        date:
          type: string
          format: date
          example: "2026-01-05"
        start:
          type: string
          format: time
          example: "09:30:00"
        end_date:
          type: string
          format: date
          example: "2026-01-05"
        end:
          type: string
          format: time
          example: "10:00:00"
        items:
          type: array
          items:
            $ref: "#/components/schemas/ConflictItem"
        capacity:
          type: integer
          nullable: true
          description: The pool's capacity, on `resource_overbooked` only.
        taken:
          type: integer
          nullable: true
          description: The most units held at once, on `resource_overbooked` only.
        requirement_id:
          type: integer
          nullable: true
          description: The requirement that is not met, on `requirement_unmet` only.
        message:
          type: string
          nullable: true
          description: What is missing, on `requirement_unmet` only.
        lead_id:
          type: string
          nullable: true
          description: The person leading both activities, on `lead_overlap` only.

    ConflictReport:
      type: object
      required: [from, to, conflicts]
      properties:
        from:
          type: string
          format: date
        to:
          type: string
          format: date
        conflicts:
          type: array
          description: >
            Every clash that reaches into the range, each pair named once.
            Ordered by kind, then resource_id, member_id or lead_id, then the moment
            the shared window starts. Times are naive wall clock in the
            organization's own timezone.
          items:
            $ref: "#/components/schemas/Conflict"

    ReservationCreate:
      type: object
      required: [date, start, end, purpose]
      properties:
        date:
          type: string
          format: date
          description: >
            The day the window opens on. A window that runs past midnight
            finishes on the day after this one.
          example: "2026-01-06"
        start:
          type: string
          format: time
          example: "14:00"
        end:
          type: string
          format: time
          description: >
            Earlier than the start means the window runs past midnight and
            finishes on the day after `date`: 22:00 to 06:00 is an eight
            hour night shift. Equal to the start is refused, because 09:00
            to 09:00 is either nothing at all or a full day and there is no
            way to tell which was meant.
          example: "15:00"
        purpose:
          type: string
          minLength: 1
          maxLength: 200
          example: Ward round
        external_ref:
          type: string
          nullable: true
          minLength: 1
          maxLength: 120
          description: >
            The caller's own identifier for the booking, kept exactly as
            sent. Unique per caller: a second booking under a reference the
            caller already used, cancelled or not, is a 409 with
            `RESERVATION_EXTERNAL_REF_TAKEN`. Find the booking again with
            `GET /api/v1/resources/reservations?external_ref=`. Optional, and
            any number of bookings may leave it unset.
          example: visit-42
        quantity:
          type: integer
          minimum: 1
          description: >
            How many units of a POOLED resource to take, 1 when left out.
            Above 1 on any other resource is a 422. Part of what a retry is compared on
            only when it is sent, so a retry that leaves it out still
            matches a booking made before the field existed.
          example: 2
        assignments:
          type: object
          nullable: true
          description: >
            Which resources to hold for the requirements that name a kind of
            resource: a resource class code (`ROOM`, `PERSON` or one the
            organization made) mapped to resource ids, used in order. Where it says nothing, or runs out, the engine picks the
            first free resources of the kind by code. An id that is not an
            active resource of that kind in this organization, or that no
            requirement asks for, is a 422. A named resource that is not
            free is a gap and is not swapped for another. Part of what a
            retry is compared on only when it is sent.
          additionalProperties:
            type: array
            items:
              type: integer
          example:
            PERSON: [12, 15]

    ReservationUpdate:
      type: object
      additionalProperties: false
      description: >
        What the caller may change about a reservation it already holds: its
        reference, for now. The window is what the conflict check and the
        idempotency fingerprint are built on, so moving it is a cancel and a
        new booking. Any other field is refused with a 422 rather than
        ignored.
      properties:
        external_ref:
          type: string
          nullable: true
          minLength: 1
          maxLength: 120
          description: >
            The new reference, or null to clear it. Leaving the field out
            leaves the reference as it is.
          example: visit-43

    ReservationResponse:
      type: object
      properties:
        id:
          type: integer
        resource_id:
          type: integer
        resource_code:
          type: string
        date:
          type: string
          format: date
        start:
          type: string
          format: time
        end:
          type: string
          format: time
        purpose:
          type: string
          description: >
            Returned only to the caller that made the booking. It is not on
            the availability calendar, which anyone signed in can read.
        status:
          type: string
          enum: [HELD, CANCELLED]
        requested_by_id:
          type: string
          nullable: true
          description: >
            Null once the account that booked it has been deleted. A hold
            outlives the service account that placed it.
        idempotency_key:
          type: string
        quantity:
          type: integer
          description: Units taken. Always 1 off a POOLED resource.
        external_ref:
          type: string
          nullable: true
          description: >
            The caller's own identifier for the booking, or null if it was
            given none. A cancelled booking keeps its reference.
        created_at:
          type: string
          format: date-time
        cancelled_at:
          type: string
          format: date-time
          nullable: true
        parent_reservation_id:
          type: integer
          nullable: true
          description: >
            The booking this hold was taken for, when a requirement of the
            resource made it. Null on a booking somebody asked for. Cancelling
            the parent cancels the holds that name it here.

    ReservationCreated:
      description: >
        A new booking with what its requirements held alongside it.
      allOf:
        - $ref: "#/components/schemas/ReservationResponse"
        - type: object
          properties:
            children:
              type: array
              description: >
                The holds the resource's requirements took under this
                booking, at every depth of a chain, in the order they were
                taken. Empty when the resource requires nothing. A replay
                of the same request answers with the children as they
                stand now.
              items:
                $ref: "#/components/schemas/ReservationResponse"
            unmet:
              type: array
              description: >
                The ADVISORY requirements that could not be met. The booking
                went ahead without them. A REQUIRED one that cannot be met
                refuses the booking instead (`REQUIREMENT_UNSATISFIED`).
                Always empty on a replay, because a gap is not stored.
              items:
                $ref: "#/components/schemas/UnmetRequirement"

    UnmetRequirement:
      type: object
      description: >
        A requirement that could not be held, and why. On a booking it is an
        ADVISORY gap. On GET availability with `with_requirements` it is
        whatever would stop the window being held, whatever the enforcement.
      required:
        - requirement_id
        - owner_kind
        - owner_id
        - target_resource_id
        - target_kind
        - quantity
        - enforcement
        - message
        - conflicts
      properties:
        requirement_id:
          type: integer
        owner_kind:
          type: string
          enum: [RESOURCE, ACTIVITY]
        owner_id:
          type: integer
        target_resource_id:
          type: integer
          nullable: true
        target_kind:
          type: string
          nullable: true
          description: A resource class code.
        quantity:
          type: integer
          description: How many units or resources were missing, not how many were asked for.
        enforcement:
          type: string
          enum: [REQUIRED, ADVISORY]
          description: >
            The enforcement that applied, with the organization's default
            filled in where the requirement did not say.
        message:
          type: string
        conflicts:
          type: array
          description: >
            What stands in the way on a named target. Empty when a kind had
            no free resource to name.
          items:
            $ref: "#/components/schemas/BusyInterval"

    RequirementCreate:
      type: object
      description: >
        One rule: whoever uses the owner also needs the target. Set exactly
        one of `target_resource_id` and `target_kind`.
      properties:
        target_resource_id:
          type: integer
          nullable: true
          description: >
            A specific resource of this organization. Never an activity.
        target_kind:
          type: string
          pattern: "^[A-Z][A-Z0-9_]*$"
          maxLength: 30
          nullable: true
          description: >
            Any resource of this class, picked at booking time. The code of
            an active resource class of the organization; anything else is a
            422 with `UNKNOWN_RESOURCE_CLASS`.
        quantity:
          type: integer
          minimum: 1
          maximum: 1000
          description: >
            How many. Units of the pool on a POOLED named target, which a
            named target of another mode cannot take above 1 (422); the
            number of distinct resources on a kind. 1 when left out.
        before_minutes:
          type: integer
          minimum: 0
          maximum: 1440
          description: Setup time held before the window. 0 when left out.
        after_minutes:
          type: integer
          minimum: 0
          maximum: 1440
          description: Turnover time held after the window. 0 when left out.
        enforcement:
          type: string
          enum: [REQUIRED, ADVISORY]
          nullable: true
          description: >
            REQUIRED refuses a booking that cannot meet it. ADVISORY books
            without it and lists the gap. Null, or left out, follows the
            organization's `default_requirement_enforcement`.

    RequirementResponse:
      type: object
      required:
        - id
        - owner_kind
        - owner_id
        - target_resource_id
        - target_kind
        - quantity
        - before_minutes
        - after_minutes
        - enforcement
        - created_at
      properties:
        id:
          type: integer
        owner_kind:
          type: string
          enum: [RESOURCE, ACTIVITY]
        owner_id:
          type: integer
        target_resource_id:
          type: integer
          nullable: true
        target_kind:
          type: string
          nullable: true
          description: A resource class code.
        quantity:
          type: integer
        before_minutes:
          type: integer
        after_minutes:
          type: integer
        enforcement:
          type: string
          enum: [REQUIRED, ADVISORY]
          nullable: true
          description: Null means the organization's default applies.
        created_at:
          type: string
          format: date-time

    OrganizationResponse:
      type: object
      required: [id, name, default_requirement_enforcement]
      properties:
        id:
          type: string
        name:
          type: string
        default_requirement_enforcement:
          type: string
          enum: [REQUIRED, ADVISORY]

    OrganizationUpdate:
      type: object
      additionalProperties: false
      required: [default_requirement_enforcement]
      properties:
        default_requirement_enforcement:
          type: string
          enum: [REQUIRED, ADVISORY]
          description: >
            What a requirement with no enforcement of its own does. Read when
            a booking is made, so a change applies to the next booking.

    ReservationConflict:
      type: object
      description: >
        The body of a 409. What the booking ran into, not merely that it ran
        into something, so a caller can pick its next hour without asking
        availability again and diffing the answers. Nested under detail like
        every other error here, so one error handler reads them all.
      required: [detail, code]
      properties:
        code:
          $ref: "#/components/schemas/ErrorCode"
        detail:
          type: object
          properties:
            message:
              type: string
              example: the resource is already taken for part of that window
            conflicts:
              type: array
              items:
                $ref: "#/components/schemas/BusyInterval"

    ReservationRefTaken:
      type: object
      description: >
        The body of a 409 with `RESERVATION_EXTERNAL_REF_TAKEN`. Names the
        reservation of the caller's that already carries the reference, which
        is the booking the caller made earlier under it and can now read,
        change or cancel.
      required: [detail, code]
      properties:
        code:
          $ref: "#/components/schemas/ErrorCode"
        detail:
          type: object
          required: [message, reservation_id]
          properties:
            message:
              type: string
              example: a reservation of yours already has that external_ref
            reservation_id:
              type: integer
              example: 17

    CapacityExceeded:
      type: object
      description: >
        The body of a 409 with `RESOURCE_CAPACITY_EXCEEDED`: a POOLED
        resource has not got quantity units free for the whole window.
        conflicts are the bookings that hold it, as in ReservationConflict.
        taken is the most they hold at any one moment of the window, so
        capacity minus taken is the most this window could still have.
      required: [detail, code]
      properties:
        code:
          $ref: "#/components/schemas/ErrorCode"
        detail:
          type: object
          required: [message, conflicts, capacity, taken, requested]
          properties:
            message:
              type: string
              example: the resource does not have that many units left for that window
            conflicts:
              type: array
              items:
                $ref: "#/components/schemas/BusyInterval"
            capacity:
              type: integer
              example: 12
            taken:
              type: integer
              example: 12
            requested:
              type: integer
              example: 1

    BookingsWouldNotFit:
      type: object
      description: >
        The body of a 409 with `RESOURCE_BOOKINGS_WOULD_NOT_FIT`: a change of
        mode or capacity that bookings still to come (from yesterday on)
        would no longer fit. reservations names them, so the caller can
        cancel or move them and try again.
      required: [detail, code]
      properties:
        code:
          $ref: "#/components/schemas/ErrorCode"
        detail:
          type: object
          required: [message, reservations]
          properties:
            message:
              type: string
              example: bookings still to come would not fit the resource after that change
            reservations:
              type: array
              items:
                $ref: "#/components/schemas/ReservationResponse"

    # ── Schedule ──────────────────────────────
    CycleActivationConflict:
      type: object
      description: >
        The body of the 409 that refuses to open a planning cycle. Every clash
        across every slot in the cycle, listed at once rather than one per
        attempt, because an admin opening a hundred slots should not have to
        make a hundred attempts to see the list.


        Each entry is a BusyInterval naming what was already there, plus
        blocked_slot_id naming which of the cycle's own slots wanted it. A
        pair of the cycle's own slots is listed twice, once from each side,
        because neither of the two is the one at fault.
      required: [detail, code]
      properties:
        code:
          $ref: "#/components/schemas/ErrorCode"
        detail:
          type: object
          properties:
            message:
              type: string
              example: opening this cycle would put its slots on rooms already taken
            conflicts:
              type: array
              items:
                allOf:
                  - $ref: "#/components/schemas/BusyInterval"
                  - type: object
                    required: [blocked_slot_id]
                    properties:
                      blocked_slot_id:
                        type: integer
                        description: >
                          The slot in the cycle being opened that this
                          interval stands against.
                        example: 88

    PlanningCycleCreate:
      type: object
      required: [cycle_label, date_bounds_start, date_bounds_end]
      properties:
        cycle_label:
          type: string
          example: 2026-Fall-Trimester
        date_bounds_start:
          type: string
          format: date
          example: "2026-09-01"
        date_bounds_end:
          type: string
          format: date
          example: "2026-12-20"
        operational_status:
          type: boolean
          default: false

    PlanningCycleResponse:
      type: object
      properties:
        id:
          type: integer
        cycle_label:
          type: string
        date_bounds_start:
          type: string
          format: date
        date_bounds_end:
          type: string
          format: date
        operational_status:
          type: boolean

    ActivityCreate:
      type: object
      description: >
        An activity, the same one a CSV row names by code, title and unit. It
        starts with no slots and no members; those are added with POST
        /schedule/slots and POST /schedule/activities/{activity_id}/enrollments.
      required: [activity_code, activity_title, unit_code, cycle_id]
      properties:
        activity_code:
          type: string
          minLength: 1
          maxLength: 30
          description: Unique within the cycle, retired activities included.
          example: CS201
        activity_title:
          type: string
          minLength: 1
          maxLength: 150
        unit_code:
          type: string
          minLength: 1
          maxLength: 50
          description: A UNIT_ADMIN may only name their own unit.
        cycle_id:
          type: integer

    ActivityUpdate:
      type: object
      description: >
        Only the title can change. The code and the cycle are what identify an
        activity, the same pair a CSV upsert matches on, so changing either is
        a different activity. The unit is what a unit admin's permission is
        checked against, and moving an activity between units is left to an
        import, which only an org admin can run.
      required: [activity_title]
      properties:
        activity_title:
          type: string
          minLength: 1
          maxLength: 150

    ActivityResponse:
      type: object
      properties:
        id:
          type: integer
        activity_code:
          type: string
        activity_title:
          type: string
        unit_code:
          type: string
        cycle_id:
          type: integer
        retired_at:
          type: string
          format: date-time
          nullable: true
          description: When the activity was retired. Null while it is live.

    RetireResult:
      type: object
      description: >
        What retiring an activity or a slot did to the days ahead. Days from
        today onward that nobody has marked or annotated are removed; the ones
        carrying attendance or a note are kept. Days before today are records
        and are not touched.
      properties:
        retired_at:
          type: string
          format: date-time
        slots_retired:
          type: integer
          description: >
            Slots marked retired by this request. Always 1 when a slot is
            retired; for an activity, every slot it had that was still live.
        ledger_rows_removed:
          type: integer
          description: Days from today onward that were still plans.
        ledger_rows_kept:
          type: integer
          description: >
            Days from today onward kept because attendance or a note has been
            recorded against them.

    EnrollmentCreate:
      type: object
      required: [member_id]
      properties:
        member_id:
          type: string
          minLength: 1
          maxLength: 50
          example: STU001

    EnrollmentResponse:
      type: object
      properties:
        activity_id:
          type: integer
        member_id:
          type: string

    MasterSlotCreate:
      type: object
      required:
        [rrule, time_window_start, time_window_end, activity_id, target_room_identifier]
      properties:
        rrule:
          $ref: "#/components/schemas/SlotRule"
        dtstart:
          type: string
          format: date
          nullable: true
          description: >
            The date the rule starts from, in ORG_TIMEZONE. Moved forward to
            the rule's first date on or after it, and that is what is stored.
            Absent means the start of the activity's cycle. A rule with no
            date left on or after it is a 422 with code INVALID_VALUE.
        time_window_start:
          type: string
          format: time
          example: "09:00:00"
        time_window_end:
          type: string
          format: time
          description: >
            Earlier than the start means the window runs past midnight and
            finishes on the day after the one the slot lands on: 22:00 to
            06:00 is an eight hour night shift. Equal to the start is
            refused, because 09:00 to 09:00 is either nothing at all or a
            full day and there is no way to tell which was meant.
          example: "10:00:00"
        activity_id:
          type: integer
        primary_lead_id:
          type: string
          nullable: true
        target_room_identifier:
          type: string
          description: >
            The room's name. Resolved to a resource, creating one on first
            sight, so a room does not have to be registered before a
            timetable can name it. Surrounding spaces are stripped.
          example: LH-201

    MasterSlotUpdate:
      type: object
      description: >
        Every field is optional and only the fields present are changed.
        Only primary_lead_id may be null, which takes the lead off the slot;
        a null for any other field is a 422.
        activity_id is absent on purpose: every day the slot has produced
        carries its own copy of the activity, so pointing the slot at
        another one is a delete and a create, not an edit.
      properties:
        rrule:
          $ref: "#/components/schemas/SlotRule"
        dtstart:
          type: string
          format: date
          description: >
            Moved forward to the rule's first date on or after it. A new rrule
            sent without a dtstart starts again from the start of the cycle,
            not from the old dtstart.
        time_window_start:
          type: string
          format: time
        time_window_end:
          type: string
          format: time
        primary_lead_id:
          type: string
          nullable: true
        target_room_identifier:
          type: string

    SlotRule:
      type: string
      maxLength: 261
      example: FREQ=WEEKLY;BYDAY=MO
      description: >
        The value of one RFC 5545 RRULE property, with or without "RRULE:" in
        front, stored upper case without it. The dates it gives are calendar
        dates in ORG_TIMEZONE and the slot's own times are read on each of
        them, so a 09:00 class stays at 09:00 across a daylight saving
        change. FREQ must be DAILY, WEEKLY, MONTHLY or YEARLY; BYHOUR,
        BYMINUTE and BYSECOND are refused, since a slot runs at most once a
        date; UNTIL must be a local date or date-time, not one ending in Z;
        DTSTART, EXDATE and line breaks are not part of it. Any of these is
        a 422. The stored rule is at most 255 characters.

    MasterSlotResponse:
      type: object
      properties:
        id:
          type: integer
        rrule:
          type: string
          example: FREQ=WEEKLY;BYDAY=MO
        dtstart:
          type: string
          format: date
          description: The first date the rule gives. Always one of its dates.
        time_window_start:
          type: string
          format: time
        time_window_end:
          type: string
          format: time
        activity_id:
          type: integer
        primary_lead_id:
          type: string
          nullable: true
        resource_id:
          type: integer
          nullable: true
          description: Prefer this over target_room_identifier.
        target_room_identifier:
          type: string
          nullable: true
          description: The room's code, read from the resource. Prefer resource_id.
        retired_at:
          type: string
          format: date-time
          nullable: true
          description: >
            When the slot was retired, on its own or with its activity. Null
            while it is live.

    SlotRequirementGap:
      type: object
      description: >
        A requirement of a slot's activity or resource that the slot's next
        run on the date given cannot have. A report; nothing is refused.
        The CSV import adds slot_id.
      properties:
        requirement_id:
          type: integer
        date:
          type: string
          format: date
        message:
          type: string
        slot_id:
          type: integer

    SlotUpdateResult:
      type: object
      properties:
        requirements_unmet:
          type: array
          description: >
            What the slot's activity or resource requires that its next run
            cannot have. Empty when nothing is required.
          items:
            $ref: "#/components/schemas/SlotRequirementGap"
        ledger_rows_updated:
          type: integer
          description: Days that were still plans and now carry the new lead or room.
        ledger_rows_kept:
          type: integer
          description: >
            Days left as they were because attendance or a note has been
            recorded against them. They now disagree with the timetable, and
            that is deliberate: they record what happened.
        ledger_rows_removed:
          type: integer
          description: >
            Days withdrawn because the slot was given another rrule or
            dtstart and they sit on dates it no longer gives. Zero for every
            other change.

    SlotDeletionResult:
      type: object
      properties:
        ledger_rows_removed:
          type: integer
          description: Days from today onward, which were still only plans.
        ledger_rows_detached:
          type: integer
          description: >
            Days already past. They keep their room, lead, window and
            attendance, and their master_slot_id becomes null.

    DailyLedgerUpdate:
      type: object
      description: >
        A field left out keeps its value and a null clears it, except
        operational_state and delivery_format, which cannot be null (422).
      properties:
        operational_state:
          $ref: "#/components/schemas/DynamicState"
        substitute_lead_id:
          type: string
          nullable: true
        delivery_format:
          $ref: "#/components/schemas/ExecutionMode"
        virtual_connection_string:
          type: string
          nullable: true
          example: https://meet.google.com/xyz-abc
        latitude_target:
          type: number
          format: double
          nullable: true
        longitude_target:
          type: number
          format: double
          nullable: true
        altitude_target:
          type: number
          format: double
          nullable: true
        precision_radius_meters:
          type: integer
          nullable: true
          description: Geofence radius override for this specific session.

    AuditRecord:
      type: object
      properties:
        id:
          type: integer
        at:
          type: string
          format: date-time
        actor_id:
          type: [string, "null"]
          description: The account, or null when the request carried no valid credentials.
        api_key_id:
          type: [integer, "null"]
          description: The key used, or null for a signed-in person.
        acting_for_user_id:
          type: [string, "null"]
          description: >
            The id sent in `X-Chronos-Actor`, exactly as asked for and cut to
            50 characters, or null when the request did not send the header.
            Set on a refused attempt too, whether or not that id exists, so
            `actor_id` is who sent the request and this is who it named.
        method:
          type: string
        path:
          type: string
        status_code:
          type: integer

    DailyLedgerResponse:
      type: object
      properties:
        id:
          type: integer
        target_date:
          type: string
          format: date
        activity_id:
          type: integer
        active_lead_id:
          type: string
          nullable: true
        substitute_lead_id:
          type: string
          nullable: true
        resource_id:
          type: integer
          nullable: true
          description: The room this is booked in. Prefer this over target_room_identifier.
        target_room_identifier:
          type: string
          nullable: true
          description: The room's code, read from the resource. Prefer resource_id.
        delivery_format:
          $ref: "#/components/schemas/ExecutionMode"
        virtual_connection_string:
          type: string
          nullable: true
        operational_state:
          $ref: "#/components/schemas/DynamicState"
        activity_code:
          type: string
          nullable: true
        activity_title:
          type: string
          nullable: true
        time_window_start:
          type: string
          format: time
          nullable: true
          description: >
            The day's own window, copied off the slot when the day was
            generated rather than read back through it. Editing a slot moves
            the days it has still to run and leaves the ones that already
            happened saying the hour they happened at; deleting a slot leaves
            them saying it too. Null on an ad-hoc day, which never claimed an
            hour, and on a day generated before the ledger carried a window.
        time_window_end:
          type: string
          format: time
          nullable: true
          description: >
            Earlier than time_window_start means the day finishes on the date
            after target_date. A reader that ignores that computes minus
            sixteen hours for a night shift running 22:00 to 06:00.

    StaffLocationResponse:
      type: object
      properties:
        resolved_location:
          type: string
          description: >
            A room, OFF_SITE for somebody on approved leave that day, the base
            station (or Unassigned) when nothing is scheduled, or UNKNOWN when
            a status override answered.
          example: LH-204
        status:
          type: string
          description: A sentence for display, not an enum.
          example: Leading CS101 in Room LH-204
        staff_id:
          type: string
        full_name:
          type: string
        occupancy_index:
          $ref: "#/components/schemas/AccessReadiness"

    # ── Attendance ────────────────────────────
    AttendanceMarkRequest:
      type: object
      required: [ledger_instance_id, member_id, marking_status]
      properties:
        ledger_instance_id:
          type: integer
          example: 1042
        member_id:
          type: string
          example: STU20210001
        marking_status:
          $ref: "#/components/schemas/VerificationMetric"
        user_lat:
          type: number
          format: double
          nullable: true
          example: 12.971598
        user_lon:
          type: number
          format: double
          nullable: true
          example: 77.594562
        user_alt:
          type: number
          format: double
          nullable: true
          example: 920.5
          description: Altitude in meters. Optional. The floor check runs only when the client supplies an altitude it can vouch for, and is skipped otherwise; a geo-fenced session requires lat/lon alone.
        user_accuracy:
          type: number
          format: double
          nullable: true
          minimum: 0
          example: 8.0
          description: How far off the fix may be, in meters, as the device reports it (coords.accuracy in a browser). Optional. On a geo-fenced session a fix coarser than GEOFENCE_ACCURACY_FACTOR times precision_radius_meters (30 m on the default 15 m radius) returns 400.

    AttendanceBatchRequest:
      type: object
      required: [ledger_instance_id, records]
      properties:
        ledger_instance_id:
          type: integer
        records:
          type: array
          items:
            $ref: "#/components/schemas/AttendanceMarkRequest"

    AttendanceResponse:
      type: object
      properties:
        id:
          type: integer
        ledger_instance_id:
          type: integer
        member_id:
          type: string
        marking_status:
          $ref: "#/components/schemas/VerificationMetric"
        authorizing_agent_id:
          type: string
          nullable: true
          description: User ID of the person who marked attendance (may be staff for batch).
        modification_timestamp:
          type: string
          format: date-time

    ReverseRsvpCreate:
      type: object
      required: [target_absence_date, context_justification]
      properties:
        target_absence_date:
          type: string
          format: date
          example: "2026-06-15"
        end_date:
          type: string
          format: date
          description: >
            Last day of the absence, inclusive. Omit for a single day. Must not
            be before target_absence_date, or the request gets 422.
          example: "2026-06-19"
        context_justification:
          type: string
          example: Attending national staff development seminar.

    ReverseRsvpResponse:
      type: object
      properties:
        id:
          type: integer
        submitting_user_id:
          type: string
        target_absence_date:
          type: string
          format: date
        end_date:
          type: string
          format: date
          nullable: true
        context_justification:
          type: string
        approval_state:
          $ref: "#/components/schemas/LogVerificationState"
        authorized_by_user_id:
          type: string
          nullable: true

    RsvpDecision:
      type: object
      required: [decision]
      properties:
        decision:
          $ref: "#/components/schemas/LogVerificationState"

    AnnotationCreate:
      type: object
      required: [ledger_instance_id, classification_tag, annotation_payload]
      properties:
        ledger_instance_id:
          type: integer
        classification_tag:
          type: string
          minLength: 1
          maxLength: 30
          description: >
            Free text, not a fixed vocabulary. Bounded because the column is
            a VARCHAR(30).
          example: LATE_START
        annotation_payload:
          type: string
          minLength: 1
          maxLength: 4000
          example: Class started 10 minutes late due to lab setup.

    AnnotationResponse:
      type: object
      properties:
        id:
          type: integer
        ledger_instance_id:
          type: integer
        creator_id:
          type: string
        classification_tag:
          type: string
        annotation_payload:
          type: string
        distribution_timestamp:
          type: string
          format: date-time

    # ── Guest ─────────────────────────────────
    GuestCheckInRequest:
      type: object
      required: [guest_name, contact_phone, originating_body, target_staff_id, visitation_intent]
      properties:
        guest_name:
          type: string
          minLength: 2
          maxLength: 100
          example: John Smith
        contact_phone:
          type: string
          minLength: 8
          maxLength: 20
          pattern: "^[-0-9+() ]+$"
          example: "+91 98765 43210"
        originating_body:
          type: string
          minLength: 2
          maxLength: 100
          example: TechCorp Ltd
        target_staff_id:
          type: string
          minLength: 1
          maxLength: 50
          example: FAC001
        visitation_intent:
          type: string
          minLength: 10
          maxLength: 500
          example: Research collaboration discussion

    GuestDecisionRequest:
      type: object
      required: [decision]
      properties:
        decision:
          $ref: "#/components/schemas/LogVerificationState"

    GuestExtensionRequest:
      type: object
      required: [minutes]
      properties:
        minutes:
          type: integer
          minimum: 1
          description: >
            How much longer the visit gets. The ceiling is
            GUEST_VISIT_EXTENSION_MAX_MINUTES, which defaults to 240 and is
            checked in the route rather than here, because a schema is fixed at
            import and the setting is an operator's to change.
          example: 30

    GuestResponse:
      type: object
      properties:
        id:
          type: integer
        guest_name:
          type: string
        contact_phone:
          type: string
        originating_body:
          type: string
        target_staff_id:
          type: string
        visitation_intent:
          type: string
        handshake_status:
          $ref: "#/components/schemas/LogVerificationState"
        timestamp_marked:
          type: string
          format: date-time
        visit_expires_at:
          type: string
          format: date-time
          nullable: true
          description: >
            When an approved visit is over. Null is one nobody has approved, one
            approved while GUEST_VISIT_LENGTH_MINUTES was 0, and every visit
            approved before the column existed.

    GuestVisitStatus:
      type: object
      description: >
        What a visit code opens. The name, phone and target are left out,
        because a code on a kiosk screen can be read over a shoulder.
      properties:
        handshake_status:
          $ref: "#/components/schemas/LogVerificationState"
        timestamp_marked:
          type: string
          format: date-time
          description: When the visitor checked in.
        visit_expires_at:
          type: string
          format: date-time
          nullable: true
          description: >
            When to leave, which is the one thing the visitor most needs from
            this and gives away nothing about them: whoever reads the code over
            a shoulder learns a time, not a name. Null is an open-ended visit.

    StaffAvailabilityResponse:
      type: object
      properties:
        staff_id:
          type: string
        full_name:
          type: string
        unit_code:
          type: string
          nullable: true
        availability_label:
          type: string
          description: Human-readable availability derived from current_occupancy_index.

    # ── Changes ───────────────────────────────
    Change:
      type: object
      description: >
        One thing that changed, and what it now holds. `resource` and
        `reservation` are the row as it stands, one of them filled in according
        to `entity_kind`, so an entry can be applied without a second request.
        Both are null in the full log, which is the markers alone.
      properties:
        cursor:
          type: integer
          description: >
            Send the last one back as `since`, or `next_cursor`, which is the
            same number.
        entity_kind:
          type: string
          description: >
            `resource` or `reservation`. Not a closed set: another part of the
            API gaining a feed adds a kind here, and a consumer should ignore
            one it does not know rather than fail on it.
        entity_id:
          type: integer
        change_kind:
          type: string
          description: >
            `created` or `updated`, and likewise open. Measured against the
            cursor that was sent in, not against the row's whole history: a row
            created and then edited between two polls reads as `created`,
            because the caller has never seen it. There is no `deleted`:
            nothing this feed carries is deleted, and a cancelled booking keeps
            its row and reads as `updated`.
        at:
          type: string
          format: date-time
          description: When the most recent of the collapsed changes was made.
        resource:
          allOf:
            - $ref: "#/components/schemas/ResourceResponse"
          nullable: true
        reservation:
          allOf:
            - $ref: "#/components/schemas/ReservationResponse"
          nullable: true

    ChangeFeed:
      type: object
      properties:
        changes:
          type: array
          items:
            $ref: "#/components/schemas/Change"
        next_cursor:
          type: integer
          description: >
            What the next poll sends as `since`. The cursor that was sent in
            when nothing changed, so storing it unconditionally keeps the
            caller's place.

    # ── Webhooks ──────────────────────────────
    WebhookEventType:
      type: string
      enum:
        - reservation.created
        - reservation.updated
        - resource.created
        - resource.updated

    WebhookCreate:
      type: object
      required: [url, event_types]
      properties:
        url:
          type: string
          minLength: 1
          maxLength: 2000
          description: >
            Where to POST each event. HTTPS, unless the host is listed in
            `WEBHOOK_ALLOW_HTTP_HOSTS`. A name that resolves to a loopback,
            private, link-local or otherwise internal address is refused
            unless `WEBHOOK_ALLOW_PRIVATE_TARGETS` is on.
          example: https://receiver.example.com/hooks/chronos
        event_types:
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/WebhookEventType"
          description: Which events to send. Stored sorted and deduplicated.
          example: [reservation.created, reservation.updated]
        active:
          type: boolean
          default: true
          description: >
            An inactive subscription keeps its place and sends nothing. Made
            active again, it sends what happened in between.

    WebhookUpdate:
      type: object
      description: Only the fields sent are changed.
      properties:
        url:
          type: string
          minLength: 1
          maxLength: 2000
          nullable: true
        event_types:
          type: array
          minItems: 1
          nullable: true
          items:
            $ref: "#/components/schemas/WebhookEventType"
        active:
          type: boolean
          nullable: true

    WebhookResponse:
      type: object
      description: A subscription, without its secrets.
      properties:
        id:
          type: integer
        url:
          type: string
        event_types:
          type: array
          items:
            $ref: "#/components/schemas/WebhookEventType"
        active:
          type: boolean
        paused_at:
          type: string
          format: date-time
          nullable: true
          description: >
            Set while the subscription is paused, after five deliveries in a
            row ran out of attempts or by an import that carried no secrets.
            Cleared by resume.
        consecutive_failures:
          type: integer
          description: Deliveries in a row that ran out of attempts. A success resets it.
        previous_secret_expires_at:
          type: string
          format: date-time
          nullable: true
          description: >
            Set while the secret before the last rotation still signs
            alongside the current one.
        created_at:
          type: string
          format: date-time
          nullable: true
        updated_at:
          type: string
          format: date-time
          nullable: true

    WebhookWithSecret:
      allOf:
        - $ref: "#/components/schemas/WebhookResponse"
        - type: object
          required: [secret]
          properties:
            secret:
              type: string
              description: >
                The signing secret, `whsec_` and the base64 of 32 random bytes.
                Returned here and nowhere else, so keep it: it cannot be read
                back, only replaced by rotating.

    WebhookAttemptResponse:
      type: object
      properties:
        at:
          type: string
          format: date-time
        status_code:
          type: integer
          nullable: true
          description: Null when no response came back.
        response_ms:
          type: integer
        error:
          type: string
          nullable: true
          description: Why the attempt failed, briefly. Null on success.
        response_excerpt:
          type: string
          nullable: true
          description: The start of the response body, cut short.

    WebhookDeliveryResponse:
      type: object
      properties:
        id:
          type: integer
        subscription_id:
          type: integer
        event_id:
          type: string
          description: The `webhook-id` header, the same on every attempt.
        event_type:
          $ref: "#/components/schemas/WebhookEventType"
        entity_kind:
          type: string
          enum: [resource, reservation]
        entity_id:
          type: integer
        marker_id:
          type: integer
          description: The change feed cursor this delivery was made from.
        status:
          type: string
          enum: [pending, succeeded, failed]
        attempt_count:
          type: integer
        next_attempt_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
          nullable: true
        completed_at:
          type: string
          format: date-time
          nullable: true
        attempts:
          type: array
          items:
            $ref: "#/components/schemas/WebhookAttemptResponse"

    # ── Common ────────────────────────────────
    ErrorResponse:
      type: object
      description: >
        The body of every error. detail is for a person to read and code is
        for a program to branch on. A 409 that names what stood in the way
        has its own schema, with detail as an object; see ReservationConflict
        and ReservationRefTaken.
      required: [detail, code]
      properties:
        code:
          $ref: "#/components/schemas/ErrorCode"
        detail:
          type: string
          example: Not authorized.

    ErrorCode:
      type: string
      description: >
        What went wrong, for a program to branch on. docs/api.md says what
        each one means. A code is never renamed or reused for a different
        meaning, but new codes are added, so a client should treat one it
        does not know by its HTTP status. VALIDATION_FAILED is the only code
        whose detail is a list: FastAPI's field errors for a request that did
        not match the declared shape.
      enum:
        - BAD_REQUEST
        - NOT_AUTHENTICATED
        - FORBIDDEN
        - NOT_FOUND
        - METHOD_NOT_ALLOWED
        - STATE_CONFLICT
        - PAYLOAD_TOO_LARGE
        - INVALID_VALUE
        - RATE_LIMITED
        - INTERNAL_ERROR
        - SERVICE_UNAVAILABLE
        - VALIDATION_FAILED
        - INVALID_CREDENTIALS
        - TOKEN_INVALID
        - API_KEY_INVALID
        - API_KEY_EXPIRED
        - ACCOUNT_NOT_FOUND
        - ACCOUNT_DEACTIVATED
        - REFRESH_TOKEN_INVALID
        - REFRESH_TOKEN_EXPIRED
        - REFRESH_TOKEN_USED
        - REFRESH_TOKEN_REUSED
        - FEDERATED_TOKEN_INVALID
        - FEDERATED_EMAIL_MISSING
        - FEDERATED_ADMIN_REFUSED
        - FEDERATION_UNAVAILABLE
        - CURRENT_PASSWORD_INCORRECT
        - PASSWORD_UNCHANGED
        - PASSWORD_CHANGE_REQUIRED
        - INSUFFICIENT_ROLE
        - SCOPE_MISSING
        - OUTSIDE_UNIT
        - IMPERSONATION_NOT_ALLOWED
        - IMPERSONATION_REFUSED
        - RESOURCE_CONFLICT
        - ALREADY_EXISTS
        - EMAIL_TAKEN
        - USER_DEACTIVATED
        - IDEMPOTENCY_KEY_REUSED
        - IDEMPOTENCY_KEY_IN_PROGRESS
        - RESERVATION_EXTERNAL_REF_TAKEN
        - RESOURCE_CAPACITY_EXCEEDED
        - RESOURCE_BOOKINGS_WOULD_NOT_FIT
        - REQUIREMENT_UNSATISFIED
        - UNKNOWN_RESOURCE_CLASS
        - RESOURCE_CLASS_IN_USE
        - RESOURCE_CLASS_PROTECTED
        - LOCATION_REQUIRED
        - LOCATION_TOO_COARSE
        - OUTSIDE_GEOFENCE
        - MANAGER_NOT_SET
        - IMPORT_REJECTED
        - CHANGE_FEED_DISABLED
        - SERVER_BUSY
        - DATABASE_UNAVAILABLE
        - WEBHOOK_URL_REFUSED
        - WEBHOOK_SECRET_LIMIT
      example: NOT_FOUND

  responses:
    Unauthorized:
      description: Missing or invalid JWT.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    Forbidden:
      description: Authenticated but insufficient role.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    UnprocessableEntity:
      description: >
        Validation error (e.g. malformed request body). On a write that takes
        an Idempotency-Key, also a key already used for a different request
        (`IDEMPOTENCY_KEY_REUSED`).
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    Conflict:
      description: >
        The request would destroy or contradict a record. The detail names
        the dates that stand in the way.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    TooManyRequests:
      description: >
        The caller is past its budget for this route. Sized by the
        RATE_LIMIT_* settings; the counters live in Redis, and an instance
        that cannot reach Redis stops applying the limits rather than
        refusing the requests.
      headers:
        Retry-After:
          description: Seconds until the budget refills.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"

  # Paging for the routes that return a whole list. Opt-in: with neither
  # parameter a route returns every row, as it always has.
  parameters:
    Limit:
      name: limit
      in: query
      required: false
      description: At most this many rows. Every matching row if omitted.
      schema:
        type: integer
        minimum: 1
    Offset:
      name: offset
      in: query
      required: false
      description: Skip this many rows first. Rows come in id order.
      schema:
        type: integer
        minimum: 0
        default: 0
    # Optional on every write that needs a signed-in caller. See "Idempotency"
    # in docs/api.md for what is stored and for how long.
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >
        Makes a retry safe. Send the same key with the same request again and
        the first response comes back, with `Idempotency-Replayed: true`,
        instead of a second effect. A key belongs to the API key, or the
        user, that sent it, and is remembered for
        `IDEMPOTENCY_RETENTION_HOURS` (24 by default). The same key with a
        different request is `422` with `IDEMPOTENCY_KEY_REUSED`; a retry
        while the first request is still running is `409` with
        `IDEMPOTENCY_KEY_IN_PROGRESS` and a `Retry-After`. A key outside 1 to
        255 printable ASCII characters is `422` with `INVALID_VALUE`. A
        different `X-Chronos-Actor` counts as a different request.
      schema:
        type: string
        minLength: 1
        maxLength: 255
    # Described under the ApiKeyAuth security scheme; any route that takes an
    # API key takes it.
    ActingFor:
      name: X-Chronos-Actor
      in: header
      required: false
      description: >
        The id of the person this request is for. Only an API key holding the
        `impersonate` scope may send it, and only for an active user in the
        key's own organization; anything else is `403` with
        `IMPERSONATION_NOT_ALLOWED` or `IMPERSONATION_REFUSED`. Not sent, the
        key acts as the account it is bound to.
      schema:
        type: string
        minLength: 1
        maxLength: 50

  headers:
    XTotalCount:
      description: >
        How many rows matched the request's filters before limit and offset
        cut the page. Sent whether or not the request paged.
      schema:
        type: integer
    IdempotencyReplayed:
      description: >
        `true` when this response is the stored answer to an earlier request
        with the same Idempotency-Key, sent again rather than made again.
        Absent otherwise.
      schema:
        type: string
        enum: ["true"]

# Either credential is accepted on every endpoint below.
security:
  - BearerAuth: []
  - ApiKeyAuth: []

# ─────────────────────────────────────────────
# Paths
# ─────────────────────────────────────────────
paths:

  # ── Configuration ─────────────────────────
  /api/v1/config:
    get:
      operationId: config.get
      tags: [Configuration]
      summary: Display vocabulary, password floor and version
      description: |
        Public. Returns the display labels the UI should render for the
        engine's six neutral nouns (staff, member, activity, unit, lead,
        cycle), the shortest password this deployment accepts and the API
        version. The client needs the first two before anyone has logged in.

        Each label is set on its own with `LABEL_STAFF`, `LABEL_MEMBER`,
        `LABEL_ACTIVITY`, `LABEL_UNIT`, `LABEL_LEAD` or `LABEL_CYCLE`, and
        anything left blank comes back as the engine's own word: `Staff`,
        `Member`, `Activity`, `Unit`, `Lead`, `Cycle`. There is no domain
        preset behind them. Labels are display only: no field name in this
        document changes with them.
      security: []
      responses:
        "200":
          description: Display labels and the password floor.
          content:
            application/json:
              schema:
                type: object
                properties:
                  labels:
                    type: object
                    properties:
                      staff: { type: string }
                      member: { type: string }
                      activity: { type: string }
                      unit: { type: string }
                      lead: { type: string }
                      cycle: { type: string }
                  password_min_length:
                    type: integer
                    minimum: 8
                    example: 12
                    description: >-
                      PASSWORD_MIN_LENGTH on this deployment. The onboarding
                      wizard states it in a placeholder and refuses a shorter
                      password before sending it.
                  version:
                    type: string
                    example: "0.14.0"
                    description: >-
                      The API version, the same string GET /health reports. It
                      is here so a client that pins a version can read it
                      without leaving the /api/v1 prefix it builds its URLs
                      from. The database revision stays on /health.

  # ── Authentication ────────────────────────
  /api/v1/auth/login:
    post:
      operationId: auth.login
      tags: [Authentication]
      summary: Login and receive JWT
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LoginRequest"
      responses:
        "200":
          description: Successful login.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "429":
          $ref: "#/components/responses/TooManyRequests"

  /api/v1/auth/federated:
    post:
      operationId: auth.federated
      tags: [Authentication]
      summary: Exchange a note from a registered outside issuer for a session
      description: >
        Off unless FEDERATED_IDENTITY_ENABLED is true, and a 404 while it is
        off. The note is a short-lived JWT signed with Ed25519 by a key an
        operator registered for that issuer; the reply is the same pair
        POST /auth/login returns, so a client handles the session the same way
        afterwards. A note works exactly once. The account is found by the
        (issuer, subject) pair and not by the address in the note, so an issuer
        cannot name an existing account and be handed it; the first note for a
        subject creates an account, and its role comes from the operator's own
        map of group claims, never from the note alone. Every verification
        failure is the same 401 with the same message, on purpose: the reason
        is in the server log, where an integrator can be shown it and a forger
        cannot read it.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FederatedTokenRequest"
      responses:
        "200":
          description: A session for the account the note belongs to.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenResponse"
        "401":
          description: >
            The note was refused. One message for every reason, so the answer
            cannot be used to take a forged note apart field by field.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: >
            The account behind the link has been given an admin role since it
            was linked, so the shortcut is closed for it: no issuer may hold a
            route to an admin account, which is also why the link could not
            have been created against one. Said plainly rather than as the
            opaque 401, because the note verified and the person holding it
            cannot act on the refusal. The role is not changed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: >
            Federated sign-in is off on this instance. The same answer an
            unknown path gives, so whether an instance has an integration is
            not something probing it reveals.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: >
            The address in the note already belongs to an account, and the
            (issuer, subject) pair is not linked to one. Linking on the
            address instead would let an issuer take over any account whose
            address it can guess, so this is refused and an administrator
            links the pair by hand.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: >
            A malformed body, or a note that verified and carried no usable
            email claim for a subject arriving for the first time. The second
            is not a 401 because the note was not the problem.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "503":
          description: >
            The replay cache is unreachable, so replay cannot be ruled out and
            this route answers nothing rather than accepting a note that may
            be a copy. Password sign-in is unaffected.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/auth/refresh:
    post:
      operationId: auth.refresh
      tags: [Authentication]
      summary: Exchange a refresh token for a new access token
      description: >
        A refresh token works exactly once. The response carries its
        replacement, so a client that loses the response signs in again. A
        used token presented again more than ten seconds after its use ends
        every token descended from the same sign-in, on the reading that two
        parties hold it; inside those ten seconds it is refused and nothing
        else changes.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RefreshRequest"
      responses:
        "200":
          description: A new access token and a replacement refresh token.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenResponse"
        "401":
          description: >
            The token is unknown, already used, expired, or belongs to an
            account that no longer exists.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

  /api/v1/auth/logout:
    post:
      operationId: auth.logout
      tags: [Authentication]
      summary: Revoke a refresh token
      description: >
        Deletes the refresh token named in the body along with the used tokens
        it replaced, which ends that sign-in. An unknown token is not an
        error, so a client that has already lost its token can call this
        without handling a failure. The access token keeps working until it
        expires: there is no server-side revocation of access tokens.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RefreshRequest"
      responses:
        "200":
          description: Token revoked, or it was already gone.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Logged out
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

  /api/v1/auth/me:
    get:
      operationId: auth.getMe
      tags: [Authentication]
      summary: Get current authenticated user profile
      responses:
        "200":
          description: User profile.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/v1/auth/change-password:
    post:
      operationId: auth.changePassword
      tags: [Authentication]
      summary: Change own password
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ChangePasswordRequest"
      responses:
        "200":
          description: >
            Password changed. Every existing session is revoked and the
            calendar feed token is rotated. `refresh_token` replaces the one
            the caller holds; without storing it the caller is signed out when
            its access token expires.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Password updated successfully.
                  refresh_token:
                    type: string
        "400":
          description: >
            Current password incorrect, or the new password is the one the
            account already has. A password that breaks the length or
            placeholder rule is a 422 instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"

  # ── Users ─────────────────────────────────
  /api/v1/users/:
    get:
      operationId: users.list
      tags: [Users]
      summary: List all users
      description: Requires `ORG_ADMIN` or `UNIT_ADMIN`.
      parameters:
        - name: role
          in: query
          schema:
            $ref: "#/components/schemas/InstitutionalRole"
          description: Filter by role.
        - name: unit
          in: query
          schema:
            type: string
          description: Filter by unit code.
        - name: include_deactivated
          in: query
          schema:
            type: boolean
            default: false
          description: Include deactivated accounts, which are left out otherwise.
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: User list.
          headers:
            X-Total-Count:
              $ref: "#/components/headers/XTotalCount"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/UserResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

    post:
      operationId: users.create
      tags: [Users]
      summary: Create a new user
      description: >
        Requires `ORG_ADMIN` or `UNIT_ADMIN`. A unit admin can create users
        only in their own unit, and only an organization admin can create an admin
        account; either is refused with `403`.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserCreate"
      responses:
        "201":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: User created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserResponse"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The manager named in `reporting_line_manager` does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: Duplicate user ID or email.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: >
            A malformed body, or a `reporting_line_manager` that names the
            user, someone who already reports to them, or someone who has been
            deactivated.
            A key reused with a different request is `IDEMPOTENCY_KEY_REUSED`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/users/staff/available:
    get:
      operationId: users.listAvailableStaff
      tags: [Users]
      summary: List active staff with their current status
      description: >
        Every staff member who has not been deactivated, whatever their
        status. The visitor kiosk searches by name through
        `GET /guest/directory` instead.
        This route **must** appear before `GET /users/{user_id}` in the router
        to prevent "staff" being matched as a user_id path parameter.
      parameters:
        - name: unit
          in: query
          schema:
            type: string
          description: Only staff in this unit.
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: Active staff.
          headers:
            X-Total-Count:
              $ref: "#/components/headers/XTotalCount"
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    full_name:
                      type: string
                    unit_code:
                      type: string
                      nullable: true
                    current_occupancy_index:
                      $ref: "#/components/schemas/AccessReadiness"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/v1/users/{user_id}:
    get:
      operationId: users.get
      tags: [Users]
      summary: Get a specific user
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: User details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserResponse"
        "404":
          $ref: "#/components/responses/NotFound"

    patch:
      operationId: users.update
      tags: [Users]
      summary: Update a user
      description: >
        Requires `ORG_ADMIN` or `UNIT_ADMIN`, and a unit admin only within
        their own unit. Only an organization admin can modify an account that is itself
        an admin. A user cannot update their own record here.
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserUpdate"
      responses:
        "200":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: Updated user.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserResponse"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The user, or the manager named in `reporting_line_manager`, does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: The email address is already registered to another account.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: >
            A malformed body, or a `reporting_line_manager` that names the
            user, someone who already reports to them, or someone who has been
            deactivated.
            A key reused with a different request is `IDEMPOTENCY_KEY_REUSED`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/users/{user_id}/reset-password:
    post:
      operationId: users.resetPassword
      tags: [Users]
      summary: Issue a new password for a user who cannot sign in
      description: >
        The only route back into a locked-out account: change-password needs
        the password the user has lost, and no mail sender is configured.
        The new password is returned once and is never stored. The reset also
        drops every refresh token the user holds and rotates their calendar
        feed URL. A UNIT_ADMIN is limited to their own unit and may not reset
        an admin account.
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: A new password, shown this one time.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PasswordResetResponse"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/users/{user_id}/deactivate:
    post:
      operationId: users.deactivate
      tags: [Users]
      summary: Stop an account without deleting it
      description: >
        For somebody who has left. Every record against the account stays,
        and every way in closes: signing in, refreshing, an access token
        already issued, an API key bound to the account, the calendar feed
        and an open WebSocket. The account drops out of `GET /users/` unless
        `include_deactivated=true`, out of the staff directory and staff
        locations, and cannot be named as a manager, lead or substitute, sent
        a guest, issued a new API key or enrolled by a CSV import. Its refresh
        tokens are dropped, its calendar feed URL is rotated and its API keys
        are deleted; reactivating does not bring the keys back. The email
        address stays taken, since the account can come back: to reuse it,
        change it on the deactivated account with `PATCH /users/{user_id}`
        first.


        What already names the account is left alone, and none of it stops
        the account being deactivated. The response counts it under
        `open_items`, and calling again counts afresh. An absence request
        sent to the account is decided by an admin instead; see
        `GET /attendance/absence/pending`.


        Calling it on an account that is already deactivated changes nothing.
        A UNIT_ADMIN is limited to their own unit and may not deactivate an
        admin account, and nobody may deactivate their own.
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: The account, with `deactivated_at` set and what it leaves behind.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeactivatedUserResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          description: >
            The caller named their own account.
            A key reused with a different request is `IDEMPOTENCY_KEY_REUSED`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/users/{user_id}/reactivate:
    post:
      operationId: users.reactivate
      tags: [Users]
      summary: Let a deactivated account back in
      description: >
        The password works again as it was. The API keys do not come back,
        since deactivating deleted them, and neither does the calendar feed
        URL: deactivating rotated it, so the person fetches the new one. If
        the old password should not work again, a reset-password afterwards
        issues a new one. Calling it on an active account changes nothing. A
        UNIT_ADMIN has the same limits as for deactivating.
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: The account, with `deactivated_at` null.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

  /api/v1/users/{user_id}/status:
    put:
      operationId: users.updateStatus
      tags: [Users]
      summary: Update staff availability status
      description: >
        Anyone signed in can update their own. An organization admin can update
        anyone's. This is the occupancy index, and it does not change the
        location the location routes resolve.
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserStatusUpdate"
      responses:
        "200":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: Status updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

  # ── API keys ─────────────────────────────
  /api/v1/api-keys/:
    get:
      operationId: apiKeys.list
      tags: [API Keys]
      summary: List issued keys
      description: >
        Requires `ORG_ADMIN`. Shows what each key is scoped to and when it
        runs out, which is how an unrestricted key left over from before
        scopes existed becomes visible.
      responses:
        "200":
          description: Every key, without its secret.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ApiKeyResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

    post:
      operationId: apiKeys.create
      tags: [API Keys]
      summary: Issue a key
      description: >
        Requires `ORG_ADMIN`. The raw key is in the response and nowhere
        else. Bind it to a service account rather than to a person: the key
        acts as that user, so a person's key inherits everything they can do.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ApiKeyCreate"
      responses:
        "201":
          description: Key issued. The `api_key` field will not be shown again.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiKeyCreated"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: No such user to bind the key to.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: The user to bind the key to has been deactivated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: >
            A scope that is not a scope, an empty scope list, or an
            `expires_at` already in the past.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/api-keys/{key_id}:
    delete:
      operationId: apiKeys.revoke
      tags: [API Keys]
      summary: Revoke a key
      description: >
        Requires `ORG_ADMIN`. Takes effect on the next request that uses it.
      parameters:
        - name: key_id
          in: path
          required: true
          schema:
            type: integer
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "204":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: Revoked.
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

  # ── Federation ────────────────────────────
  /api/v1/federation/issuers:
    get:
      operationId: federation.listIssuers
      tags: [Federation]
      summary: List registered issuers
      description: >
        Requires `ORG_ADMIN`; an API key needs `federation:read`. Every route
        under `/federation` works whether or not federated sign-in is switched
        on, because an issuer and a key have to be registered before switching
        it on is worth doing. It is the exchange route that answers 404 while
        the feature is off.
      responses:
        "200":
          description: Every registration, oldest first.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/IssuerResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

    post:
      operationId: federation.createIssuer
      tags: [Federation]
      summary: Register an outside issuer
      description: >
        Requires `ORG_ADMIN`. A registration on its own accepts nothing: a note
        names its key by `kid`, so the issuer needs at least one key before any
        note it mints will verify. A role map is optional, and an issuer without
        one puts everybody it sends on `MEMBER`.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IssuerCreate"
      responses:
        "201":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: Registered.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IssuerResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          description: That `iss` value is already registered. The detail names the registration.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

  /api/v1/federation/issuers/{issuer_id}:
    patch:
      operationId: federation.updateIssuer
      tags: [Federation]
      summary: Change a registration
      description: >
        Requires `ORG_ADMIN`. `enabled` false is how an issuer is stopped
        without losing what it was allowed to assert; notes from it are then
        refused exactly the way an unknown issuer's are.
      parameters:
        - name: issuer_id
          in: path
          required: true
          schema:
            type: integer
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IssuerUpdate"
      responses:
        "200":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: Changed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IssuerResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

    delete:
      operationId: federation.deleteIssuer
      tags: [Federation]
      summary: Remove a registration
      description: >
        Requires `ORG_ADMIN`. Takes the issuer's keys, its role map and its
        links with it. The accounts stay: somebody who signed in through this
        issuer keeps their account and their history, and loses the shortcut.
        Give them a password or link them to another registration.
      parameters:
        - name: issuer_id
          in: path
          required: true
          schema:
            type: integer
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "204":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: Removed.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

  /api/v1/federation/issuers/{issuer_id}/keys:
    get:
      operationId: federation.listKeys
      tags: [Federation]
      summary: List an issuer's signing keys
      description: >
        Requires `ORG_ADMIN`; an API key needs `federation:read`. The keys are
        public and are returned in full, which is how an integrator checks that
        what was registered is what they are signing with.
      parameters:
        - name: issuer_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Every key on this registration, oldest first.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/IssuerKeyResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

    post:
      operationId: federation.addKey
      tags: [Federation]
      summary: Add a signing key
      description: >
        Requires `ORG_ADMIN`. A rotation is this route and then
        `federation.retireKey` on the old key: add the new one, give the old one
        an end far enough ahead that notes already in flight still verify, and
        delete it afterwards. Adding a key does not retire anything.
      parameters:
        - name: issuer_id
          in: path
          required: true
          schema:
            type: integer
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IssuerKeyCreate"
      responses:
        "201":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: Added.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IssuerKeyResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: This issuer already has a key with that `kid`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: >
            A `public_key` that is not a PEM public key or is not Ed25519, or a
            `not_after` that is not after `not_before`.
            A key reused with a different request is `IDEMPOTENCY_KEY_REUSED`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/federation/issuers/{issuer_id}/keys/{key_id}:
    patch:
      operationId: federation.retireKey
      tags: [Federation]
      summary: Give a key an end
      description: >
        Requires `ORG_ADMIN`. A moment in the past stops the key now: the next
        note naming it is refused. A moment in the future is the overlap a
        planned rotation wants. The key stays readable either way, which is why
        this is a separate route from deleting it.
      parameters:
        - name: issuer_id
          in: path
          required: true
          schema:
            type: integer
        - name: key_id
          in: path
          required: true
          schema:
            type: integer
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IssuerKeyRetire"
      responses:
        "200":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: Retired at the moment given.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IssuerKeyResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          description: >
            `not_after` is not after the key's `not_before`, which would leave a
            key that was never valid. Delete it instead.
            A key reused with a different request is `IDEMPOTENCY_KEY_REUSED`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

    delete:
      operationId: federation.deleteKey
      tags: [Federation]
      summary: Remove a key
      description: >
        Requires `ORG_ADMIN`. Immediate and complete: a note naming it is
        refused as naming an unknown key. Retiring it first is the kinder path
        during a rotation, and deleting it is the right one for a key that
        leaked.
      parameters:
        - name: issuer_id
          in: path
          required: true
          schema:
            type: integer
        - name: key_id
          in: path
          required: true
          schema:
            type: integer
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "204":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: Removed.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

  /api/v1/federation/issuers/{issuer_id}/role-map:
    get:
      operationId: federation.listRoleMap
      tags: [Federation]
      summary: What this issuer's groups mean here
      description: >
        Requires `ORG_ADMIN`; an API key needs `federation:read`. Entries are
        returned oldest first, which is also the order that decides ties: where
        a note asserts two groups that both match, `STAFF` beats `MEMBER` and
        the older entry of the winning role supplies the unit.
      parameters:
        - name: issuer_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Every entry on this registration.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/RoleMapEntryResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

    post:
      operationId: federation.addRoleMapEntry
      tags: [Federation]
      summary: Map a group to a role
      description: >
        Requires `ORG_ADMIN`. The map belongs to the operator: a note names a
        subject and may name groups, and never a role. Two groups may map to
        different units, which is the ordinary case for a library and a lab.
      parameters:
        - name: issuer_id
          in: path
          required: true
          schema:
            type: integer
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RoleMapEntryCreate"
      responses:
        "201":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: Mapped.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RoleMapEntryResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: >
            This issuer already maps that group. Delete the entry to change what
            it means, so the map never holds two answers for one group.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: >
            A `role_type` of `ORG_ADMIN` or `UNIT_ADMIN`. No issuer may assert
            either, which is what keeps a leaked signing key to the level the
            operator chose.
            A key reused with a different request is `IDEMPOTENCY_KEY_REUSED`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/federation/issuers/{issuer_id}/role-map/{entry_id}:
    delete:
      operationId: federation.deleteRoleMapEntry
      tags: [Federation]
      summary: Unmap a group
      description: >
        Requires `ORG_ADMIN`. Nobody who has already signed in changes: roles
        are read once, when the account is created. What changes is what the
        next first-time subject in that group gets, which with no entry is
        `MEMBER` and no unit.
      parameters:
        - name: issuer_id
          in: path
          required: true
          schema:
            type: integer
        - name: entry_id
          in: path
          required: true
          schema:
            type: integer
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "204":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: Unmapped.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

  /api/v1/federation/links:
    get:
      operationId: federation.listLinks
      tags: [Federation]
      summary: Which accounts arrive through which issuer
      description: >
        Requires `ORG_ADMIN`; an API key needs `federation:read`. A link made by
        a first sign-in has an id nobody was told, so this is how one is found
        before it can be removed. Both filters are optional and combine.
      parameters:
        - name: issuer_id
          in: query
          required: false
          description: Only links on this registration.
          schema:
            type: integer
        - name: user_id
          in: query
          required: false
          description: Only links pointing at this account.
          schema:
            type: string
      responses:
        "200":
          description: Links, oldest first.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/LinkResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

    post:
      operationId: federation.createLink
      tags: [Federation]
      summary: Let an existing account arrive through an issuer
      description: >
        Requires `ORG_ADMIN`. The link is the identity: a note is the account
        its `(issuer, subject)` pair points at, whatever address the note
        carries. Without this route the only accounts that can use the shortcut
        are ones federation created itself, so this is how somebody who already
        has a password here starts arriving through their institution instead.
        One account may hold several links, one per issuer.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LinkCreate"
      responses:
        "201":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: Linked. The next note carrying that pair is this account.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LinkResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: No such issuer, or no such account.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: >
            Either that `(issuer, subject)` pair is already linked, or the
            account is an `ORG_ADMIN` or `UNIT_ADMIN`. An admin account is
            refused because the answer to a leaked signing key is that no
            issuer holds a route to one; a link would be exactly that route.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

  /api/v1/federation/links/{link_id}:
    delete:
      operationId: federation.deleteLink
      tags: [Federation]
      summary: Stop an account arriving through an issuer
      description: >
        Requires `ORG_ADMIN`. The account stays, with whatever role and unit it
        holds; what goes is the route. A note carrying the unlinked pair is then
        a stranger, and a stranger whose address is taken is refused rather than
        given a second account.
      parameters:
        - name: link_id
          in: path
          required: true
          schema:
            type: integer
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "204":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: Unlinked.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
  # ── Resource classes ──────────────────────
  /api/v1/resource-classes/:
    get:
      operationId: resourceClasses.list
      tags: [Resource classes]
      summary: List resource classes
      description: >
        The kinds of resource the organization books, in code order, `ROOM`
        and `PERSON` among them. Readable by anyone signed in, as resources
        are.
      parameters:
        - name: active
          in: query
          required: false
          schema:
            type: boolean
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: Classes, ordered by code.
          headers:
            X-Total-Count:
              $ref: "#/components/headers/XTotalCount"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ResourceClassResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"

    post:
      operationId: resourceClasses.create
      tags: [Resource classes]
      summary: Create a resource class
      description: >
        Requires `ORG_ADMIN`. Adds a kind of resource. The class is a label:
        resources are filed under it and requirements can ask for it, and
        nothing about how it books differs from any other resource. The code
        is permanent.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ResourceClassCreate"
      responses:
        "201":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: The class as created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceClassResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          description: The organization already has a class with that code (`ALREADY_EXISTS`).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

  /api/v1/resource-classes/{code}:
    parameters:
      - name: code
        in: path
        required: true
        schema:
          type: string
        example: EQUIPMENT_CART
    patch:
      operationId: resourceClasses.update
      tags: [Resource classes]
      summary: Rename or switch a class off
      description: >
        Requires `ORG_ADMIN`. Renaming is allowed for every class.
        Deactivating stops new resources and new requirements naming the
        class and leaves the ones that already do as they are; deactivating
        `ROOM` or `PERSON` is a 409 with `RESOURCE_CLASS_PROTECTED`.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ResourceClassUpdate"
      responses:
        "200":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: The class as it now stands.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceClassResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: >
            `ROOM` or `PERSON` cannot be switched off
            (`RESOURCE_CLASS_PROTECTED`).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

    delete:
      operationId: resourceClasses.delete
      tags: [Resource classes]
      summary: Delete a class nothing uses
      description: >
        Requires `ORG_ADMIN`. Refused with 409 `RESOURCE_CLASS_PROTECTED` for
        `ROOM` and `PERSON`, and with 409 `RESOURCE_CLASS_IN_USE` while any
        resource has the class or any requirement asks for it, whether the
        class is active or not. Switch it off instead to stop new uses and
        keep the old.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "204":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: Deleted.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: Protected (`RESOURCE_CLASS_PROTECTED`) or in use (`RESOURCE_CLASS_IN_USE`).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  # ── Resources ─────────────────────────────
  /api/v1/resources/:
    get:
      operationId: resources.list
      tags: [Resources]
      summary: List resources
      description: >
        Every room, person and piece of equipment the schedule can point at.
        Readable by anyone signed in: an external system that has to book a
        room needs to be able to find it first.
      parameters:
        - name: resource_type
          in: query
          required: false
          description: A resource class code.
          schema:
            type: string
        - name: active
          in: query
          required: false
          schema:
            type: boolean
        - name: code
          in: query
          required: false
          schema:
            type: string
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: Resources, ordered by code.
          headers:
            X-Total-Count:
              $ref: "#/components/headers/XTotalCount"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ResourceResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"

    post:
      operationId: resources.create
      tags: [Resources]
      summary: Create a resource
      description: >
        Requires `ORG_ADMIN`. Registers a resource before any timetable
        names it, for a system that manages its own rooms. It is a room
        unless `resource_type` names another class of the organization. The row is the one an
        import would have made, so a later CSV naming the room finds it
        rather than creating a second. A retry after a lost response can
        send an Idempotency-Key, or read the room back with
        `GET /api/v1/resources/?code=`: the code already identifies it.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ResourceCreate"
      responses:
        "201":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: The room as created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          description: A resource with that code already exists in the caller's organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: >
            A blank or over-long code, latitude without longitude or the
            reverse, a coordinate out of range, or a `resource_type` that is
            not an active class of the organization (`UNKNOWN_RESOURCE_CLASS`).
            A key reused with a different request is `IDEMPOTENCY_KEY_REUSED`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/resources/reservations:
    get:
      operationId: resources.listReservations
      tags: [Resources]
      summary: List the caller's own reservations
      description: >
        Requires `ORG_ADMIN` or `UNIT_ADMIN`. The reservations the caller
        made, cancelled ones included, in id order. Only the caller's, for
        every role, an `ORG_ADMIN` included: a reference means something only
        to the system that chose it, so asking for one must return the
        caller's own booking and never another caller's under the same
        string. This is where an integration finds its bookings, not a view
        of everybody's.


        `external_ref` matches exactly, case included, so with it the answer
        is one reservation or none. Under `/resources` so that a key scoped
        `resources:read` reaches it.
      parameters:
        - name: external_ref
          in: query
          required: false
          schema:
            type: string
          example: visit-42
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: The caller's reservations, ordered by id.
          headers:
            X-Total-Count:
              $ref: "#/components/headers/XTotalCount"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ReservationResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  /api/v1/resources/{resource_id}:
    parameters:
      - name: resource_id
        in: path
        required: true
        schema:
          type: integer
    patch:
      operationId: resources.update
      tags: [Resources]
      summary: Update a resource
      description: >
        Fill in what a CSV could not know: capacity, mode, and where the
        room physically is. Setting latitude and longitude is what switches
        geofencing on for every session held there. A change of mode or
        capacity is checked against the bookings still to come and refused
        with 409 if any would no longer fit.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ResourceUpdate"
      responses:
        "200":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: The resource as it now stands.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: >
            Bookings still to come would not fit the new mode or capacity
            (`RESOURCE_BOOKINGS_WOULD_NOT_FIT`). They are listed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BookingsWouldNotFit"
        "422":
          description: >
            latitude and longitude were not set or cleared together, a
            coordinate was out of range, mode was null, or a POOLED resource
            would be left without a capacity of at least 1.
            A key reused with a different request is `IDEMPOTENCY_KEY_REUSED`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/resources/{resource_id}/availability:
    get:
      operationId: resources.getAvailability
      tags: [Resources]
      summary: When a resource is already taken
      description: >
        Expands the weekly slots pointing at this resource over the range,
        inclusive of both ends, and unions in the reservations and the days
        the nightly generator has already written. A slot counts when its
        cycle is flagged open and the date is inside the cycle's date bounds,
        both ends included, which are the two tests nightly ledger generation
        applies; answering otherwise would report a room free on a date the
        generator is going to fill.


        A generated day counts whatever its cycle now says: closing a cycle
        leaves behind the days already past and any ahead that carry
        attendance or a note, deleting a slot leaves behind the days
        attendance was marked on, and the database refuses a second booking
        on top of either. Where a day and the slot it
        came from both cover a date you get the day, once, because the day is
        the row that holds the hour and keeps its window when the slot is
        corrected later. Dates the generator has not reached yet come from the
        slot. An inactive resource still answers: retiring a room does not
        clear its calendar.


        A busy interval's date can be the day before `from`. A booking
        that runs past midnight is dated the day it opened on and occupies
        the morning after, so a caller asking about Tuesday is told about a
        hold dated Monday that ends at six. Read each interval by its own
        date and end_date and not by the range that returned it: grouping
        by date alone files that hold under a day nobody asked about, and
        discarding anything outside the range shows a ward as free while it
        is staffed.


        The resource's mode changes which reservations count. On a POOLED
        resource one booking does not make it busy: each stretch in which
        the bookings together hold the whole pool is reported instead, as an
        interval with every id null. On a SHARED resource reservations are
        never reported.
      parameters:
        - name: resource_id
          in: path
          required: true
          schema:
            type: integer
        - name: from
          in: query
          required: true
          schema:
            type: string
            format: date
          example: "2026-01-05"
        - name: to
          in: query
          required: true
          schema:
            type: string
            format: date
          example: "2026-01-11"
        - name: with_requirements
          in: query
          required: false
          description: >
            Also answer whether the resource could be held for one window
            together with everything it requires, as a booking would hold it,
            in `requirements_met` and `unmet`. Holds nothing. Needs `from`
            and `to` to be the same date and `start` and `end` to be given,
            otherwise 422.
          schema:
            type: boolean
            default: false
        - name: start
          in: query
          required: false
          description: The window's start, with `with_requirements`.
          schema:
            type: string
            format: time
        - name: end
          in: query
          required: false
          description: >
            The window's end, with `with_requirements`. Earlier than start
            means it runs past midnight, as for a booking.
          schema:
            type: string
            format: time
      responses:
        "200":
          description: The busy intervals in the range.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AvailabilityResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          description: >
            from was after to, or the inclusive range was longer than 366
            days.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/resources/{resource_id}/reservations:
    post:
      operationId: resources.createReservation
      tags: [Resources]
      summary: Hold a resource for one dated window
      description: >
        Requires `ORG_ADMIN` or `UNIT_ADMIN`. A UNIT_ADMIN may hold a
        resource their own unit owns, or one with no unit (shared by the whole
        organization), and is refused a resource of another unit with 403
        `OUTSIDE_UNIT`. The route an outside system
        uses to take a room. What it refuses is exactly what GET availability
        calls busy, through the same queries and the same expansion, so a
        caller cannot read an hour as free and then be refused it.


        The rule runs both ways. A class cannot be put on top of a hold
        either, so POST /schedule/slots, PATCH /schedule/slots/{slot_id} and
        a CSV upload are each refused where a booking already stands. A hold
        taken here holds against the timetable and not only against other
        holds.


        Windows are half open, so an interval ending at ten and one starting
        at ten do not clash. A window may end earlier than it starts, and
        that is how it says it runs past midnight: 22:00 to 06:00 is a
        night shift of eight hours, and date is the day it opens on. Equal
        times are refused, because 09:00 to 09:00 is either nothing at all
        or a full day and there is no way to tell which was meant.


        A weekly slot reads its two times by the same rule, so an overnight
        booking is checked against night shifts on the timetable as well as
        against day ones.


        An `external_ref` already on one of the caller's reservations,
        cancelled or not, is a 409 with `RESERVATION_EXTERNAL_REF_TAKEN` and
        the id of that reservation in `detail.reservation_id`. The reference
        is checked after the Idempotency-Key, so a retry under the same key
        and the same body is still a `200` with the original hold, and
        before the window, so the same booking sent again under a new key is
        told it already exists rather than that the window is taken. Two
        requests racing for one reference get one booking and the same 409
        for the loser. A cancelled reservation keeps its reference: clear or
        change it with PATCH before booking under it again.


        The resource's mode decides what is in the way. EXCLUSIVE is all of
        the above. POOLED refuses a window the timetable holds, because a
        class takes the whole pool, and otherwise takes `quantity` units
        when the bookings already there leave that many free at every
        moment of the window; otherwise 409 `RESOURCE_CAPACITY_EXCEEDED`.
        SHARED refuses nothing. A quantity above 1 on a resource that is
        not POOLED is a 422.


        What the resource requires is held in the same transaction, each as
        its own reservation naming this one in `parent_reservation_id`, and
        listed in `children`. See `GET /api/v1/resources/{resource_id}/requirements`.
        A named resource is held for the window widened by the requirement's
        `before_minutes` and `after_minutes`, by its own mode. A kind is
        filled from `assignments`, then by the first free resources of the
        kind by code. A REQUIRED requirement that cannot be met holds
        nothing and answers 409 `REQUIREMENT_UNSATISFIED`; an ADVISORY one is
        left out and listed in `unmet`. A padded window that would cross
        midnight of the booking's last day is a 422. Cancelling the booking
        cancels the holds it took.
      parameters:
        - name: resource_id
          in: path
          required: true
          schema:
            type: integer
        - name: Idempotency-Key
          in: header
          required: true
          description: >
            Unique per caller across every resource. A UUID is the right
            shape. Required rather than optional because a booking client
            retries, and a retry that books a second room is worse than one
            that fails. This route keeps the answer it gave before the
            shared Idempotency-Key: a retry gets the hold as it is now with
            `200`, not a replay.
          schema:
            type: string
            minLength: 8
            maxLength: 120
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReservationCreate"
      responses:
        "201":
          description: >
            The hold was taken, with the holds its requirements took in
            `children` and the advisory gaps in `unmet`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReservationCreated"
        "200":
          description: >
            The same key and the same body arrived again. This is the original
            hold, cancelled or not: a retry is asking what happened, not
            asking for a second room.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReservationCreated"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: >
            The caller already has a reservation with that external_ref
            (`RESERVATION_EXTERNAL_REF_TAKEN`, ReservationRefTaken), a
            pool has too few units free (`RESOURCE_CAPACITY_EXCEEDED`,
            CapacityExceeded), a REQUIRED requirement cannot be met
            (`REQUIREMENT_UNSATISFIED`, ReservationConflict, naming what was
            missing), or something already holds part of that
            window (`RESOURCE_CONFLICT`, ReservationConflict). Branch on
            `code`. ReservationConflict is listed last because its detail
            has no required fields, so a client trying each shape in turn
            tells them apart.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/ReservationRefTaken"
                  - $ref: "#/components/schemas/CapacityExceeded"
                  - $ref: "#/components/schemas/ReservationConflict"
        "422":
          description: >
            end was not after start, quantity was above 1 on a resource
            that is not POOLED, `assignments` named a resource of the wrong
            kind, of no requirement or of no active resource of this
            organization, a requirement's padded window would cross
            midnight, or the Idempotency-Key had already been used
            for a different request (`IDEMPOTENCY_KEY_REUSED`).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/resources/{resource_id}/requirements:
    get:
      operationId: resources.listRequirements
      tags: [Resources]
      summary: What a resource requires
      description: >
        Any signed-in user. The standing rules of the resource: using it also
        needs these. Booking the resource holds them, see
        `POST /api/v1/resources/{resource_id}/reservations`.
      parameters:
        - name: resource_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: The requirements, oldest first.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/RequirementResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"

    post:
      operationId: resources.createRequirement
      tags: [Resources]
      summary: Say that a resource requires another
      description: >
        Requires `ORG_ADMIN`. The target is a specific resource or any
        resource of a kind, never an activity. A chain of requirements is
        followed to depth 4 when a booking is made. A requirement that would
        make a resource need itself, directly or through other named
        resources, is refused here with a 422. A second requirement of the
        same owner for the same target is a 409 `ALREADY_EXISTS`.
      parameters:
        - name: resource_id
          in: path
          required: true
          schema:
            type: integer
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RequirementCreate"
      responses:
        "201":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: The requirement was saved.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RequirementResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "422":
          description: >
            Neither or both targets, a target that is not a resource of this
            organization, a quantity above 1 on a named target that is not
            POOLED, or a cycle.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/resources/{resource_id}/requirements/{requirement_id}:
    delete:
      operationId: resources.deleteRequirement
      tags: [Resources]
      summary: Remove a requirement of a resource
      description: >
        Requires `ORG_ADMIN`. Holds already taken for it stay.
      parameters:
        - name: resource_id
          in: path
          required: true
          schema:
            type: integer
        - name: requirement_id
          in: path
          required: true
          schema:
            type: integer
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "204":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: Removed.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/resources/{resource_id}/reservations/{reservation_id}:
    patch:
      operationId: resources.updateReservation
      tags: [Resources]
      summary: Change a reservation's external_ref
      description: >
        Requires `ORG_ADMIN` or `UNIT_ADMIN`. Sets, changes or clears the
        caller's reference for a reservation. Only the reference can change:
        moving the window is a cancel and a new booking.


        The reference is unique per requester, the same rule as on create,
        and taking one already on another of the requester's reservations is
        the same 409. When an `ORG_ADMIN` changes a reservation somebody else
        made, the reference is checked against that requester's, not the
        admin's. A cancelled reservation keeps its reference, so this is how
        a caller frees one to book under again.


        Who may change a reservation is who may cancel it: whoever took it,
        or an `ORG_ADMIN`. A `UNIT_ADMIN` that did not make it gets a 403.
        Sending the reference the reservation already has changes nothing
        and leaves no entry on the change feed; a real change leaves one.
      parameters:
        - name: resource_id
          in: path
          required: true
          schema:
            type: integer
        - name: reservation_id
          in: path
          required: true
          schema:
            type: integer
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReservationUpdate"
      responses:
        "200":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: The reservation as it now stands.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReservationResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: Another of the requester's reservations already has that external_ref.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReservationRefTaken"
        "422":
          description: >
            An empty or over-long external_ref, or a field other than
            external_ref.
            A key reused with a different request is `IDEMPOTENCY_KEY_REUSED`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

    delete:
      operationId: resources.cancelReservation
      tags: [Resources]
      summary: Let a hold go
      description: >
        Requires `ORG_ADMIN` or `UNIT_ADMIN`. Marks the reservation
        cancelled and leaves the row in place. A deleted row cannot be told to
        anybody, and a system that was informed the room was held has to be
        able to learn that it no longer is.


        The freed window is bookable again immediately and stops appearing in
        availability. Cancelling twice is not an error and returns the same
        timestamp. Cancelling through the wrong resource id is a 404.


        A hold is let go by whoever took it. A `UNIT_ADMIN` that did not make
        the reservation gets a 403; an `ORG_ADMIN` overrides, because a hold
        taken by an account that no longer exists has nobody left to cancel
        it.
      parameters:
        - name: resource_id
          in: path
          required: true
          schema:
            type: integer
        - name: reservation_id
          in: path
          required: true
          schema:
            type: integer
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: The cancelled hold.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReservationResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

  # ── Schedule ──────────────────────────────
  /api/v1/schedule/activities:
    get:
      operationId: schedule.listActivities
      tags: [Schedule]
      summary: List activities
      description: >
        Any signed-in user. Retired activities are left out unless
        `include_retired` is set.
      parameters:
        - name: cycle_id
          in: query
          required: false
          schema:
            type: integer
        - name: include_retired
          in: query
          required: false
          schema:
            type: boolean
            default: false
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: Activities.
          headers:
            X-Total-Count:
              $ref: "#/components/headers/XTotalCount"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ActivityResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"

    post:
      operationId: schedule.createActivity
      tags: [Schedule]
      summary: Add an activity
      description: >
        Admin only. A UNIT_ADMIN may only add activities to their own unit
        (403 `OUTSIDE_UNIT`). The activity starts with no slots and no
        members. Each slot added to it with POST /schedule/slots fills the
        days ahead at once, through the same generator a CSV import and the
        nightly job use, so an activity built here gets exactly the days the
        same activity imported from a CSV would.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ActivityCreate"
      responses:
        "201":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: Activity created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActivityResponse"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The cycle does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: >
            The code is already used in that cycle (`ALREADY_EXISTS`), by a
            live activity or a retired one. The detail says which.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

  /api/v1/schedule/activities/{activity_id}:
    get:
      operationId: schedule.getActivity
      tags: [Schedule]
      summary: Read one activity
      description: Any signed-in user. A retired activity is still returned.
      parameters:
        - name: activity_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: The activity.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActivityResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"

    patch:
      operationId: schedule.updateActivity
      tags: [Schedule]
      summary: Rename an activity
      description: >
        Admin only, inside the admin's unit. Only the title can change; see
        ActivityUpdate for why. Refused with 409 `STATE_CONFLICT` once the
        activity is retired.
      parameters:
        - name: activity_id
          in: path
          required: true
          schema:
            type: integer
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ActivityUpdate"
      responses:
        "200":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: The activity as it now stands.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActivityResponse"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: The activity is retired.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

  /api/v1/schedule/activities/{activity_id}/retire:
    post:
      operationId: schedule.retireActivity
      tags: [Schedule]
      summary: Retire an activity
      description: >
        Admin only, inside the admin's unit. Nothing is deleted that has
        happened. The activity and every slot it still has are marked
        retired, so the generator writes no more days for them and their
        rooms are free again. Days from today onward that nobody has marked
        or annotated are removed; days that carry attendance or a note are
        kept; days before today are not touched.


        A retired activity stays readable through GET
        /schedule/activities/{activity_id} and is left out of the list
        unless `include_retired` is set. It cannot be edited, given slots or
        members, or retired again (409 `STATE_CONFLICT`), and a CSV import
        that names it is refused. Its code stays taken in the cycle.
      parameters:
        - name: activity_id
          in: path
          required: true
          schema:
            type: integer
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: What retiring removed and what it kept.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RetireResult"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: The activity is already retired.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

  /api/v1/schedule/activities/{activity_id}/enrollments:
    get:
      operationId: schedule.listEnrollments
      tags: [Schedule]
      summary: List an activity's members
      description: Admin only, inside the admin's unit.
      parameters:
        - name: activity_id
          in: path
          required: true
          schema:
            type: integer
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: The roster.
          headers:
            X-Total-Count:
              $ref: "#/components/headers/XTotalCount"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/EnrollmentResponse"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

    post:
      operationId: schedule.createEnrollment
      tags: [Schedule]
      summary: Enroll a member
      description: >
        Admin only, inside the admin's unit. The member has to exist and be
        active, as in a CSV import. Days belong to slots rather than members,
        so no day is written: the member sees the activity's days from now
        on.
      parameters:
        - name: activity_id
          in: path
          required: true
          schema:
            type: integer
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EnrollmentCreate"
      responses:
        "201":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: Member enrolled.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EnrollmentResponse"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The activity or the member does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: >
            The member is already enrolled (`ALREADY_EXISTS`), or the activity
            is retired (`STATE_CONFLICT`).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: >
            A malformed body, or a member who has been deactivated (`USER_DEACTIVATED`).
            A key reused with a different request is `IDEMPOTENCY_KEY_REUSED`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/schedule/activities/{activity_id}/enrollments/{member_id}:
    delete:
      operationId: schedule.deleteEnrollment
      tags: [Schedule]
      summary: Remove a member from an activity
      description: >
        Admin only, inside the admin's unit. Only the enrollment goes. Days
        belong to slots, so no day is removed, and the attendance already
        recorded for the member stays.
      parameters:
        - name: activity_id
          in: path
          required: true
          schema:
            type: integer
        - name: member_id
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: The enrollment that was removed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  activity_id:
                    type: integer
                  member_id:
                    type: string
                  removed:
                    type: boolean
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The activity does not exist, or the member is not enrolled in it.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: The activity is retired.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

  /api/v1/schedule/activities/{activity_id}/requirements:
    get:
      operationId: schedule.listActivityRequirements
      tags: [Schedule]
      summary: What an activity needs besides its room
      description: Admin only, inside the admin's unit.
      parameters:
        - name: activity_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: The requirements, oldest first.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/RequirementResponse"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

    post:
      operationId: schedule.createActivityRequirement
      tags: [Schedule]
      summary: Say that an activity also needs a resource
      description: >
        Admin only, inside the admin's unit. The timetable holds nothing for
        a requirement. One that a slot's dates cannot have is reported as a
        `requirement_unmet` in `GET /api/v1/schedule/conflicts`, in
        `requirements_unmet` on the slot routes and the CSV import, and in
        the generator's log, and no slot or day is refused for it.
      parameters:
        - name: activity_id
          in: path
          required: true
          schema:
            type: integer
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RequirementCreate"
      responses:
        "201":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: The requirement was saved.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RequirementResponse"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: >
            The activity already requires that target (`ALREADY_EXISTS`), or
            the activity is retired (`STATE_CONFLICT`).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: >
            Neither or both targets, a target that is not a resource of this
            organization, or a quantity above 1 on a named target that is not
            POOLED.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/schedule/activities/{activity_id}/requirements/{requirement_id}:
    delete:
      operationId: schedule.deleteActivityRequirement
      tags: [Schedule]
      summary: Remove a requirement of an activity
      description: Admin only, inside the admin's unit.
      parameters:
        - name: activity_id
          in: path
          required: true
          schema:
            type: integer
        - name: requirement_id
          in: path
          required: true
          schema:
            type: integer
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "204":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: Removed.
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/schedule/slots:
    get:
      operationId: schedule.listSlots
      tags: [Schedule]
      summary: List master slots
      description: >
        The recurring timetable, before any day is generated from it. Filter
        by cycle to get one term's worth. Retired slots are left out unless
        `include_retired` is set.
      parameters:
        - name: cycle_id
          in: query
          required: false
          schema:
            type: integer
        - name: include_retired
          in: query
          required: false
          schema:
            type: boolean
            default: false
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: Master slots.
          headers:
            X-Total-Count:
              $ref: "#/components/headers/XTotalCount"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/MasterSlotResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"

    post:
      operationId: schedule.createSlot
      tags: [Schedule]
      summary: Add a master slot
      description: >
        Admin only. A UNIT_ADMIN may only add slots inside their own unit,
        and only in a room of their own unit or a room with no unit (403
        `OUTSIDE_UNIT` otherwise).
        The new slot fills the days ahead at once, through the same generator
        a CSV import and the nightly job use. A retired activity takes no new
        slots (409 `STATE_CONFLICT`).


        Refused with 409 where the room is already taken for part of that
        window, whether by a booking or by another class. Only holds from
        today forward count, because a slot lays down days from now onwards
        and never backwards, and a slot in a closed cycle is neither checked
        nor counted against, because such a slot does not occupy the room and
        a booking is already accepted on top of one. Every open cycle counts,
        including a second one covering a different part of the year: the
        nightly generator lays every open cycle onto today, so all of them
        hold the room today.


        Refused with 409 as well where a day has already been generated on
        that room in part of that window. Such a day may have no slot
        speaking for it any more: closing a cycle leaves behind the days
        ahead that carry attendance or a note, and deleting a slot leaves
        behind the days that carry attendance. Both of those read as free to the two checks above
        while somebody is still due at the door, so this one has no cycle
        gate on either side.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MasterSlotCreate"
      responses:
        "200":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: >
            The slot's id, and `requirements_unmet`: what its activity or its
            resource requires that the slot's next run cannot have. Empty
            when nothing is required. A report; the slot is saved either way.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  requirements_unmet:
                    type: array
                    items:
                      $ref: "#/components/schemas/SlotRequirementGap"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The activity, or the user named in `primary_lead_id`, does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: >
            The room is taken for part of that window, either by a booking or
            by another class already on the timetable. The message says which.
            The body is the one a refused booking sends, so a clash reads the
            same way whichever end it came from; a conflict caused by a class
            names the activity and carries a null reservation_id, and one
            caused by a booking does the reverse. Slots in a closed cycle
            occupy nothing and are not counted, but the days such a slot has
            already generated do, and a clash with one of those is refused
            here too.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReservationConflict"
        "422":
          description: >
            A malformed body, or a `primary_lead_id` naming somebody who has been deactivated.
            A key reused with a different request is `IDEMPOTENCY_KEY_REUSED`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/schedule/slots/{slot_id}:
    patch:
      operationId: schedule.updateSlot
      tags: [Schedule]
      summary: Change a master slot, and the days it has already produced
      description: >
        Admin only. A UNIT_ADMIN may only change slots of their own unit, and
        only move one into a room of their own unit or a room with no unit
        (403 `OUTSIDE_UNIT` otherwise). A new window, lead or room is copied onto the days that
        are still plans, while days carrying attendance or a note are counted
        and left alone. Only days after today are moved, so a class shifted
        to 10:00 runs at 10:00 from tomorrow and the days it already ran at
        09:00 still say 09:00.


        A new rrule or dtstart is the one change that cannot be copied
        across, because the days already generated sit on the dates of the
        old rule. Those are withdrawn for the generator to lay down again, and
        the request is refused with 409 if any of them has been marked.


        Also refused with 409 where the room it would move to is already
        taken for part of the window it would move to, by a booking or by
        another class. The slot's own window is not counted against it, so
        widening one is not refused by the window it replaces. A refusal
        changes nothing: the room is resolved and the clashes are checked
        before any day is withdrawn or any field is written.


        A change that leaves the room, rule and window alone is not
        checked, so a new lead can be set on a slot a hold is already sitting
        on. Such a hold predates this rule or was written straight into the
        database, and refusing would leave the lead unfixable short of
        cancelling somebody else's booking.


        A day already generated on that room in part of the window refuses
        the change as well, with no cycle gate on either side, because such a
        day still puts somebody at a door whatever its cycle now says. The
        check is made before anything is written and again if the database
        refuses the write anyway: two admins moving two classes onto one room
        at the same moment both pass the first ask, and the loser is told
        what beat it rather than handed a 500.
      parameters:
        - name: slot_id
          in: path
          required: true
          schema:
            type: integer
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MasterSlotUpdate"
      responses:
        "200":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: What the change reached and what it left alone.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SlotUpdateResult"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The slot, or the user named in `primary_lead_id`, does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: >
            Either a day the slot has already produced has been marked, and
            the detail names those dates, or the room is taken for part of the
            window by a booking or by another class, and the body is the one a
            refused booking sends. A day already generated on that room is a
            third reason, and reads as a class in the body. A change that does
            not move the class, a new lead for instance, is checked against
            none of them.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/ErrorResponse"
                  - $ref: "#/components/schemas/ReservationConflict"
        "422":
          description: >
            A malformed body, a window that starts and ends at the same time,
            or a `primary_lead_id` naming somebody who has been deactivated.
            A key reused with a different request is `IDEMPOTENCY_KEY_REUSED`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

    delete:
      operationId: schedule.deleteSlot
      tags: [Schedule]
      summary: Take a master slot off the timetable
      description: >
        Admin only. Days from today onward are still plans and are removed;
        days already past keep their attendance and notes and are left with
        no slot to point at. If any day from today onward has been marked,
        nothing is deleted and the response names those dates.


        A detached day keeps its window. The day was copied off the slot when
        it was generated, so losing the slot does not lose the hour it ran at
        and it stays a timed event on a calendar feed. Days generated before
        the ledger carried its own window have none to keep and still appear
        as all-day events.
      parameters:
        - name: slot_id
          in: path
          required: true
          schema:
            type: integer
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: What was removed and what was kept.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SlotDeletionResult"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

  /api/v1/schedule/slots/{slot_id}/retire:
    post:
      operationId: schedule.retireSlot
      tags: [Schedule]
      summary: Retire a master slot
      description: >
        Admin only, inside the admin's unit. Where DELETE refuses while a day
        ahead carries attendance or a note, this keeps that day and removes
        the days ahead that are still plans. Days before today are not
        touched. The slot stays, marked retired, so the generator writes no
        more days for it and its room is free again. A retired slot cannot be
        edited, deleted or retired again (409 `STATE_CONFLICT`), and a CSV
        row naming it is refused.
      parameters:
        - name: slot_id
          in: path
          required: true
          schema:
            type: integer
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: What retiring removed and what it kept.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RetireResult"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: The slot is already retired.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

  /api/v1/schedule/ledger/today:
    get:
      operationId: schedule.getTodayLedger
      tags: [Schedule]
      summary: Today's ledger entries for the authenticated user
      description: >
        Staff receive entries where they are the active or substitute lead.
        Members receive entries for their registered activities.
        An ORG_ADMIN receives all entries; a UNIT_ADMIN receives the entries
        of the activities in their own unit.
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: Today's schedule.
          headers:
            X-Total-Count:
              $ref: "#/components/headers/XTotalCount"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/DailyLedgerResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/v1/schedule/ledger:
    get:
      operationId: schedule.listLedger
      tags: [Schedule]
      summary: Ledger entries between two dates
      description: >
        Both dates included, ordered by date, then start time. Rows and the
        role filter are the same as `/schedule/ledger/today`. `to` before
        `from` is refused with 422.
      parameters:
        - name: from
          in: query
          required: true
          schema:
            type: string
            format: date
        - name: to
          in: query
          required: true
          schema:
            type: string
            format: date
        - name: resource_id
          in: query
          required: false
          schema:
            type: integer
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: The ledger over the range.
          headers:
            X-Total-Count:
              $ref: "#/components/headers/XTotalCount"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/DailyLedgerResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

  /api/v1/schedule/conflicts:
    get:
      operationId: schedule.listConflicts
      tags: [Schedule]
      summary: Clashes already in the schedule between two dates
      description: >
        Reports two rows holding one resource at once, one member enrolled in
        two activities that run at once, and one lead leading two activities
        at once. It reads and reports; nothing is refused or changed. Both dates are included. `to` before `from`, or a
        range longer than 92 days, is refused with 422 and code
        INVALID_VALUE. ORG_ADMIN and UNIT_ADMIN only. An ORG_ADMIN gets every
        clash. A UNIT_ADMIN gets the clashes in which at least one item
        belongs to their own unit (through its activity, or through its
        resource for a reservation or a row with no activity), each returned
        whole.
      parameters:
        - name: from
          in: query
          required: true
          schema:
            type: string
            format: date
        - name: to
          in: query
          required: true
          schema:
            type: string
            format: date
      responses:
        "200":
          description: The clashes over the range.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConflictReport"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

  /api/v1/schedule/ledger/{ledger_id}:
    patch:
      operationId: schedule.updateLedgerEntry
      tags: [Schedule]
      summary: Update a ledger entry
      description: >
        Requires `ORG_ADMIN` or `UNIT_ADMIN`, and a unit admin only within
        their own unit. Sets the substitute, the delivery format, or the day's
        own geofence. A field left out, or sent as null, keeps its current
        value.
      parameters:
        - name: ledger_id
          in: path
          required: true
          schema:
            type: integer
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DailyLedgerUpdate"
      responses:
        "200":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: The entry was updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Updated
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The ledger entry, or the user named in `substitute_lead_id`, does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: >
            A malformed body, or a `substitute_lead_id` naming somebody who has been deactivated.
            A key reused with a different request is `IDEMPOTENCY_KEY_REUSED`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/schedule/staff/{staff_id}/location:
    get:
      operationId: schedule.getStaffLocation
      tags: [Schedule]
      summary: Resolve a staff member's current location via 4-tier resolver
      parameters:
        - name: staff_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Resolved location.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StaffLocationResponse"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/schedule/staff/all/locations:
    get:
      operationId: schedule.listStaffLocations
      tags: [Schedule]
      summary: Snapshot of all staff locations (Member Locator feed)
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: All staff locations.
          headers:
            X-Total-Count:
              $ref: "#/components/headers/XTotalCount"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/StaffLocationResponse"

  /api/v1/schedule/cycles:
    get:
      operationId: schedule.listCycles
      tags: [Schedule]
      summary: List planning cycles
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: Cycle list.
          headers:
            X-Total-Count:
              $ref: "#/components/headers/XTotalCount"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/PlanningCycleResponse"

    post:
      operationId: schedule.createCycle
      tags: [Schedule]
      summary: Create a new planning cycle
      description: >
        Requires `ORG_ADMIN`. The two dates are the days the cycle's slots
        run on, both included. An end earlier than the start is refused with
        422; equal dates are a cycle of one day.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PlanningCycleCreate"
      responses:
        "200":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: Cycle created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlanningCycleResponse"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

  /api/v1/schedule/cycles/{cycle_id}/close:
    patch:
      operationId: schedule.closeCycle
      tags: [Schedule]
      summary: Take a planning cycle out of service
      description: >
        Sets `operational_status = false`, so the nightly generator writes no
        more days for the cycle's slots, and removes the days it has already
        written from today onward, which are still only plans. A day that
        carries attendance or a note is kept rather than refused over. Days
        before today are not touched.


        Closing a cycle that is already closed runs the same sweep. Requires
        `ORG_ADMIN`.
      parameters:
        - name: cycle_id
          in: path
          required: true
          schema:
            type: integer
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: Cycle closed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Cycle 3 closed
                  ledger_rows_removed:
                    type: integer
                    description: Days from today onward that were withdrawn.
                  ledger_rows_kept:
                    type: integer
                    description: Days from today onward kept because they carry attendance or a note.
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

  /api/v1/schedule/cycles/{cycle_id}/open:
    patch:
      operationId: schedule.openCycle
      tags: [Schedule]
      summary: Put a drafted planning cycle into service
      description: >
        Sets `operational_status = true`, and it is the only thing that does.
        A cycle can be created closed, filled in over as long as that takes,
        and opened once it is ready.


        Not a flag flip. A slot entered into a closed cycle is never checked
        against the bookings or against the rest of the timetable, because a
        closed cycle's slots occupy nothing, and every one of them starts
        occupying its room the moment the flag goes true. The checks
        `POST /schedule/slots` would have run are run here over every slot in
        the cycle at once, the cycle's own slots counting against each other,
        and the whole open is refused where any of them lands on a room that
        is taken. A refused open writes nothing.


        Opening a cycle that is already open changes nothing. Requires
        `ORG_ADMIN`.
      parameters:
        - name: cycle_id
          in: path
          required: true
          schema:
            type: integer
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: Cycle opened, or already open.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Cycle 3 opened
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: A slot in the cycle would land on a room already taken.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CycleActivationConflict"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

  /api/v1/schedule/cycles/{old_id}/clone-to/{new_id}:
    post:
      operationId: schedule.cloneCycle
      tags: [Schedule]
      summary: Copy one cycle's activities and weekly slots into another
      description: >
        Copies every `Activity` in the old cycle and every
        `StructuralMasterSlot` under them, each slot pointed at its activity's
        copy with the same lead, room and window. Member enrollment and
        attendance records are **not** cloned. Re-import CSV after cloning to
        update enrollment. Retired activities and retired slots are left
        behind.


        The target must be closed and have no activities. The copied slots
        are not checked against the rooms here; opening the target runs those
        checks over all of them at once. Requires `ORG_ADMIN`.
      parameters:
        - name: old_id
          in: path
          required: true
          schema:
            type: integer
        - name: new_id
          in: path
          required: true
          schema:
            type: integer
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: Clone complete.
          content:
            application/json:
              schema:
                type: object
                properties:
                  cloned:
                    type: integer
                    description: Activities copied.
                  cloned_slots:
                    type: integer
                    description: Weekly slots copied.
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: The target cycle is open or already has activities.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

  # ── Attendance ────────────────────────────
  /api/v1/attendance/mark:
    post:
      operationId: attendance.mark
      tags: [Attendance]
      summary: Mark single member attendance
      description: >
        Members may only mark themselves. Anyone else must be the ledger's
        assigned or substitute lead, or an admin, and a UNIT_ADMIN only within
        their own unit. Same rule as `/attendance/batch`.
        A ledger that carries `latitude_target` and `longitude_target` is
        geo-fenced: a member must send `user_lat` and `user_lon`, and the
        backend checks Haversine surface distance against
        `precision_radius_meters`. `user_alt` is optional and only adds a
        floor check when the ledger also carries an `altitude_target`.
        Omitting the coordinates on a fenced session returns 400; there is no
        client-side way to skip the fence. When the member sends
        `user_accuracy`, a fix coarser than `GEOFENCE_ACCURACY_FACTOR` times
        the radius also returns 400.
        Marking a member again replaces their status rather than adding a
        second row.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AttendanceMarkRequest"
      responses:
        "200":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: Attendance marked.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: marked
                  member_id:
                    type: string
                  marking_status:
                    $ref: "#/components/schemas/VerificationMetric"
        "400":
          description: >
            Outside the geofence, or a fenced session marked without
            coordinates.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: No such ledger, or no such member.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

  /api/v1/attendance/batch:
    post:
      operationId: attendance.markBatch
      tags: [Attendance]
      summary: Batch mark attendance for multiple members
      description: >
        For whoever runs the session, on the same rule as
        `/attendance/mark`: the ledger's assigned or substitute lead, or an
        admin, and a UNIT_ADMIN only within their own unit. Every record must
        repeat the batch's `ledger_instance_id` and no member may appear
        twice, or the batch is refused with 422. A member id matching nobody
        is refused with 404. A refused batch writes nothing; an accepted one
        is written in one transaction.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AttendanceBatchRequest"
      responses:
        "200":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: Every record written.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: batch_complete
                  count:
                    type: integer
                    description: Records in the batch.
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: No such ledger, or a record names a member who does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: >
            A record names a different ledger from the batch, or one member
            appears twice.
            A key reused with a different request is `IDEMPOTENCY_KEY_REUSED`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/attendance/ledger/{ledger_id}:
    get:
      operationId: attendance.listForLedger
      tags: [Attendance]
      summary: Get the roster for a ledger entry
      description: >
        Whoever runs the session gets every row: the assigned lead, the
        substitute, an organization admin, or a unit admin inside that unit. A member
        gets their own row and nothing else. Anyone else is refused rather
        than handed an empty list.
      parameters:
        - name: ledger_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Attendance records.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/AttendanceResponse"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/attendance/absence:
    post:
      operationId: attendance.submitAbsence
      tags: [Attendance]
      summary: Submit an absence request (Reverse RSVP)
      description: >
        Any signed-in user whose account names a `reporting_line_manager` can
        submit one. The request is routed to that manager for approval, and
        the manager is sent an `ABSENCE_APPROVAL_REQUIRED` WebSocket frame.
        On approval, every daily ledger row the submitter leads on that date
        becomes `ON_LEAVE` and loses its substitute. Either decision sends the
        submitter an `ABSENCE_DECISION` frame.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReverseRsvpCreate"
      responses:
        "200":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: Absence request created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReverseRsvpResponse"
        "400":
          description: >
            The caller has no manager set, or the one set has been
            deactivated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

  /api/v1/attendance/absence/pending:
    get:
      operationId: attendance.listPendingAbsences
      tags: [Attendance]
      summary: List absence requests pending the caller's approval
      description: >
        Any signed-in user. Returns the undecided requests the caller may
        decide: those routed to them as the submitter's line manager and,
        for an admin, those whose manager has since been deactivated. A
        ORG_ADMIN gets every one of those, a UNIT_ADMIN those from the
        non-admin accounts of their own unit, and nobody gets their own.
      responses:
        "200":
          description: Pending requests.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ReverseRsvpResponse"

  /api/v1/attendance/absence/{log_id}/decide:
    patch:
      operationId: attendance.decideAbsence
      tags: [Attendance]
      summary: Approve or deny an absence request
      description: >
        The manager the request went to decides it or, once that manager is
        deactivated, an admin by the rules of the pending list. Whoever
        decides becomes `authorized_by_user_id` and can revisit the decision.
      parameters:
        - name: log_id
          in: path
          required: true
          schema:
            type: integer
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RsvpDecision"
      responses:
        "200":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: >
            Decision recorded. Approval turns the submitter's sessions that
            day `ON_LEAVE`, and either decision sends them an
            `ABSENCE_DECISION` WebSocket frame.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: "#/components/schemas/LogVerificationState"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: No such request, or not one the caller may decide.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

  /api/v1/attendance/annotations:
    post:
      operationId: attendance.createAnnotation
      tags: [Attendance]
      summary: Create a ledger annotation
      description: >
        Freeform notes about a session: lab issues, late starts, a handover.
        Restricted to whoever runs it, meaning the assigned lead, the
        substitute, an organization admin, or a unit admin inside that unit.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AnnotationCreate"
      responses:
        "200":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: Annotation created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AnnotationResponse"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

  /api/v1/attendance/annotations/{ledger_id}:
    get:
      operationId: attendance.listAnnotations
      tags: [Attendance]
      summary: Get all annotations for a ledger entry
      description: >
        The same gate as writing one. Unlike the roster there is no
        per-member fallback, because a note is about the session rather than
        about one person in it.
      parameters:
        - name: ledger_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Annotations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/AnnotationResponse"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

  # ── Guest Gate ────────────────────────────
  /api/v1/guest/register-checkin:
    post:
      operationId: guest.checkIn
      tags: [Guest Gate]
      summary: Register an organization visitor (kiosk)
      description: >
        The visitor does not authenticate; the kiosk device does, with an
        admin-issued API key in `X-API-Key`.
        Sends a `GUEST_HANDSHAKE_REQ` WebSocket frame to the target staff
        member. The kiosk and the visitor learn the decision from
        `/guest/visit/{code}`, with the code this response carries.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GuestCheckInRequest"
      responses:
        "200":
          description: Guest registered.
          content:
            application/json:
              schema:
                type: object
                properties:
                  registration_state:
                    type: string
                    example: PENDING_STAFF_AUTH
                  reference_token:
                    type: integer
                    description: The entry id that `/guest/{entry_id}/decide` takes.
                  visit_code:
                    type: string
                    example: 7KQM-3XHP-R9DW-4TNC
                    description: >
                      The visitor's code for `/guest/visit/{code}`. It is in
                      this response and nowhere else: the server keeps only
                      its hash.
        "404":
          description: Target staff not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/TooManyRequests"

  /api/v1/guest/directory:
    get:
      operationId: guest.getDirectory
      tags: [Guest Gate]
      summary: Staff availability directory (kiosk)
      description: >
        Returns active staff whose name matches, busy ones included, each with
        an availability label for kiosk display. Twenty at a time by default,
        in name order; X-Total-Count says how many matched.
        Requires a credential: this response carries the staff roster and each
        person's live presence.
      parameters:
        - name: name
          in: query
          schema:
            type: string
            minLength: 2
            maxLength: 100
          description: >
            Case-insensitive search by staff name. Two characters minimum, so
            the roster cannot be walked one letter at a time.
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          description: At most this many staff.
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: Matching staff.
          headers:
            X-Total-Count:
              $ref: "#/components/headers/XTotalCount"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/StaffAvailabilityResponse"

  /api/v1/guest/visit/{code}:
    get:
      operationId: guest.getVisit
      tags: [Guest Gate]
      summary: Follow a visit by its code (visitor)
      description: >
        No credential: the code the check-in returned is the credential.
        Case, spaces and dashes are ignored. The answer is the visit's status
        and nothing about who came or whom they came to see. Not rate
        limited: a code is about 79 bits, and a right guess shows only whether
        one unnamed visit was approved.
      security: []
      parameters:
        - name: code
          in: path
          required: true
          schema:
            type: string
          example: 7KQM-3XHP-R9DW-4TNC
      responses:
        "200":
          description: The visit's status.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GuestVisitStatus"
        "404":
          description: >
            No visit with that code, including one deleted under
            `GUEST_RETENTION_DAYS` and one past the window in
            `GUEST_VISIT_CODE_TTL_MINUTES`, which answers exactly as an
            unknown code does.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/guest/pending:
    get:
      operationId: guest.listPending
      tags: [Guest Gate]
      summary: List the pending guest requests this account may decide
      description: >
        Guests with PENDING_VERIFICATION status that this account may decide: the ones
        targeting it, and with GUEST_ADMIN_CAN_DECIDE on also those an admin may decide,
        which for an ORG_ADMIN is the whole organization's queue. Unpaginated.
      responses:
        "200":
          description: Pending guest requests.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/GuestResponse"

  /api/v1/guest/overstays:
    get:
      operationId: guest.listOverstays
      tags: [Guest Gate]
      summary: List the approved visits that have run past their end
      description: >
        Longest over first, which is the desk's other list: who was let in and
        has not been dealt with since. The same reach as the decision, so for an
        ORG_ADMIN with GUEST_ADMIN_CAN_DECIDE on it is the whole organization's.
        Nothing here has been revoked; each row says the time is up, and a person
        decides whether to extend it or to go and find them. Empty while
        GUEST_VISIT_LENGTH_MINUTES is 0, since then no visit has an end.
        Unpaginated, as /guest/pending is.
      responses:
        "200":
          description: Approved visits past their end.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/GuestResponse"

  /api/v1/guest/{entry_id}/decide:
    patch:
      operationId: guest.decide
      tags: [Guest Gate]
      summary: Accept or decline a guest visit
      parameters:
        - name: entry_id
          in: path
          required: true
          schema:
            type: integer
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GuestDecisionRequest"
      responses:
        "200":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: Decision recorded. The kiosk reads it from `/guest/visit/{code}`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: "#/components/schemas/LogVerificationState"
                  guest:
                    type: string
                    description: The visitor's name.
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: >
            No such entry, or the visitor asked for somebody else. By default only the
            staff member the visitor named may decide; with GUEST_ADMIN_CAN_DECIDE on an
            ORG_ADMIN may decide any visit and a UNIT_ADMIN those meant for their own unit.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

  /api/v1/guest/{entry_id}/extend:
    patch:
      operationId: guest.extendVisit
      tags: [Guest Gate]
      summary: Give an approved visit longer
      description: >
        Whoever could have decided the visit can extend it, on the reasoning that
        a desk which may let somebody in may also let them stay. The extension
        runs from whichever is later, now or the end the visit already has, so a
        visit half an hour over gets the full grant rather than a window that has
        already gone. There is no limit on how many times: this bounds one grant,
        and the audit record of each extension is what an organization gets in
        place of a ceiling on the whole visit.
      parameters:
        - name: entry_id
          in: path
          required: true
          schema:
            type: integer
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GuestExtensionRequest"
      responses:
        "200":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: The visit's new end.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: VISIT_EXTENDED
                  guest:
                    type: string
                    description: The visitor's name.
                  visit_expires_at:
                    type: string
                    format: date-time
                    description: When the visit is now over.
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: >
            No such entry, or one this account could not have decided either.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: >
            The visit is not approved, or it is approved with no end to move,
            which is any visit approved while GUEST_VISIT_LENGTH_MINUTES was 0.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: >
            Longer than GUEST_VISIT_EXTENSION_MAX_MINUTES, refused rather than
            quietly trimmed so that a desk which meant 30 and typed 300 hears
            about it. Also every extension when that setting is 0.
            A key reused with a different request is `IDEMPOTENCY_KEY_REUSED`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  # ── Ingestion ─────────────────────────────
  /api/v1/ingestion/upload-csv:
    post:
      operationId: ingestion.uploadCsv
      tags: [Ingestion]
      summary: Bulk import schedule from CSV
      description: >
        Requires `ORG_ADMIN`. The matrix rewrites activities and
        registrations across every unit, so a unit-scoped admin cannot
        upload it.
        The CSV must contain these columns (case-sensitive):
        `member_id`, `member_name`, `member_email`, `activity_code`, `activity_title`,
        `unit`, `day_of_week_index` (ISO 8601: 1=Monday .. 7=Sunday), `time_window_start` (HH:MM),
        `time_window_end` (HH:MM), `lead_id`, `room`.
        A row's weekday becomes the rule FREQ=WEEKLY;BYDAY=.. on its slot,
        starting on the first such date in the cycle.

        Creates/updates: Users, ActivityOfferings, StructuralMasterSlots, ActivityRegistrations.
        Idempotent, re-uploading the same CSV is safe: an existing member
        keeps their password.


        Removes nothing unless `remove_missing` is set. Slots and
        enrollments the file does not mention come back in `not_in_file` for
        somebody to act on, which is what makes a partial upload safe. With
        `remove_missing=true` the upload also removes exactly those, and
        reports what it removed in `removed` and what it could not remove in
        `not_removed`. They are the rows of this cycle, in the units the file
        names, that the file does not list; a unit the file does not name, or
        another cycle, is never touched. A slot goes the way
        `DELETE /schedule/slots/{id}` removes one: its days from today on are
        withdrawn and its past days stay. A slot with attendance or a note on
        a day ahead is left and listed in `not_removed` with the reason,
        and the rest of the import carries on. An enrollment goes the way
        `DELETE /schedule/activities/{id}/enrollments/{member_id}` removes
        one, and the attendance already recorded for the member stays. The
        removal is part of the import's transaction, and the rows are checked
        before the removal runs, so a row that needs a room a missing slot
        holds is refused: upload without the option first, or remove that
        slot yourself.


        A row that would put a class in a room already taken for that window,
        by a booking, by another class, or by a day already generated onto
        it, is refused with 422 and the whole file is rolled back, which is
        what every other bad row in an import does. Rows are checked against
        each other as well as against what is already stored, so one file
        cannot put two classes in one room at one hour. The check only looks
        where a row would actually move a class, so re-uploading a file that
        describes the timetable as it already stands is not refused by what
        is sitting on it.


        A closed cycle changes two of those three. Its slots occupy nothing,
        so an upload into one is not checked against the bookings or against
        the rest of the timetable, the same way a slot in a closed cycle does
        not block a booking. The days already generated are checked either
        way, because a correction is copied onto them whatever the cycle says
        and the database refuses to move one onto a room something else is
        holding.

        Each new member costs a bcrypt hash on the request thread, about
        half a second, so a file creating more than roughly 100 new
        members will exceed the 60s client and proxy timeouts. Split it.
      parameters:
        - name: cycle_id
          in: query
          required: true
          schema:
            type: integer
          description: Target planning cycle ID.
        - name: remove_missing
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: >
            Also remove the slots and enrollments the response lists in
            `not_in_file`. Off by default, and with it off the upload removes
            nothing and `removed` and `not_removed` come back empty.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
                  format: binary
      responses:
        "200":
          description: Import complete.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CsvImportResult"
        "400":
          description: The upload is not named `.csv`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "413":
          description: >
            The file is larger than `CSV_UPLOAD_MAX_MB` (25 MB unless the
            instance sets it), and nothing was imported. Behind the bundled
            nginx a request over 25 MB is refused by nginx itself, also with
            413 but with an HTML body.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: >
            The file was refused and nothing was saved. `detail` says why, and
            names the line where the file is at fault: a missing column, an
            unparseable time, an address already belonging to somebody else, a
            room already taken for that window, a lead who has no account, a
            member or lead who has been deactivated. Where the failure is the
            server's rather than the file's, `detail` says only that the import
            failed and that the reason is in the server log.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/ingestion/generate-ledger:
    post:
      operationId: ingestion.generateLedger
      tags: [Ingestion]
      summary: Trigger daily ledger generation
      description: >
        Requires `ORG_ADMIN`. Generates `DailyLedger` rows from
        `StructuralMasterSlot` for a given date, tomorrow by default. The
        same job the nightly cron runs. Safe to re-run: a day already written
        for a slot is skipped.


        A day is skipped as well where the room is already taken for part of
        that window by another day. Two slots on one room at one hour is a
        state the API refuses to create, and a database holding one anyway
        materializes the slot that was put on the timetable first and drops
        the other. The dropped day is written to the server log naming the
        slot, the date and the room. It is not in this response.
      parameters:
        - name: target_date
          in: query
          required: false
          description: Date to generate. Defaults to tomorrow.
          schema:
            type: string
            format: date
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: Generation complete.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: generated
                  date:
                    type: string
                    format: date
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

  # ── Admin ─────────────────────────────────
  /api/v1/admin/export:
    get:
      operationId: admin.export
      tags: [Admin]
      summary: The organization's data as one archive
      description: >
        Requires `ORG_ADMIN`; an API key needs `admin:read`. A zip holding
        `manifest.json` and one JSON Lines file per table, described in
        docs/portability.md, with the caller's organization's rows only.
        `chronos-engine export` writes every organization. Password hashes, API key hashes, calendar feed
        tokens and visit code hashes are always left out; an archive with them
        comes only from `chronos-engine export --include-secrets`. Refresh
        tokens and the signing key are never in it. Every export is written to
        the audit log, although it is a read. `chronos-engine import` loads the
        archive into an empty database.
      responses:
        "200":
          description: The archive, as an attachment named chronos-ledger-export.zip.
          content:
            application/zip:
              schema:
                type: string
                format: binary
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

  /api/v1/admin/organization:
    get:
      operationId: admin.getOrganization
      tags: [Admin]
      summary: The caller's organization and its settings
      description: Requires `ORG_ADMIN`; an API key needs `admin:read`.
      responses:
        "200":
          description: The organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrganizationResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
    patch:
      operationId: admin.updateOrganization
      tags: [Admin]
      summary: Change the organization's settings
      description: >
        Requires `ORG_ADMIN`; an API key needs `admin:write`. Today the one
        setting is `default_requirement_enforcement`, what a requirement with
        no enforcement of its own does. It applies from the next booking.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OrganizationUpdate"
      responses:
        "200":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: The organization as it now is.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrganizationResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

  # ── Calendar Sync ─────────────────────────
  /api/v1/audit/:
    get:
      operationId: audit.list
      tags: [Audit]
      summary: Writes made through the API, newest first
      description: >
        Requires `ORG_ADMIN`; an API key needs `audit:read`. One record per
        request under `/api/v1` with a method other than GET, HEAD or OPTIONS,
        and one per GET of the conflict report (`schedule.listConflicts`),
        including refused ones. Bodies are never stored. `from` and `to` are
        dates in the organization's timezone, both included.
      parameters:
        - name: from
          in: query
          required: false
          schema:
            type: string
            format: date
        - name: to
          in: query
          required: false
          schema:
            type: string
            format: date
        - name: actor_id
          in: query
          required: false
          schema:
            type: string
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: The records.
          headers:
            X-Total-Count:
              $ref: "#/components/headers/XTotalCount"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/AuditRecord"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

  /api/v1/changes/:
    get:
      operationId: changes.list
      tags: [Changes]
      summary: What has changed about the rooms and the bookings
      description: >
        Requires `ORG_ADMIN`; an API key needs `changes:read`. For a system
        that keeps its own copy of the rooms and the bookings: the websocket
        cannot tell it anything, because those notices go to a signed-in socket
        and a service behind another firewall has none, and re-reading every
        room on a timer costs the building rather than the change.


        One entry per row, not one per change. A room renamed to Bedroom and
        then to Living Room is one entry saying Living Room, because a consumer
        catching up wants where things ended and not the walk. `full=true`
        returns the walk: every marker, oldest first, with no row state.


        Send `next_cursor` back as `since`. An entry can arrive twice, after a
        crash between a write and the poll that read it, or because a row
        changed again while the page was being built; applying an entry is
        replacing a row with what the row already says, so no bookkeeping is
        needed for that.


        An entry can also be missed, which is the one thing to plan around.
        The cursor is the marker's own id, handed out when the row is inserted
        and not when it commits, so two writes that commit in the other order
        leave a gap: a poll that reads the later id and stores it does not come
        back for the earlier one. So re-read the rooms and the bookings in full
        on a slow timer. That is needed anyway, because the feed records only
        from the moment it was switched on.


        A page as long as `limit` means there is probably more, so poll again
        rather than waiting for the timer.


        The role is higher than reading the rooms takes because a booking
        carries what it is for, which the availability calendar withholds from
        everyone but the account that made it. This hands the booking over
        whole, so it sits where the audit log sits.
      parameters:
        - name: since
          in: query
          required: false
          description: The cursor the last poll returned. 0 is from the beginning.
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: limit
          in: query
          required: false
          description: At most this many entries.
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 200
        - name: full
          in: query
          required: false
          description: >
            Every marker rather than one entry per row, and no row state.
          schema:
            type: boolean
            default: false
      responses:
        "200":
          description: >
            The changes, oldest first, and the cursor to send next time. Empty
            with the cursor handed back unchanged when nothing has changed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChangeFeed"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "503":
          description: >
            The feed is off, which is the default. `CHANGE_FEED_ENABLED=true`
            starts recording; changes made while it was off were not recorded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  # ── Webhooks ──────────────────────────────
  /api/v1/webhooks/:
    get:
      operationId: webhooks.list
      tags: [Webhooks]
      summary: List webhook subscriptions
      description: >
        Requires `ORG_ADMIN`; an API key needs `webhooks:read`. Every
        subscription, oldest first, without its secrets. docs/webhooks.md
        describes what is sent, how it is signed and how failures are retried.
      responses:
        "200":
          description: Every subscription.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/WebhookResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

    post:
      operationId: webhooks.create
      tags: [Webhooks]
      summary: Subscribe a URL to changes
      description: >
        Requires `ORG_ADMIN`; an API key needs `webhooks:write`. Events are
        made from the change feed, so the feed has to be on. The subscription
        starts at the newest change and is sent nothing that happened before
        it existed: read the rooms and the bookings in full once, as a change
        feed consumer does.


        The signing secret is in the response and nowhere else. An
        Idempotency-Key is ignored here, because keeping the response would
        keep the secret.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WebhookCreate"
      responses:
        "201":
          description: Subscribed. The `secret` field will not be shown again.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookWithSecret"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          description: >
            `WEBHOOK_URL_REFUSED` for a URL that may not receive webhooks
            (not HTTPS, an internal address, credentials in the URL), or
            `VALIDATION_FAILED` for an unknown event type.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "503":
          description: The change feed is off, so there would be nothing to send.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/webhooks/{subscription_id}:
    get:
      operationId: webhooks.get
      tags: [Webhooks]
      summary: Get a webhook subscription
      description: Requires `ORG_ADMIN`; an API key needs `webhooks:read`.
      parameters:
        - name: subscription_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: The subscription, without its secrets.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

    patch:
      operationId: webhooks.update
      tags: [Webhooks]
      summary: Change a webhook subscription
      description: >
        Requires `ORG_ADMIN`; an API key needs `webhooks:write`. New event
        types apply to changes fanned out from now on. Switched off, a
        subscription keeps its place and sends nothing; switched back on, it
        sends what happened in between.
      parameters:
        - name: subscription_id
          in: path
          required: true
          schema:
            type: integer
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WebhookUpdate"
      responses:
        "200":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: The updated subscription.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          description: >
            `WEBHOOK_URL_REFUSED` for a URL that may not receive webhooks, or
            `VALIDATION_FAILED` for an unknown event type.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

    delete:
      operationId: webhooks.delete
      tags: [Webhooks]
      summary: Delete a webhook subscription
      description: >
        Requires `ORG_ADMIN`; an API key needs `webhooks:write`. Stops
        sending at once and removes the subscription with its deliveries and
        their attempts.
      parameters:
        - name: subscription_id
          in: path
          required: true
          schema:
            type: integer
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "204":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: Deleted.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/webhooks/{subscription_id}/rotate-secret:
    post:
      operationId: webhooks.rotateSecret
      tags: [Webhooks]
      summary: Issue a new signing secret
      description: >
        Requires `ORG_ADMIN`; an API key needs `webhooks:write`. The new
        secret is in the response and nowhere else. The old one keeps signing
        alongside it for 24 hours, or until it is removed, so every send in
        that time carries two signatures and receivers can switch over at
        their own pace. An Idempotency-Key is ignored here, for the reason it
        is on create.
      parameters:
        - name: subscription_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Rotated. The `secret` field will not be shown again.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookWithSecret"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: >
            `WEBHOOK_SECRET_LIMIT`: two secrets are already live. Remove the
            previous one first.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/webhooks/{subscription_id}/previous-secret:
    delete:
      operationId: webhooks.removePreviousSecret
      tags: [Webhooks]
      summary: Stop signing with the previous secret
      description: >
        Requires `ORG_ADMIN`; an API key needs `webhooks:write`. For when
        every receiver has moved to the new secret before the 24 hours are
        up. Nothing to remove is not an error.
      parameters:
        - name: subscription_id
          in: path
          required: true
          schema:
            type: integer
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "204":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: Only the current secret signs now.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/webhooks/{subscription_id}/resume:
    post:
      operationId: webhooks.resume
      tags: [Webhooks]
      summary: Resume a paused subscription
      description: >
        Requires `ORG_ADMIN`; an API key needs `webhooks:write`. Clears the
        pause and the failure count. Nothing is skipped: what changed while it
        was paused is sent, oldest first. Resuming one that is not paused
        changes nothing.
      parameters:
        - name: subscription_id
          in: path
          required: true
          schema:
            type: integer
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: The subscription, no longer paused.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/webhooks/{subscription_id}/deliveries:
    get:
      operationId: webhooks.listDeliveries
      tags: [Webhooks]
      summary: What was sent and what came back
      description: >
        Requires `ORG_ADMIN`; an API key needs `webhooks:read`. Deliveries
        newest first, each with every attempt made at it.
      parameters:
        - name: subscription_id
          in: path
          required: true
          schema:
            type: integer
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: Deliveries, newest first.
          headers:
            X-Total-Count:
              $ref: "#/components/headers/XTotalCount"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/WebhookDeliveryResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/webhooks/{subscription_id}/deliveries/{delivery_id}/redeliver:
    post:
      operationId: webhooks.redeliver
      tags: [Webhooks]
      summary: Send a delivery again
      description: >
        Requires `ORG_ADMIN`; an API key needs `webhooks:write`. The delivery
        goes back in the queue with a fresh set of attempts and is sent on the
        worker's next pass, with the same `webhook-id` and body and a new
        timestamp and signature.
      parameters:
        - name: subscription_id
          in: path
          required: true
          schema:
            type: integer
        - name: delivery_id
          in: path
          required: true
          schema:
            type: integer
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "202":
          headers:
            Idempotency-Replayed:
              $ref: "#/components/headers/IdempotencyReplayed"
          description: Queued.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookDeliveryResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/sync/feed-token:
    get:
      operationId: sync.getFeedToken
      tags: [Calendar Sync]
      summary: Get the caller's calendar feed token
      description: >
        Returns the token that keys the caller's iCalendar feed, minting one on
        the first call. `feed_path` is the path to subscribe, already built from
        the token. The token is the only thing guarding the feed, so hand it out
        the way a password is handed out.
      responses:
        "200":
          description: The feed token and the path built from it.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FeedToken"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/v1/sync/feed-token/rotate:
    post:
      operationId: sync.rotateFeedToken
      tags: [Calendar Sync]
      summary: Replace the caller's calendar feed token
      description: >
        Mints a new token and invalidates the old one. Every calendar app
        subscribed to the old path stops updating and has to be resubscribed,
        which is the point: this is what to call when a feed URL has leaked.
      responses:
        "200":
          description: The new feed token and the path built from it.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FeedToken"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/v1/sync/user-feed/{feed_token}.ics:
    get:
      operationId: sync.getFeed
      tags: [Calendar Sync]
      summary: iCalendar feed for a user (rolling 37-day window)
      description: >
        Subscribe this URL directly in Google Calendar, Apple Calendar, or Outlook.
        Returns standard iCalendar (text/calendar) content.
        Staff feed includes all sessions where they are active or substitute lead.
        Member feed includes all registered activities.
        Timed sessions are written as UTC instants (DTSTART and DTEND end in Z),
        converted from the organization's wall clock through ORG_TIMEZONE, so a
        subscriber reading the feed from anywhere sees the session at the moment
        it happens. An entry with no window of its own is an all-day date and
        carries no zone, because a date reads the same everywhere. That is an
        ad-hoc day nobody gave a time to, or a day generated before the ledger
        carried its own window.
      parameters:
        - name: feed_token
          in: path
          required: true
          schema:
            type: string
          description: >
            The token from `GET /api/v1/sync/feed-token`, not a user id. The
            feed itself is unauthenticated so a calendar app can poll it, which
            leaves the token as the only thing guarding it.
      responses:
        "200":
          description: iCalendar feed.
          content:
            text/calendar:
              schema:
                type: string
                example: "BEGIN:VCALENDAR\nVERSION:2.0\n..."
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"

  # ── WebSocket ─────────────────────────
  /api/v1/ws/stats:
    get:
      operationId: ws.getStats
      tags: [WebSocket]
      summary: Count of people with an open websocket, on every instance
      description: >
        Requires `ORG_ADMIN`. The count is of the caller's organization, and
        there is nothing in it a unit admin could be shown only their own
        share of. A person counts once however many instances they are connected to. The
        other instances' figures can be up to 15 seconds old, and an instance
        that cannot reach Redis counts only its own sockets.
      responses:
        "200":
          description: Open connection count.
          content:
            application/json:
              schema:
                type: object
                properties:
                  online_connections:
                    type: integer
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  # ── Health ────────────────────────────────
  /health:
    get:
      operationId: health.check
      tags: [System]
      summary: Health check
      security: []
      description: >
        Liveness: answers without touching the database. Also names the
        running release and the version of the schema its models describe.
      responses:
        "200":
          description: Healthy.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: healthy
                  service:
                    type: string
                    example: chronos-ledger
                  version:
                    type: string
                    example: "0.13.0"
                  schema_version:
                    type: string
                    example: "1"
                    description: >
                      Bumped by the maintainers when the models change. There
                      are no migrations: a database built by one schema
                      version is not upgraded to the next.

  /health/ready:
    get:
      operationId: health.ready
      tags: [System]
      summary: Readiness check
      security: []
      description: >
        Runs `SELECT 1` against PostgreSQL and pings Redis. Fails with 503 only
        when PostgreSQL does not answer: without Redis the app keeps working,
        so Redis being down is reported but still ready. The container
        healthchecks use this route.
      responses:
        "200":
          description: Ready.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Readiness"
        "503":
          description: PostgreSQL did not answer.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Readiness"

# ─────────────────────────────────────────────
# WebSocket (informational, not an HTTP path)
# ─────────────────────────────────────────────
# WebSocket endpoint: ws://<server>/ws
#
# The server accepts the socket, then waits five seconds for one frame naming
# the token:
#
#   { "event": "AUTH", "payload": { "token": "<jwt>" } }
#
# It answers { "event": "AUTHENTICATED", "payload": {} } and begins routing
# domain events to this client. A refused token closes with 4003; silence past
# the five seconds closes with 4008. The token is checked the way an HTTP
# request's is, so one naming an account that is gone, or an admin who has not
# chosen a password yet, is refused here too.
#
# Not a query parameter on purpose: a query string lands in the proxy's access
# log and the browser's history, and is sent onward as a Referer.
#
# Inbound frames (server → client):
#
#   { "event": "ABSENCE_APPROVAL_REQUIRED",
#     "payload": { "log_id": 12, "from": "Prof. A", "date": "2026-06-15" } }
#
#   { "event": "ABSENCE_DECISION",
#     "payload": { "log_id": 12, "decision": "VERIFIED_APPROVED" } }
#
#   { "event": "GUEST_HANDSHAKE_REQ",
#     "payload": { "transaction_reference": 5, "guest_name": "J. Smith",
#                  "organization": "TechCorp", "intent": "..." } }
#
#   { "event": "GUEST_VISIT_EXPIRED",
#     "payload": { "transaction_reference": 5, "guest_name": "J. Smith",
#                  "visit_expires_at": "2026-09-12T07:31:07Z" } }
#   Sent once per overrun, within five minutes of the end passing, to the
#   target staff and to whoever decided the visit. GET /guest/overstays is
#   the same list for a desk that had no socket open at the time.
#
# The AUTH frame is the only thing a client sends upstream.