)jUdZddlmZddlmZmZmZmZmZdZ de d<dddZ d e d <dZ de d <d Z d e d<ddZ ddZy)u.W21B-w4 · #4(C) render-input substrate policy — deterministic resolver core. brief ``docs/w21b-wave4-bg-render-substrate-policy-20260531`` (APPROVED v0.2) + Codex design lock (2026-05-31). Single pure helper :func:`resolve_render_substrate` that decides, per shot-aware-plan node, what render-input substrate the bg gets — WITHOUT calling any image/LLM API. It reads the 3a/3b stamped fields (``render_action`` / ``needs_new_plate`` / ``ref_tree_parents`` / ``ref_role_per_parent``) and the caller-supplied PNG snapshots, and returns an ordered reference plan: - **reuse alias** (``reuse_existing_plate`` / ``needs_new_plate=False``) → render input 0 (copy-less alias is materialised elsewhere; ``proceed=False``). - **fresh plate** → FP PNG first, then ``ref_tree_parents`` reordered ``space_continuity`` → ``style`` (already canonical anchors from 3b), each resolved to its rendered-plate PNG. A parent whose PNG is not yet rendered is dropped and recorded in ``missing_parent_bg_ids`` + ``fallback_reason`` (brief §5 v0 = graceful degrade, never a silent drop). All parents missing → ``fallback_fp_only``. - **fp-less / direct** → no FP png for the fp → ``direct`` (parents/text only). card-withheld fresh folds into ``fresh`` (route_v2 already dropped its reuse_target, so it is not in ``ref_tree_parents`` — never re-added here). The resolver decides the **PNG substrate only**. Plate prose / projection-card ``pass`` gating stays with C4 ``resolve_projection_plate_injection`` / background_prompt (Codex caution — no overlap). This module is a pure helper and is **not wired into any step yet** (default-inert): the ``background_render_step`` consumer (replacing the legacy ``depends_on_bg`` prior selection behind a selector/flag) is a separate, separately-reviewed change. ) annotations)AnyDictListOptionalTupleintMAX_PARENT_REFS)space_continuitystylezDict[str, int] _ROLE_RANK_DEFAULT_ROLE_RANK bg_id node_classproceedfp_pathordered_parent_bg_idsordered_prior_bg_pathsattached_ref_labelsref_usedfallback_reasonmissing_parent_bg_idszTuple[str, ...]SUBSTRATE_FIELDSc |dddgggddgd S)N reuse_aliasFr)rs f/Users/manta/Documents/Projects/TheRoad-I1/backend/app/modules/pipeline/background_render_substrate.py_reuse_alias_decisionr":s*#!#"$!!!#  c |jd}|jddk(s|jddur t|S|j|}|r t|nd}|jdxsgDcgc]}t|tr|r|}}|jdxsit |fd  dt } g} g} g} | D]R}|j|} | r,| j || j t| B| j |Tg}d }|r|j d |d |d d}t| | D]3\}} |j ||j|xsd| d |dz }5| rdjd| Dnd}|d}d}nd}| rd}n| rd}nd}||d|| | |||| d Scc}w)uResolve the render-input substrate for one shot-aware-plan node. ``fp_png_by_fp`` maps ``fp_id -> floor-plan PNG path``; ``rendered_plate_png_by_bg`` maps an already-rendered plate ``bg_id -> PNG path`` (the render snapshot). Both are caller-supplied — this function performs no IO. See module docstring for the node-class policy. The returned dict always carries every :data:`SUBSTRATE_FIELDS` key. r render_actionreuse_existing_plateneeds_new_plateFNref_tree_parentsref_role_per_parentcVtjj|tS)N)rgetr)proless r!z*resolve_render_substrate..osz~~eiilz+resolve_render_substrate..s>g(,gsrfp_less_directdirectfresh fp_plus_refsfallback_fp_onlyfp_onlyTr) r+r"str isinstancesortedr appendzipjoin) plan_nodefp_id fp_png_by_fprendered_plate_png_by_bgrraw_fprr,parentsordered_parents resolved_idsresolved_pathsmissingpnglabelsorder_irrrr-s @r!resolve_render_substraterSIs! MM' "E  o&*@@ ==* +u 4$U++   e $F,2S[G MM"45;;;a a ! ; &MM*?@FBEOO!L "NG &**1-     "  ! !#c( + NN1  $&FG %w O lN33 IIaL1M    1 4CJ>g>>r%  %H )H H !-"0%*!(  os<GN)rz Optional[str]returnDict[str, Any]) rFrUrGr@rHrUrIrUrTrU)__doc__ __future__rtypingrrrrrr __annotations__rrrr"rSr r#r!rZs>#3334a@ N@C %/  bb b! b - b  br#