From e4d0af6af4347ccb39202be0b21269e32485901c Mon Sep 17 00:00:00 2001 From: Joao Paulo Furtado Date: Thu, 8 Oct 2026 14:19:33 -0700 Subject: [PATCH] docs(prds): renumber the low-resolution temporal PRD to 539 #398 filed it as PRD-537 while #464 landed a different PRD-537 (far hills) first. Rename the file and repoint PRD-455, PRD-384, the machinefall RUNBOOK and the temporal CI comment. No behaviour change. --- .github/workflows/integration.yml | 2 +- ...ral-reconstruction-from-dynamic-resolution.md | 16 ++++++++-------- ...UNBOOK-machinefall-120fps-with-fab-quality.md | 2 +- .../PRD-384-adaptive-resolution-gpu-headroom.md | 2 +- ...-temporal-reconstruction-quality-and-cost.md} | 3 ++- 5 files changed, 13 insertions(+), 12 deletions(-) rename docs/PRDs/rendering/{PRD-537-low-resolution-temporal-reconstruction-quality-and-cost.md => PRD-539-low-resolution-temporal-reconstruction-quality-and-cost.md} (95%) diff --git a/.github/workflows/integration.yml b/.github/workflows/integration.yml index a53b9c4985..11fad31441 100644 --- a/.github/workflows/integration.yml +++ b/.github/workflows/integration.yml @@ -377,7 +377,7 @@ jobs: run: pnpm exec vitest run packages/core/__tests__/temporal-chain.spec.ts packages/core/__tests__/render-chain.spec.ts packages/core/__tests__/render-velocity.spec.ts packages/create-threenative/__tests__/temporal-aa.spec.ts packages/create-threenative/__tests__/temporal-initial-projection.spec.ts packages/create-threenative/__tests__/temporal-resolve.spec.ts packages/runtime-native/__tests__/temporal-velocity-probe.spec.ts scripts/__tests__/temporal-aa-evidence.spec.ts scripts/__tests__/temporal-aa-quality.spec.ts --maxWorkers=2 - name: Render temporal motion and reset variants run: node --import tsx scripts/verify-temporal-aa.ts - # The strict 31-arm corpus (verify-temporal-motion.ts) is PRD-537's proof and fails by design until + # The strict 31-arm corpus (verify-temporal-motion.ts) is PRD-539's proof and fails by design until # a reconstructor clears its edge/reveal gate; this job enforces the shipped ghosting scope. - name: Measure animated-character ghosting against the zero-velocity control run: node --import tsx scripts/verify-temporal-ghosting.ts diff --git a/docs/PRDs/done/PRD-455-temporal-reconstruction-from-dynamic-resolution.md b/docs/PRDs/done/PRD-455-temporal-reconstruction-from-dynamic-resolution.md index f12f6fe1e6..c10f9ae318 100644 --- a/docs/PRDs/done/PRD-455-temporal-reconstruction-from-dynamic-resolution.md +++ b/docs/PRDs/done/PRD-455-temporal-reconstruction-from-dynamic-resolution.md @@ -4,8 +4,8 @@ prd_contract: v1 # PRD-455 — Fewer rendered pixels reconstruct into a stable full-resolution frame -**Status:** DONE (scoped) — the opt-in full-resolution temporal provider, history-correctness lifecycle and ghosting/cost controls shipped; the low-resolution reconstruction quality, frame-time and scaler criteria moved to [PRD-537](../rendering/PRD-537-low-resolution-temporal-reconstruction-quality-and-cost.md) (2026-10-07). -**Priority:** P1 — closed as scoped; the unmet reconstruction work continues in PRD-537. +**Status:** DONE (scoped) — the opt-in full-resolution temporal provider, history-correctness lifecycle and ghosting/cost controls shipped; the low-resolution reconstruction quality, frame-time and scaler criteria moved to [PRD-539](../rendering/PRD-539-low-resolution-temporal-reconstruction-quality-and-cost.md) (2026-10-07). +**Priority:** P1 — closed as scoped; the unmet reconstruction work continues in PRD-539. **Complexity:** 8 → HIGH. The renderer already has the difficult prerequisites; the remaining risk is history correctness and proving reconstruction wins more GPU time than it costs. **Depends on:** the landed motion-history implementation from PRD-269 (`packages/core/src/render/velocity.ts`, commit `3630847a`), its pending canonical [PR393 repair](https://github.com/ThreeNativeHQ/threenative/pull/393) at `47e188e41601a64decb4fe0f580037546d63b543`, the existing `RenderChain`, and [PRD-384 adaptive resolution](../performance/PRD-384-adaptive-resolution-gpu-headroom.md). @@ -334,18 +334,18 @@ above do not qualify this source. Original quality, cost and platform acceptance - [x] The opt-in full-resolution provider is stable on the motion corpus and rejects history it should. **proof:** `sh scripts/xvfb.sh node --import tsx scripts/verify-temporal-motion.ts` captured all 31 arms on nvidia/turing `webgpu` (2026-10-07, source `f45434a98`); `causalNegativeControl`, `recompileVelocity`, `velocityProjection`, `stabilityImprovement`, `uncheckedHistoryDetected`, `zeroVelocityDetected` and `qualityBeatsSpatialStability` are true in the summary, and `sh scripts/xvfb.sh node --import tsx scripts/verify-temporal-ghosting.ts` exits 0 (moving-edge ratio `.629` against no-AA, zero-velocity control `1.485x`). - **Moved, decision R4 (owner delegation "go with best option", 2026-10-07):** these two original boxes fail on hardware across five independent candidates and continue unchanged in PRD-537. No threshold changed. Original wording, verbatim: + **Moved, decision R4 (owner delegation "go with best option", 2026-10-07):** these two original boxes fail on hardware across five independent candidates and continue unchanged in PRD-539. No threshold changed. Original wording, verbatim: - "A fixed camera route containing thin fences, foliage, sub-pixel edges, a moving character and an instanced moving object stays within pinned temporal-stability/ghosting thresholds against a full-resolution reference. **proof:** automated frame-sequence report records edge flicker, rejected-history ratio and image delta for full-res, low-res spatial upscale and temporal reconstruction; the temporal arm must beat the spatial arm on the named stability metric." Failing checks: `edgeImprovement` (`.05849` vs `<.04778`), `qualityEdgeImprovement` (`.08062` vs `<.04687`). - "Newly revealed surfaces do not inherit stale colour after occlusion/disocclusion events. **proof:** foreground-occluder fixture reveals a contrasting background and asserts stale-history pixels decay within the declared frame bound; disabling disocclusion rejection makes it fail." Failing checks: `revealRecovery` (`1.77%` vs `<=1%`, including the full-resolution `temporal` arm), `qualityRevealRecovery` (`4.89%`). - The `verify-temporal-motion.ts` exit-1 above is exactly those four checks. CI no longer runs that script (its hardware flags lose the device on the GPU-less runner, and the four checks fail by design); the `temporal` CI job gates `verify-temporal-ghosting.ts` instead. Returning the 31-arm corpus to CI with the four unmet checks report-only is Phase 1 work in PRD-537. + The `verify-temporal-motion.ts` exit-1 above is exactly those four checks. CI no longer runs that script (its hardware flags lose the device on the GPU-less runner, and the four checks fail by design); the `temporal` CI job gates `verify-temporal-ghosting.ts` instead. Returning the 31-arm corpus to CI with the four unmet checks report-only is Phase 1 work in PRD-539. ### Phase 3 — Keep it only if it buys real frame time -- [x] The reconstruction path stays opt-in and experimental because its quality and cost gates are unmet; nothing in a shipped template or quality tier enables it. **proof:** `rg -n '^\s+authoredStageNames: \[' packages/create-threenative/templates --glob '*.ts'` lists exactly one real stage list, `rain` with `["stormPost"]` (2026-10-07), so no shipped template or tier names `traa`; `quality.ts:106` documents the opt-in. The unmet low-resolution win continues in PRD-537. +- [x] The reconstruction path stays opt-in and experimental because its quality and cost gates are unmet; nothing in a shipped template or quality tier enables it. **proof:** `rg -n '^\s+authoredStageNames: \[' packages/create-threenative/templates --glob '*.ts'` lists exactly one real stage list, `rain` with `["stormPost"]` (2026-10-07), so no shipped template or tier names `traa`; `quality.ts:106` documents the opt-in. The unmet low-resolution win continues in PRD-539. - **Moved, decision R4 (2026-10-07):** the GPU/render p95 win against full resolution and the three-scale automatic-resolution route both require a reconstructor that first clears the quality gate, so they continue in PRD-537. + **Moved, decision R4 (2026-10-07):** the GPU/render p95 win against full resolution and the three-scale automatic-resolution route both require a reconstructor that first clears the quality gate, so they continue in PRD-539. ### Current execution notes @@ -413,7 +413,7 @@ If the qualified reconstruction path does not beat the existing full-resolution GPU-bound workload after accounting for its own cost, it stays optional/experimental rather than becoming a default. -- [x] **The reconstruction path does not become a default while its win is unproven.** proof: `rg -l "createTemporalAA\(" packages/create-threenative/templates --glob '!**/render/temporal*'` prints nothing (2026-10-07); the unmet low-resolution win continues in PRD-537. +- [x] **The reconstruction path does not become a default while its win is unproven.** proof: `rg -l "createTemporalAA\(" packages/create-threenative/templates --glob '!**/render/temporal*'` prints nothing (2026-10-07); the unmet low-resolution win continues in PRD-539. - [x] **History degrades safely when it cannot be trusted.** proof: the Phase 1 reset/disposal boxes (hosted run `36990452407`, native reset and zero-velocity mutant sections below) plus `sh scripts/xvfb.sh node --import tsx scripts/verify-temporal-ghosting.ts` exiting 0 on hardware WebGPU (2026-10-07). @@ -2004,4 +2004,4 @@ not converge to the bar at all: static `quality-temporal` edge `.08132` against `.06930` and a `<.04687` requirement, so a 426×240 input does not recover native-resolution edge accuracy in this metric with the current reconstructor. Flag not committed; no threshold changed. -**Closed as scoped, 2026-10-07.** The full-resolution findings above remain the record; PRD-537 owns every unmet low-resolution criterion. Useful control for its owner: at a 1:1 raster the resolve reads the plain current sample, so the raw4 candidate is byte-identical to the ordinary lane on every full-resolution arm (identical PNG hashes); it can only matter on the low-input family. +**Closed as scoped, 2026-10-07.** The full-resolution findings above remain the record; PRD-539 owns every unmet low-resolution criterion. Useful control for its owner: at a 1:1 raster the resolve reads the plain current sample, so the raw4 candidate is byte-identical to the ordinary lane on every full-resolution arm (identical PNG hashes); it can only matter on the low-input family. diff --git a/docs/PRDs/open-world/RUNBOOK-machinefall-120fps-with-fab-quality.md b/docs/PRDs/open-world/RUNBOOK-machinefall-120fps-with-fab-quality.md index 65de91883b..e3951e8c41 100644 --- a/docs/PRDs/open-world/RUNBOOK-machinefall-120fps-with-fab-quality.md +++ b/docs/PRDs/open-world/RUNBOOK-machinefall-120fps-with-fab-quality.md @@ -92,7 +92,7 @@ The gap is CPU while walking. The costs, as span p95s, which overlap and do not - [ ] **A6 · PRD-478 Phase 3: terrain merges and seams run in a worker.** After: A5. ⏱🌍👁 - The settled terrain must be byte-identical to the inline path. - [ ] **A7 · No pipeline compiles mid-walk:** [PRD-459](PRD-459-smooth-streaming-one-admission-budget-per-frame.md) AC-3 with [PRD-387](../performance/critical/PRD-387-shader-variants-are-prepared-off-frame-and-bounded.md). After: A6. ⏱🌍👁 -- [ ] **A8 · [PRD-537](../rendering/PRD-537-low-resolution-temporal-reconstruction-quality-and-cost.md): temporal reconstruction closes the GPU gap (successor of PRD-455).** After: A7. ⏱🌍👁 +- [ ] **A8 · [PRD-539](../rendering/PRD-539-low-resolution-temporal-reconstruction-quality-and-cost.md): temporal reconstruction closes the GPU gap (successor of PRD-455).** After: A7. ⏱🌍👁 - [ ] **A9 · PRD-478 acceptance.** After: A8. ⏱🌍👁 - Done when: AC-1, AC-2 and AC-3 are ticked on a quiet host 🙋, and PRD-478 is in `done/`. - [ ] **A10 · PRD-477 Phases 2–3 and AC-1: budgets and switches become engine decisions.** After: A9. ⏱🌍👁 diff --git a/docs/PRDs/performance/PRD-384-adaptive-resolution-gpu-headroom.md b/docs/PRDs/performance/PRD-384-adaptive-resolution-gpu-headroom.md index 548fdf8276..cd9423115d 100644 --- a/docs/PRDs/performance/PRD-384-adaptive-resolution-gpu-headroom.md +++ b/docs/PRDs/performance/PRD-384-adaptive-resolution-gpu-headroom.md @@ -1,7 +1,7 @@ # PRD-384 — Adaptive resolution must distinguish host delay from GPU cost **Status:** PARTIAL -**Priority:** P1 — Declared required by P1 PRD-537's temporal reconstruction (successor of PRD-455); one open box, native controller execution for the landed scaler. +**Priority:** P1 — Declared required by P1 PRD-539's temporal reconstruction (successor of PRD-455); one open box, native controller execution for the landed scaler. **Complexity:** 5 (MEDIUM); risk override: none **Owner:** Codex **Depends on:** PRD-228; Midway's installed PRD-382 engine branch diff --git a/docs/PRDs/rendering/PRD-537-low-resolution-temporal-reconstruction-quality-and-cost.md b/docs/PRDs/rendering/PRD-539-low-resolution-temporal-reconstruction-quality-and-cost.md similarity index 95% rename from docs/PRDs/rendering/PRD-537-low-resolution-temporal-reconstruction-quality-and-cost.md rename to docs/PRDs/rendering/PRD-539-low-resolution-temporal-reconstruction-quality-and-cost.md index d83fe15f72..a045e82d46 100644 --- a/docs/PRDs/rendering/PRD-537-low-resolution-temporal-reconstruction-quality-and-cost.md +++ b/docs/PRDs/rendering/PRD-539-low-resolution-temporal-reconstruction-quality-and-cost.md @@ -2,11 +2,12 @@ prd_contract: v1 --- -# PRD-537 — A lower internal raster reconstructs into a stable full-resolution frame +# PRD-539 — A lower internal raster reconstructs into a stable full-resolution frame **Status:** NOT STARTED — successor to [PRD-455](../done/PRD-455-temporal-reconstruction-from-dynamic-resolution.md); no reconstructor has cleared the quality gate (2026-10-07). **Priority:** P1 — Carried over unchanged from PRD-455, whose own note ranked it the highest-value rendering project; the owner may lower it. **Complexity:** 8 → HIGH. Five candidates failed the same gate on hardware; the next one is a new design, not a parameter change. +**Numbering:** filed in #398 as PRD-537; #464 took that number for the far-hills PRD first, so this PRD is PRD-539 (2026-10-08). **Depends on:** PRD-455 (opt-in provider, lifecycle, fixture and 31-arm corpus) and PRD-269 (motion history). ## Problem