subsystem: schema_bible
schema:
- id: schema_character_phase
  model: CharacterPhase
  file: recoil/pipeline/_lib/render_schema.py::CharacterPhase
  reduced_tier: never
  fields:
  - name: phase_id
    type: str
    meaning: Unique wardrobe or appearance phase identifier.
    semantic: null
    dup_tier: never
  - name: start_ep
    type: int
    meaning: First episode where this phase applies.
    semantic: null
    dup_tier: never
  - name: end_ep
    type: int
    meaning: Last episode where this phase applies.
    semantic: null
    dup_tier: never
  - name: phase_trigger_event
    type: str
    meaning: Legacy prose reason the phase changed.
    semantic: null
    dup_tier: never
  - name: wardrobe_description
    type: str
    meaning: Legacy full wardrobe description for the phase.
    semantic: null
    dup_tier: never
  - name: wardrobe_arc_delta
    type: str
    meaning: Structured wardrobe additions, removals, or modifications from the prior phase.
    semantic: wardrobe_arc
    dup_tier: always
  - name: wardrobe_arc_carries
    type: str
    meaning: Wardrobe items carried forward unchanged from the prior phase.
    semantic: wardrobe_arc
    dup_tier: always
  - name: hair_makeup
    type: str
    meaning: Hair and makeup notes for this phase.
    semantic: null
    dup_tier: never
  - name: distinguishing_marks
    type: str
    meaning: Mutable scars, injuries, or accumulated damage for this phase.
    semantic: marks
    dup_tier: always
  - name: trigger
    type: Optional['PhaseTrigger']
    meaning: Structured evidence-backed trigger for the phase.
    semantic: null
    dup_tier: never
  - name: appearance
    type: Optional['PhaseAppearance']
    meaning: Structured phase appearance block alongside legacy prose.
    semantic: null
    dup_tier: never
- id: schema_identity_invariants
  model: IdentityInvariants
  file: recoil/pipeline/_lib/render_schema.py::IdentityInvariants
  reduced_tier: never
  fields:
  - name: hair_color
    type: str
    meaning: Never-changing canonical hair color.
    semantic: identity_lock
    dup_tier: always
  - name: eye_color
    type: str
    meaning: Never-changing canonical eye color.
    semantic: identity_lock
    dup_tier: always
  - name: skin_tone
    type: str
    meaning: Never-changing canonical skin tone.
    semantic: identity_lock
    dup_tier: always
  - name: build
    type: str
    meaning: Never-changing canonical body build.
    semantic: identity_lock
    dup_tier: always
  - name: distinguishing
    type: list[str]
    meaning: Never-changing distinguishing identity traits.
    semantic: marks
    dup_tier: always
- id: schema_phase_trigger
  model: PhaseTrigger
  file: recoil/pipeline/_lib/render_schema.py::PhaseTrigger
  reduced_tier: never
  fields:
  - name: type
    type: Literal['script_event', 'ep_range']
    meaning: Whether the phase trigger is a script event or episode range.
    semantic: null
    dup_tier: never
  - name: scene_ref
    type: str
    meaning: Scene reference anchoring a script-event trigger.
    semantic: null
    dup_tier: never
  - name: description
    type: str
    meaning: Human-readable trigger description.
    semantic: null
    dup_tier: never
  - name: evidence_hash
    type: str
    meaning: Hash of the evidence supporting this trigger.
    semantic: null
    dup_tier: never
- id: schema_wardrobe_piece
  model: WardrobePiece
  file: recoil/pipeline/_lib/render_schema.py::WardrobePiece
  reduced_tier: never
  fields:
  - name: piece
    type: str
    meaning: Named wardrobe item.
    semantic: null
    dup_tier: never
  - name: descriptor
    type: str
    meaning: Visual descriptor for the wardrobe item.
    semantic: null
    dup_tier: never
  - name: state
    type: Literal['worn', 'removed', 'damaged', 'torn']
    meaning: Current worn, removed, damaged, or torn state.
    semantic: prop_carrier
    dup_tier: always
  - name: salient
    type: bool
    meaning: Whether this item is visually important enough to surface.
    semantic: null
    dup_tier: never
- id: schema_phase_appearance
  model: PhaseAppearance
  file: recoil/pipeline/_lib/render_schema.py::PhaseAppearance
  reduced_tier: never
  fields:
  - name: wardrobe
    type: list[WardrobePiece]
    meaning: Structured wardrobe pieces for the phase.
    semantic: null
    dup_tier: never
  - name: hair_state
    type: Literal['loose', 'tucked', 'tied', 'covered']
    meaning: Structured hair presentation state.
    semantic: null
    dup_tier: never
  - name: visible_gear
    type: list[str]
    meaning: Gear visible on the character in this phase.
    semantic: prop_carrier
    dup_tier: always
  - name: notable_marks
    type: list[str]
    meaning: Structured notable marks visible in this phase.
    semantic: marks
    dup_tier: always
- id: schema_bible_character
  model: BibleCharacter
  file: recoil/pipeline/_lib/render_schema.py::BibleCharacter
  reduced_tier: never
  fields:
  - name: char_id
    type: str
    meaning: Canonical character identifier.
    semantic: null
    dup_tier: never
  - name: display_name
    type: str
    meaning: Human-readable character name.
    semantic: null
    dup_tier: never
  - name: visual_description
    type: str
    meaning: Core visual identity description.
    semantic: null
    dup_tier: never
  - name: height_cm
    type: Optional[int]
    meaning: Optional character height in centimeters.
    semantic: null
    dup_tier: never
  - name: scale_prompt_fragment
    type: Optional[str]
    meaning: Optional relative scale prompt fragment.
    semantic: null
    dup_tier: never
  - name: wardrobe_arc_thesis
    type: str
    meaning: One-sentence thesis for wardrobe progression.
    semantic: wardrobe_arc
    dup_tier: always
  - name: wardrobe_arc_thesis_approved
    type: bool
    meaning: Whether the wardrobe thesis is director-approved.
    semantic: null
    dup_tier: never
  - name: wardrobe_arc_thesis_source
    type: str
    meaning: Source of the wardrobe thesis decision.
    semantic: null
    dup_tier: never
  - name: wardrobe_arc_vision
    type: str
    meaning: Director free-text wardrobe vision notes.
    semantic: wardrobe_arc
    dup_tier: always
  - name: phases
    type: list[CharacterPhase]
    meaning: Wardrobe and appearance phases for this character.
    semantic: null
    dup_tier: never
  - name: episodes
    type: list[int]
    meaning: Episodes where this character appears.
    semantic: null
    dup_tier: never
  - name: identity_invariants
    type: Optional[IdentityInvariants]
    meaning: Never-changing identity block for this character.
    semantic: identity_lock
    dup_tier: always
  - name: transients
    type: Optional[list[str]]
    meaning: Optional declared transient visual states.
    semantic: identity_lock
    dup_tier: always
- id: schema_location_lighting_profile
  model: LocationLightingProfile
  file: recoil/pipeline/_lib/render_schema.py::LocationLightingProfile
  reduced_tier: never
  fields:
  - name: primary_source
    type: str
    meaning: Primary practical light source for the location.
    semantic: null
    dup_tier: never
  - name: direction
    type: LightDirection
    meaning: Default light direction.
    semantic: null
    dup_tier: never
  - name: quality
    type: LightQuality
    meaning: Default light quality.
    semantic: null
    dup_tier: never
  - name: color_temp
    type: LightColorTemp
    meaning: Default light color temperature.
    semantic: null
    dup_tier: never
- id: schema_bible_location
  model: BibleLocation
  file: recoil/pipeline/_lib/render_schema.py::BibleLocation
  reduced_tier: never
  fields:
  - name: location_id
    type: str
    meaning: Canonical location identifier.
    semantic: null
    dup_tier: never
  - name: habitat_zone
    type: str
    meaning: Super-category zone for the location.
    semantic: null
    dup_tier: never
  - name: aliases
    type: list[str]
    meaning: Original scene headings mapped to this location.
    semantic: null
    dup_tier: never
  - name: description
    type: str
    meaning: Full visual location description.
    semantic: null
    dup_tier: never
  - name: lighting_profile
    type: Optional[LocationLightingProfile]
    meaning: Default lighting profile for the location.
    semantic: null
    dup_tier: never
  - name: color_palette
    type: list[str]
    meaning: Location color palette as hex codes.
    semantic: null
    dup_tier: never
  - name: atmosphere
    type: str
    meaning: Atmospheric or environmental notes.
    semantic: null
    dup_tier: never
  - name: sublocations
    type: Optional[dict[str, 'BibleSublocation']]
    meaning: Semantic named sublocations owned by the bible.
    semantic: subloc
    dup_tier: never
- id: schema_bible_sublocation
  model: BibleSublocation
  file: recoil/pipeline/_lib/render_schema.py::BibleSublocation
  reduced_tier: never
  fields:
  - name: description
    type: str
    meaning: Semantic description of the named sublocation.
    semantic: subloc
    dup_tier: never
- id: schema_prop_state
  model: PropState
  file: recoil/pipeline/_lib/render_schema.py::PropState
  reduced_tier: never
  fields:
  - name: description
    type: str
    meaning: Operative prop state description.
    semantic: null
    dup_tier: never
  - name: visual_delta
    type: str
    meaning: Visual delta that distinguishes this prop state.
    semantic: prop_state
    dup_tier: always
- id: schema_bible_prop_transition
  model: BiblePropTransition
  file: recoil/pipeline/_lib/render_schema.py::BiblePropTransition
  reduced_tier: never
  fields:
  - name: from_state
    type: str
    meaning: Source prop state; serialized with alias "from".
    semantic: prop_state
    dup_tier: always
  - name: to
    type: str
    meaning: Destination prop state.
    semantic: prop_state
    dup_tier: always
  - name: reversible
    type: bool
    meaning: Whether the transition can be reversed.
    semantic: prop_state
    dup_tier: always
  - name: trigger_scene
    type: Optional[str]
    meaning: Optional scene that triggers the transition.
    semantic: prop_state
    dup_tier: always
- id: schema_bible_prop
  model: BibleProp
  file: recoil/pipeline/_lib/render_schema.py::BibleProp
  reduced_tier: never
  fields:
  - name: prop_id
    type: str
    meaning: Canonical prop identifier.
    semantic: null
    dup_tier: never
  - name: description
    type: str
    meaning: Visual description of the prop.
    semantic: null
    dup_tier: never
  - name: state_notes
    type: str
    meaning: Annotation notes; operative states live in states and transitions.
    semantic: prop_state
    dup_tier: always
  - name: associated_characters
    type: list[str]
    meaning: Character IDs that use this prop, not necessarily carriers.
    semantic: associated_characters
    dup_tier: always
  - name: episodes
    type: list[int]
    meaning: Episodes where this prop appears.
    semantic: null
    dup_tier: never
  - name: is_permanent_attachment
    type: bool
    meaning: Whether the prop is baked into character identity refs.
    semantic: prop_carrier
    dup_tier: always
  - name: attached_to
    type: Optional[str]
    meaning: Character ID this prop is permanently attached to or worn by.
    semantic: prop_carrier
    dup_tier: always
  - name: states
    type: dict[str, PropState | str]
    meaning: Operative prop state machine keyed by state_id.
    semantic: prop_state
    dup_tier: always
  - name: initial_state
    type: str
    meaning: Initial state_id for the prop state machine.
    semantic: prop_state
    dup_tier: always
  - name: transitions
    type: list['BiblePropTransition']
    meaning: Allowed directed transitions between prop states.
    semantic: null
    dup_tier: never
  - name: carriable
    type: bool
    meaning: Whether the prop can be transiently carried by a character.
    semantic: prop_carrier
    dup_tier: always
- id: schema_lighting_motif
  model: LightingMotif
  file: recoil/pipeline/_lib/render_schema.py::LightingMotif
  reduced_tier: never
  fields:
  - name: motif_id
    type: str
    meaning: Canonical lighting motif identifier.
    semantic: null
    dup_tier: never
  - name: description
    type: str
    meaning: Visual and thematic motif description.
    semantic: null
    dup_tier: never
  - name: color_temp
    type: LightColorTemp
    meaning: Motif color temperature.
    semantic: null
    dup_tier: never
  - name: associated_locations
    type: list[str]
    meaning: Location IDs associated with this lighting motif.
    semantic: null
    dup_tier: never
  - name: associated_characters
    type: list[str]
    meaning: Character IDs associated with this lighting motif.
    semantic: associated_characters
    dup_tier: always
- id: schema_global_bible
  model: GlobalBible
  file: recoil/pipeline/_lib/render_schema.py::GlobalBible
  reduced_tier: never
  fields:
  - name: schema_version
    type: int
    meaning: Persisted-shape schema version.
    semantic: null
    dup_tier: never
  - name: structural_analysis
    type: str
    meaning: Scratchpad analysis stripped before Pass 2.
    semantic: null
    dup_tier: never
  - name: project
    type: str
    meaning: Project identifier.
    semantic: null
    dup_tier: never
  - name: total_episodes
    type: int
    meaning: Total episode count.
    semantic: null
    dup_tier: never
  - name: generated_at
    type: datetime
    meaning: UTC generation timestamp.
    semantic: null
    dup_tier: never
  - name: wardrobe_philosophy
    type: str
    meaning: Series-level wardrobe philosophy.
    semantic: null
    dup_tier: never
  - name: wardrobe_philosophy_approved
    type: bool
    meaning: Whether the wardrobe philosophy is director-approved.
    semantic: null
    dup_tier: never
  - name: characters
    type: dict[str, BibleCharacter]
    meaning: Bible characters keyed by char_id.
    semantic: null
    dup_tier: never
  - name: locations
    type: dict[str, BibleLocation]
    meaning: Bible locations keyed by location_id.
    semantic: null
    dup_tier: never
  - name: props
    type: dict[str, BibleProp]
    meaning: Bible props keyed by prop_id.
    semantic: null
    dup_tier: never
  - name: lighting_motifs
    type: list[LightingMotif]
    meaning: Recurring lighting motifs.
    semantic: null
    dup_tier: never
- id: schema_ref_asset
  model: RefAsset
  file: recoil/core/ref_types.py::RefAsset
  reduced_tier: never
  fields:
  - name: path
    type: Path
    meaning: Filesystem path to the reference asset.
    semantic: null
    dup_tier: never
  - name: role
    type: RefRole
    meaning: Reference role such as identity, board, location, prop, or sheet.
    semantic: ref_role
    dup_tier: never
  - name: subject
    type: str
    meaning: Subject identifier the reference depicts.
    semantic: ref_subject
    dup_tier: never
  - name: kind
    type: str
    meaning: Reference kind or view family.
    semantic: ref_kind
    dup_tier: never
  - name: is_hero
    type: bool
    meaning: Whether this is the canonical hero identity reference.
    semantic: ref_hero
    dup_tier: never
  - name: content_hash
    type: Optional[str]
    meaning: Optional content hash for the asset.
    semantic: null
    dup_tier: never
  - name: source
    type: RefSource
    meaning: Origin of the reference asset.
    semantic: ref_source
    dup_tier: never
  - name: view
    type: Optional[str]
    meaning: Optional turn-view qualifier.
    semantic: ref_view
    dup_tier: never
- id: schema_reference_bundle
  model: ReferenceBundle
  file: recoil/core/ref_types.py::ReferenceBundle
  reduced_tier: never
  fields:
  - name: assets
    type: tuple[RefAsset, ...]
    meaning: Ordered role-tagged references for one shot.
    semantic: null
    dup_tier: never
