# Reference resolution — char/location/prop/wardrobe refs → payload-ready image refs.
# THE forcing case for this whole topology (PR #135). Two divergent routes by surface:
#   - board  (board_builder._collect_board_refs): char refs are INDIVIDUAL (char bundle
#     turn-views); prop refs are individual prop-identity for NON-worn props — a WORN prop
#     (bible attached_to a char in the shot) renders as PROSE on the carrier with NO standalone
#     ref (REC-213 C4); the LOCATION ref is the composite SHEET when the board is locked to one
#     sublocation + use_composite_sheets is on (REC-213 C3), else the sublocation plate.
#   - video  (dispatch_payload._collect_reference_images): composite multi-angle SHEETS
#     via _collect_sheet_refs → ref_resolver.resolve_sheet_asset, gated by
#     use_composite_sheets (else two-pass angles).
# Capability state/canonical/deprecated live in ssot_manifest.yaml (ref_resolution,
# state: transitioning, canonical_target resolve_reference_bundle).
subsystem: ref_resolution

routes:
  - id: board_ref_path
    capability: ref_resolution
    surface: board
    entry: recoil/pipeline/_lib/board_builder.py::_collect_board_refs
    resolves_via: recoil/core/ref_resolver.py::resolve_character_bundle
    ref_kind: individual          # char turn-views + prop identity for NON-worn props (a WORN prop, bible attached_to a char in the shot, renders as PROSE on the carrier with NO standalone ref — REC-213 C4); LOCATION ref forks (see ref_resolution_full board_location_sheet_route)
    gated_by: null                # char refs ungated; the LOCATION ref is gated by use_composite_sheets (locked board, C3)
    fallback_route: null
    risk_level: high

  - id: video_ref_path
    capability: ref_resolution
    surface: video
    entry: recoil/pipeline/_lib/dispatch_payload.py::_collect_reference_images
    resolves_via: recoil/core/ref_resolver.py::resolve_sheet_asset
    ref_kind: composite_sheet     # one multi-angle sheet per entity (the Seedance/Kling lock)
    gated_by: use_composite_sheets
    fallback_route: video_twopass_route   # flag OFF / any sheet missing → two-pass angle collection (ref_resolution_full)
    risk_level: high

# use_composite_sheets flag declared once in dispatch_payload.topo.yaml (canonical home,
# defines both activation channels); the ref_system_split divergence below references it
# via on_flag only.

divergences:
  - id: ref_system_split
    capability: ref_resolution
    forks: [board_ref_path, video_ref_path]
    on_flag: use_composite_sheets
    invariant: "for a LOCKED board with use_composite_sheets ENABLED, board_ref_path resolves the LOCATION sheet via the SAME recoil/core/ref_resolver.py::resolve_sheet_asset as video, gated by the SAME composite_sheets_enabled flag (REC-213 C3 — one activation SSOT, no board/video fork); board CHARACTER refs stay individual (resolve_character_bundle) by design — an intentional per-surface choice, not a silent fork."
    risk: "PR#135 — the board path fed individual plates while video uses composite SHEETS; an engineer extending board refs could not see the split, fed the wrong location ref, and mis-injected the debt_counter WARDROBE item as a prop."
    reduced_tier: always
    risk_level: critical
