openapi: 3.0.3
info:
  title: Human Seed API
  description: |
    Async gateway for human-readable multidimensional profile synthesis.

    The public report promotes verified facts from Western Astrology, Chinese BaZi,
    and Human Design, then adds a long-form `profile_narrative` for readable
    person-level interpretation. Public responses keep raw engine output private by
    default. During development, append `debug=1` to compose/status requests to get
    `_debug` diagnostics; append `raw=1` and provide a valid API key to include raw
    engine payloads for inspection.
  version: 1.21.0
servers:
  - url: https://4ura.de/api
    description: Production API root
  - url: http://h0.tail099aa2.ts.net/dev/4ura/dev-ops/api
    description: h0menode dev-ops branch API root
  - url: http://h0.tail099aa2.ts.net/dev/4ura/main/api
    description: Shared h0menode main branch API root

tags:
  - name: Compose
    description: Queue and poll multidimensional profile synthesis.
  - name: Match
    description: Compare already calculated Human Seed profiles for contextual fit.
  - name: Geocode
    description: Verified birth-city search and coordinate resolution.
  - name: Visuals
    description: Route-backed deterministic and generated image assets.
  - name: Observability
    description: Health, degradation, and debug surfaces.
  - name: Persistence
    description: Protected seed-first persistence verification.
  - name: Chain Connectors
    description: Standard bridges for interoperability with external engines (e.g. OSINT Owl).
  - name: Avatar Generation
    description: Dynamic neon holographic and TMNT archetype avatar generation.
  - name: Admin
    description: Administrative control plane for tenancy lifecycle, analytics, and GDPR compliance.
  - name: Identity
    description: Public and internal handle resolution endpoints.
  - name: Maintenance
    description: Diagnostic replays, backfills, telemetry capture, and localized lore lookup.

paths:
  /mcp:
    post:
      tags: [Identity]
      operationId: personalMcpRequest
      summary: Read your saved reports through MCP
      description: |
        Available only when optional stable accounts are enabled; otherwise 404.
        Streamable HTTP with the personal profile key in X-4ura-API-Key, without
        browser cookies, Bearer/query credentials or automatic OAuth enrollment.
        Send one JSON-RPC message per POST; JSON-RPC batches are refused.
        Accept must include application/json and text/event-stream. The published
        2025-11-25 protocol is supported; subsequent requests carry MCP-Protocol-Version.

        Read-only tools: 4ura_list_reports, 4ura_read_report and 4ura_usage.
        Report ownership is selected from the admitted key, never caller arguments.
        Explicit methodology reads may contain the owner's birth data. There is no
        public/cache fallback, calculation/image generation or LLM invocation.

        REST and MCP share 100 admitted requests/account/UTC day, including
        initialization, notifications, discovery, calls and admitted errors.
        Independent minute limits still apply. Rotation does not reset usage.
        Invalid keys, refused Origin and oversized input do not spend daily usage.
        GET and DELETE return 405 after valid personal-key admission; no persistent
        transport session or standalone SSE stream is created.
      security:
        - PersonalApiKeyAuth: []
      parameters:
        - in: header
          name: Accept
          required: true
          schema: { type: string, example: 'application/json, text/event-stream' }
        - in: header
          name: MCP-Protocol-Version
          required: false
          schema: { type: string, example: '2025-11-25' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [jsonrpc, method]
              properties:
                jsonrpc: { type: string, enum: ['2.0'] }
                id: { oneOf: [{ type: string }, { type: integer }] }
                method: { type: string, example: tools/list }
                params: { type: object, additionalProperties: true }
      responses:
        '200':
          description: MCP JSON-RPC result or protocol/tool error; private, no-store.
          headers:
            X-4ura-API-Daily-Limit:
              schema: { type: integer, enum: [100] }
            X-4ura-API-Daily-Remaining:
              schema: { type: integer, minimum: 0, maximum: 99 }
            X-4ura-API-Daily-Reset:
              schema: { type: string, format: date-time }
          content:
            application/json:
              schema: { type: object, additionalProperties: true }
        '202': { description: Accepted notification; no body. }
        '400': { description: Invalid JSON-RPC, batch or unsupported protocol. }
        '401': { description: Personal key required; no session or tenant fallback. }
        '403': { description: Invalid/ambiguous key or refused Origin. }
        '404': { description: MCP not enabled on this runtime. }
        '405': { description: Only POST is supported. }
        '406': { description: Required Accept media types missing. }
        '413': { description: Body exceeds 64 KiB. }
        '415': { description: Content-Type must be application/json. }
        '429': { description: Shared daily API allowance or independent minute throttle exceeded. }
        '503': { description: Admission/persistence dependency unavailable; no cached authority fallback. }
  /compose:
    post:
      tags: [Compose]
      summary: Queue a Human Seed profile synthesis
      operationId: composeHologram
      description: |
        `birth_time` is optional. When it is missing or empty the run is composed under
        the untimed contract: `birth_time_known` becomes `false`, `seed_context.time` is
        `null`, and everything that depends on the time of day is withheld instead of
        being derived from a substituted time. See `ComposeRequest.seed_profile` and the
        `UntimedContract` schema.

        Identical submits are deduplicated. When a resolved run already exists for the
        same seed fingerprint and the same language, and it is younger than the reuse
        window (`FOURA_SEED_REUSE_TTL_DAYS`, default 30 days), its hash is returned with
        `reused: true` instead of starting a second compute. The response is still `202`,
        so a client needs no special handling: the very first poll answers `200`.
      parameters:
        - $ref: '#/components/parameters/DebugQuery'
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ComposeRequest'
            examples:
              timed:
                summary: Birth time known
                value:
                  seed_profile:
                    birth_date: "1987-03-18"
                    birth_time: "22:22"
                    birth_city: "Regensburg, Bayern, Deutschland"
                    birth_coords:
                      lat: 49.01343
                      lng: 12.10162
                    timezone: Europe/Berlin
                    gender: female
                  orchestration_options:
                    language: en
                    priority: standard
                    lenses: [personal]
              untimed:
                summary: Birth time unknown - no time is sent at all
                value:
                  seed_profile:
                    birth_date: "1987-03-18"
                    birth_time_known: false
                    birth_city: "Regensburg, Bayern, Deutschland"
                    birth_coords:
                      lat: 49.01343
                      lng: 12.10162
                    timezone: Europe/Berlin
                    gender: female
                  orchestration_options:
                    language: en
                    priority: standard
                    lenses: [personal]
      responses:
        '202':
          description: Accepted. Poll the returned hash until status returns 200.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComposeAcceptedResponse'
        '400':
          description: |
            Invalid seed, timezone, or local birth moment. A missing `birth_time` is no
            longer a 400 - it selects the untimed contract.
            Optional `seed_profile.birth_time_range` requires explicit dated start/end
            clocks and a verified IANA zone. Malformed, reversed, over-24-hour, gap,
            ambiguous-without-occurrence and contradictory exact/range inputs return
            400. A misplaced request-root range remains invalid. Nonzero intervals
            never select a representative personal chart; separate recorded comparison
            evidence is available through explicit full-method reads.

  /compose/status/{hash}:
    get:
      tags: [Compose]
      summary: Poll synthesis status by hash
      operationId: getHologramStatus
      parameters:
        - $ref: '#/components/parameters/HashPath'
        - name: lang
          in: query
          required: false
          schema:
            type: string
            enum: [en, de]
          description: Response language for finalized copy.
        - $ref: '#/components/parameters/DebugQuery'
        - $ref: '#/components/parameters/RawQuery'
        - name: apikey
          in: query
          required: false
          schema:
            type: string
          description: Optional API key for raw debug output. Prefer the `X-4ura-API-Key` header.
      responses:
        '200':
          description: Completed public report. `_debug` appears only when `debug=1`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComposeResponse'
        '202':
          description: Job is still processing. Returned only while a run is genuinely in flight.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComposeAcceptedResponse'
        '404':
          description: No run exists for this hash (never composed, evicted, or deleted - a soft-deleted run answers exactly like an unknown hash). Clients must stop polling.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusNotFoundResponse'
        '500':
          description: The run ended in a terminal failure (orchestration error, timeout, failed fallback, or a run interrupted by a restart). The message is plain language in the requested `lang`; no diagnostics are exposed. Clients must stop polling and may start a new analysis.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusFailedResponse'

        '503':
          description: Report storage is temporarily unavailable and no usable cached report exists. Retry within a bounded client deadline; this does not mean a calculation is processing.
          headers:
            Retry-After:
              schema:
                type: integer
              description: Minimum delay in seconds before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusUnavailableResponse'

  /status/{hash}:
    get:
      tags: [Compose]
      summary: Compatibility alias for `/compose/status/{hash}`
      operationId: getHologramStatusAlias
      parameters:
        - $ref: '#/components/parameters/HashPath'
        - $ref: '#/components/parameters/DebugQuery'
        - $ref: '#/components/parameters/RawQuery'
      responses:
        '200':
          description: Completed public report.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComposeResponse'
        '202':
          description: Job is still processing.
        '404':
          description: No run exists for this hash (never composed, or deleted).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusNotFoundResponse'
        '500':
          description: Terminal failure of the run; see `/compose/status/{hash}`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusFailedResponse'

        '503':
          description: Report storage is temporarily unavailable and no usable cached report exists. Retry within a bounded client deadline; this does not mean a calculation is processing.
          headers:
            Retry-After:
              schema:
                type: integer
              description: Minimum delay in seconds before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusUnavailableResponse'

  /status/{hash}/methods:
    get:
      tags: [Compose]
      summary: Index of the methodologies behind a report
      operationId: getMethodologyIndex
      description: |
        One row per methodology, saying what it is, how real it is, whether a full
        document exists for it and where that document lives.

        Same contract as `/status/{hash}`: no API key (a trusted browser origin or
        Tailscale caller is enough), the same `status` rate-limit bucket, and the same
        four terminal answers. `?lang` resolves every label; without it the language the
        run was composed in is used.
      parameters:
        - $ref: '#/components/parameters/HashPath'
        - $ref: '#/components/parameters/LangQuery'
      responses:
        '200':
          description: The index. Carries an `ETag`; a conditional request answers `304`.
          headers:
            ETag: { $ref: '#/components/headers/MethodsETag' }
            Cache-Control: { $ref: '#/components/headers/MethodsCacheControl' }
            Content-Language: { $ref: '#/components/headers/MethodsContentLanguage' }
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MethodologyIndex'
              example:
                schema_version: "1.1.7"
                hash: "cf44b388063aa169569edc61"
                language: en
                birth_time_known: true
                engine_version: repo-owned-deterministic/2.1.0
                deterministic_matrix_status: ok
                generated_at: "2026-09-04T19:34:41.512Z"
                methods:
                  - key: western
                    label: Western Astrology
                    slug: western
                    aliases: []
                    requested: true
                    status: available
                    evidence_tier: computed
                    evidence_tier_label: computed
                    evidence_note: These values are computed from your birth moment.
                    contribution_factor: 1
                    confidence: 0.92
                    weight: 1.18
                    birth_time_known: true
                    available: true
                    unavailable_reason: null
                    data_completeness: complete
                    data_completeness_label: Complete
                    engine_version: repo-owned-deterministic/2.1.0
                    href: /api/status/cf44b388063aa169569edc61/methods/western?lang=en
        '304':
          description: The document has not changed since the `ETag` the client presented.
        '202':
          description: The run is still composing.
        '404':
          description: No run exists for this hash.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusNotFoundResponse'
        '500':
          description: Terminal failure of the run.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusFailedResponse'

        '503':
          description: Report storage is temporarily unavailable and no usable cached report exists. Retry within a bounded client deadline; this does not mean a calculation is processing.
          headers:
            Retry-After:
              schema:
                type: integer
              description: Minimum delay in seconds before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusUnavailableResponse'

  /status/{hash}/methods/western:
    get:
      tags: [Compose]
      summary: The complete Western chart
      operationId: getWesternMethodology
      description: |
        Every placement the engine computed (Sun through Pluto plus the mean lunar node
        and, on a timed run, the ascendant) with its sign, ecliptic longitude, degree
        inside the sign, house, retrograde flag and daily motion; the four angles; the
        twelve house cusps carrying the bilingual house title and life theme; every
        aspect with its orb and whether it is applying; and the element and modality
        balance.

        Untimed runs have no ascendant, so `angles`, `houses` and `aspects` are `null`
        or empty, `placements[].house` is `null`, and the day-level uncertainties the
        engine reports (a Moon that changes sign on the birth day, an inner planet that
        does the same) are published under `uncertainty` rather than smoothed over.

        Runs stored before the engine rebuild answer with what they have and report
        `data_completeness: stub_era` instead of failing.
      parameters:
        - $ref: '#/components/parameters/HashPath'
        - $ref: '#/components/parameters/LangQuery'
      responses:
        '200':
          description: The complete Western chart.
          headers:
            ETag: { $ref: '#/components/headers/MethodsETag' }
            Cache-Control: { $ref: '#/components/headers/MethodsCacheControl' }
            Content-Language: { $ref: '#/components/headers/MethodsContentLanguage' }
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WesternMethodology'
              example:
                schema_version: "1.1.7"
                hash: "cf44b388063aa169569edc61"
                method: western
                label: Westliche Astrologie
                language: de
                status: available
                birth_time_known: true
                evidence_tier: computed
                data_completeness: complete
                engine_version: repo-owned-deterministic/2.1.0
                generated_at: "2026-09-04T19:34:41.512Z"
                provenance:
                  calculation_engine: astronomy-engine
                  calculation_engine_version: "2.1.19"
                  calculation_time_utc: "1987-03-18T21:22:00.000Z"
                  deterministic_matrix_status: ok
                chart:
                  sun_sign: { key: pisces, label: Fische }
                  moon_sign: { key: scorpio, label: Skorpion }
                  rising_sign: { key: scorpio, label: Skorpion }
                  ascendant_longitude: 222.294595
                  obliquity_degrees: 23.443578
                  house_system: { key: placidus, label: Placidus }
                  time_reference: { key: birth_time, label: Angegebene Geburtszeit }
                placements:
                  - body: { key: sun, label: Sonne }
                    sign: { key: pisces, label: Fische }
                    longitude: 357.743065
                    degree_in_sign: 27.7431
                    house: 4
                    retrograde: false
                    speed_deg_per_day: 0.994424
                angles:
                  mc:
                    key: mc
                    label: Medium Coeli
                    longitude: 146.261155
                    sign: { key: leo, label: Löwe }
                    degree_in_sign: 26.2612
                houses:
                  system: { key: placidus, label: Placidus }
                  anchor: mc
                  fallback_reason: null
                  cusps:
                    - house: 1
                      label: 1st House
                      longitude: 222.294595
                      sign: { key: scorpio, label: Skorpion }
                      degree_in_sign: 12.2946
                      title: Selbst und Auftreten
                      life_theme: "Identität, Verkörperung, erster Eindruck, persönliche Initiative"
                      angularity: angular
                      quadrant: self_development
                aspects:
                  - bodies:
                      - { key: venus, label: Venus }
                      - { key: mars, label: Mars }
                    type: { key: square, label: Quadrat }
                    angle: 90
                    orb: 0.3507
                    orb_allowed: 7
                    applying: false
                element_scores:
                  - { key: water, label: Wasser, value: 58.97 }
                modality_scores:
                  - { key: fixed, label: Fix, value: 58.97 }
        '304':
          description: The document has not changed since the `ETag` the client presented.
        '202':
          description: The run is still composing.
        '404':
          description: No run exists for this hash.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusNotFoundResponse'
        '500':
          description: Terminal failure of the run.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusFailedResponse'

        '503':
          description: Report storage is temporarily unavailable and no usable cached report exists. Retry within a bounded client deadline; this does not mean a calculation is processing.
          headers:
            Retry-After:
              schema:
                type: integer
              description: Minimum delay in seconds before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusUnavailableResponse'

  /status/{hash}/methods/bazi:
    get:
      tags: [Compose]
      summary: The complete BaZi chart (alias `/methods/chinese`)
      operationId: getBaziMethodology
      description: |
        The four pillars with their heavenly stem and earthly branch (romanization plus
        the Chinese character), each with its element, polarity and animal; the hidden
        stems of every branch with their weights; the ten gods per pillar; the weighted
        five-element counts and shares with the basis they were counted on; the day
        master with its strength label and the arithmetic behind that strength; the
        solar terms that fix the year and month boundaries; the boundary-sensitivity
        flags; `eight_char`; and the luck cycles.

        `luck_cycles.stretch` is always `true`: the cycles are a projection from a
        boundary distance, not an observation, and the flag says so. They are absent
        with `available: false` and a reason when the run states no gender or the
        boundary could not be resolved.

        Untimed runs report `pillars.hour: null` with `hour_pillar_reason:
        birth_time_unknown`; the `hour` key of `hidden_stems` and `ten_gods` is absent
        and the element counts are computed over three pillars. A run stored before the
        engine rebuild reports `hour_pillar_reason: stub_era_payload` instead, because
        its birth time was known and only the pillar is missing.

        The same document is served under `/status/{hash}/methods/chinese`.
      parameters:
        - $ref: '#/components/parameters/HashPath'
        - $ref: '#/components/parameters/LangQuery'
      responses:
        '200':
          description: The complete BaZi chart.
          headers:
            ETag: { $ref: '#/components/headers/MethodsETag' }
            Cache-Control: { $ref: '#/components/headers/MethodsCacheControl' }
            Content-Language: { $ref: '#/components/headers/MethodsContentLanguage' }
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaziMethodology'
              example:
                schema_version: "1.1.7"
                hash: "cf44b388063aa169569edc61"
                method: bazi
                label: Chinesisches BaZi
                language: de
                evidence_tier: computed
                data_completeness: complete
                day_master:
                  element: { key: fire, label: Feuer }
                  stem: Ding
                  stem_hanzi: 丁
                  polarity: { key: yin, label: Yin }
                  strength: { key: developing, label: Im Aufbau }
                  strength_score: 0.412
                  strength_method: heuristic
                year_animal: { key: rabbit, label: Hase }
                pillars:
                  year:
                    role: year
                    role_label: Jahressäule
                    available: true
                    hanzi: 丁卯
                    stem:
                      romanization: Ding
                      hanzi: 丁
                      element: { key: fire, label: Feuer }
                      polarity: { key: yin, label: Yin }
                    branch:
                      romanization: Mao
                      hanzi: 卯
                      element: { key: wood, label: Holz }
                      animal: { key: rabbit, label: Hase }
                    sexagenary_index: 3
                  hour: null
                eight_char: 丁卯 癸卯 丙寅
                hour_pillar_available: false
                hour_pillar_reason: birth_time_unknown
                element_shares:
                  - { key: fire, label: Feuer, value: 31.2 }
                luck_cycles:
                  available: false
                  stretch: true
                  reason: gender_unknown
        '304':
          description: The document has not changed since the `ETag` the client presented.
        '202':
          description: The run is still composing.
        '404':
          description: No run exists for this hash.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusNotFoundResponse'
        '500':
          description: Terminal failure of the run.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusFailedResponse'

        '503':
          description: Report storage is temporarily unavailable and no usable cached report exists. Retry within a bounded client deadline; this does not mean a calculation is processing.
          headers:
            Retry-After:
              schema:
                type: integer
              description: Minimum delay in seconds before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusUnavailableResponse'

  /status/{hash}/methods/chinese:
    get:
      tags: [Compose]
      summary: Alias for `/status/{hash}/methods/bazi`
      operationId: getChineseMethodologyAlias
      parameters:
        - $ref: '#/components/parameters/HashPath'
        - $ref: '#/components/parameters/LangQuery'
      responses:
        '200':
          description: The complete BaZi chart; identical to `/status/{hash}/methods/bazi`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaziMethodology'
        '404':
          description: No run exists for this hash.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusNotFoundResponse'

        '503':
          description: Report storage is temporarily unavailable and no usable cached report exists. Retry within a bounded client deadline; this does not mean a calculation is processing.
          headers:
            Retry-After:
              schema:
                type: integer
              description: Minimum delay in seconds before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusUnavailableResponse'

  /status/{hash}/methods/human-design:
    get:
      tags: [Compose]
      summary: The complete Human Design bodygraph (alias `/methods/hd`)
      operationId: getHumanDesignMethodology
      description: |
        Type, strategy, authority with its `authority_detail`, profile, definition, all
        nine centers (defined or not, each with the activated gates that belong to it
        and the full gate set of that center), the channels, both activation sets
        (thirteen bodies each with gate, line and ecliptic longitude), the design instant
        (the Sun 88 degrees of solar arc before birth), the incarnation cross, the
        not-self theme and the signature.

        A bodygraph needs two exact instants. An untimed run therefore answers **422**
        with `reason: birth_time_unknown`, exactly as `GET /api/render/hd` does, rather
        than returning a half-drawn chart. `/status/{hash}/methods` announces this in
        advance: the Human Design row carries `available: false` with the same reason.

        The same document is served under `/status/{hash}/methods/hd`.
      parameters:
        - $ref: '#/components/parameters/HashPath'
        - $ref: '#/components/parameters/LangQuery'
      responses:
        '200':
          description: The complete bodygraph.
          headers:
            ETag: { $ref: '#/components/headers/MethodsETag' }
            Cache-Control: { $ref: '#/components/headers/MethodsCacheControl' }
            Content-Language: { $ref: '#/components/headers/MethodsContentLanguage' }
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanDesignMethodology'
              example:
                schema_version: "1.1.7"
                hash: "cf44b388063aa169569edc61"
                method: human_design
                label: Human Design
                language: de
                evidence_tier: computed
                data_completeness: complete
                type: { key: generator, label: Generator }
                strategy: { key: to_respond, label: Reagieren }
                authority: { key: emotional, label: Emotional }
                authority_detail: Emotional (Solar Plexus)
                profile: 6/2
                definition: { key: single_definition, label: Einfache Definition }
                signature: { key: satisfaction, label: Zufriedenheit }
                not_self_theme: { key: frustration, label: Frustration }
                defined_center_count: 5
                active_gate_count: 21
                centers:
                  - key: solar_plexus
                    label: Solarplexus
                    defined: true
                    activated_gates: [6, 22, 36, 55]
                    gate_count: 7
                    gates: [6, 22, 30, 36, 37, 49, 55]
                channels:
                  - key: 5-15
                    gates: [5, 15]
                    centers:
                      - { key: sacral, label: Sakral }
                      - { key: g, label: G-Zentrum }
                activations:
                  personality:
                    key: personality
                    label: Persönlichkeit
                    time_utc: "1987-03-18T21:22:00.000Z"
                    bodies:
                      - body: { key: sun, label: Sonne }
                        gate: 36
                        line: 6
                        longitude: 357.743065
                        center: { key: solar_plexus, label: Solarplexus }
                  design:
                    key: design
                    label: Design
                    time_utc: "1986-12-21T21:58:05.634Z"
                    bodies: []
                design_time_utc: "1986-12-21T21:58:05.634Z"
                node_model: mean
                incarnation_cross:
                  gates: [36, 6, 10, 15]
                  angle: { key: left, label: Linker Winkel }
        '304':
          description: The document has not changed since the `ETag` the client presented.
        '202':
          description: The run is still composing.
        '404':
          description: No run exists for this hash.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusNotFoundResponse'
        '422':
          description: |
            The run has no birth time, so no bodygraph exists. This is not a fault: the
            run itself is fine and `/status/{hash}` answers `200`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MethodUnavailableResponse'
              example:
                status: unavailable
                hash: "a0a5ac03febb08974dd5128d"
                method: human_design
                language: en
                reason: birth_time_unknown
                message: This part of the chart needs an exact birth time, which this run does not have.
                birth_time_known: false
                evidence_tier: unavailable
                generated_at: "2026-09-04T19:34:41.512Z"
        '500':
          description: Terminal failure of the run.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusFailedResponse'

        '503':
          description: Report storage is temporarily unavailable and no usable cached report exists. Retry within a bounded client deadline; this does not mean a calculation is processing.
          headers:
            Retry-After:
              schema:
                type: integer
              description: Minimum delay in seconds before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusUnavailableResponse'

  /status/{hash}/methods/hd:
    get:
      tags: [Compose]
      summary: Alias for `/status/{hash}/methods/human-design`
      operationId: getHdMethodologyAlias
      parameters:
        - $ref: '#/components/parameters/HashPath'
        - $ref: '#/components/parameters/LangQuery'
      responses:
        '200':
          description: The complete bodygraph; identical to `/status/{hash}/methods/human-design`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanDesignMethodology'
        '404':
          description: No run exists for this hash.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusNotFoundResponse'
        '422':
          description: The run has no birth time, so no bodygraph exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MethodUnavailableResponse'

        '503':
          description: Report storage is temporarily unavailable and no usable cached report exists. Retry within a bounded client deadline; this does not mean a calculation is processing.
          headers:
            Retry-After:
              schema:
                type: integer
              description: Minimum delay in seconds before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusUnavailableResponse'

  /match/partner-profile:
    post:
      tags: [Match]
      summary: Compare two calculated identities for symbolic relationship reflection
      operationId: matchPartnerProfile
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartnerMatchRequest'
            example:
              left_hash: "aaaaaaaaaaaaaaaaaaaaaaaa"
              right_hash: "bbbbbbbbbbbbbbbbbbbbbbbb"
              purpose: dating_partner
      responses:
        '200':
          description: Symbolic model comparison with data coverage and a localized reflection prompt. Scores are not relationship-success probabilities.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerMatchResponse'
        '404':
          description: One or both calculated hashes were not found in database or cache.
        '422':
          description: A report lacks complete validated model data (MATCH_INSUFFICIENT_DATA).
        '401':
          description: No accepted API key or trusted public UI origin.
        '403':
          description: An API key is invalid or revoked.
        '429':
          description: General request quota exceeded; Retry-After is returned.
        '500':
          description: Comparison failed; a localized diagnostic excludes internal exception details.

  /match/dating/partner-profile:
    post:
      tags: [Match]
      summary: Compare two calculated identities in a symbolic dating context
      description: Alternative matching route configured specifically for dating lens context profiles.
      operationId: matchPartnerProfileDating
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartnerMatchRequest'
      responses:
        '200':
          description: Symbolic model comparison with data coverage and a localized reflection prompt. Scores are not relationship-success probabilities.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerMatchResponse'
        '404':
          description: One or both calculated hashes were not found in database or cache.
        '422':
          description: A report lacks complete validated model data (MATCH_INSUFFICIENT_DATA).
        '401':
          description: No accepted API key or trusted public UI origin.
        '403':
          description: An API key is invalid or revoked.
        '429':
          description: General request quota exceeded; Retry-After is returned.
        '500':
          description: Comparison failed; a localized diagnostic excludes internal exception details.

  /match/business-work:
    post:
      tags: [Match]
      summary: Explore symbolic profile themes in a work context
      operationId: matchBusinessWork
      security:
        - ApiKeyAuth: []
      description: |
        Accepts a completed report and a curated role or valid custom domains. This maps symbolic model themes, not occupational ability or eligibility.
        Schema 1.1.0 / symbolic-reflection/2 corrects target units and removes evidence-text bonuses and invented score priors.
        Requirements remain unverified; no work samples are accepted or evaluated. Recommendation is always reflection_only.
        Stage, seniority and environment values are returned as unscored_context; they do not alter the score. Legacy mode and band IDs remain for compatibility.
        Unknown roles without valid custom domains, empty specs and zero-total weights return 400. Incomplete validated model vectors return 422.
        Public Origin/Referer routing selects the UI quota, not an authenticated identity. Private callers require their API key. All callers are rate limited.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BusinessWorkMatchRequest'
            example:
              hash: "cccccccccccccccccccccccc"
              role_archetype: "product_manager"
              mode: "candidate_to_role"
      responses:
        '200':
          description: Symbolic theme index, unverified requirements and a reflection-only recommendation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BusinessWorkMatchResponse'
        '400':
          description: Missing hash or role spec (archetype or custom_required_domains).
        '404':
          description: Calculated report for the provided hash was not found.
        '422':
          description: A report lacks complete validated model data (MATCH_INSUFFICIENT_DATA).
        '401':
          description: No accepted API key or trusted public UI origin.
        '403':
          description: An API key is invalid or revoked.
        '429':
          description: General request quota exceeded; Retry-After is returned.
        '500':
          description: Comparison failed; a localized diagnostic excludes internal exception details.

  /match/role-fit:
    post:
      tags: [Match]
      summary: Alias for symbolic work-context reflection
      operationId: matchBusinessWorkAlias
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BusinessWorkMatchRequest'
      responses:
        '200':
          description: Same schema and behavior as /match/business-work.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BusinessWorkMatchResponse'
        '400':
          description: Invalid input or role specification.
        '401':
          description: No accepted API key or trusted public UI origin.
        '403':
          description: Invalid or revoked key.
        '404':
          description: Report not found.
        '422':
          description: Incomplete validated model data.
        '429':
          description: General request quota exceeded.
        '500':
          description: Safe localized comparison failure.

  /geocode/search:
    get:
      tags: [Geocode]
      summary: Search recorded birth-city coordinates and timezone
      description: |
        Public endpoint for guests and accounts alike. Searches a pinned GeoNames city
        catalogue before configured providers and a bounded Photon fallback. The catalogue
        covers its recorded populated places, not every settlement or historical birthplace.
        Candidates require explicit selection; no coordinate or timezone is guessed.
      operationId: searchVerifiedCities
      parameters:
        - name: q
          in: query
          required: true
          schema: { type: string, minLength: 1, maxLength: 160 }
          example: Regensburg
        - name: lang
          in: query
          required: false
          schema: { type: string, enum: [en, de, es, fr, ja] }
        - name: limit
          in: query
          required: false
          schema: { type: integer, minimum: 1, maximum: 8, default: 5 }
      responses:
        '200':
          description: Search result with a bounded list of city suggestions, possibly empty.
          content:
            application/json:
              schema:
                type: object
                properties:
                  query: { type: string }
                  normalized_query: { type: string }
                  suggestions:
                    type: array
                    maxItems: 8
                    items: { $ref: '#/components/schemas/CitySuggestion' }
                  source: { type: string }
                  cached: { type: boolean }
                  limit: { type: integer }
                  validated_empty: { type: boolean }
                  empty_until: { type: number, description: 'Expiry of a validated negative result, Unix milliseconds; at most one minute.' }
        '400':
          description: Missing, oversized or invalid city query.
        '429':
          description: Client rate limit reached; retain Retry-After and retry later.
        '503':
          description: No usable provider or lookup capacity; retry or enter explicit coordinates and IANA timezone.

  /identity/lookup/{handle}:
    get:
      tags: [Identity]
      summary: Public handle lookup resolution
      description: Returns publicly shareable seed identity contexts linked to the given username/handle.
      operationId: resolveHandlePublic
      parameters:
        - name: handle
          in: path
          required: true
          schema:
            type: string
          example: "osint_user"
      responses:
        '200':
          description: Public handle snapshot mapping.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicHandleResponse'
        '404':
          description: Handle not found.

  /identity/internal/persistence/handle:
    get:
      tags: [Identity, Persistence]
      summary: Read full persisted handle metadata
      description: Internal endpoint retrieving comprehensive database linkages. Requires internal smoke auth.
      operationId: getInternalHandleSnapshot
      security:
        - SmokeKeyAuth: []
      parameters:
        - name: handle
          in: query
          required: false
          schema:
            type: string
        - name: value
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Detailed repository handle snapshot.
        '403':
          description: Missing or invalid internal key.

  /internal/persistence/run/{hash}:
    get:
      tags: [Persistence]
      summary: Read one persisted calculation run by hash
      operationId: getInternalPersistenceRun
      security:
        - SmokeKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/HashPath'
      responses:
        '200':
          description: Seed identity, calculation run, factors, assets, and linked handles.
        '403':
          description: Missing or invalid internal key.
        '503':
          description: Runtime database is not configured.

  /internal/persistence/handle:
    get:
      tags: [Persistence]
      summary: Read persisted handle linkage
      operationId: getInternalPersistenceHandle
      security:
        - SmokeKeyAuth: []
      parameters:
        - name: value
          in: query
          required: false
          schema:
            type: string
        - name: handle
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Handle snapshot and latest linked run data.
        '403':
          description: Missing or invalid internal key.
        '503':
          description: Runtime database is not configured.

  /internal/persistence/diagnostics:
    get:
      tags: [Persistence]
      summary: Read persistence counts and latest-run diagnostics
      operationId: getInternalPersistenceDiagnostics
      security:
        - SmokeKeyAuth: []
      responses:
        '200':
          description: Seed-first persistence counts and latest run metadata.
        '403':
          description: Missing or invalid internal key.
        '503':
          description: Runtime database is not configured.

  /internal/persistence/by-birth-year/{year}:
    get:
      tags: [Persistence]
      summary: Summarise calculation runs by seed birth year
      description: >-
        Returns a PII-free inventory of every calculation run whose seed birth
        date falls in the given four-digit year: hologram hashes, per-run counts
        (lenses, methodology snapshots, assets, avatars, events), and a stable
        hashed seed reference so the same person can be recognised across runs.
        Never returns the birth date, coordinates, or any identity field.
      operationId: getInternalPersistenceByBirthYear
      security:
        - SmokeKeyAuth: []
      parameters:
        - name: year
          in: path
          required: true
          schema:
            type: string
            pattern: '^\d{4}$'
          description: Four-digit birth year (YYYY).
      responses:
        '200':
          description: Per-year run summary (people, runs, and per-hash inventory).
        '400':
          description: Year is not four digits.
        '403':
          description: Missing or invalid internal key.
        '503':
          description: Runtime database is not configured.

  /geocode:
    get:
      tags: [Geocode]
      summary: Direct birth city coordinate/timezone resolver
      operationId: resolveGeocodeExact
      parameters:
        - name: city
          in: query
          required: false
          schema:
            type: string
          description: Exact formatted city query
      responses:
        '200':
          description: Resolved location details.

  /geo:
    get:
      tags: [Geocode]
      summary: Direct birth-city coordinate resolver
      description: Standard API lookup path aliasing `/geocode`.
      operationId: resolveGeoExact
      parameters:
        - name: city
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Geolocation coordinates and timezone offset.

  /geo/search:
    get:
      tags: [Geocode]
      summary: Search verified birth cities
      description: Standard API autocomplete query path aliasing `/geocode/search`.
      operationId: searchGeoCities
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
        - name: lang
          in: query
          required: false
          schema:
            type: string
            enum: [en, de]
      responses:
        '200':
          description: Suggested listings array.

  /render/{hash}/{type}:
    get:
      tags: [Visuals]
      summary: Fetch deterministic SVG visual
      description: |
        Renders are language specific and cached per language as
        `<hash>-<type>.<lang>.svg`. Without `lang` the compose language of the run
        is used (`summary.language`, then `metadata.language`, then `en`).
      operationId: getRenderVisual
      parameters:
        - $ref: '#/components/parameters/HashPath'
        - name: type
          in: path
          required: true
          schema:
            type: string
            enum: [radar, bazi, hd, western]
        - name: lang
          in: query
          required: false
          schema:
            type: string
            enum: [en, de]
          description: |
            Render language for titles, labels and legends. Defaults to the
            language the run was composed in. Unknown values fall back to `en`.
      responses:
        '200':
          description: SVG visual markup.
          content:
            image/svg+xml:
              schema:
                type: string
        '404':
          description: Unknown hash, unknown render type, or no payload to render from.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenderErrorResponse'
        '422':
          description: |
            The run exists but carries no usable data for this render type - for
            example a radar request against a payload without vectors, or a
            degraded run whose `deterministic_matrix_status` is not `ok`. The
            builders throw instead of emitting an empty shape (Wave 1.7), so this
            is an honest "no data", not a server fault.

            Wave 4.4: `type=hd` on a run without a birth time answers `422` with
            `detail: "birth_time_unknown"` - a bodygraph needs two exact instants, so
            there is no chart to draw and no educational variant that would not still
            look like a reading. `type=western` on the same run does render: it falls
            back to the sign-only educational wheel with no house segments.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenderErrorResponse'
        '500':
          description: Render synthesis failed unexpectedly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenderErrorResponse'

  /generated/{hash}/{type}:
    get:
      tags: [Visuals]
      summary: Fetch generated imagery asset
      operationId: getGeneratedImagery
      parameters:
        - $ref: '#/components/parameters/HashPath'
        - name: type
          in: path
          required: true
          schema:
            type: string
            enum: [cover, share-card, report-cover]
        - name: profile
          in: query
          required: false
          schema:
            type: string
            enum: [business, private, dating, personal]
      responses:
        '422':
          description: Personal interpretation is unavailable; no provider generation or stale personalized image fallback occurs.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }
                  reason: { type: string, enum: [no_effective_sources] }

        '200':
          description: Generated WebP/SVG asset binary.

  /health:
    get:
      tags: [Observability]
      summary: Read health and degradation counters
      description: |
        Without `format=json` the route answers with the plain text body `OK`.
        With `format=json` it returns the full snapshot including the `engine`
        reachability block (Wave 0.3). `status` is `DEGRADED` whenever the
        deterministic engine is known to be unreachable, so a silent
        `engine_unavailable_mock` outage is now visible here.
      operationId: getHealth
      parameters:
        - name: format
          in: query
          required: false
          schema:
            type: string
            enum: [json]
          description: Pass `json` for the structured snapshot; omitted returns `OK` as text/plain.
        - name: runtime
          in: query
          required: false
          schema: { type: string, enum: ['1'] }
          description: With format=json, include a bounded fresh observation of the configured engine core version. No-store; never substitutes app/schema/report versions or a placeholder.
      responses:
        '200':
          description: Service health parameters.
          content:
            text/plain:
              schema:
                type: string
                enum: [OK]
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'

  /maintenance/health:
    get:
      tags: [Observability]
      summary: Detailed diagnostic health report
      description: Alias of /health with the same format=json and runtime=1 options. The core version observation does not rewrite compose reachability or historical report provenance.
      parameters:
        - name: format
          in: query
          schema: { type: string, enum: [json] }
        - name: runtime
          in: query
          schema: { type: string, enum: ['1'] }
      operationId: getMaintenanceHealth
      responses:
        '200':
          description: Comprehensive JSON breakdown.

  /maintenance/telemetry:
    post:
      tags: [Observability, Maintenance]
      summary: Post a telemetry log event
      description: Captured client-side exception metrics, asset performance benchmarks, or audit trails.
      operationId: logTelemetryEvent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [event]
              properties:
                event: { type: string }
                metadata: { type: object }
                payload: { type: object }
                timestamp: { type: string, format: date-time }
                sessionId: { type: string }
                url: { type: string }
      responses:
        '200':
          description: Telemetry logged successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  logged: { type: boolean }

  /maintenance/lore:
    get:
      tags: [Maintenance]
      summary: Query localized esoteric lore topics
      description: Returns definitions for Human Design types, Authorities, Chinese BaZi elements, and Western signs.
      operationId: queryEsotericLore
      parameters:
        - name: topic
          in: query
          required: false
          schema:
            type: string
          description: Topic keyword key
        - name: lang
          in: query
          required: false
          schema:
            type: string
            enum: [en, de]
            default: en
      responses:
        '200':
          description: Localized lore dictionary entry.

  /maintenance/internal/replay/{hash}:
    post:
      tags: [Maintenance]
      summary: Force-replay a calculation run from raw upstream engine payloads
      description: |
        Restricted internal utility. Enforced by `verifyInternalKey` (Wave 2.5):
        accepts the `x-4ura-smoke-key` header, the configured internal
        `X-4ura-API-Key`, an `apikey` query parameter, or an Authlion SSO session
        cookie for a `@weretrade.com` / `@illforte.com` account. Same-origin
        browser access alone is never sufficient here.

        This router is mounted at both `/api` and `/api/maintenance`, so the
        endpoint also answers at `/api/internal/replay/{hash}` under the same
        authentication.
      operationId: forceReplayRun
      security:
        - SmokeKeyAuth: []
        - ApiKeyAuth: []
      parameters:
        - name: hash
          in: path
          required: true
          schema:
            type: string
            pattern: '^[a-f0-9]{24,32}$'
      responses:
        '200':
          description: Replay result mapping summary.
        '400':
          description: Hash did not match the 24-32 character hex contract.
        '403':
          description: Missing or unauthorized internal credential.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalAuthError'

  /maintenance/internal/backfill/{hash}:
    post:
      tags: [Maintenance]
      summary: Force backfill assets for a run
      description: |
        Reconstructs premium SVG cover and share templates without re-querying
        computational layers. Restricted internal utility with the same
        `verifyInternalKey` contract as `/maintenance/internal/replay/{hash}`
        (Wave 2.5), and likewise also reachable at
        `/api/internal/backfill/{hash}`.
      operationId: backfillRunAssets
      security:
        - SmokeKeyAuth: []
        - ApiKeyAuth: []
      parameters:
        - name: hash
          in: path
          required: true
          schema:
            type: string
            pattern: '^[a-f0-9]{24,32}$'
      responses:
        '200':
          description: Rebuilt assets array.
        '400':
          description: Hash did not match the 24-32 character hex contract.
        '403':
          description: Missing or unauthorized internal credential.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalAuthError'

  /maintenance/internal/observability:
    get:
      tags: [Observability, Maintenance]
      summary: Live and deploy-surviving observability snapshot
      description: |
        The full telemetry picture behind Sprint 10 S9. `live` is the in-memory
        half `/health?format=json` already embeds: counters, latency
        percentiles and the recent-outcome window since `process_started_at`,
        all of which reset on every deploy. `persistent` is the database half,
        which survives deploys: run counts and statuses, run-event codes and
        `fallback_modes`.

        `fallback_rate` keeps its historical definition (`FALLBACK_ACTIVATED`
        run events over total runs). `degraded_rate` and
        `engine_unavailable_rate` are derived from `CalculationRun.fallbackMode`
        instead, because an `engine_unavailable_mock` run is persisted as a
        *resolved* run carrying a fallback mode and never writes a run event -
        so the event-derived rate reads 0 during exactly the outage that
        finding 0.3 was about.

        A database that is unreachable or unconfigured degrades `persistent` to
        `database_configured: false` (with `persistent_error` when a read threw)
        rather than failing the request, since the live half is what an operator
        needs at that moment.

        Restricted internal utility with the same `verifyInternalKey` contract
        as `/maintenance/internal/replay/{hash}`, and likewise also reachable at
        `/api/internal/observability`.
      operationId: getObservabilitySnapshot
      security:
        - SmokeKeyAuth: []
        - ApiKeyAuth: []
      parameters:
        - name: days
          in: query
          required: false
          description: Reporting window for the persistent half, in days.
          schema:
            type: integer
            minimum: 1
            maximum: 90
            default: 7
      responses:
        '200':
          description: Combined live and persistent observability snapshot.
          content:
            application/json:
              schema:
                type: object
                properties:
                  generated_at:
                    type: string
                    format: date-time
                  timeframe_days:
                    type: integer
                  process_started_at:
                    type: string
                    format: date-time
                    description: Boot time of the process the live counters belong to.
                  engine:
                    type: object
                    description: Deterministic engine reachability, same block as `/health`.
                  live:
                    type: object
                    description: In-memory counters, latency percentiles and recent-outcome window.
                  persistent:
                    type: object
                    properties:
                      timeframe_days:
                        type: integer
                      since:
                        type: string
                        format: date-time
                      total_runs:
                        type: integer
                      statuses:
                        type: object
                        additionalProperties:
                          type: integer
                      event_summary:
                        type: object
                        additionalProperties:
                          type: integer
                      fallback_modes:
                        type: object
                        additionalProperties:
                          type: integer
                      degraded_runs:
                        type: integer
                      engine_unavailable_runs:
                        type: integer
                      fallback_rate:
                        type: number
                      degraded_rate:
                        type: number
                      engine_unavailable_rate:
                        type: number
                      database_configured:
                        type: boolean
                  persistent_error:
                    type: string
                    description: Present only when the database read threw.
        '400':
          description: '`days` was not an integer in 1-90.'
        '403':
          description: Missing or unauthorized internal credential.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalAuthError'

  /maintenance/internal/recompose/{hashId}:
    post:
      tags: [Maintenance]
      summary: Recompute one stored run in place
      description: |
        Re-runs the composer pipeline `POST /compose` runs, for the same hash,
        from the seed the run was persisted with, then overwrites the stored
        payload, the file cache and the visuals catalog and sets the run
        `resolved`. A `RECOMPOSED` run event records
        `{ previous_matrix_status, new_matrix_status }`.

        This is what `/maintenance/internal/replay/{hash}` is not:
        replay re-finalizes the payload that is already stored and restores the
        JSON cache, so it can never repair a run that was served from the
        baseline mock matrix during an engine outage (all six vectors 46, no
        facts). This recomputes.

        Two guarantees make that safe. The deterministic engine's health
        endpoint is probed first and the request is refused with `503` while it
        is unreachable, so a recompose can never *produce* a mock. And a result
        that comes back untrusted anyway - the engine died between the probe and
        the compose - never replaces a trusted report: the stored payload is put
        back, a `RECOMPOSE_ROLLBACK` event is written and the response reports
        `ok: false`. Avatar rows survive, because every write goes through the
        `MANAGED_ASSET_TYPES`-scoped persistence path (Wave 2, J S5).

        Send `{"dry_run": true}` (or `?dry_run=true`) to resolve the candidate
        and its current matrix status without recomputing anything.

        Restricted internal utility with the same `verifyInternalKey` contract
        as `/maintenance/internal/replay/{hash}`, and likewise also reachable at
        `/api/internal/recompose/{hashId}`.
      operationId: recomposeRun
      security:
        - SmokeKeyAuth: []
        - ApiKeyAuth: []
      parameters:
        - name: hashId
          in: path
          required: true
          schema:
            type: string
            pattern: '^[a-f0-9]{24,32}$'
        - name: dry_run
          in: query
          required: false
          description: List the candidate without recomputing it.
          schema:
            type: boolean
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                dry_run:
                  type: boolean
                  default: false
      responses:
        '200':
          description: The run was recomputed (or, on a dry run, resolved).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecomposeResult'
        '400':
          description: Hash did not match the 24-32 character hex contract.
        '403':
          description: Missing or unauthorized internal credential.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalAuthError'
        '404':
          description: No run is stored under this hash.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecomposeResult'
        '409':
          description: |
            The run is already trusted but its stored payload cannot be read
            back, so there would be no restore point if the recompose failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecomposeResult'
        '422':
          description: The stored seed is incomplete, so the run cannot be recomputed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecomposeResult'
        '502':
          description: |
            The compose failed or produced an untrusted matrix. When the
            previous report was trusted it has been restored (`rolled_back: true`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecomposeResult'
        '503':
          description: Refused - the deterministic engine is unreachable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecomposeResult'

  /maintenance/internal/recompose:
    post:
      tags: [Maintenance]
      summary: Recompute a filtered batch of stored runs in place
      description: |
        The batch form of `/maintenance/internal/recompose/{hashId}`, with the
        same semantics and the same two guarantees, for repairing an outage
        window.

        Candidates are matched on both columns the two mock markers live in:
        `mock` is the stored `deterministic_matrix_status`, while
        `engine_unavailable_mock` is the `fallback_mode` written next to it when
        the engine was the reason. Newest first, `limit` capped at 100
        (default 25), soft-deleted runs excluded.

        Execution is sequential with a short pause between runs
        (`FOURA_RECOMPOSE_DELAY_MS`), and stops at the first engine failure, so
        an outage that starts mid-batch cannot walk the rest of the backlog into
        mocks. `dry_run` returns the candidate list and nothing else.

        Restricted internal utility with the same `verifyInternalKey` contract
        as `/maintenance/internal/replay/{hash}`, and likewise also reachable at
        `/api/internal/recompose`.
      operationId: recomposeRunBatch
      security:
        - SmokeKeyAuth: []
        - ApiKeyAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                where:
                  type: object
                  properties:
                    matrix_status:
                      type: array
                      maxItems: 10
                      description: Defaults to `["mock", "engine_unavailable_mock"]`.
                      items:
                        type: string
                    since:
                      type: string
                      format: date-time
                      description: Only runs created at or after this instant.
                limit:
                  type: integer
                  minimum: 1
                  maximum: 100
                  default: 25
                dry_run:
                  type: boolean
                  default: false
            example:
              where:
                matrix_status: [engine_unavailable_mock, mock]
                since: '2026-09-03T00:00:00.000Z'
              limit: 25
              dry_run: true
      responses:
        '200':
          description: Batch report. `ok` is false when the batch was aborted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  dry_run:
                    type: boolean
                  ok:
                    type: boolean
                  filter:
                    type: object
                    properties:
                      matrix_status:
                        type: array
                        items:
                          type: string
                      since:
                        type: string
                        nullable: true
                      limit:
                        type: integer
                  totals:
                    type: object
                    properties:
                      candidates:
                        type: integer
                      recomposed:
                        type: integer
                      failed:
                        type: integer
                      skipped:
                        type: integer
                      rolled_back:
                        type: integer
                  aborted_after:
                    type: string
                    description: Hash the batch stopped at, present only when aborted.
                  candidates:
                    type: array
                    description: Dry runs only.
                    items:
                      type: object
                      properties:
                        hashId:
                          type: string
                        previous_matrix_status:
                          type: string
                        fallback_mode:
                          type: string
                          nullable: true
                        run_status:
                          type: string
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/RecomposeResult'
        '400':
          description: Request body did not match the filter contract.
        '403':
          description: Missing or unauthorized internal credential.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalAuthError'
        '503':
          description: Refused - the deterministic engine is unreachable, nothing was written.

  /chain/default:
    get:
      tags: [Chain Connectors]
      summary: Get standard capability descriptor
      description: Public capability descriptor for external bridges.
      operationId: defaultChainConnector
      responses:
        '200':
          description: System descriptor, versioning metadata, and capability list.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string }
                  name: { type: string }
                  version: { type: string }
                  supported_chains: { type: array, items: { type: string } }

  /chain/osintowl:
    post:
      tags: [Chain Connectors]
      summary: OSINT Owl metadata ingestion bridge
      description: Authenticated bridge connecting OSINT scraping targets to calculated 4ura SeedIdentities. Requires internal smoke auth.
      operationId: ingestOsintOwl
      security:
        - SmokeKeyAuth: []
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [target]
              properties:
                target: { type: string, description: "Identifier e.g. email, handle, or username" }
                email: { type: string }
                username: { type: string }
                hashId: { type: string }
                hash: { type: string }
                osintData: { type: object }
      responses:
        '200':
          description: Success status.
        '403':
          description: Access denied.

  /chain/4ura:
    post:
      tags: [Chain Connectors]
      summary: 4ura internal factor resolver
      description: Authenticated bridge allowing OSINT Owl to resolve normalized HD, BaZi, and Western highlights from a calculated report. Requires internal smoke auth.
      operationId: resolve4uraFactors
      security:
        - SmokeKeyAuth: []
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                hashId: { type: string }
                hash: { type: string }
                target: { type: string }
                email: { type: string }
                username: { type: string }
      responses:
        '200':
          description: Ingestion report data highlights.

  /avatar/generate:
    post:
      tags: [Avatar Generation]
      summary: Queue premium WebGL or TMNT archetype avatar generation
      description: Async GPU generator producing optimized `.webp` portraits based on calculated seed traits. Requires `X-4ura-API-Key` or a same-origin browser request; rate-limited to 8/hour per IP, and only the internal smoke key bypasses that quota. There is no header- or address-based bypass.
      operationId: queueAvatarGeneration
      security:
        - ApiKeyAuth: []
        - {}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [hashId, type]
              properties:
                hashId: { type: string, example: "aaaaaaaaaaaaaaaaaaaaaaaa" }
                type: { type: string, enum: [avatar_personal, avatar_tmnt], example: "avatar_personal" }
      responses:
        '422':
          description: Personal interpretation is unavailable; no provider generation or stale personalized image fallback occurs.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }
                  reason: { type: string, enum: [no_effective_sources] }

        '200':
          description: Cache hit. Completed URL supplied immediately.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string, enum: [completed] }
                  url: { type: string }
                  cached: { type: boolean }
        '202':
          description: Enqueued for generation.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string, enum: [processing] }
                  prompt_preview: { type: string }
        '429':
          description: Too Many Requests. Hourly IP quota exceeded.

  /avatar/status/{hashId}/{type}:
    get:
      tags: [Avatar Generation]
      summary: Poll status of queued avatar generation
      description: |
        Same authentication as `/avatar/generate` and `/avatar/stream` since
        1.16.11 - `X-4ura-API-Key`, or a same-origin browser request (the report
        page polls this route) - but without the image quota. It used to answer
        anyone, which let a caller enumerate hashes and read stored portrait URLs.
      operationId: pollAvatarStatus
      security:
        - ApiKeyAuth: []
        - {}
      parameters:
        - name: hashId
          in: path
          required: true
          schema:
            type: string
        - name: type
          in: path
          required: true
          schema:
            type: string
            enum: [avatar_personal, avatar_tmnt]
      responses:
        '200':
          description: Status representation.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string, enum: [processing, completed, failed, evicted, not_requested, unavailable] }
                  url: { type: string }
                  provider_ready: { type: boolean }
        '400':
          description: Unknown avatar type.
        '401':
          description: No API key and not a recognized same-origin browser request.
        '403':
          description: The API key is unknown, revoked or expired.
        '404':
          description: Hologram hash not found (never composed, or deleted).

  /avatar/stream/{hashId}/{type}:
    get:
      tags: [Avatar Generation]
      summary: Real-time status event stream (SSE)
      description: |
        Keeps a keep-alive connection streaming state progress events until
        complete, failed or timed out (60 polls at 2 s = 2 minutes).

        Wave 2.6: carries the same authentication and quota as
        `/avatar/generate` - `X-4ura-API-Key` or a same-origin browser request,
        plus the 8-per-hour-per-IP avatar rate limit. Closing the connection now
        cancels the underlying database poll, so an abandoned tab no longer costs
        60 queries.
      operationId: streamAvatarStatus
      security:
        - ApiKeyAuth: []
        - {}
      parameters:
        - name: hashId
          in: path
          required: true
          schema:
            type: string
        - name: type
          in: path
          required: true
          schema:
            type: string
            enum: [avatar_personal, avatar_tmnt]
      responses:
        '200':
          description: |
            Server-sent event stream connection established. Events: `status`
            (connected), then one terminal `completed`, `failed`, `timeout` or
            `error`.
          headers:
            Content-Type:
              schema: { type: string, example: "text/event-stream" }
            Cache-Control:
              schema: { type: string, example: "no-cache" }
            Connection:
              schema: { type: string, example: "keep-alive" }
        '400':
          description: Unknown avatar type.
        '401':
          description: No API key and not a recognized same-origin browser request.
        '429':
          description: Avatar quota exceeded for this IP.

  /admin/tenants:
    get:
      tags: [Admin]
      summary: List registered Client Tenants
      description: Returns tenant lists with database metrics. Requires internal admin key. API keys are listed as `{ id, name, isActive, expiresAt, createdAt, keyPreview }` - the first six and last four characters, stored when the key was issued; the plaintext key is returned once, by `POST /admin/tenants/{id}/keys`, and never again.
      operationId: listTenantsAdmin
      security:
        - SmokeKeyAuth: []
      responses:
        '200':
          description: List of tenants.
    post:
      tags: [Admin]
      summary: Create a Client Tenant
      description: Provision a new tenant slug. Requires internal admin key.
      operationId: createTenantAdmin
      security:
        - SmokeKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, slug]
              properties:
                name: { type: string }
                slug: { type: string }
                tier: { type: string, enum: [free, pro, premium, enterprise], default: free }
                metadata: { type: object }
      responses:
        '201':
          description: Created tenant record.

  /admin/tenants/{id}/keys:
    post:
      tags: [Admin]
      summary: Provision or rotate API keys for a tenant
      description: Generates a cryptographically secure tenant access token. Requires internal admin key. The response carries the plaintext `key` once, next to `{ id, clientId, name, isActive, expiresAt, createdAt, keyPreview }`. Only its SHA-256 hash and the masked preview are stored, so the key cannot be shown again - a lost key is replaced by issuing a new one and revoking the old one with `POST /admin/keys/{keyId}/toggle`.
      operationId: provisionTenantKey
      security:
        - SmokeKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string, default: "Default Key" }
      responses:
        '201':
          description: Key provisioned successfully.

  /admin/usage:
    get:
      tags: [Admin]
      summary: Read global usage statistics
      description: Aggregates metrics from usage meters. Requires internal admin key.
      operationId: getUsageStatsAdmin
      security:
        - SmokeKeyAuth: []
      responses:
        '200':
          description: Usage reports array.

  /admin/degradations:
    get:
      tags: [Admin]
      summary: Read degradation audit logs
      description: Fetch persistent histories of database failures, model fallbacks, or engine omissions. Requires internal admin key.
      operationId: getDegradationAuditsAdmin
      security:
        - SmokeKeyAuth: []
      parameters:
        - name: days
          in: query
          required: false
          schema: { type: integer, default: 7 }
        - name: tier
          in: query
          required: false
          schema: { type: string }
        - name: code
          in: query
          required: false
          schema: { type: string }
      responses:
        '200':
          description: Filtered list of degradation events.

  /admin/identity/unlink:
    post:
      tags: [Admin]
      summary: Sever user handle linkages
      description: GDPR compliance route. Disconnects user handle mappings from calculation runs without altering aggregates. Requires internal admin key.
      operationId: unlinkHandleAdmin
      security:
        - SmokeKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [handle, seedFingerprint]
              properties:
                handle: { type: string }
                seedFingerprint: { type: string }
      responses:
        '200':
          description: Success confirmation.

  /admin/identity/anonymize:
    post:
      tags: [Admin]
      summary: Permanently redact seed identity parameters
      description: GDPR compliance route. Redacts the location of one seed identity (city name and query, coordinates, geocoder reference and precision) and withdraws consent. It does not erase the birth date, birth time, timezone, gender or verified city id on the seed identity, nor the stored report payloads of its runs (`CalculationRun.canonicalPayload`, which still carries the seed context) - it is a location redaction, not an erasure. Requires internal admin key.
      operationId: anonymizeSeedAdmin
      security:
        - SmokeKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [seedFingerprint]
              properties:
                seedFingerprint: { type: string }
      responses:
        '200':
          description: Successfully anonymized.

  /admin/migration/status:
    get:
      tags: [Admin]
      summary: Read operational file-to-db migration status
      description: Returns file count metrics inside local cache nodes and PostgreSQL tables. Probes geocoding latencies. Requires internal admin key.
      operationId: getMigrationStatusAdmin
      security:
        - SmokeKeyAuth: []
      responses:
        '200':
          description: Telemetry breakdown.

  /admin/replay/dry-run:
    post:
      tags: [Admin]
      summary: Run dry-run payload normalization comparisons
      description: Compares stored canonical payloads through the current finalizer without modifying DB records or cache files. Returns vector/fidelity differences, bounded Western placement/cusp and BaZi element-count differences, and existing schema diagnostics. comparisons.visuals.renderAvailability independently reports radar, western, bazi and hd as renderable or unavailable; typed omissions retain their reason and detail, including birth_time_unknown. An unavailable chart does not invalidate the saved report or stop sibling probes. Unexpected renderer faults and deleted-run refusal still fail. No SVG byte equality, HD structural comparison or independent calculation accuracy is certified. Requires internal admin key.
      operationId: dryRunReplayAdmin
      security:
        - SmokeKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [hashId]
              properties:
                hashId: { type: string }
      responses:
        '200':
          description: Structural normalization diffs and per-renderer availability. Existing SVG comparison descriptors remain omitted; no chart bytes are returned or persisted.

  /admin/replay/bulk:
    post:
      tags: [Admin]
      summary: Trigger bulk database replay workers
      description: Reconstructs caches in parallel. Requires internal admin key.
      operationId: bulkReplayAdmin
      security:
        - SmokeKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                isDegradedOnly: { type: boolean, default: false }
                schemaVersionFilter: { type: string }
                limit: { type: integer, default: 250 }
      responses:
        '200':
          description: Bulk processing metadata logs.

  /admin/run/{hashId}/timeline:
    get:
      tags: [Admin]
      summary: Fetch run execution stage logs
      description: Chronological execution steps for a synthesis run. Requires internal admin key.
      operationId: getRunTimelineAdmin
      security:
        - SmokeKeyAuth: []
      parameters:
        - name: hashId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Event timeline list.

  /api/status/{hash}/oracle:
    get:
      operationId: getReportOracleAllowance
      tags: [Oracle]
      summary: Check report-scoped AI question availability
      description: Optional stable only. Requires a fresh active account owning the resolved report, or a verified durable guest capability bound when this new report was created. Public hashes and personal API keys do not authorize this endpoint. No question or chart is sent to the AI service by this read.
      parameters:
        - $ref: '#/components/parameters/HashPath'
      security:
        - AccountSessionCookie: []
        - OracleGuestCookie: []
      responses:
        '200':
          description: Current3guest or10account allowance; in-flight reservations temporarily hold capacity. The server resets the successful-answer budget at UTC midnight across reports and sessions. Independent of the100/day personal REST/MCP budget.
          content:
            application/json:
              schema:
                type: object
                required: [allowance]
                properties:
                  allowance:
                    $ref: '#/components/schemas/OracleAllowance'
        '401':
          description: Account session must be renewed; never downgraded to a guest
        '403':
          description: Account is not active or current terms/verification are missing
        '404':
          description: Disabled or no authorized resolved report/capability
        '503':
          description: Identity, storage, selected facts or configuration unavailable
    post:
      operationId: askReportOracle
      tags: [Oracle]
      summary: Ask about selected values of the authorized stored report
      description: Explicit question submission shares only minimized source-admitted facts with the private0racle service. Context is partial; unsupported questions are refused without a successful-answer charge. Failed work releases its reservation. A completed answer is charged once even if delivery disconnects; the same request key can replay its encrypted result for15minutes. Expired replay preserves its charged tombstone. No client role, chart, owner or quota is accepted. Cookie authentication only; personal API keys are not admitted.
      security:
        - AccountSessionCookie: []
          AccountCsrfHeader: []
        - OracleGuestCookie: []
      parameters:
        - $ref: '#/components/parameters/HashPath'
        - name: Origin
          in: header
          required: true
          schema:
            type: string
          description: Exact configured4ura origin; cross-site submissions are refused
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
            format: uuid
          description: UUIDv4 retained when retrying the same question, language and report source
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [question, language]
              properties:
                question:
                  type: string
                  minLength: 1
                  maxLength: 1000
                language:
                  type: string
                  enum: [en, de]
      responses:
        '200':
          description: Plain-text answered/refused result with cited selected source categories and current server allowance. Refusals have no citations and do not consume a successful answer.
          content:
            application/json:
              schema:
                type: object
                required: [status, answer, citations, allowance, replayed]
                properties:
                  status:
                    type: string
                    enum: [answered, refused]
                  answer:
                    type: string
                    maxLength: 16000
                  citations:
                    type: array
                    maxItems: 3
                    items:
                      type: string
                      enum: [western.major_aspect, bazi.day_main_hidden_stem, hd.moon_pair]
                  allowance:
                    $ref: '#/components/schemas/OracleAllowance'
                  replayed:
                    type: boolean
        '400':
          description: Invalid bounded JSON question or request key
        '401':
          description: Account session expired or revoked
        '403':
          description: Origin/CSRF or current account admission refused
        '404':
          description: Disabled or no authorized resolved report/capability
        '409':
          description: Same request is in progress, or was answered but its short replay has expired
        '422':
          description: Request key reused with different question, language, report or admitted source
        '429':
          description: Daily allowance exhausted or short-burst abuse protection refused
        '503':
          description: Question provider, identity, database or configured service unavailable

components:
  securitySchemes:
    OracleGuestCookie:
      type: apiKey
      in: cookie
      name: __Host-4ura_oracle
      description: Server-signed Secure/HttpOnly functional capability with a durable identity and creation-time report binding. A legacy guest header/public report link is not authority.
    AccountSessionCookie:
      type: apiKey
      in: cookie
      name: __Host-4ura_session
      description: Fresh server-side authLion account session; upstream tokens stay server-side
    AccountCsrfHeader:
      type: apiKey
      in: header
      name: X-4ura-CSRF
      description: Current synchronizer token from the same-origin account session endpoint
    PersonalApiKeyAuth:
      type: apiKey
      in: header
      name: X-4ura-API-Key
      description: Owner-scoped sk-4ura-user personal profile key. Shared durable100 requests/account/UTC day across REST and MCP. No guest, tenant or operator scope.
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-4ura-API-Key
    SmokeKeyAuth:
      type: apiKey
      in: header
      name: x-4ura-smoke-key

  parameters:
    HashPath:
      name: hash
      in: path
      required: true
      schema:
        type: string
        pattern: '^[a-f0-9]{24,32}$'
    DebugQuery:
      name: debug
      in: query
      required: false
      schema:
        type: string
        enum: ["1", "true"]
      description: Include `_debug` diagnostics and enable matching browser console output.
    RawQuery:
      name: raw
      in: query
      required: false
      schema:
        type: string
        enum: ["1", "true"]
      description: Include full `_debug.raw_engines` only when `debug=1` and a valid API key is present.
    LangQuery:
      name: lang
      in: query
      required: false
      schema:
        type: string
        enum: [en, de]
      description: |
        Language of every label in the response. Defaults to the language the run was
        composed in. The document is cached per language, so switching `lang` yields a
        different `ETag` for the same content.

  headers:
    MethodsETag:
      description: |
        Content fingerprint of this family inside this run, plus the language. It changes
        when the run is recomposed with different engine output and never otherwise, so a
        client may hold the document until the ETag moves.
      schema: { type: string }
    MethodsCacheControl:
      description: '`public, max-age=3600, must-revalidate`'
      schema: { type: string }
    MethodsContentLanguage:
      description: The language every label in the body is written in.
      schema: { type: string }

  schemas:
    OracleAllowance:
      type: object
      required: [tier, limit, remaining, resetsAt]
      properties:
        tier:
          type: string
          enum: [guest, account]
        limit:
          type: integer
          enum: [3, 10]
        remaining:
          type: integer
          minimum: 0
          maximum: 10
        resetsAt:
          type: string
          format: date-time
          description: Next UTC midnight from the database admission clock
    ComposeRequest:
      type: object
      required: [seed_profile]
      properties:
        birth_time_range:
          not: {}
          description: A range belongs inside seed_profile. Any supplied request-root value returns 400.
        seed_profile:
          type: object
          required: [birth_date, birth_city, birth_coords, timezone]
          properties:
            birth_date:
              type: string
              format: date
            birth_time:
              type: string
              pattern: '^\\d{2}:\\d{2}$'
              description: |
                Optional. Omit it (or send an empty string) when the birth time is not
                known; do not substitute a placeholder such as `00:00` or `12:00`.
            birth_time_known:
              type: boolean
              description: |
                Optional override. Defaults to `true` when a usable `birth_time` is
                present and `false` otherwise. Sending `false` alongside a time discards
                the time: the caller's declaration wins. Sending `true` without a time is
                downgraded to `false`.

                When `false`, the run is composed under the untimed contract - see the
                `UntimedContract` schema for exactly which fields are withheld.
              default: true
            birth_time_range:
              allOf:
                - $ref: '#/components/schemas/BirthTimeRangeInput'
              description: |
                Optional explicit civil-minute precision. The first date must equal birth_date;
                UTC endpoints must be ordered and at most 86400 seconds apart. Nonzero
                windows require no birth_time, no single dst_choice and no true known-time
                flag. A zero-width window admits exactly its selected instant and must agree
                with any supplied clock/occurrence. Absence preserves point/untimed behavior.
            birth_city:
              type: string
            birth_coords:
              type: object
              description: Explicit paired geographic coordinates; real zero is valid.
              required: [lat, lng]
              properties:
                lat: { type: number, minimum: -90, maximum: 90 }
                lng: { type: number, minimum: -180, maximum: 180 }
            timezone:
              type: string
              description: Valid named IANA timezone, including UTC, Etc/UTC and signed Etc/GMT zones; raw numeric offsets and unknown names are rejected.
              default: UTC
              example: Europe/Berlin
            gender:
              type: string
              enum: [neutral, male, female]
              default: neutral
        orchestration_options:
          type: object
          properties:
            language:
              type: string
              enum: [en, de]
              default: en
            priority:
              type: string
              enum: [standard]
            lenses:
              type: array
              items:
                type: string
                enum: [personal, business, dating, hr, private, other]

    BirthTimeRangeInput:
      type: object
      additionalProperties: false
      required: [start, end]
      properties:
        start: { $ref: '#/components/schemas/BirthTimeRangeEndpointInput' }
        end: { $ref: '#/components/schemas/BirthTimeRangeEndpointInput' }
    BirthTimeRangeEndpointInput:
      type: object
      additionalProperties: false
      required: [date, time]
      properties:
        date: { type: string, format: date }
        time: { type: string, pattern: '^(?:[01][0-9]|2[0-3]):[0-5][0-9]$' }
        dst_choice:
          type: string
          enum: [first, second]
          description: Required for ambiguous clocks. Second is refused when no second occurrence exists. Gaps and historical second-resolution offsets are unsupported.
    CanonicalBirthTimeRange:
      type: object
      description: Persisted endpoint provenance is re-resolved and compared exactly before admission. A fold is an explicit selected occurrence, not an uncertainty window.
      required: [schema_version, timezone, start, end, duration_seconds, exact_instant, maximum_supported_seconds, endpoint_resolution]
      properties:
        schema_version: { type: string, enum: ['birth-time-range/1'] }
        timezone: { type: string }
        start: { $ref: '#/components/schemas/CanonicalBirthTimeRangeEndpoint' }
        end: { $ref: '#/components/schemas/CanonicalBirthTimeRangeEndpoint' }
        duration_seconds: { type: number, minimum: 0, maximum: 86400 }
        exact_instant: { type: boolean }
        maximum_supported_seconds: { type: integer, enum: [86400] }
        endpoint_resolution: { type: string, enum: [explicit_civil_minutes_and_selected_utc_occurrences] }
    CanonicalBirthTimeRangeEndpoint:
      type: object
      required: [date, time, dst_choice, utc_iso, epoch_ms, utc_offset_minutes, offset_label, utc_occurrence, utc_candidates]
      properties:
        date: { type: string, format: date }
        time: { type: string }
        dst_choice: { type: string, nullable: true, enum: [first, second, null] }
        utc_iso: { type: string, format: date-time }
        epoch_ms: { type: integer, description: Milliseconds since the Unix epoch. }
        utc_offset_minutes: { type: integer }
        offset_label: { type: string }
        utc_occurrence: { type: integer, enum: [1, 2] }
        utc_candidates:
          type: array
          items:
            type: object
            properties:
              utc_iso: { type: string, format: date-time }
              epoch_ms: { type: integer }
              utc_offset_minutes: { type: integer }
    BirthIntervalSummary:
      type: object
      description: Bounded public availability summary. It is not numerical evidence and cannot be reused as a full sensitivity result. Missing or conflicting provenance withholds every personal point fact, score and image.
      required: [schema_version, scope, range, personal_point_admissible, status, reason, note, families]
      properties:
        schema_version: { type: string, enum: ['birth-interval-analysis/1'] }
        scope: { type: string, enum: [summary] }
        range: { allOf: [{ $ref: '#/components/schemas/CanonicalBirthTimeRange' }], nullable: true }
        personal_point_admissible: { type: boolean }
        status: { type: string, enum: [point, interval, invalid, conflict] }
        reason: { type: string, nullable: true }
        note: { type: string, nullable: true }
        families:
          type: object
          additionalProperties:
            type: object
            required: [status, field_count, detail_available, href]
            properties:
              status: { type: string }
              field_count: { type: integer, nullable: true }
              detail_available: { type: boolean }
              href: { type: string, nullable: true }
    BirthIntervalRuntimePolicy:
      type: object
      additionalProperties: false
      required: [schema_version, id, maximum_evaluations, requested_time_tolerance_ms, evaluation_unit, numerical_contact_rule]
      description: Server-owned policy recorded with nonzero interval analyses. The current default allows 512 family point-oracle evaluations. Smaller backend caps are distinct policy identities; reuse requires the current complete policy. A numerical contact band uses the admitted signed rate and coordinate margin and can be wider than the requested one millisecond tolerance. This policy is not a whole-request latency guarantee.
      properties:
        schema_version: { type: string, enum: ['birth-interval-runtime-policy/1'] }
        id: { type: string, enum: ['repo-owned-birth-interval/1'] }
        maximum_evaluations: { type: integer, minimum: 1, maximum: 512 }
        requested_time_tolerance_ms: { type: integer, enum: [1] }
        evaluation_unit: { type: string, enum: [family_point_oracle] }
        numerical_contact_rule: { type: string, enum: [coordinate_margin_and_admitted_signed_rate] }
    BirthIntervalFamilySensitivity:
      type: object
      description: |
        One explicit full-method read, separate from personal chart fields. Analysis preserves
        declared support/bounds, endpoint UTC calculations, alternatives, boundary distances,
        numerical transition intervals, unresolved segments and source-root residuals. The
        compact projection links the complete stored raw trace by SHA-256 and sample count;
        it never replaces that trace. Unresolved, unsupported and budget_exhausted do not mean
        unchanged. Calculations and symbolic categories do not establish measured personality.
      required: [schema_version, scope, range, personal_point_admissible, family, analysis]
      properties:
        schema_version: { type: string, enum: ['birth-interval-analysis/1'] }
        scope: { type: string, enum: [family] }
        range: { $ref: '#/components/schemas/CanonicalBirthTimeRange' }
        personal_point_admissible: { type: boolean }
        family: { type: string, enum: [western, chinese, hd] }
        analysis:
          type: object
          additionalProperties: true
          description: Recorded versioned western-interval/1, bazi-interval/1 or hd-interval/1 result, or an explicit unsupported result. Angular distances are degrees, UTC brackets use ISO timestamps, epoch probes use milliseconds, rates name seconds/day in their field names, and evaluation counts are integers.
          properties:
            runtime_policy: { $ref: '#/components/schemas/BirthIntervalRuntimePolicy' }
    ComposeAcceptedResponse:
      type: object
      properties:
        status:
          type: string
          enum: [processing]
        hologram_hash:
          type: string
        reused:
          type: boolean
          description: |
            Present and `true` when this hash is an existing resolved run for an identical
            seed and language rather than a newly started compute. The first poll of
            `/compose/status/{hash}` answers `200` immediately.
        _debug:
          $ref: '#/components/schemas/DebugPayload'

    UntimedContract:
      type: object
      description: |
        What a run composed without a birth time (`birth_time_known: false`) does and does
        not contain. A birth time nobody supplied used to be substituted silently - `00:00`
        by the UI, `12:00` by the engine - and changed five of eight core facts (moon sign,
        dominant element, Human Design type, authority, strategy) with nothing marked.

        Solar noon is used as the reference instant. Planetary signs and longitudes are
        provisional reference-time values, not verified as stable across the whole day. Everything that depends on the earth's rotation within the day is
        withheld:

        **Seed and metadata**
        - `seed_context.time` is `null`, `seed_context.birth_time_known` is `false`,
          `seed_context.time_reference` is `civil_noon` (local civil 12:00, not solar noon)
        - `metadata.birth_time_known` is `false`

        **Western**
        - kept: `sun_sign`, `moon_sign`, planetary signs and longitudes
        - withheld: `rising_sign` / ascendant, `house_cusps`, `occupied_houses`, and the
          `house` field on each placement
        - the narrative section is written at the educational tier
          (`tier: "educational"`, `requires_birth_time: true`)

        **Human Design**
        - `type`, `authority`, `strategy` are `null`; `activeGates` and `defined_centers`
          are empty; the payload carries `reason: "birth_time_unknown"`
        - `general_information.methodologies[key=hd].status` is `unavailable` with
          `reason: "birth_time_unknown"`
        - the narrative section explains that a birth time is needed and asserts nothing

        **BaZi**
        - unaffected: the year, month and day pillars are date derived. The hour pillar was
          never computed; `hour_pillar_available: false` says so explicitly.

        **General information facts**
        - `western.rising_sign`, `hd.energy_type`, `hd.authority` and `hd.strategy` keep
          their place in `facts[]` but carry `status: "requires_birth_time"`,
          `value: null` and an explanatory `displayValue`

        **Renders**
        - `/render/{hash}/western` returns the sign-only educational wheel: no house
          segments, no `TIMED` stamp
        - `/render/{hash}/hd` returns `422` with `detail: "birth_time_unknown"`
        - `/render/{hash}/radar` and `/render/{hash}/bazi` are unaffected

        **Confidence**
        - the Western and Human Design methodology confidence carry an untimed penalty
          (`source_summary.untimed_penalty`)
      properties:
        birth_time_known:
          type: boolean
          enum: [false]
        reason:
          type: string
          enum: [birth_time_unknown]

    PartnerMatchRequest:
      type: object
      description: Provide two existing calculated report hashes. `hash_a/hash_b` and `hashes` are accepted aliases.
      properties:
        left_hash:
          type: string
          pattern: '^[a-f0-9]{24,32}$'
        right_hash:
          type: string
          pattern: '^[a-f0-9]{24,32}$'
        hash_a:
          type: string
          pattern: '^[a-f0-9]{24,32}$'
        hash_b:
          type: string
          pattern: '^[a-f0-9]{24,32}$'
        hashes:
          type: array
          minItems: 2
          maxItems: 2
          items:
            type: string
            pattern: '^[a-f0-9]{24,32}$'
        purpose:
          type: string
          enum: [dating_partner, dating, partner, relationship]
          default: dating_partner
        language:
          type: string
          enum: [en, de]
          default: en

    PartnerMatchResponse:
      type: object
      properties:
        schema_version: { type: string, example: '1.1.0' }
        scoring_version: { type: string }
        interpretation:
          type: object
          description: Explicit symbolic scope, score_is_probability=false and the confidence field's actual basis.
        purpose_display_label:
          type: string
          description: Localized UI label; purpose_label remains the canonical legacy label.
        matching_schema_version:
          type: string
          description: Partner matching factor-matrix schema version.
        status: { type: string, enum: [ok] }
        match_type: { type: string, enum: [partner_profile] }
        purpose: { type: string }
        purpose_label: { type: string }
        score:
          description: Symbolic model index, not measured ability or a probability.
          type: integer
          minimum: 0
          maximum: 100
        band:
          type: string
          enum: [exceptional, strong, supportive, mixed, low]
        confidence:
          description: Legacy model coverage or policy-cap field; not calibrated predictive confidence. See interpretation.confidence_basis.
          type: number
          minimum: 0
          maximum: 1
        identities:
          type: object
        vector_alignment:
          type: object
        complementarity:
          type: object
        methodology_alignment:
          $ref: '#/components/schemas/PartnerMatchMethodologyAlignment'
        strengths:
          type: array
          items: { type: string }
        cautions:
          type: array
          items: { type: string }
        narrative:
          type: string

    PartnerMatchMethodologyAlignment:
      type: object
      properties:
        schema_version: { type: string }
        score:
          type: integer
          nullable: true
          description: Null when no method can be compared; no neutral value is fabricated.
          minimum: 0
          maximum: 100
        available_methods:
          type: integer
          minimum: 0
          maximum: 3
        coverage:
          type: number
          minimum: 0
          maximum: 1
        western:
          $ref: '#/components/schemas/PartnerMatchMethodologyEntry'
        bazi:
          $ref: '#/components/schemas/PartnerMatchMethodologyEntry'
        human_design:
          $ref: '#/components/schemas/PartnerMatchMethodologyEntry'

    PartnerMatchMethodologyEntry:
      type: object
      properties:
        score:
          type: integer
          nullable: true
          minimum: 0
          maximum: 100
        status:
          type: string
          enum: [available, insufficient_data]
        coverage:
          type: number
          minimum: 0
          maximum: 1
        evidence:
          type: array
          items: { type: string }
        factors:
          type: array
          items:
            $ref: '#/components/schemas/PartnerMatchFactor'
        inputs:
          type: object
          additionalProperties: true

    PartnerMatchFactor:
      type: object
      properties:
        id: { type: string }
        label: { type: string }

    # Business / Work Match (prototype activation of businessWorkMatchingDataset)
    BusinessWorkMatchRequest:
      type: object
      description: Provide one existing calculated report hash plus either a curated role_archetype or custom_required_domains. Stage, seniority and environment are retained as unscored context. Requirements are unverified prompts, not submitted evidence.
      properties:
        hash:
          type: string
          pattern: '^[a-f0-9]{24,32}$'
        profile_hash:
          type: string
          pattern: '^[a-f0-9]{24,32}$'
        role_archetype:
          type: string
          description: Curated archetype id from the dataset (e.g. product_manager, engineering_builder, founder_operator)
        archetype:
          type: string
        role:
          type: string
        custom_required_domains:
          type: array
          minItems: 1
          maxItems: 18
          items:
            type: object
            properties:
              id: { type: string }
              weight: { type: number, minimum: 0, maximum: 1 }
        required_domains:
          type: array
          minItems: 1
          maxItems: 18
          items:
            type: object
            properties:
              id: { type: string }
              weight: { type: number, minimum: 0, maximum: 1 }
        business_stage:
          type: string
        stage:
          type: string
        seniority_level:
          type: string
        seniority:
          type: string
        environment_factors:
          type: array
          maxItems: 20
          items: { type: string, minLength: 1, maxLength: 80 }
        hard_requirements:
          type: array
          maxItems: 20
          items: { type: string, minLength: 1, maxLength: 80 }
        mode:
          type: string
          enum: [candidate_to_role, profile_to_business_stage]
          default: candidate_to_role
        language:
          type: string
          enum: [en, de]
          default: en
      example:
        hash: "cccccccccccccccccccccccc"
        role_archetype: "product_manager"
        mode: "candidate_to_role"

    BusinessWorkMatchResponse:
      type: object
      properties:
        schema_version: { type: string, example: '1.1.0' }
        scoring_version: { type: string }
        interpretation:
          type: object
          description: Explicit symbolic scope, score_is_probability=false and the confidence field's actual basis.
        purpose_display_label:
          type: string
          description: Localized UI label; purpose_label remains the canonical legacy label.
        dataset_schema_version:
          type: string
          description: businessWorkMatchingDataset schema version (1.4.0 at prototype activation).
        status: { type: string, enum: [ok] }
        match_type: { type: string, enum: [business_work] }
        mode: { type: string }
        purpose_label: { type: string }
        score:
          description: Symbolic model index, not measured ability or a probability.
          type: integer
          minimum: 0
          maximum: 100
        band:
          type: string
          enum: [exceptional, strong, meets, developing, insufficient]
        confidence:
          description: Legacy model coverage or policy-cap field; not calibrated predictive confidence. See interpretation.confidence_basis.
          type: number
          minimum: 0
          maximum: 1
        unscored_context:
          type: object
          description: Caller stage, seniority and environment context retained without numeric inference.
        profile:
          type: object
          properties:
            hash: { type: string }
            source: { type: string }
        role:
          type: object
          properties:
            id: { type: string }
            label: { type: string }
            display_label: { type: string }
            source: { type: string, enum: [archetype, custom] }
            vector_target: { type: object }
            required_domains: { type: array }
            hard_requirement_hints: { type: array, items: { type: string } }
        vector_fit:
          type: object
        domain_coverages:
          type: array
          items:
            type: object
            properties:
              domain: { type: string }
              label: { type: string }
              required_weight: { type: number }
              profile_strength: { type: number }
              coverage: { type: number }
              evidence_bonus: { type: number }
        gaps:
          type: array
          items:
            type: object
        risk_flags:
          type: array
          items: { type: string }
        evidence_quality:
          type: object
          properties:
            tier: { type: string }
            cap: { type: number }
            verified_work_evidence: { type: boolean, enum: [false] }
            description: { type: string }
        recommendation:
          type: object
          properties:
            type: { type: string, enum: [reflection_only] }
            label: { type: string }
            rationale: { type: string }
            rubric:
              type: object
        strengths:
          type: array
          items: { type: string }
        cautions:
          type: array
          items: { type: string }
        narrative:
          type: string
          description: Explainable narrative including strong disclaimers (not a hiring decision).
        citations:
          type: object
        generated_at: { type: string }

    ReportProvenance:
      type: object
      description: Stored source metadata captured before display-time defaults. Re-finalization preserves unknown source versions. This is not independent verification or a recalculation.
      properties:
        schema_version: { type: string, enum: [report-provenance/1] }
        provenance_status:
          type: string
          enum: [recorded_source_versions, incomplete_source_provenance, explicit_noncomputed_source]
        verification: { type: string, enum: [stored_metadata_only] }
        recomputed: { type: boolean, enum: [false] }
        source:
          type: object
          properties:
            schema_version: { type: string, nullable: true }
            synthesis_engine_version: { type: string, nullable: true }
            wording_version: { type: string, nullable: true }
            matrix_status: { type: string }

    ComposeResponse:
      type: object
      properties:
        interpretation_status:
          type: string
          enum: [available, unavailable]
          description: Availability of numeric synthesis, independently of calculation status. Absent on legacy reports. Unavailable means no personal scores, ranking, lens interpretation or generated personal imagery; underlying chart facts may still exist.
        interpretation_reason:
          type: string
          nullable: true
          enum: [no_effective_sources, birth_time_interval, invalid_birth_time_range, birth_time_range_source_conflict, null]
          description: No source with a positive effective weight supplied a usable score. Zero is a valid score and does not imply unavailability.
        report_provenance:
          $ref: '#/components/schemas/ReportProvenance'
        hologram_hash: { type: string }
        deterministic_matrix_status:
          type: string
          enum: [ok, mock, fallback, unavailable, unknown]
          description: |
            Trust marker for the deterministic matrix. Only `ok` means the numbers
            describe the person who was submitted. A missing or empty value
            finalizes as `unknown` (Wave 1.5) - absence of a status is never taken
            as proof of health. Anything other than `ok` degrades
            `profile_narrative`, `vectors[*].status` and `profile_views.*.status`
            to `unavailable` and replaces lens prose with pending copy.
        metadata:
          type: object
          properties:
            language:
              type: string
              enum: [en, de]
              description: Requested display language of this finalized response.
            compose_language:
              type: string
              enum: [en, de]
              description: Original composition language of the stored run. Switching the display language does not change it or recompute chart facts. Legacy records without language metadata fall back to the requested language; the original is then unknown.
            birth_time_known: { type: boolean }
            birth_time_range: { $ref: '#/components/schemas/CanonicalBirthTimeRange' }
            grounded_context_version:
              type: string
              enum: ['2.0.0']
              description: Server-owned new-compose rule profile; clients cannot select it. Both seed and metadata markers are required. Legacy stored profiles are never enriched.
            grounded_context_validation:
              type: object
              description: Rebuilt grounded-source-validation/v2 record of delivered envelope consistency, selected fact/rule/source/basis identities and eligibility dispositions. Refused or absent sources carry no stale personal claims. This is not independent agreement or read authorization.
        vectors:
          type: array
          items:
            $ref: '#/components/schemas/Vector'
        profile_views:
          $ref: '#/components/schemas/ProfileViews'
        seed_context:
          type: object
          description: |
            The seed the run was composed from. Wave 4.4: `time` is `null` and
            `birth_time_known` is `false` for an untimed run - it never echoes a
            substituted time. See the `UntimedContract` schema.
          properties:
            date: { type: string, format: date }
            time:
              type: string
              nullable: true
              description: '`null` when `birth_time_known` is false.'
            birth_time_known: { type: boolean }
            time_reference:
              type: string
              enum: [birth_time, civil_noon, solar_noon, birth_time_interval]
            birth_time_range: { $ref: '#/components/schemas/CanonicalBirthTimeRange' }
            grounded_context_version: { type: string, enum: ['2.0.0'] }
            timezone: { type: string }
            gender: { type: string }
            city: { type: string }
        summary:
          type: object
          properties:
            archetype: { type: string }
            holographic_summary: { type: string }
            synthesis_engine:
              type: string
              example: deterministic-composer
              description: |
                What composed the numerical synthesis. Optional language refinement can
                edit narrative text without recomputing chart facts; `composer_model` used to be stamped with the
                configured LiteLLM model name anyway and is now always `null` (S11).
            synthesis_engine_version:
              type: string
              description: Version recorded when this report was composed, preserved for historical reports. The currently observed calculation core is reported by `/health?format=json&runtime=1`; this is a separate identity.
            composer_model:
              type: string
              nullable: true
              deprecated: true
              description: Always `null`. Kept only so older readers see "no model".
        general_information:
          $ref: '#/components/schemas/GeneralInformation'
        methodologies:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/MethodologyStatus'
        report_evidence:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/MethodologyEvidence'
        grounded_context:
          allOf:
            - $ref: '#/components/schemas/GroundedContext'
          description: Optional stored, source-admitted context. The v1 major-aspect observation remains first; a server-owned v2 compose can add a recorded Mercury-motion observation when eligible. Missing legacy or stale context is never backfilled during a read. These observations are separate from optional language refinement and numerical synthesis.
        grounded_bazi_context:
          allOf:
            - $ref: '#/components/schemas/GroundedBaziContext'
          description: Optional recorded BaZi context. The v1 day-main hidden-stem/Ten God observation remains first; a server-owned v2 compose can add the strongest recorded weighted-element observation with its source arithmetic when eligible. Original Chinese records and explicit timing/day-boundary gates are required; missing legacy or stale context is never backfilled. Recorded weighted elements do not establish measured personality or predictive accuracy.
        grounded_hd_context:
          allOf:
            - $ref: '#/components/schemas/GroundedHdContext'
          description: Optional recorded Human Design context. The v1 Personality/Design Moon pair remains first; a server-owned v2 compose can add one canonical defined channel joined to its recorded gates, centers and activation witnesses when eligible. Exact original source, contribution, explicit timing and civil-time/UTC lineage are required. Missing legacy or stale context is omitted without backfill. Symbolic explanations do not establish personality or independent correctness.
        profile_narrative:
          $ref: '#/components/schemas/ProfileNarrative'
        sensitivity:
          $ref: '#/components/schemas/BirthIntervalSummary'
        visuals:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/VisualManifest'
        generated_imagery:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/VisualManifest'
        _debug:
          $ref: '#/components/schemas/DebugPayload'

    GroundedRecordedContextV2:
      type: object
      required: [schema_version, selection_rule_id, status, reason, facts, observations, selection_dispositions]
      description: |
        Server-owned v2 profile for new composes. The existing v1 fact/observation remains
        first and byte-exact. An eligible additional source-admitted fact/observation is
        second; unavailable context has empty fact/observation arrays. Both selection
        dispositions are recorded, including ineligibility reasons. Additional facts
        conservatively require the legacy context to be source-admitted and available.
        Replay of v1 never adds these fields or clauses. Delivery re-admits the whole
        stored envelope against its original raw source; symbolic explanations establish
        neither measured traits nor independent reference agreement.
      properties:
        schema_version: { type: string, enum: ['2.0.0'] }
        selection_rule_id: { type: string }
        status: { type: string, enum: [available, unavailable] }
        reason: { type: string, nullable: true }
        facts: { type: array, maxItems: 2, items: { type: object } }
        observations:
          type: array
          maxItems: 2
          items: { $ref: '#/components/schemas/GroundedAdditionalObservation' }
        selection_dispositions:
          type: array
          minItems: 2
          maxItems: 2
          items:
            type: object
            required: [selection_rule_id, status, reason, fact_ids]
            properties:
              selection_rule_id: { type: string }
              status: { type: string, enum: [selected, ineligible] }
              reason: { type: string, nullable: true }
              fact_ids: { type: array, items: { type: string } }
    GroundedWesternContextV2:
      allOf:
        - $ref: '#/components/schemas/GroundedRecordedContextV2'
        - type: object
          properties:
            selection_rule_id: { type: string, enum: ['western.recorded-observations/v2'] }
            facts:
              type: array
              maxItems: 2
              items:
                oneOf:
                  - $ref: '#/components/schemas/GroundedAspectFact'
                  - $ref: '#/components/schemas/GroundedWesternMotionFactV2'
    GroundedBaziContextV2:
      allOf:
        - $ref: '#/components/schemas/GroundedRecordedContextV2'
        - type: object
          properties:
            selection_rule_id: { type: string, enum: ['bazi.recorded-observations/v2'] }
            facts:
              type: array
              maxItems: 2
              items:
                oneOf:
                  - $ref: '#/components/schemas/GroundedBaziFact'
                  - $ref: '#/components/schemas/GroundedBaziWeightedElementFactV2'
    GroundedHdContextV2:
      allOf:
        - $ref: '#/components/schemas/GroundedRecordedContextV2'
        - type: object
          properties:
            selection_rule_id: { type: string, enum: ['hd.recorded-observations/v2'] }
            facts:
              type: array
              maxItems: 2
              items:
                oneOf:
                  - $ref: '#/components/schemas/GroundedHdFact'
                  - $ref: '#/components/schemas/GroundedHdChannelFactV2'
    GroundedAdditionalFactV2:
      type: object
      required: [id, type, methodology, value, units, source, calculation_basis, eligibility, uncertainty]
      properties:
        id: { type: string }
        type: { type: string }
        methodology: { type: string, enum: [western, chinese, hd] }
        value: { type: object }
        units: { type: string }
        source:
          type: object
          description: Exact recorded collection path, selector, field_names and join/reference collections. Source links open one explicit full-method read and verify every selected recorded value; a stale row is not highlighted.
        calculation_basis:
          type: object
          description: Exact recorded source engine/version, calculation UTC and relevant family basis; never regenerated as provider prose.
        eligibility:
          type: object
          required: [eligible, requires_birth_time, requires_legacy_context_available, evidence_tier]
          properties:
            eligible: { type: boolean, enum: [true] }
            requires_birth_time: { type: boolean, enum: [true] }
            requires_legacy_context_available: { type: boolean, enum: [true] }
            evidence_tier: { type: string, enum: [computed] }
        uncertainty:
          type: object
          description: Explicit timing, source lineage and not_assessed precision/boundary/independent-agreement qualifications. These clauses do not claim interval sensitivity.
    GroundedWesternMotionFactV2:
      allOf:
        - $ref: '#/components/schemas/GroundedAdditionalFactV2'
        - type: object
          properties:
            id: { type: string, enum: [western.mercury.recorded-motion] }
            type: { type: string, enum: [western.mercury_motion] }
            units: { type: string, enum: [degrees/day] }
            value:
              type: object
              required: [body, longitude, sign, retrograde, speed_deg_per_day]
              properties:
                body: { type: string, enum: [mercury] }
                longitude: { type: number, minimum: 0, maximum: 360 }
                sign: { type: string }
                retrograde: { type: boolean }
                speed_deg_per_day: { type: number, description: Signed recorded angular motion; genuine zero is retained. }
    GroundedBaziWeightedElementFactV2:
      allOf:
        - $ref: '#/components/schemas/GroundedAdditionalFactV2'
        - type: object
          properties:
            type: { type: string, enum: [bazi.weighted_element] }
            units: { type: string, enum: [weighted-count] }
            value:
              type: object
              required: [element, count, total, share_percent, counts, weight_basis, contributors]
              properties:
                element: { type: string, enum: [wood, fire, earth, metal, water] }
                count: { type: number, minimum: 0 }
                total: { type: number, minimum: 0 }
                share_percent: { type: number, minimum: 0, maximum: 100 }
                counts: { type: object, description: All five recorded weighted counts, including genuine zero. }
                weight_basis: { type: object, description: Recorded visible_stem 1, branch_main 1, branch_middle 0.4 and branch_residual 0.2. }
                contributors:
                  type: array
                  items:
                    type: object
                    required: [pillar_role, source_kind, hidden_stem_role, stem, element, weight]
                    properties:
                      pillar_role: { type: string, enum: [year, month, day, hour] }
                      source_kind: { type: string, enum: [visible, hidden] }
                      hidden_stem_role: { type: string, nullable: true, enum: [main, middle, residual, null] }
                      stem: { type: string }
                      element: { type: string, enum: [wood, fire, earth, metal, water] }
                      weight: { type: number }
    GroundedHdChannelFactV2:
      allOf:
        - $ref: '#/components/schemas/GroundedAdditionalFactV2'
        - type: object
          properties:
            type: { type: string, enum: [hd.defined_channel_relation] }
            units: { type: string, enum: [identifiers] }
            value:
              type: object
              required: [key, gates, centers, activation_witnesses]
              properties:
                key: { type: string }
                gates: { type: array, minItems: 2, maxItems: 2, items: { type: integer, minimum: 1, maximum: 64 } }
                centers: { type: array, minItems: 2, maxItems: 2, items: { type: string } }
                activation_witnesses:
                  type: array
                  items:
                    type: object
                    required: [side, body, gate, line, longitude]
                    properties:
                      side: { type: string, enum: [personality, design] }
                      body: { type: string }
                      gate: { type: integer, minimum: 1, maximum: 64 }
                      line: { type: integer, minimum: 1, maximum: 6 }
                      longitude: { type: number, minimum: 0, maximum: 360 }
    GroundedAdditionalObservation:
      type: object
      required: [id, fact_ids, interpretation_rule_id, general_meaning, in_this_report, qualification]
      properties:
        id: { type: string }
        fact_ids: { type: array, minItems: 1, maxItems: 1, items: { type: string } }
        interpretation_rule_id: { type: string }
        general_meaning: { $ref: '#/components/schemas/GroundedBilingualText' }
        in_this_report: { $ref: '#/components/schemas/GroundedBilingualText' }
        qualification: { $ref: '#/components/schemas/GroundedBilingualText' }
        reflection: { $ref: '#/components/schemas/GroundedBilingualText' }
    GroundedContext:
      oneOf:
        - $ref: '#/components/schemas/GroundedContextV1'
        - $ref: '#/components/schemas/GroundedWesternContextV2'
    GroundedContextV1:
      type: object
      additionalProperties: false
      required: [schema_version, selection_rule_id, status, reason, facts, observations]
      description: Available context has exactly one fact and observation; unavailable context has empty arrays. Public delivery regenerates and compares the stored contract against original raw source, contribution gates and explicit time flags. Structural consistency alone does not authenticate a source or authorize a report read.
      properties:
        schema_version: { type: string, enum: ['1.0.0'] }
        selection_rule_id: { type: string, enum: ['western.major_aspect.tightest-recorded/v1'] }
        status: { type: string, enum: [available, unavailable] }
        reason:
          type: string
          nullable: true
          enum: [matrix_not_trusted, source_unavailable, source_not_computed, source_excluded, birth_time_unknown, birth_time_unconfirmed, missing_calculation_provenance, no_eligible_aspect, null]
        facts:
          type: array
          maxItems: 1
          items:
            $ref: '#/components/schemas/GroundedAspectFact'
        observations:
          type: array
          maxItems: 1
          items:
            $ref: '#/components/schemas/GroundedAspectObservation'

    GroundedHdContext:
      oneOf:
        - $ref: '#/components/schemas/GroundedHdContextV1'
        - $ref: '#/components/schemas/GroundedHdContextV2'
    GroundedHdContextV1:
      type: object
      additionalProperties: false
      required: [schema_version, selection_rule_id, status, reason, facts, observations]
      description: Available has exactly one recorded Moon pair and one deterministic EN/DE explanation; unavailable has empty arrays. Stored delivery rebuilds source, UTC lineage and eligibility. Structural checks alone neither authenticate source nor authorize a read.
      properties:
        schema_version: { type: string, enum: ['1.0.0'] }
        selection_rule_id: { type: string, enum: ['hd.activation.moon-both-sides.recorded/v1'] }
        status: { type: string, enum: [available, unavailable] }
        reason:
          type: string
          nullable: true
          enum: [matrix_not_trusted, source_unavailable, source_not_computed, source_excluded, birth_time_unknown, birth_time_unconfirmed, missing_calculation_provenance, birth_instant_unconfirmed, birth_instant_conflict, source_conflict, no_eligible_activation, null]
        facts:
          type: array
          maxItems: 1
          items: { $ref: '#/components/schemas/GroundedHdFact' }
        observations:
          type: array
          maxItems: 1
          items: { $ref: '#/components/schemas/GroundedHdObservation' }

    GroundedHdMoonActivation:
      type: object
      additionalProperties: false
      required: [body, gate, line, longitude]
      properties:
        body: { type: string, enum: [moon] }
        gate: { type: integer, minimum: 1, maximum: 64 }
        line: { type: integer, minimum: 1, maximum: 6 }
        longitude: { type: number, minimum: 0, maximum: 360, exclusiveMaximum: true }

    GroundedHdFact:
      type: object
      additionalProperties: false
      required: [id, type, methodology, value, units, source, calculation_basis, eligibility, uncertainty]
      properties:
        id: { type: string, enum: [hd.activation.moon.personality-and-design] }
        type: { type: string, enum: [hd.moon_activation_pair] }
        methodology: { type: string, enum: [hd] }
        units: { type: string, enum: [degrees] }
        value:
          type: object
          additionalProperties: false
          required: [body, personality, design]
          properties:
            body: { type: string, enum: [moon] }
            personality: { $ref: '#/components/schemas/GroundedHdMoonActivation' }
            design: { $ref: '#/components/schemas/GroundedHdMoonActivation' }
        source:
          type: object
          additionalProperties: false
          required: [collection_path, selector, field_names, join, full_method_collections]
          properties:
            collection_path: { type: string, enum: [raw_engines.hd.personality] }
            selector: { type: object, properties: { body: { type: string, enum: [moon] } }, required: [body], additionalProperties: false }
            field_names: { type: array, items: { type: string } }
            join:
              type: object
              additionalProperties: false
              required: [collection_path, selector, field_names]
              properties:
                collection_path: { type: string, enum: [raw_engines.hd.design] }
                selector: { type: object, properties: { body: { type: string, enum: [moon] } }, required: [body], additionalProperties: false }
                field_names: { type: array, items: { type: string } }
            full_method_collections: { type: array, items: { type: string, enum: [personality, design] }, minItems: 2, maxItems: 2 }
        calculation_basis:
          type: object
          additionalProperties: false
          required: [engine_version, calculation_engine, hd_algorithm_version, node_model, provenance, calculation_time_utc, design_time_utc]
          properties:
            engine_version: { type: string, enum: ['repo-owned-deterministic/2.1.0'] }
            calculation_engine: { type: string, enum: [astronomy-engine] }
            hd_algorithm_version: { type: string, enum: ['rave-mandala/1.0'] }
            node_model: { type: string, enum: [mean] }
            provenance:
              type: object
              additionalProperties: false
              required: [engine, engine_version, method]
              properties:
                engine: { type: string, enum: [astronomy-engine] }
                engine_version: { type: string, enum: ['2.1.19'] }
                method: { type: string, enum: [rave-mandala] }
            calculation_time_utc: { type: string, format: date-time }
            design_time_utc: { type: string, format: date-time }
        eligibility:
          type: object
          additionalProperties: false
          required: [eligible, requires_birth_time, evidence_tier]
          properties:
            eligible: { type: boolean, enum: [true] }
            requires_birth_time: { type: boolean, enum: [true] }
            evidence_tier: { type: string, enum: [computed] }
        uncertainty:
          type: object
          additionalProperties: false
          required: [birth_time_known, birth_time_precision, boundary_sensitivity, civil_time_utc_lineage, design_utc_provenance, independent_agreement]
          properties:
            birth_time_known: { type: boolean, enum: [true] }
            birth_time_precision: { type: string, enum: [not_assessed] }
            boundary_sensitivity: { type: string, enum: [not_assessed] }
            civil_time_utc_lineage: { type: string, enum: [matched_to_recorded_birth_instant] }
            design_utc_provenance: { type: string, enum: [recorded_algorithm_only] }
            independent_agreement: { type: string, enum: [not_assessed] }

    GroundedHdObservation:
      type: object
      additionalProperties: false
      required: [id, fact_ids, interpretation_rule_id, general_meaning, in_this_report, qualification]
      properties:
        id: { type: string }
        fact_ids: { type: array, minItems: 1, maxItems: 1, items: { type: string, enum: [hd.activation.moon.personality-and-design] } }
        interpretation_rule_id: { type: string, enum: [hd.activation.moon-both-sides.table-explanation/v1] }
        general_meaning: { type: object, required: [en, de], additionalProperties: false, properties: { en: { type: string }, de: { type: string } } }
        in_this_report: { type: object, required: [en, de], additionalProperties: false, properties: { en: { type: string }, de: { type: string } } }
        qualification: { type: object, required: [en, de], additionalProperties: false, properties: { en: { type: string }, de: { type: string } } }

    GroundedBaziContext:
      oneOf:
        - $ref: '#/components/schemas/GroundedBaziContextV1'
        - $ref: '#/components/schemas/GroundedBaziContextV2'
    GroundedBaziContextV1:
      type: object
      additionalProperties: false
      required: [schema_version, selection_rule_id, status, reason, facts, observations]
      description: Available has exactly one recorded day-main joined fact and deterministic EN/DE observation; unavailable has empty arrays. Structural checks do not authenticate source lineage or authorize access. Stored delivery rebuilds the exact source, basis and gates; missing legacy context is never backfilled.
      properties:
        schema_version: { type: string, enum: ['1.0.0'] }
        selection_rule_id: { type: string, enum: ['bazi.hidden_stem.day-main.recorded/v1'] }
        status: { type: string, enum: [available, unavailable] }
        reason:
          type: string
          nullable: true
          enum: [matrix_not_trusted, source_unavailable, source_not_computed, source_excluded, birth_time_unknown, birth_time_unconfirmed, day_boundary_sensitive, day_boundary_unconfirmed, missing_calculation_provenance, source_conflict, no_eligible_hidden_stem, null]
        facts:
          type: array
          maxItems: 1
          items: { $ref: '#/components/schemas/GroundedBaziFact' }
        observations:
          type: array
          maxItems: 1
          items: { $ref: '#/components/schemas/GroundedBaziObservation' }

    GroundedBaziStem:
      type: object
      additionalProperties: false
      required: [stem, stem_hanzi, element, polarity]
      properties:
        stem: { type: string }
        stem_hanzi: { type: string }
        element: { type: string, enum: [wood, fire, earth, metal, water] }
        polarity: { type: string, enum: [yin, yang] }

    GroundedBaziFact:
      type: object
      additionalProperties: false
      required: [id, type, methodology, value, units, source, calculation_basis, eligibility, uncertainty]
      properties:
        id: { type: string, example: 'bazi.hidden_stem.day.main.jia.indirect_resource' }
        type: { type: string, enum: [bazi.hidden_stem_ten_god] }
        methodology: { type: string, enum: [chinese] }
        units: { type: string, enum: [dimensionless], description: The recorded weight has dimensionless units; other value fields are categorical identities. }
        value:
          type: object
          additionalProperties: false
          required: [pillar_role, hidden_stem_role, day_pillar, day_master, hidden_stem, ten_god, weight]
          properties:
            pillar_role: { type: string, enum: [day] }
            hidden_stem_role: { type: string, enum: [main] }
            weight: { type: number, enum: [1] }
            day_pillar:
              type: object
              additionalProperties: false
              required: [stem, stem_hanzi, branch, branch_hanzi, hanzi, element, polarity]
              properties:
                stem: { type: string }
                stem_hanzi: { type: string }
                branch: { type: string }
                branch_hanzi: { type: string }
                hanzi: { type: string }
                element: { type: string, enum: [wood, fire, earth, metal, water] }
                polarity: { type: string, enum: [yin, yang] }
            day_master: { $ref: '#/components/schemas/GroundedBaziStem' }
            hidden_stem: { $ref: '#/components/schemas/GroundedBaziStem' }
            ten_god:
              type: object
              additionalProperties: false
              required: [key, relation, name, hanzi, english]
              properties:
                key: { type: string, enum: [peer, rob_wealth, eating_god, hurting_officer, indirect_wealth, direct_wealth, seven_killings, direct_officer, indirect_resource, direct_resource] }
                relation: { type: string, enum: [parallel, resource, output, wealth, officer] }
                name: { type: string }
                hanzi: { type: string }
                english: { type: string }
        source:
          type: object
          additionalProperties: false
          required: [collection_path, selector, field_names, join, references, full_method_collections]
          properties:
            collection_path: { type: string, enum: [raw_engines.chinese.hidden_stems.day] }
            selector: { $ref: '#/components/schemas/GroundedBaziSelector' }
            field_names:
              type: array
              minItems: 9
              maxItems: 9
              items: { type: string, enum: [role, stem, stem_hanzi, element, polarity, weight, ten_god, ten_god_hanzi, ten_god_english] }
            join:
              type: object
              additionalProperties: false
              required: [collection_path, selector, field_names]
              properties:
                collection_path: { type: string, enum: [raw_engines.chinese.ten_gods.day.hidden] }
                selector: { $ref: '#/components/schemas/GroundedBaziSelector' }
                field_names:
                  type: array
                  minItems: 3
                  maxItems: 3
                  items: { type: string, enum: [role, stem, ten_god] }
            references:
              type: array
              minItems: 2
              maxItems: 2
              items:
                type: object
                additionalProperties: false
                required: [collection_path, field_names]
                properties:
                  collection_path: { type: string, enum: [raw_engines.chinese.pillars.day, raw_engines.chinese] }
                  field_names:
                    type: array
                    items: { type: string }
            full_method_collections:
              type: array
              minItems: 4
              maxItems: 4
              items: { type: string, enum: [pillars, day_master, hidden_stems, ten_gods] }
        calculation_basis:
          type: object
          additionalProperties: false
          required: [engine_version, calculation_engine, bazi_algorithm_version, provenance, time_basis, time_basis_offset_minutes, timezone_offset_minutes, local_solar_time]
          description: Exact current recorded Chinese-family basis. No calculation_time_utc or calculation_engine_version is invented for this raw shape.
          properties:
            engine_version: { type: string, enum: ['repo-owned-deterministic/2.1.0'] }
            calculation_engine: { type: string, enum: [astronomy-engine] }
            bazi_algorithm_version: { type: string, enum: ['four-pillars/1.0'] }
            provenance:
              type: object
              additionalProperties: false
              required: [engine, engine_version, method]
              properties:
                engine: { type: string, enum: [astronomy-engine] }
                engine_version: { type: string, enum: ['2.1.19'] }
                method: { type: string, enum: [four-pillars] }
            time_basis: { type: string, enum: [local_solar] }
            time_basis_offset_minutes: { type: integer, minimum: -720, maximum: 720 }
            timezone_offset_minutes: { type: integer, minimum: -840, maximum: 840 }
            local_solar_time: { type: string, pattern: '^(?:[01]\d|2[0-3]):[0-5]\d$' }
        eligibility:
          type: object
          additionalProperties: false
          required: [eligible, requires_birth_time, requires_recorded_day_boundary_false, evidence_tier]
          properties:
            eligible: { type: boolean, enum: [true] }
            requires_birth_time: { type: boolean, enum: [true] }
            requires_recorded_day_boundary_false: { type: boolean, enum: [true] }
            evidence_tier: { type: string, enum: [computed] }
        uncertainty:
          type: object
          additionalProperties: false
          required: [birth_time_known, day_pillar_boundary_sensitive, birth_time_precision, boundary_sensitivity, independent_agreement]
          properties:
            birth_time_known: { type: boolean, enum: [true] }
            day_pillar_boundary_sensitive: { type: boolean, enum: [false] }
            birth_time_precision: { type: string, enum: [not_assessed] }
            boundary_sensitivity: { type: string, enum: [not_assessed] }
            independent_agreement: { type: string, enum: [not_assessed] }

    GroundedBaziSelector:
      type: object
      additionalProperties: false
      required: [role, stem]
      properties:
        role: { type: string, enum: [main] }
        stem: { type: string }

    GroundedBaziObservation:
      type: object
      additionalProperties: false
      required: [id, fact_ids, interpretation_rule_id, general_meaning, in_this_report, qualification]
      properties:
        id: { type: string }
        fact_ids:
          type: array
          minItems: 1
          maxItems: 1
          items: { type: string }
        interpretation_rule_id: { type: string, enum: ['bazi.hidden_stem_ten_god.recorded-relation/v1'] }
        general_meaning: { $ref: '#/components/schemas/GroundedBilingualText' }
        in_this_report: { $ref: '#/components/schemas/GroundedBilingualText' }
        qualification: { $ref: '#/components/schemas/GroundedBilingualText' }

    GroundedAspectValue:
      type: object
      additionalProperties: false
      required: [bodies, type, angle_deg, orb_deg, orb_allowed_deg]
      properties:
        bodies:
          type: array
          minItems: 2
          maxItems: 2
          description: Canonical ASCII order, independent of source order. Together with type, identifies the raw aspect; reversed duplicates with contradictory values are refused.
          items: { type: string, enum: [sun, moon, mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto, asc, mc] }
        type: { type: string, enum: [conjunction, sextile, square, trine, opposition] }
        angle_deg: { type: number, enum: [0, 60, 90, 120, 180] }
        orb_deg: { type: number, minimum: 0, maximum: 10 }
        orb_allowed_deg: { type: number, minimum: 0, exclusiveMinimum: true, maximum: 10 }

    GroundedAspectFact:
      type: object
      additionalProperties: false
      required: [id, type, methodology, value, units, source, calculation_basis, eligibility, uncertainty]
      properties:
        id: { type: string, example: 'western.aspect.mars.square.venus' }
        type: { type: string, enum: [western.major_aspect] }
        methodology: { type: string, enum: [western] }
        value:
          $ref: '#/components/schemas/GroundedAspectValue'
        units: { type: string, enum: [degrees] }
        source:
          type: object
          additionalProperties: false
          required: [collection_path, selector, field_names, full_method_collection]
          properties:
            collection_path: { type: string, enum: [raw_engines.western.aspects] }
            selector:
              type: object
              additionalProperties: false
              required: [bodies, type]
              properties:
                bodies:
                  type: array
                  minItems: 2
                  maxItems: 2
                  items: { type: string }
                type: { type: string, enum: [conjunction, sextile, square, trine, opposition] }
            field_names:
              type: array
              minItems: 6
              maxItems: 6
              items: { type: string, enum: [a, b, type, angle, orb, orb_allowed] }
            full_method_collection: { type: string, enum: [aspects] }
        calculation_basis:
          type: object
          additionalProperties: false
          required: [calculation_engine, calculation_engine_version, engine_version, calculation_time_utc]
          properties:
            calculation_engine: { type: string }
            calculation_engine_version: { type: string }
            engine_version: { type: string }
            calculation_time_utc: { type: string, format: date-time }
        eligibility:
          type: object
          additionalProperties: false
          required: [eligible, requires_birth_time, evidence_tier]
          properties:
            eligible: { type: boolean, enum: [true] }
            requires_birth_time: { type: boolean, enum: [true] }
            evidence_tier: { type: string, enum: [computed] }
        uncertainty:
          type: object
          additionalProperties: false
          required: [birth_time_known, birth_time_precision, boundary_sensitivity, independent_agreement]
          properties:
            birth_time_known: { type: boolean, enum: [true] }
            birth_time_precision: { type: string, enum: [not_assessed] }
            boundary_sensitivity: { type: string, enum: [not_assessed] }
            independent_agreement: { type: string, enum: [not_assessed] }

    GroundedAspectObservation:
      type: object
      additionalProperties: false
      required: [id, fact_ids, interpretation_rule_id, general_meaning, in_this_report, reflection, qualification]
      properties:
        id: { type: string, example: 'observation.western.aspect.mars.square.venus' }
        fact_ids:
          type: array
          minItems: 1
          maxItems: 1
          items: { type: string }
        interpretation_rule_id: { type: string, example: 'western.major_aspect.square.reflection/v1' }
        general_meaning:
          $ref: '#/components/schemas/GroundedBilingualText'
        in_this_report:
          $ref: '#/components/schemas/GroundedBilingualText'
        reflection:
          $ref: '#/components/schemas/GroundedBilingualText'
        qualification:
          $ref: '#/components/schemas/GroundedBilingualText'

    GroundedBilingualText:
      type: object
      additionalProperties: false
      required: [en, de]
      properties:
        en: { type: string }
        de: { type: string }

    GeneralInformation:
      type: object
      properties:
        schema_version: { type: string }
        seed: { type: object }
        facts:
          type: array
          items:
            type: object
            properties:
              id: { type: string, example: western.sun_sign }
              methodology: { type: string, enum: [western, chinese, hd] }
              label: { type: string }
              value: { type: string, nullable: true }
              display_value: { type: string }
              status:
                type: string
                enum: [requires_birth_time]
                description: |
                  Present only on the facts that need a birth time
                  (`western.rising_sign`, `hd.energy_type`, `hd.authority`,
                  `hd.strategy`) when the run has none. `value` is then `null` and
                  `display_value` explains what is missing (Wave 4.4).
              reason:
                type: string
                enum: [birth_time_unknown]
              evidence_tier:
                allOf:
                  - $ref: '#/components/schemas/EvidenceTier'
                description: |
                  Inherited from the fact's own methodology (Wave 7L). A fact never
                  carries a tier of its own: `hd.*` facts are `symbolic` while the
                  Human Design engine is hash-derived, and `unavailable` on an
                  untimed run.
        methodologies:
          type: array
          description: One card per requested methodology, in `DEFAULT_ENGINES` order.
          items:
            $ref: '#/components/schemas/MethodologyStatus'
        birth_time_known:
          type: boolean
          description: Present and `false` for a run composed without a birth time.

    Vector:
      type: object
      description: One normalized 4ura signal axis.
      properties:
        key:
          type: string
          enum: [intuition, logic, passion, stability, creation, vitality]
        status:
          type: string
          enum: [available, unavailable]
          description: |
            `unavailable` whenever `deterministic_matrix_status` is not `ok`.
            The `value` is then a shape-stability placeholder, not a personal
            measurement, and must not be presented as one (Wave 1.4).
        label: { type: string }
        value:
          type: number
          minimum: 0
          maximum: 100
        band: { type: string }
        confidence:
          type: number
          nullable: true
          description: Internal model support; null means missing or invalid evidence, distinct from numeric zero. Not a calibrated accuracy probability.
          minimum: 0
          maximum: 1
        confidence_key: { type: string }
        confidence_label: { type: string }
        methodologies:
          type: array
          items: { type: string }
        contributions:
          type: object
          additionalProperties: { type: number }
        source_notes:
          type: array
          items: { type: string }

    ProfileViews:
      type: object
      description: |
        Per-lens read of the same vectors. `hr`, `private` and `other` are
        computed but not currently surfaced in the UI.
      properties:
        schema_version: { type: string }
        business: { $ref: '#/components/schemas/ProfileView' }
        hr: { $ref: '#/components/schemas/ProfileView' }
        dating: { $ref: '#/components/schemas/ProfileView' }
        personal: { $ref: '#/components/schemas/ProfileView' }
        private: { $ref: '#/components/schemas/ProfileView' }
        other: { $ref: '#/components/schemas/ProfileView' }

    ProfileView:
      type: object
      properties:
        key:
          type: string
          enum: [business, hr, dating, personal, private, other]
        status:
          type: string
          enum: [available, unavailable]
          description: |
            `unavailable` when `deterministic_matrix_status` is not `ok` or no
            methodology returned trustworthy evidence. `summary` then carries the
            localized pending copy and `strengths`/`risks` are empty (Wave 1.4).
        label: { type: string }
        description: { type: string }
        summary: { type: string }
        focus_scores:
          type: array
          items: { $ref: '#/components/schemas/ProfileViewScore' }
        growth_edges:
          type: array
          items: { $ref: '#/components/schemas/ProfileViewScore' }
        strengths:
          type: array
          items: { type: string }
        risks:
          type: array
          items: { type: string }
        evidence:
          type: object
          description: |
            Evidence lines keyed by methodology (`western`, `chinese`, `hd`), plus
            `evidence_tiers`: the resolved `EvidenceTier` per methodology for this run
            (Wave 7L), so a lens can mark the lines it drew from an uncomputed source.
          properties:
            evidence_tiers:
              type: object
              additionalProperties:
                $ref: '#/components/schemas/EvidenceTier'
          additionalProperties:
            type: array
            items: { type: string }

    ProfileViewScore:
      type: object
      properties:
        key: { type: string }
        label: { type: string }
        score: { type: number }
        contextual_score: { type: number }
        weight: { type: number }
        band: { type: string }
        confidence: { type: number, nullable: true, description: "Internal model support; null means missing or invalid evidence, not zero." }
        confidence_label: { type: string }
        confidence_display: { type: string }

    InternalAuthError:
      type: object
      properties:
        error:
          type: string
          example: Forbidden
        diagnostic:
          type: string
          example: Internal persistence routes require x-4ura-smoke-key, a valid SSO session, or an authorized internal API key.

    RecomposeResult:
      type: object
      description: The outcome of recomputing one stored run in place.
      properties:
        hashId:
          type: string
        previous_matrix_status:
          type: string
          nullable: true
          description: Stored `deterministic_matrix_status` before the recompose.
        new_matrix_status:
          type: string
          nullable: true
          description: |
            After the recompose. On a rollback this is the restored status, i.e.
            the previous one - the untrusted result is reported on the run event.
        duration_ms:
          type: integer
        ok:
          type: boolean
          description: True only when the recompose produced a trusted matrix.
        dry_run:
          type: boolean
          description: Present on a dry run.
        rolled_back:
          type: boolean
          description: The previous, trusted report was restored.
        reason:
          type: string
          description: Present only when `ok` is false.
          enum:
            - not_found
            - lookup_failed
            - seed_incomplete
            - no_restore_point
            - engine_unreachable
            - compose_failed
            - mock_result
            - rolled_back

    RenderErrorResponse:
      type: object
      properties:
        error: { type: string }
        reason:
          type: string
          nullable: true
          description: Machine-readable cause; birth_time_unknown for an untimed bodygraph or no_effective_sources for unavailable numeric synthesis.
        render_type:
          type: string
          enum: [radar, bazi, hd, western]
        detail:
          type: string
          description: |
            Present on 422 - names the field the builder could not read, or
            `birth_time_unknown` when the render cannot exist without a birth time
            (Wave 4.4).

    EvidenceTier:
      type: string
      enum: [computed, partial, symbolic, unavailable]
      description: |
        Wave 7L - how much of a methodology is actually computed, resolved from the
        engine payload's provenance. It is the honest counterpart to `status`, which
        only reports whether the source answered.

        * `computed` - real astronomy or real calendar arithmetic. Today: Western
          (sun through Mars plus the ascendant, from `astronomy-engine`).
        * `partial` - part of the family is computed, part is a deterministic
          stand-in. Today: Chinese BaZi, whose year pillar is genuine while the day
          and month stems come out of the repo-owned deterministic engine.
        * `symbolic` - structurally plausible, not computed from the sky. Today:
          Human Design in full. Kept because it is meaningful language, never
          presented as a measurement.
        * `unavailable` - nothing could be computed: no payload, or the input the
          family needs is missing (a bodygraph without a birth time).

        The tier is derived, never hardcoded per family: a family reaches `computed`
        by emitting `evidence_tier: computed` alongside a real ephemeris engine name.
        See `docs/METHODOLOGY_EVIDENCE_TIERS.md`.

    MethodologyStatus:
      type: object
      properties:
        key: { type: string }
        label: { type: string }
        requested: { type: boolean }
        status:
          type: string
          enum: [available, mock, unavailable, not_requested]
        display_status: { type: string }
        confidence:
          type: number
          nullable: true
          minimum: 0
          maximum: 1
          description: Internal rule-based model indicator; null means missing or invalid, not numeric zero or calibrated accuracy.
        confidence_label:
          type: string
          description: Recorded model category; empty when not reported. Not an independent verification result.
        weight:
          type: number
          nullable: true
          minimum: 0
          maximum: 1
          description: Recorded model blending share; null means missing or invalid, distinct from zero contribution.
        has_payload: { type: boolean }
        evidence_tier:
          $ref: '#/components/schemas/EvidenceTier'
        evidence_note:
          type: string
          description: |
            One localized sentence (per the requested `lang`) explaining the tier to a
            reader, e.g. "Diese Werte sind heute symbolisch und werden nicht aus dem
            Himmel berechnet; die echte Berechnung ist in Arbeit."
        contribution_factor:
          type: number
          minimum: 0
          maximum: 1
          description: |
            How much of this methodology's signal was allowed to move the six vectors:
            `computed` 1, `partial` 0.5, `symbolic` and `unavailable` 0. A methodology
            at 0 is listed and narrated but decides no number, and its `weight` is 0.

    MethodologyEvidence:
      type: object
      properties:
        key: { type: string }
        label: { type: string }
        status: { type: string }
        has_payload: { type: boolean }
        payload_preview: { type: object }
        highlights: { type: object }
        evidence_tier:
          $ref: '#/components/schemas/EvidenceTier'
        evidence_note:
          type: string
          description: The same localized one-sentence explainer as on `MethodologyStatus`.
        contribution_factor:
          type: number
          minimum: 0
          maximum: 1
        source_summary:
          type: object
          description: |
            Per-methodology evidence trace. Carries `provenance` (the Wave 4.3
            confidence tier) and a copy of `evidence_tier`. It never names an upstream
            library: every engine in the mesh is the same repo-owned deterministic
            service, so any upstream naming is stripped before the payload is built and
            survives only inside the API-key gated `_debug` block.

    ProfileNarrative:
      type: object
      properties:
        status:
          type: string
          enum: [available, unavailable]
        overview_text:
          type: string
          description: Human-readable profile overview. Current product contract targets at least 500 words when all three methods are available.
        overview_word_count:
          type: integer
          minimum: 500
        sections:
          type: array
          items:
            $ref: '#/components/schemas/ProfileNarrativeSection'

    ProfileNarrativeSection:
      type: object
      properties:
        key:
          type: string
          enum: [western, chinese, hd]
        title: { type: string }
        text:
          type: string
          description: Method-specific human-readable interpretation. Current product contract targets at least 300 words.
        word_count:
          type: integer
          minimum: 300
        facts:
          type: array
          items: { type: string }

    VisualManifest:
      type: object
      properties:
        type: { type: string }
        title: { type: string }
        status: { type: string }
        url: { type: string }

    DebugPayload:
      type: object
      description: Present only for `debug=1`; full `raw_engines` appears only for authorized `debug=1&raw=1` requests.
      properties:
        schema_version: { type: string }
        enabled: { type: boolean }
        gateway: { type: object }
        backend_connection: { type: object }
        methods: { type: object }
        raw_output_summary: { type: object }
        raw_engines: { type: object }

    CitySuggestion:
      type: object
      properties:
        id: { type: string }
        primary_name: { type: string }
        display_name: { type: string }
        source: { type: string }
        attribution: { type: string }
        source_snapshot: { type: string }
        country: { type: string }
        region: { type: string }
        lat: { type: number, minimum: -90, maximum: 90 }
        lng: { type: number, minimum: -180, maximum: 180 }
        timezone:
          type: string
          nullable: true
          description: Resolved named IANA timezone; unresolved provider results require explicit manual selection.

    HealthResponse:
      type: object
      description: |
        Returned by `GET /health?format=json`. `status` is derived from
        `engine.reachable`: a known-unreachable deterministic engine yields
        `DEGRADED`, everything else yields `OK`.
      properties:
        status:
          type: string
          enum: [OK, DEGRADED]
          description: '`DEGRADED` when `engine.reachable` is false.'
        visual_schema_version: { type: string }
        generated_imagery_schema_version: { type: string }
        release:
          type: object
          properties:
            version: { type: string }
            revision: { type: string }
            channel:
              type: string
              enum: [stable, alpha]
              description: |
                Runtime channel of this process. One image serves both: `stable` is
                the public app, `alpha` requires a private account for reports.
        engine:
          $ref: '#/components/schemas/EngineHealth'
        observability:
          type: object
          description: Counter and event snapshot from ObservabilityService.
          properties:
            counters:
              type: object
              additionalProperties:
                type: integer
              description: |
                Includes `engine_unavailable_mock`, which is counted as a fallback
                so the degradation alert threshold can fire on an engine outage.
            engine:
              $ref: '#/components/schemas/EngineHealth'

    EngineHealth:
      type: object
      description: |
        Reachability of the deterministic engine cluster. All fields are `null`
        until the first compose of the process has touched the engine.
      properties:
        reachable:
          type: boolean
          nullable: true
          description: '`null` = not yet observed since boot; `false` = last call failed.'
        last_ok_at:
          type: string
          format: date-time
          nullable: true
        last_failure_at:
          type: string
          format: date-time
          nullable: true
        last_transition_at:
          type: string
          format: date-time
          nullable: true
        consecutive_failures:
          type: integer
          minimum: 0
        last_error:
          type: string
          nullable: true

        runtime_identity:
          $ref: '#/components/schemas/RuntimeEngineIdentity'

    RuntimeEngineIdentity:
      type: object
      required: [version, status, checked_at, expires_at, source]
      description: |
        Optional engine.runtime_identity when health is requested with format=json&runtime=1.
        Observed from the configured core health endpoint, bounded by a 2-second deadline
        including its JSON body. A successful observation is cached for at most 15 seconds;
        failed/unknown observations carry null rather than a numeric placeholder. This is
        not the app version, a library/schema version or the provenance of a stored report.
      properties:
        version: { type: string, nullable: true, maxLength: 120 }
        status: { type: string, enum: [available, unavailable, unknown] }
        checked_at: { type: string, format: date-time }
        expires_at: { type: string, format: date-time }
        source: { type: string, enum: [configured_engine_health] }

    PublicHandleResponse:
      type: object
      properties:
        status: { type: string, enum: [resolved] }
        handle: { type: string }
        verified: { type: boolean }
        linked_seeds:
          type: array
          items:
            type: object
            properties:
              created_at: { type: string, format: date-time }
              source: { type: string }
              metadata:
                type: object
                properties:
                  city: { type: string }
                  status: { type: string }
                  hash: { type: string }
                  language: { type: string }

    StatusNotFoundResponse:
      type: object
      required: [status]
      properties:
        status:
          type: string
          enum: [not_found]
        hologram_hash:
          type: string
        error:
          type: object
          properties:
            code:
              type: string
              enum: [not_found]
            message:
              type: string
              description: Plain-language explanation in the requested language.

    StatusUnavailableResponse:
      type: object
      required: [status, error]
      properties:
        status:
          type: string
          enum: [temporarily_unavailable]
        hologram_hash:
          type: string
        hash:
          type: string
          description: Methodology routes use this alias for the report reference.
        error:
          type: object
          required: [code, message]
          properties:
            code:
              type: string
              enum: [storage_unavailable]
            message:
              type: string
              description: Plain-language retrieval failure in the requested language.

    StatusFailedResponse:
      type: object
      required: [status, hologram_hash, error]
      properties:
        status:
          type: string
          enum: [failed]
        hologram_hash:
          type: string
        error:
          type: object
          required: [code, message]
          properties:
            code:
              type: string
              enum: [orchestration_timeout, orchestration_failed, fallback_failed, stale_processing_timeout]
              description: Stable failure code. `stale_processing_timeout` is set by the stale-run sweeper for runs interrupted by a restart.
            message:
              type: string
              description: Plain-language explanation in the requested language (`lang`), safe to show to end users.

    LabelledKey:
      type: object
      description: |
        A machine key with its reader-facing word in the requested language. Every
        enumerable value in the methodology documents is shaped like this, so a client
        matches on `key` and prints `label` without owning a translation table.
      properties:
        key:
          type: string
          description: Stable identifier, e.g. `scorpio`, `mean_node`, `solar_plexus`, `rob_wealth`.
        label:
          type: string
          description: The same value in the language given by `?lang`.

    DataCompleteness:
      type: string
      enum: [complete, partial, stub_era, unavailable]
      description: |
        How much of a methodology the stored run actually holds. Distinct from
        `evidence_tier`, which says how *real* the material is rather than how much of
        it there is.

        * `complete` - the family named the engine that computed it and every block is
          present.
        * `partial` - the engine ran but withheld part of the family, almost always
          because the run has no birth time (no angles, no houses, no hour pillar).
        * `stub_era` - the run was stored before the Wave 7A/7B/7C engine rebuild. Those
          payloads carry a fraction of today's fields; the endpoint returns what exists
          rather than failing.
        * `unavailable` - the run holds no payload for this family at all.

    MethodologyEnvelope:
      type: object
      description: The header every methodology document carries, index and detail alike.
      properties:
        birth_time_range: { $ref: '#/components/schemas/CanonicalBirthTimeRange' }
        sensitivity: { $ref: '#/components/schemas/BirthIntervalFamilySensitivity' }
        schema_version: { type: string, example: "1.1.7" }
        hash: { type: string }
        method:
          type: string
          enum: [western, bazi, human_design]
        label:
          type: string
          description: The methodology's name in the requested language.
        language:
          type: string
          enum: [en, de]
        status:
          type: string
          enum: [available, mock, unavailable, not_requested]
        birth_time_known: { type: boolean }
        evidence_tier:
          $ref: '#/components/schemas/EvidenceTier'
        evidence_tier_label: { type: string }
        evidence_note:
          type: string
          description: One localized sentence explaining the tier to a reader.
        contribution_factor:
          type: number
          minimum: 0
          maximum: 1
          description: |
            How much of this methodology was allowed to move the six vectors: `computed`
            1, `partial` 0.5, `symbolic`/`unavailable` 0. An existing policy gate, not
            observational evidence - always a number, never `null`. Only actual finite
            numbers in [0, 1] are admitted. Malformed input is 0. If original report
            evidence records a factor, the lower of both stored gates wins; neither
            can override the other's exclusion.
        confidence:
          type: number
          nullable: true
          minimum: 0
          maximum: 1
          description: |
            The methodology's own model-support indicator, in [0, 1]. `null` when the
            recorded value was absent, blank, a boolean, non-numeric, non-finite or
            out of range; a genuine `0` is preserved.
        data_completeness:
          $ref: '#/components/schemas/DataCompleteness'
        data_completeness_label: { type: string }
        engine_version: { type: string, nullable: true }
        generated_at:
          type: string
          format: date-time
          description: When this document was rendered. A cached document keeps the timestamp it was built with.
        provenance:
          type: object
          description: |
            What computed this family. `calculation_engine` names the real ephemeris
            (e.g. `astronomy-engine`), which is how a family proves it reached the
            `computed` tier. Any upstream library claim is still rewritten to
            `repo-owned-deterministic` before it reaches a reader.
          properties:
            calculation_engine: { type: string, nullable: true }
            calculation_engine_version: { type: string, nullable: true }
            calculation_time_utc: { type: string, format: date-time, nullable: true }
            algorithm_version:
              type: string
              nullable: true
              description: The per-family algorithm, e.g. `rave-mandala/1.0` or `four-pillars/1.0`.
            engine: { type: string, nullable: true }
            engine_version: { type: string, nullable: true }
            method: { type: string, nullable: true }
            deterministic_matrix_status: { type: string }

    MethodologyIndex:
      type: object
      properties:
        schema_version: { type: string }
        hash: { type: string }
        language: { type: string, enum: [en, de] }
        birth_time_known: { type: boolean }
        engine_version: { type: string, nullable: true }
        deterministic_matrix_status: { type: string }
        generated_at: { type: string, format: date-time }
        methods:
          type: array
          items:
            $ref: '#/components/schemas/MethodologyIndexEntry'

    MethodologyIndexEntry:
      type: object
      properties:
        key: { type: string, enum: [western, bazi, human_design] }
        label: { type: string }
        slug:
          type: string
          enum: [western, bazi, human-design]
          description: The path segment of this family's detail document.
        aliases:
          type: array
          items: { type: string }
          description: Other path segments that resolve to the same document (`chinese`, `hd`).
        requested: { type: boolean }
        status: { type: string }
        evidence_tier: { $ref: '#/components/schemas/EvidenceTier' }
        evidence_tier_label: { type: string }
        evidence_note: { type: string }
        contribution_factor: { type: number, minimum: 0, maximum: 1 }
        confidence: { type: number, nullable: true, minimum: 0, maximum: 1 }
        weight:
          type: number
          nullable: true
          minimum: 0
          description: |
            A recorded, unbounded nonnegative blend coefficient (e.g. a legacy `1.18`).
            Not a percentage and never clamped or renormalized; `null` when the recorded
            value was absent, blank, a boolean, non-numeric, non-finite or negative. A
            genuine `0` is preserved.
        birth_time_known: { type: boolean }
        available:
          type: boolean
          description: |
            Whether the detail document exists. `false` means the detail route answers
            404 (no payload) or 422 (Human Design without a birth time); `unavailable_reason`
            says which.
        unavailable_reason:
          type: string
          nullable: true
          enum: [birth_time_unknown, engine_payload_missing, null]
        data_completeness: { $ref: '#/components/schemas/DataCompleteness' }
        data_completeness_label: { type: string }
        engine_version: { type: string, nullable: true }
        href:
          type: string
          description: Relative URL of the detail document, with the current `lang` already applied.

    MethodUnavailableResponse:
      type: object
      description: |
        The 422 answer for a methodology that cannot exist for this run. Not a fault:
        the run is fine, the input the family needs is simply missing.
      required: [status, hash, method, reason]
      properties:
        status: { type: string, enum: [unavailable] }
        hash: { type: string }
        method: { type: string, enum: [human_design] }
        language: { type: string, enum: [en, de] }
        reason: { type: string, enum: [birth_time_unknown] }
        message:
          type: string
          description: Plain-language explanation in the requested language.
        birth_time_known: { type: boolean, enum: [false] }
        evidence_tier: { $ref: '#/components/schemas/EvidenceTier' }
        generated_at: { type: string, format: date-time }

    WesternPlacement:
      type: object
      properties:
        body:
          allOf: [{ $ref: '#/components/schemas/LabelledKey' }]
          description: "One of: sun, moon, mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto, mean_node, rising."
        sign: { allOf: [{ $ref: '#/components/schemas/LabelledKey' }], nullable: true }
        longitude:
          type: number
          nullable: true
          minimum: 0
          maximum: 360
          description: Ecliptic longitude in degrees, 0-360, six decimals. Missing or malformed recorded values are null.
        degree_in_sign:
          type: number
          nullable: true
          minimum: 0
          maximum: 30
          description: Position inside the sign, 0-30. Missing or malformed recorded values are null.
        house:
          type: integer
          nullable: true
          minimum: 1
          maximum: 12
          description: "`null` on an untimed run: without an ascendant there are no houses."
        retrograde: { type: boolean, nullable: true }
        speed_deg_per_day:
          type: number
          nullable: true
          description: Apparent daily motion. Negative means retrograde. Absent for the ascendant.

    WesternAngle:
      type: object
      properties:
        key: { type: string, enum: [asc, mc, dc, ic] }
        label: { type: string }
        longitude: { type: number, nullable: true, minimum: 0, maximum: 360 }
        sign: { allOf: [{ $ref: '#/components/schemas/LabelledKey' }], nullable: true }
        degree_in_sign: { type: number, nullable: true, minimum: 0, maximum: 30 }

    WesternHouseCusp:
      type: object
      properties:
        house: { type: integer, minimum: 1, maximum: 12 }
        label: { type: string, description: "Canonical English name, e.g. `1st House`." }
        longitude: { type: number, nullable: true, minimum: 0, maximum: 360 }
        sign: { allOf: [{ $ref: '#/components/schemas/LabelledKey' }], nullable: true }
        degree_in_sign: { type: number, nullable: true, minimum: 0, maximum: 30 }
        title:
          type: string
          description: The house's theme, localized from `src/data/westernHouses.js`.
        life_theme:
          type: string
          description: What that house covers in everyday terms, localized.
        angularity: { type: string, nullable: true, enum: [angular, succedent, cadent, null] }
        quadrant: { type: string, nullable: true }
        polarity: { type: string, nullable: true }

    WesternAspect:
      type: object
      properties:
        bodies:
          type: array
          minItems: 2
          maxItems: 2
          items: { $ref: '#/components/schemas/LabelledKey' }
        type: { $ref: '#/components/schemas/LabelledKey' }
        angle: { type: number, nullable: true, minimum: 0, maximum: 180, description: "Degrees; normally 0, 60, 90, 120 or 180. Missing or malformed input is null." }
        orb: { type: number, nullable: true, minimum: 0, maximum: 180, description: Degrees away from exact. }
        orb_allowed: { type: number, nullable: true, minimum: 0, maximum: 180, description: The tolerance this pair was tested against. }
        applying:
          type: boolean
          nullable: true
          description: True when the aspect is tightening rather than separating.

    ScoreEntry:
      type: object
      properties:
        key: { type: string }
        label: { type: string }
        value: { type: number, minimum: 0 }

    PercentageScoreEntry:
      allOf:
        - $ref: '#/components/schemas/ScoreEntry'
        - type: object
          properties:
            value: { type: number, minimum: 0, maximum: 100 }
      description: An absolute percentage share. Invalid entries are omitted; partial lists are never renormalized.

    NonNegativeNumericMap:
      type: object
      nullable: true
      additionalProperties: { type: number, nullable: true, minimum: 0 }
      description: Recorded nonnegative coefficients, without rounding or normalization. Invalid scalar values remain null; a malformed container is null.

    WesternMethodology:
      allOf:
        - $ref: '#/components/schemas/MethodologyEnvelope'
        - type: object
          properties:
            grounded_context:
              allOf:
                - $ref: '#/components/schemas/GroundedContext'
              description: Optional source-admitted stored context. An explicit source-navigation read checks its fact values and calculation basis against the displayed observation. Missing or stale context cannot authenticate a source link; other full chart details remain readable.
            chart:
              type: object
              properties:
                sun_sign: { allOf: [{ $ref: '#/components/schemas/LabelledKey' }], nullable: true }
                moon_sign: { allOf: [{ $ref: '#/components/schemas/LabelledKey' }], nullable: true }
                rising_sign:
                  allOf: [{ $ref: '#/components/schemas/LabelledKey' }]
                  nullable: true
                ascendant_longitude: { type: number, nullable: true, minimum: 0, maximum: 360 }
                obliquity_degrees:
                  type: number
                  nullable: true
                  minimum: 0
                  maximum: 90
                  description: True obliquity of the ecliptic at the birth instant.
                house_system:
                  allOf: [{ $ref: '#/components/schemas/LabelledKey' }]
                  nullable: true
                time_reference:
                  allOf: [{ $ref: '#/components/schemas/LabelledKey' }]
                  description: "`birth_time` on a timed run, `civil_noon` (local civil 12:00) on a new untimed run; `solar_noon` is a legacy stored alias for that same reference."
            placements:
              type: array
              items: { $ref: '#/components/schemas/WesternPlacement' }
            angles:
              type: object
              nullable: true
              description: "`null` on an untimed run."
              additionalProperties: { $ref: '#/components/schemas/WesternAngle' }
            houses:
              type: object
              nullable: true
              description: "`null` on an untimed run."
              properties:
                system: { $ref: '#/components/schemas/LabelledKey' }
                anchor: { type: string, nullable: true }
                fallback_reason:
                  type: string
                  nullable: true
                  enum: [placidus_undefined_at_latitude, placidus_numerical_nonconvergence, null]
                  description: Present when Placidus is undefined at this latitude and equal houses were used instead.
                fallback_note: { type: string, nullable: true }
                cusps:
                  type: array
                  minItems: 12
                  maxItems: 12
                  items: { $ref: '#/components/schemas/WesternHouseCusp' }
            aspects:
              type: array
              description: Sorted by orb, tightest first. Empty on an untimed run.
              items: { $ref: '#/components/schemas/WesternAspect' }
            element_scores:
              type: array
              description: Fire, earth, air and water as percentage shares, ranked.
              items: { $ref: '#/components/schemas/PercentageScoreEntry' }
            modality_scores:
              type: array
              description: Cardinal, fixed and mutable as percentage shares, ranked.
              items: { $ref: '#/components/schemas/PercentageScoreEntry' }
            uncertainty:
              type: object
              description: What an untimed chart cannot pin down. All fields are inert on a timed run.
              properties:
                moon_precision: { type: string, nullable: true, enum: [day_level, null] }
                moon_sign_uncertain:
                  type: boolean
                  description: True when the Moon changes sign on the birth day.
                moon_sign_alternatives:
                  type: array
                  items: { $ref: '#/components/schemas/LabelledKey' }
                sign_uncertain_bodies:
                  type: array
                  items: { $ref: '#/components/schemas/LabelledKey' }
                sign_alternatives:
                  type: object
                  nullable: true
                sign_uncertainty_interval:
                  type: object
                  nullable: true
                  description: Actual local civil-day UTC bounds scanned for sign alternatives; null for timed or legacy records. The end is exclusive.
                  properties:
                    start_utc: { type: string, format: date-time, nullable: true }
                    end_utc: { type: string, format: date-time, nullable: true }
                    timezone: { type: string, nullable: true }
                    basis: { type: string, nullable: true, enum: [local_civil_day, null] }
            unavailable_fields:
              type: array
              items: { type: string }
            unavailable_reason: { type: string, nullable: true, enum: [birth_time_unknown, null] }
            unavailable_note: { type: string, nullable: true }

    BaziPillar:
      type: object
      properties:
        role: { type: string, enum: [year, month, day, hour, cycle] }
        role_label: { type: string }
        available: { type: boolean }
        hanzi: { type: string, nullable: true, description: The two characters of the pillar. }
        stem:
          type: object
          description: The visible heavenly stem.
          properties:
            key: { type: string, nullable: true }
            romanization: { type: string, nullable: true, description: "Pinyin, e.g. `Ding`." }
            hanzi: { type: string, nullable: true }
            element: { allOf: [{ $ref: '#/components/schemas/LabelledKey' }], nullable: true }
            polarity: { allOf: [{ $ref: '#/components/schemas/LabelledKey' }], nullable: true }
        branch:
          type: object
          description: The earthly branch and the animal it carries.
          properties:
            key: { type: string, nullable: true }
            romanization: { type: string, nullable: true }
            hanzi: { type: string, nullable: true }
            element: { allOf: [{ $ref: '#/components/schemas/LabelledKey' }], nullable: true }
            polarity: { allOf: [{ $ref: '#/components/schemas/LabelledKey' }], nullable: true }
            animal: { allOf: [{ $ref: '#/components/schemas/LabelledKey' }], nullable: true }
        sexagenary_index: { type: integer, nullable: true, minimum: 0, maximum: 59 }
        bazi_year: { type: integer, nullable: true, description: "Year pillar only: the Lichun-adjusted year. A recorded safe integer; no modern-year range is imposed." }
        solar_term: { type: string, description: "Month pillar only." }
        solar_term_hanzi: { type: string, nullable: true }
        month_ordinal: { type: integer, nullable: true, minimum: 1, maximum: 12 }
        julian_day_number: { type: integer, nullable: true, description: "Day pillar only. A recorded signed safe integer; missing or malformed input is null." }

    BaziMethodology:
      allOf:
        - $ref: '#/components/schemas/MethodologyEnvelope'
        - type: object
          properties:
            grounded_bazi_context:
              allOf: [{ $ref: '#/components/schemas/GroundedBaziContext' }]
              description: Optional source-admitted stored BaZi observation. A fresh authorized source read must also match actual day pillar, Day Master, main hidden-stem row, joined day Ten God row and recorded calculation basis. Same fact ID alone does not authenticate the source.
            day_master:
              type: object
              description: The day stem, the reference point of the whole chart.
              properties:
                element: { allOf: [{ $ref: '#/components/schemas/LabelledKey' }], nullable: true }
                stem: { type: string, nullable: true }
                stem_hanzi: { type: string, nullable: true }
                polarity: { allOf: [{ $ref: '#/components/schemas/LabelledKey' }], nullable: true }
                strength: { allOf: [{ $ref: '#/components/schemas/LabelledKey' }], nullable: true }
                strength_score: { type: number, nullable: true, minimum: 0, maximum: 1 }
                strength_method: { type: string, nullable: true }
                strength_basis:
                  type: object
                  nullable: true
                  description: The arithmetic behind the strength label - season relation, ally share and their weights.
                  properties:
                    season_component: { type: number, nullable: true, minimum: 0, maximum: 1 }
                    ally_share: { type: number, nullable: true, minimum: 0, maximum: 1 }
                    ally_component: { type: number, nullable: true, minimum: 0, maximum: 1 }
                    weights: { $ref: '#/components/schemas/NonNegativeNumericMap' }
            year_animal: { allOf: [{ $ref: '#/components/schemas/LabelledKey' }], nullable: true }
            dominant_element: { allOf: [{ $ref: '#/components/schemas/LabelledKey' }], nullable: true }
            strongest_element: { allOf: [{ $ref: '#/components/schemas/LabelledKey' }], nullable: true }
            weakest_element: { allOf: [{ $ref: '#/components/schemas/LabelledKey' }], nullable: true }
            pillars:
              type: object
              properties:
                year: { $ref: '#/components/schemas/BaziPillar' }
                month: { $ref: '#/components/schemas/BaziPillar' }
                day: { $ref: '#/components/schemas/BaziPillar' }
                hour:
                  allOf: [{ $ref: '#/components/schemas/BaziPillar' }]
                  nullable: true
                  description: "`null` when the run has no birth time. Never a substituted pillar."
            eight_char:
              type: string
              nullable: true
              description: The pillar characters, space separated. Three pillars on an untimed run.
            hidden_stems:
              type: object
              additionalProperties:
                type: array
                items:
                  type: object
                  properties:
                    weight: { type: number, nullable: true, minimum: 0 }
              description: |
                Per pillar role, the stems hidden inside the branch with their weight
                (main 1, middle 0.4, residual 0.2) and the ten god each one is.
            ten_gods:
              type: object
              description: Per pillar role, the ten god of the visible stem and of the hidden stems.
            element_counts:
              type: array
              items: { $ref: '#/components/schemas/ScoreEntry' }
            element_shares:
              type: array
              items: { $ref: '#/components/schemas/PercentageScoreEntry' }
            element_count_total: { type: number, nullable: true, minimum: 0 }
            element_count_basis:
              allOf: [{ $ref: '#/components/schemas/NonNegativeNumericMap' }]
              nullable: true
              description: 'The weight each source contributed, e.g. `visible_stem` 1 and `branch_residual` 0.2.'
            solar_terms:
              type: object
              nullable: true
              properties:
                year_boundary_utc: { type: string, format: date-time, nullable: true }
                month_boundary_utc: { type: string, format: date-time, nullable: true }
                next_boundary_utc: { type: string, format: date-time, nullable: true }
                current_term: { type: string, nullable: true }
                next_term: { type: string, nullable: true }
                sun_longitude_deg: { type: number, nullable: true, minimum: 0, maximum: 360 }
            time_basis:
              type: object
              description: BaZi is read in local solar time, not political clock time.
              properties:
                basis: { allOf: [{ $ref: '#/components/schemas/LabelledKey' }], nullable: true }
                offset_minutes: { type: integer, nullable: true, description: "Signed recorded minutes; absent or malformed values are null, not UTC zero." }
                timezone_offset_minutes: { type: integer, nullable: true, description: "Signed recorded minutes; absent or malformed values are null, not UTC zero." }
                local_solar_time: { type: string, nullable: true }
            boundaries:
              type: object
              description: |
                Whether a small error in the birth moment would move a pillar. A `true`
                flag means the pillar sits close to a solar-term or day boundary.
            hour_pillar_available: { type: boolean }
            hour_pillar_reason:
              type: string
              nullable: true
              enum: [birth_time_unknown, stub_era_payload, null]
            hour_pillar_note: { type: string, nullable: true }
            luck_cycles:
              type: object
              nullable: true
              description: |
                The decade cycles. `stretch` is always `true`: they are a projection from
                a boundary distance, not an observation.
              properties:
                available: { type: boolean }
                stretch: { type: boolean, enum: [true] }
                reason: { type: string, nullable: true, enum: [birth_time_unknown, gender_unknown, boundary_unresolved, null] }
                reason_note: { type: string, nullable: true }
                direction: { allOf: [{ $ref: '#/components/schemas/LabelledKey' }], nullable: true }
                start_age: { type: number, nullable: true, minimum: 0 }
                days_to_boundary: { type: number, nullable: true, minimum: 0 }
                boundary_utc: { type: string, format: date-time, nullable: true }
                cycles:
                  type: array
                  items:
                    allOf:
                      - $ref: '#/components/schemas/BaziPillar'
                      - type: object
                        properties:
                          index: { type: integer, nullable: true, minimum: 1 }
                          start_age: { type: number, nullable: true, minimum: 0 }

    HdCenter:
      type: object
      properties:
        key:
          type: string
          enum: [head, ajna, throat, g, heart, spleen, sacral, solar_plexus, root]
        label: { type: string }
        defined:
          type: boolean
          description: A center is defined when at least one of its channels is complete.
        activated_gates:
          type: array
          items: { type: integer, minimum: 1, maximum: 64 }
          description: The gates of this center this chart activated.
        gate_count: { type: integer }
        gates:
          type: array
          items: { type: integer }
          description: Every gate that belongs to this center, activated or not.

    HdActivation:
      type: object
      properties:
        body: { $ref: '#/components/schemas/LabelledKey' }
        gate: { type: integer, nullable: true, minimum: 1, maximum: 64 }
        line: { type: integer, nullable: true, minimum: 1, maximum: 6 }
        longitude: { type: number, nullable: true, minimum: 0, maximum: 360 }
        center:
          allOf: [{ $ref: '#/components/schemas/LabelledKey' }]
          nullable: true
          description: The center this gate belongs to.

    HumanDesignMethodology:
      allOf:
        - $ref: '#/components/schemas/MethodologyEnvelope'
        - type: object
          properties:
            type: { allOf: [{ $ref: '#/components/schemas/LabelledKey' }], nullable: true }
            strategy: { allOf: [{ $ref: '#/components/schemas/LabelledKey' }], nullable: true }
            authority: { allOf: [{ $ref: '#/components/schemas/LabelledKey' }], nullable: true }
            authority_detail:
              type: string
              nullable: true
              description: "Which center the authority sits in, e.g. `Emotional (Solar Plexus)`."
            profile: { type: string, nullable: true, description: "Personality and design Sun lines, e.g. `6/2`." }
            definition: { allOf: [{ $ref: '#/components/schemas/LabelledKey' }], nullable: true }
            not_self_theme: { allOf: [{ $ref: '#/components/schemas/LabelledKey' }], nullable: true }
            signature: { allOf: [{ $ref: '#/components/schemas/LabelledKey' }], nullable: true }
            centers:
              type: array
              minItems: 9
              maxItems: 9
              description: All nine centers in bodygraph order, defined or not.
              items: { $ref: '#/components/schemas/HdCenter' }
            defined_center_count: { type: integer }
            active_gates:
              type: array
              description: Strict recorded integers. Invalid scalar input is omitted; actual legacy out-of-range integers remain visible as unassigned.
              items: { type: integer }
            active_gate_count: { type: integer }
            unassigned_gates:
              type: array
              items: { type: integer }
              description: |
                Stored gates outside 1-64. Empty for every chart the current engine
                produced; a run from before the rebuild can carry them and they are
                reported rather than dropped.
            channels:
              type: array
              items:
                type: object
                properties:
                  key: { type: string, description: "The two gates, e.g. `5-15`." }
                  gates: { type: array, items: { type: integer } }
                  centers:
                    type: array
                    items: { $ref: '#/components/schemas/LabelledKey' }
            activations:
              type: object
              properties:
                personality:
                  type: object
                  properties:
                    key: { type: string, enum: [personality] }
                    label: { type: string }
                    time_utc: { type: string, format: date-time, nullable: true }
                    bodies:
                      type: array
                      items: { $ref: '#/components/schemas/HdActivation' }
                design:
                  type: object
                  description: The chart at the moment the Sun stood 88 degrees of solar arc before birth.
                  properties:
                    key: { type: string, enum: [design] }
                    label: { type: string }
                    time_utc: { type: string, format: date-time, nullable: true }
                    bodies:
                      type: array
                      items: { $ref: '#/components/schemas/HdActivation' }
            grounded_hd_context:
              allOf: [{ $ref: '#/components/schemas/GroundedHdContext' }]
              description: Exact admitted stored envelope; missing or stale legacy context is omitted.
            design_time_utc: { type: string, format: date-time, nullable: true }
            node_model: { type: string, nullable: true, enum: [mean, true, null] }
            incarnation_cross:
              type: object
              nullable: true
              properties:
                gates:
                  type: array
                  description: Four gates on a current complete chart; partial legacy records retain their validated integer list without invented replacements.
                  items: { type: integer }
                angle: { allOf: [{ $ref: '#/components/schemas/LabelledKey' }], nullable: true }
            unavailable_fields:
              type: array
              items: { type: string }
            unavailable_reason: { type: string, nullable: true }
