Support original sprite palettes for faithful HD terrain remasters

docs/hd-streaming.md

@@ -16,6 +16,14 @@ All policies below default to disabled. They require explicit frame metadata and
 - `preserve_reserved_coverage: true` retains an original gameplay palette label 250–255 at a feathered edge only when its resident logical cell has mean alpha of at least 128 and at least half its area has alpha of 128 or greater. Missing or sparse artwork stays transparent. Ordinary colors, water/fire classes and static-card rendering keep their existing behavior.
 - `native_nearest_cues: [[x, y], ...]` samples the unchanged resident RGBA at the nearest pixel for up to 64 explicitly listed original cells, only at gameplay scale 1. Coordinates must be sorted lexicographically, unique, within an opaque original canvas, and refer to ordinary source indices below 240. This can preserve a small raw-supported warning color that averaging dulls. It does not recolor artwork or reconstruct absent details; other cells, higher scales and static-card rendering keep their existing sampler.
 
+- `palette_constraint: "original-painted-ordinary-v1"` limits visible generated gameplay samples to the exact distinct indices painted in that frame's checked Original. Eligibility requires a nonempty, fully opaque Original canvas containing only ordinary indices 0–239. The list is derived from the catalog; authors cannot supply extra colors. The raw PNG, crop/atlas selection, logical canvas, origin, Lanczos/nearest sampling and alpha threshold are unchanged. An absent or null value keeps the previous serialization, cache keys and output. This is an optional runtime quantization treatment of existing generated artwork, not a new generation or copied Original detail.
+
+The palette constraint applies in SourceClasses gameplay mode at scales 1–4; Static-card sampling remains unchanged and cannot supply approval for this treatment. It chooses the closest allowed ordinary color by squared RGB distance; an exact tie selects the lowest allowed palette index. Sources containing transparency, water/fire or glow/blink labels 240–255 are ineligible for this version, so their existing functional palette behavior is preserved. Exact Original detail retention still takes priority, including authentic joined Original samples and transparent ScaleNx subpixels.
+
+Terrain must pass the trusted domain returned by `terrain_sprite_with_palette` into `compose_with_palette_constraints`. The domain is present in the detailed input before neighbor sampling and in each owner's shared/final join quantization. Default `Replacement` literals and composition APIs remain valid. The older `terrain_sprite` rejects opted-in frames rather than silently dropping their domains. A rejected or shadowed owner does not apply a domain and does not suppress a valid neighbor; invalid metadata on an accepted owner fails closed. Source boundary controls and explicitly retained Original samples are not generated contributions and are preserved. Different tile domains may have no common color: this policy cannot promise identical seams, correct geometry or spatial material placement. Whole-scale and genuine-neighbor review remains required.
+
+Palette-constrained frames have a separate versioned frame/indexed/prepared-terrain identity. Default keys remain exact. A validated domain costs 48 bytes on 64-bit targets and is included in the existing combined 32 MiB Source-reference budget; no additional full Source raster or unbounded per-domain transition table is retained.
+
 - `original_detail_cells: [[x, y], ...]` retains explicitly listed **Original** logical details at gameplay scales 1–4. Legacy lists of up to 64 cells keep their existing behavior. Lists of 65–128 cells additionally require `4 * retained_cell_count <= painted_Source_cell_count`, counted from the decoded authentic Original payload (indices 0–255, excluding transparency), never canvas area or generated PNG alpha. All cells must remain sorted, unique, in bounds, painted and disjoint from `native_nearest_cues`; transparent Source cells are rejected. The runtime copies the exact Original ScaleNx footprint into the generated replacement only in SourceClasses/gameplay mode. Terrain conditions retained samples with the authentic joined Original control before blending neighbors, then restores their exact footprints after all joins. This can also change neighboring pixels within the existing join bands; unrelated pixels and fallback behavior remain unchanged. Static cards continue to sample the PNG. Raw PNG bytes, alpha, framing and loader eligibility do not change.
 
 Retained pixels are Original details, not generated HD. Original palette cycling, water/fire and blinking labels remain live Source indices; ScaleNx may also contain transparent subpixels shaped by Original neighbors. Coarse detail or palette effects can form visible seams and require explicit independent all-scale and genuine-context hybrid review. The ordinary-only predecessor is not a current hybrid approval. Registration accepts the existing `retained-original-details-v2-painted0255` declaration only for legacy lists of up to 64, or `retained-original-details-v3-max128-quarter-painted0255` with exact selected cells. Longer lists always require v3 and actual catalog Source validation by the registrar. Metadata-only candidate preparation cannot prove the density bound. Lists up to 64 preserve existing per-frame, indexed and rejected-fallback cache identities; longer lists use new indexed and rejected-fallback namespaces. Protected terrain joins follow the conditioning rule above for either list size. The combined 32 MiB Source-reference budget is unchanged. Retained cells never count as generated detail, and the area rule does not prove novelty in the unretained cells. A whole-Source fallback cannot gain artistic HD approval through this option; legacy acceptance is preserved without relabeling its pixels. Material, all-scale and genuine-context gates stay in force (the separately bounded unused-catalog scope still explicitly declares no genuine runtime context). Existing default artwork holds are preserved; this option does not rescue invalid framing, provider refusals or broad geometry/material failures.
@@ -24,6 +32,16 @@ Opt-in metadata participates in both derived and indexed cache identities. Frame
 
 `HdAssets::load` performs full eager validation using the same bounded caches. `validate_all()` can also validate a lazily registered pack; its report distinguishes registered, validated and rejected frames. Full validation can therefore be used in a CLI or audit without raising runtime memory limits. It validates supplied artwork and does not infer coverage for absent originals.
 
+## Reviewing a palette-constrained candidate
+
+Keep the untouched generated PNG and its complete generation inventory/history. Add only the explicit frame field in a new candidate; preserve every native field except any necessary file-only namespace. A later treatment of a selected historical raw does not make it the latest generated raw, repair a newer held result, or approve its unselected siblings. Retained Original cells remain separately declared as Original pixels.
+
+`hd_candidate_review.py` selects the maintained `tools/hd_palette_review.rs` successor when this field is present. It must be compiled against the actual newly built library; frozen historical helpers are not modified or relabeled. The successor records the derived Source indices/colors and measured visible/out-of-domain counts at every scale, in addition to the existing source/raw/frame-binding/current-library evidence. Pure loader or domain success is not material approval. Quantization can flatten tones, retain a wrong but allowed gray/brown color in the wrong place, or leave a boundary between disjoint domains.
+
+Registration keeps all existing approval, exact binding, freshness, whole-material and genuine-context requirements. A coordinator review additionally declares `palette_constraint_review` with `policy_version: "original-painted-ordinary-v1"`, its exact `frame_bindings_sha256`, `unchanged_generated_raw: true` and `independent_allscale_and_genuine_context_review: true`. The registrar derives the domain again from actual catalog bytes and checks the measured SourceClasses evidence; an old default-sampler QA or static-card result cannot authorize it. No asset receives this field automatically.
+
+Legacy terrain review constructors compiled against the new library must migrate to the domain-aware wrapper and composition method before reviewing these candidates. Recompiling an old constructor without that change is unsupported and fails closed. Intrinsic galleries do not prove terrain joins, Source reachability, animation or all-placement coverage. Actual build/CLI/default-continuity and asset-specific context reviews must be completed before publishing a new runtime or admitting a candidate.
+
 ## Memory bounds
 
 Each PNG is limited to 32 MiB on disk, 4,096 pixels per dimension, 4,194,304 total pixels and a 64 MiB decoder allocation limit. Reads are bounded even if a file grows after metadata inspection. A loaded frame retains at most its logical canvas at 4× resolution. Larger generated originals remain unchanged on disk.