{
  "openapi": "3.1.0",
  "info": {
    "title": "PHASE developer preview",
    "version": "0.1.0-preview",
    "description": "Limited, authenticated research simulations. No measured circadian phase, observed-sleep assimilation, clinical validation, billing, or SLA. Use synthetic inputs."
  },
  "servers": [
    {
      "url": "/",
      "description": "This developer-preview origin"
    }
  ],
  "paths": {
    "/v0/phase/sleep-light-options": {
      "post": {
        "operationId": "analyzeSleepLightOptions",
        "summary": "Generate and compare simulated sleep/light options",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SleepLightRequest"
              },
              "example": {
                "metadata": {
                  "mode": "SIMULATION"
                },
                "trip": {
                  "origin_timezone": "America/New_York",
                  "destination_timezone": "Asia/Seoul",
                  "legs": [
                    {
                      "departure_at": "2027-02-10T00:30:00-05:00",
                      "arrival_at": "2027-02-11T05:00:00+08:00"
                    },
                    {
                      "departure_at": "2027-02-11T08:15:00+08:00",
                      "arrival_at": "2027-02-11T12:45:00+09:00"
                    }
                  ]
                },
                "baseline_schedule": {
                  "sleep_start_local": "23:00",
                  "sleep_end_local": "07:00",
                  "awake_lux": 150
                },
                "target_schedule": {
                  "sleep_start_local": "00:00",
                  "sleep_end_local": "08:00",
                  "awake_lux": 150
                },
                "candidate_policy": {
                  "sleep_leg_index": 0,
                  "sleep_durations_minutes": [
                    360,
                    480
                  ],
                  "placements": [
                    "EARLY",
                    "LATE"
                  ],
                  "margin_minutes": 30,
                  "light_windows": [
                    {
                      "id": "morning",
                      "start_local": "09:00",
                      "end_local": "13:00",
                      "lux": 500,
                      "stage": "POST_ARRIVAL"
                    },
                    {
                      "id": "afternoon",
                      "start_local": "13:00",
                      "end_local": "17:00",
                      "lux": 500,
                      "stage": "POST_ARRIVAL"
                    },
                    {
                      "id": "cabin-evening",
                      "stage": "SLEEP_LEG",
                      "start_local": "19:00",
                      "end_local": "21:00",
                      "lux": 100
                    }
                  ],
                  "cabin_awake_lux": 10,
                  "postarrival_awake_lux": 100
                },
                "evaluation": {
                  "days_after_arrival": 3,
                  "initial_s_range": [
                    0,
                    1
                  ],
                  "phase_shifts_hours": [
                    -2,
                    0,
                    2
                  ]
                },
                "hard_constraints": {
                  "locked_blocks": []
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Unranked options, no feasible options, or model withholding. Clinical validity is never implied.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SleepLightResponse"
                }
              }
            }
          },
          "400": {
            "description": "Unsupported or invalid simulation input",
            "headers": {},
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PreviewError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired key",
            "headers": {},
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PreviewError"
                }
              }
            }
          },
          "403": {
            "description": "Cross-origin browser request denied",
            "headers": {},
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PreviewError"
                }
              }
            }
          },
          "413": {
            "description": "JSON body exceeds64KiB",
            "headers": {},
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PreviewError"
                }
              }
            }
          },
          "429": {
            "description": "Quota exceeded; see Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds until the limiting fixed window resets"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PreviewError"
                }
              }
            }
          },
          "503": {
            "description": "Storage, runtime or calculation unavailable/timeout",
            "headers": {},
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PreviewError"
                }
              }
            }
          }
        },
        "security": [
          {
            "PreviewKey": []
          }
        ],
        "description": "SIMULATION only.6 calls/minute and30/day/key,30/day/IP,200/day service-wide. Body≤64KiB. UTC day/fixed minute windows. Invalid authenticated requests may consume quota. Calculation deadline2seconds; population model, no best option selected."
      }
    },
    "/v0/phase/preview-keys": {
      "post": {
        "operationId": "issuePreviewKey",
        "summary": "Issue an expiring preview key",
        "security": [],
        "description": "One-time key return,24-hour expiry.3 issues/day/IP and100/day globally. Empty JSON object required. No signup/payment.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "maxProperties": 0
              },
              "example": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "Store the returned key safely; it cannot be retrieved again.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "api_key",
                    "expires_at",
                    "limits"
                  ],
                  "properties": {
                    "api_key": {
                      "type": "string"
                    },
                    "expires_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "limits": {
                      "type": "object",
                      "properties": {
                        "requests_per_minute": {
                          "const": 6
                        },
                        "requests_per_day": {
                          "const": 30
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Issuance quota exceeded; Retry-After applies."
          },
          "503": {
            "description": "Preview access storage unavailable."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "RegularSchedule": {
        "type": "object",
        "properties": {
          "sleep_start_local": {
            "type": "string",
            "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$",
            "description": "HH:MM local recurring clock. Equal start/end is invalid; overnight windows are supported."
          },
          "sleep_end_local": {
            "type": "string",
            "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$",
            "description": "HH:MM local recurring clock. Equal start/end is invalid; overnight windows are supported."
          },
          "awake_lux": {
            "type": "number",
            "minimum": 1,
            "maximum": 1000
          }
        },
        "required": [
          "sleep_start_local",
          "sleep_end_local",
          "awake_lux"
        ]
      },
      "Leg": {
        "type": "object",
        "properties": {
          "departure_at": {
            "type": "string",
            "format": "date-time",
            "description": "Offset-aware ISO 8601 timestamp; compare elapsed time in UTC."
          },
          "arrival_at": {
            "type": "string",
            "format": "date-time",
            "description": "Offset-aware ISO 8601 timestamp; compare elapsed time in UTC."
          }
        },
        "required": [
          "departure_at",
          "arrival_at"
        ],
        "description": "Positive duration <=24h. Legs are chronological and do not overlap. Entire itinerary <=72h."
      },
      "Trip": {
        "type": "object",
        "properties": {
          "origin_timezone": {
            "type": "string",
            "example": "America/New_York",
            "description": "Valid IANA timezone."
          },
          "destination_timezone": {
            "type": "string",
            "example": "Asia/Seoul",
            "description": "Valid IANA timezone. All generated recurring action clocks use this zone."
          },
          "legs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Leg"
            },
            "minItems": 1,
            "maxItems": 4
          }
        },
        "required": [
          "origin_timezone",
          "destination_timezone",
          "legs"
        ]
      },
      "LightWindow": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{1,40}$"
          },
          "stage": {
            "type": "string",
            "enum": [
              "POST_ARRIVAL",
              "SLEEP_LEG"
            ],
            "default": "POST_ARRIVAL"
          },
          "start_local": {
            "type": "string",
            "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$",
            "description": "HH:MM local recurring clock. Equal start/end is invalid; overnight windows are supported."
          },
          "end_local": {
            "type": "string",
            "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$",
            "description": "HH:MM local recurring clock. Equal start/end is invalid; overnight windows are supported."
          },
          "lux": {
            "type": "number",
            "minimum": 0,
            "maximum": 1000
          }
        },
        "required": [
          "id",
          "start_local",
          "end_local",
          "lux"
        ],
        "description": "One simulated light intervention per candidate; IDs unique. POST_ARRIVAL recurs until evaluation horizon; SLEEP_LEG clips to the selected flight leg. Conflicting/no-exposure candidates are excluded, not silently shortened around sleep. Light IDs are case-insensitively unique. Lux may be below the ambient assumption: the kind is a light-exposure option, not proof of increased brightness."
      },
      "CandidatePolicy": {
        "type": "object",
        "properties": {
          "sleep_leg_index": {
            "type": "integer",
            "minimum": 0,
            "maximum": 3
          },
          "sleep_durations_minutes": {
            "type": "array",
            "items": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1440
            },
            "minItems": 1,
            "uniqueItems": true,
            "maxItems": 2
          },
          "placements": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "EARLY",
                "LATE"
              ]
            },
            "minItems": 1,
            "uniqueItems": true,
            "maxItems": 2
          },
          "margin_minutes": {
            "type": "number",
            "minimum": 0,
            "maximum": 240
          },
          "light_windows": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LightWindow"
            },
            "minItems": 0,
            "default": [],
            "maxItems": 3
          },
          "cabin_awake_lux": {
            "type": "number",
            "minimum": 0,
            "maximum": 1000
          },
          "postarrival_awake_lux": {
            "type": "number",
            "minimum": 0,
            "maximum": 1000
          }
        },
        "required": [
          "sleep_leg_index",
          "sleep_durations_minutes",
          "placements",
          "margin_minutes",
          "cabin_awake_lux",
          "postarrival_awake_lux"
        ],
        "description": "Generates at most16 candidates: up to2 durations x2 placements x(DIM control+3 light windows). Too-long sleep is excluded. Not a medical optimizer."
      },
      "Evaluation": {
        "type": "object",
        "properties": {
          "days_after_arrival": {
            "type": "integer",
            "minimum": 1,
            "maximum": 5,
            "default": 3
          },
          "initial_s_range": {
            "type": "array",
            "items": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "minItems": 2,
            "default": [
              0,
              1
            ],
            "maxItems": 2
          },
          "phase_shifts_hours": {
            "type": "array",
            "items": {
              "type": "number",
              "minimum": -3,
              "maximum": 3
            },
            "minItems": 1,
            "uniqueItems": true,
            "default": [
              -2,
              0,
              2
            ],
            "maxItems": 3
          }
        },
        "required": [],
        "description": "Initial S lower<=upper; shift list must include0. Ranges/schedule shifts are simulation assumptions, not measured phase or confidence intervals."
      },
      "LockedBlock": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{1,40}$"
          },
          "start_at": {
            "type": "string",
            "format": "date-time",
            "description": "Offset-aware ISO 8601 timestamp; compare elapsed time in UTC."
          },
          "end_at": {
            "type": "string",
            "format": "date-time",
            "description": "Offset-aware ISO 8601 timestamp; compare elapsed time in UTC."
          }
        },
        "required": [
          "id",
          "start_at",
          "end_at"
        ],
        "description": "Unique ID; positive interval within first departure through evaluation horizon."
      },
      "SleepLightRequest": {
        "type": "object",
        "properties": {
          "metadata": {
            "type": "object",
            "properties": {
              "mode": {
                "type": "string",
                "const": "SIMULATION"
              }
            },
            "required": [
              "mode"
            ]
          },
          "trip": {
            "$ref": "#/components/schemas/Trip"
          },
          "baseline_schedule": {
            "$ref": "#/components/schemas/RegularSchedule"
          },
          "target_schedule": {
            "$ref": "#/components/schemas/RegularSchedule"
          },
          "candidate_policy": {
            "$ref": "#/components/schemas/CandidatePolicy"
          },
          "evaluation": {
            "$ref": "#/components/schemas/Evaluation"
          },
          "hard_constraints": {
            "type": "object",
            "properties": {
              "locked_blocks": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/LockedBlock"
                },
                "minItems": 0,
                "default": [],
                "maxItems": 32
              }
            },
            "required": []
          }
        },
        "required": [
          "metadata",
          "trip",
          "baseline_schedule",
          "target_schedule",
          "candidate_policy"
        ],
        "description": "Research simulations only. No identity, token, wearable records or observed-sleep assimilation. Local stateless calculation; not the existing observation-based feasibility planner.",
        "additionalProperties": false
      },
      "LocalTime": {
        "type": "object",
        "properties": {
          "at": {
            "type": "string",
            "format": "date-time",
            "description": "Offset-aware ISO 8601 timestamp; compare elapsed time in UTC."
          },
          "timezone": {
            "type": "string"
          },
          "utc_offset": {
            "type": "string",
            "example": "+0900"
          }
        },
        "required": [
          "at",
          "timezone",
          "utc_offset"
        ]
      },
      "Window": {
        "type": "object",
        "properties": {
          "start_at": {
            "type": "string",
            "format": "date-time",
            "description": "Offset-aware ISO 8601 timestamp; compare elapsed time in UTC."
          },
          "end_at": {
            "type": "string",
            "format": "date-time",
            "description": "Offset-aware ISO 8601 timestamp; compare elapsed time in UTC."
          },
          "duration_minutes": {
            "type": "number",
            "minimum": 0,
            "maximum": 10000
          },
          "local": {
            "type": "object",
            "properties": {
              "start": {
                "$ref": "#/components/schemas/LocalTime"
              },
              "end": {
                "$ref": "#/components/schemas/LocalTime"
              }
            },
            "required": [
              "start",
              "end"
            ]
          },
          "lux": {
            "type": "number",
            "minimum": 0,
            "maximum": 1000
          },
          "kind": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "stage": {
            "type": "string",
            "enum": [
              "POST_ARRIVAL",
              "SLEEP_LEG"
            ]
          }
        },
        "required": [
          "start_at",
          "end_at",
          "duration_minutes",
          "local"
        ]
      },
      "PhaseSensitivity": {
        "type": "object",
        "properties": {
          "phase_shift_hours": {
            "type": "number",
            "minimum": -3,
            "maximum": 3
          },
          "dayN_cbtmin_offset_hours": {
            "type": "number",
            "minimum": -12,
            "maximum": 12
          },
          "paired_control_improvement_hours": {
            "type": "number",
            "minimum": -12,
            "maximum": 12
          }
        },
        "required": [
          "phase_shift_hours",
          "dayN_cbtmin_offset_hours",
          "paired_control_improvement_hours"
        ]
      },
      "Metrics": {
        "type": "object",
        "properties": {
          "arrival_process_s": {
            "type": "object",
            "properties": {
              "lower": {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              },
              "upper": {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              }
            },
            "required": [
              "lower",
              "upper"
            ],
            "description": "Normalized Process S state interval at final arrival; not probability, fatigue score, or a confidence interval."
          },
          "dayN_cbtmin_offset_hours": {
            "type": "number",
            "minimum": -12,
            "maximum": 12,
            "description": "Signed wrapped24h model CBT-min phase distance to separately initialized destination target near dayN. Not measured body temperature."
          },
          "paired_control_improvement_hours": {
            "type": "number",
            "minimum": -12,
            "maximum": 12,
            "description": "Absolute control distance minus absolute candidate distance, same sleep and starting clock. Positive means closer at this horizon, not proven clinical benefit."
          },
          "phase_sensitivity": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PhaseSensitivity"
            },
            "minItems": 1,
            "maxItems": 3
          }
        },
        "required": [
          "arrival_process_s",
          "dayN_cbtmin_offset_hours",
          "paired_control_improvement_hours",
          "phase_sensitivity"
        ]
      },
      "Option": {
        "type": "object",
        "properties": {
          "option_id": {
            "type": "string",
            "description": "Deterministic response-local candidate identifier, not a persistent global user/decision ID."
          },
          "kind": {
            "type": "string",
            "enum": [
              "DIM_CONTROL",
              "LIGHT_EXPOSURE_OPTION"
            ]
          },
          "comparison": {
            "type": "object",
            "properties": {
              "control_option_id": {
                "type": "string"
              },
              "same_sleep_candidate": {
                "type": "string"
              }
            },
            "required": [
              "control_option_id",
              "same_sleep_candidate"
            ]
          },
          "sleep_windows": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Window"
            },
            "minItems": 1,
            "maxItems": 1
          },
          "light_windows": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Window"
            },
            "minItems": 0
          },
          "target_sleep_windows": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Window"
            },
            "minItems": 0
          },
          "metrics": {
            "$ref": "#/components/schemas/Metrics"
          },
          "robust_benefit": {
            "type": "boolean",
            "description": "True only for a light intervention with both negative and positive tested shifts and improvement >0.25h at every supplied shift including0. Engineering sensitivity flag; never clinical benefit/confidence."
          },
          "robust_benefit_threshold_hours": {
            "type": "number",
            "const": 0.25
          }
        },
        "required": [
          "option_id",
          "kind",
          "comparison",
          "sleep_windows",
          "light_windows",
          "target_sleep_windows",
          "metrics",
          "robust_benefit",
          "robust_benefit_threshold_hours"
        ]
      },
      "ExcludedOption": {
        "type": "object",
        "properties": {
          "option_id": {
            "type": "string"
          },
          "reason": {
            "type": "string"
          },
          "conflict_refs": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "minItems": 0
          }
        },
        "required": [
          "option_id",
          "reason",
          "conflict_refs"
        ]
      },
      "SleepLightResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "OPTIONS_AVAILABLE",
              "NO_FEASIBLE_OPTIONS",
              "WITHHELD"
            ]
          },
          "metadata": {
            "type": "object",
            "properties": {
              "mode": {
                "const": "SIMULATION"
              },
              "version": {
                "const": "phase-sleep-light-options/v1"
              },
              "scope": {
                "type": "string"
              },
              "model_source_pin": {
                "type": "string"
              },
              "observed_fitting": {
                "const": false
              },
              "medical_or_clinical_prediction": {
                "const": false
              },
              "marker_status": {
                "type": "string",
                "enum": [
                  "USABLE",
                  "UNUSABLE"
                ]
              },
              "evaluation": {
                "type": "object",
                "properties": {
                  "arrival_at": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Offset-aware ISO 8601 timestamp; compare elapsed time in UTC."
                  },
                  "objective_at": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Offset-aware ISO 8601 timestamp; compare elapsed time in UTC."
                  },
                  "days_after_arrival": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 5
                  },
                  "display_timezone": {
                    "type": "string"
                  }
                },
                "required": [
                  "arrival_at",
                  "objective_at",
                  "days_after_arrival",
                  "display_timezone"
                ]
              }
            },
            "required": [
              "mode",
              "version",
              "observed_fitting",
              "medical_or_clinical_prediction",
              "marker_status",
              "evaluation"
            ]
          },
          "options": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Option"
            },
            "minItems": 0,
            "maxItems": 16
          },
          "excluded_options": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExcludedOption"
            },
            "minItems": 0,
            "maxItems": 16
          },
          "assumptions": {
            "$ref": "#/components/schemas/Assumptions"
          },
          "unverified_inputs": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "minItems": 1
          },
          "coverage": {
            "type": "object",
            "properties": {
              "observed": {
                "const": false
              },
              "all_inputs_assumed": {
                "const": true
              },
              "not_observed": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "minItems": 0
              }
            },
            "required": [
              "observed",
              "all_inputs_assumed"
            ]
          },
          "limitations": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "minItems": 1
          }
        },
        "required": [
          "status",
          "metadata",
          "options",
          "excluded_options",
          "assumptions",
          "unverified_inputs",
          "coverage",
          "limitations"
        ],
        "description": "WITHHELD suppresses all options when required model markers are unusable. NO_FEASIBLE_OPTIONS is a conditional schedule result. OPTIONS_AVAILABLE never means observed or clinically validated."
      },
      "Error": {
        "type": "object",
        "properties": {
          "status": {
            "const": "error"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "status",
          "message"
        ]
      },
      "AssumedSchedule": {
        "type": "object",
        "properties": {
          "sleep_start_local": {
            "type": "string",
            "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$",
            "description": "HH:MM local recurring clock. Equal start/end is invalid; overnight windows are supported."
          },
          "sleep_end_local": {
            "type": "string",
            "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$",
            "description": "HH:MM local recurring clock. Equal start/end is invalid; overnight windows are supported."
          },
          "awake_lux": {
            "type": "number",
            "minimum": 1,
            "maximum": 1000
          },
          "timezone": {
            "type": "string",
            "description": "IANA zone of the assumed recurring schedule."
          }
        },
        "required": [
          "sleep_start_local",
          "sleep_end_local",
          "awake_lux",
          "timezone"
        ]
      },
      "Assumptions": {
        "type": "object",
        "properties": {
          "baseline_warmup_days": {
            "type": "integer",
            "const": 35
          },
          "warmup_not_a_convergence_claim": {
            "type": "boolean",
            "const": true
          },
          "baseline_schedule": {
            "$ref": "#/components/schemas/AssumedSchedule"
          },
          "target_schedule": {
            "$ref": "#/components/schemas/AssumedSchedule"
          },
          "flight_sleep_lux": {
            "type": "number",
            "const": 0
          },
          "cabin_awake_lux": {
            "type": "number",
            "minimum": 0,
            "maximum": 1000
          },
          "postarrival_awake_lux": {
            "type": "number",
            "minimum": 0,
            "maximum": 1000
          },
          "initial_s_range": {
            "type": "array",
            "items": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "minItems": 2,
            "default": [
              0,
              1
            ],
            "maxItems": 2
          },
          "phase_shifts_hours": {
            "type": "array",
            "items": {
              "type": "number",
              "minimum": -3,
              "maximum": 3
            },
            "minItems": 1,
            "uniqueItems": true,
            "default": [
              -2,
              0,
              2
            ],
            "maxItems": 3
          },
          "transfers_assumed_awake": {
            "type": "boolean",
            "const": true
          },
          "hard_constraints": {
            "type": "string",
            "description": "Caller-provided constraints only; not a verified complete calendar."
          },
          "initial_s_range_interpretation": {
            "type": "string"
          },
          "comparison_threshold": {
            "type": "object",
            "properties": {
              "hours": {
                "type": "number",
                "const": 0.25
              },
              "meaning": {
                "type": "string"
              }
            },
            "required": [
              "hours",
              "meaning"
            ]
          },
          "single_intervention": {
            "type": "string"
          }
        },
        "required": [
          "baseline_warmup_days",
          "warmup_not_a_convergence_claim",
          "baseline_schedule",
          "target_schedule",
          "flight_sleep_lux",
          "cabin_awake_lux",
          "postarrival_awake_lux",
          "initial_s_range",
          "phase_shifts_hours",
          "transfers_assumed_awake",
          "hard_constraints",
          "initial_s_range_interpretation",
          "comparison_threshold",
          "single_intervention"
        ],
        "description": "Explicit simulation assumptions echoed from normalized caller input. No measurement/fitting is implied."
      },
      "PreviewError": {
        "type": "object",
        "required": [
          "status",
          "message"
        ],
        "properties": {
          "status": {
            "const": "error"
          },
          "message": {
            "type": "string"
          }
        }
      }
    },
    "securitySchemes": {
      "PreviewKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "phase_preview_<random key>",
        "description": "Issue a24-hour key with POST /v0/phase/preview-keys. Keep out of public code."
      }
    }
  }
}
