feat(render): consolidate motion history and temporal reconstruction (PRDs 269, 455)

[jonit-dev]

Final state (2026-10-07) — PRD-269 and PRD-455 closed

PRD-269 is 100% (8/8 phase boxes, 5/5 acceptance). The last two ghosting boxes use a moving-edge metric: the rejection-fraction counter is velocity-blind (real vs zero-velocity arms within .001 of the display at 1x, 4x and 8x character speed on nvidia/turing), so the criterion changed under decision R4. scripts/verify-temporal-ghosting.ts exits 0 on hardware WebGPU: temporal .02805 vs no-AA .04459 (ratio .629, pin <=.75), zero-velocity control .04164 (1.485x, pin >=1.25x). Temporal-off cost passes on hardware: 0 velocity targets, 0 history objects, p50 0.8 vs 0.9 ms inside a 0.2 ms noise band.

PRD-455 is closed as scoped, not as fully achieved. The opt-in full-resolution provider, history lifecycle and 31-arm corpus shipped. The low-resolution reconstruction criteria failed on hardware and moved unchanged to PRD-537 (no threshold relaxed): full-res edge .05849 vs <.04778, low-input edge .08062 vs <.04687, reveal stale 1.77% / 4.89% vs <=1%, plus the p95 win and three-scale scaler boxes. Falsified levers are recorded in the PRDs: reactive mask, raw4 current-footprint (byte-identical to the ordinary lane at a 1:1 raster), variance-clip widening, and a static-camera control that localizes the loss to sub-pixel camera drift (~.010 of edge error).

Also fixed on this branch: the develop merge left pnpm-lock.yaml with mixed three patch hashes (frozen install failed with ERR_PNPM_LOCKFILE_MISSING_DEPENDENCY), and docs/verification was over its evidence budget (cited JSON now gzipped).

Decisions to overturn if wrong: the PRD-269 metric change (D1), the PRD-455 split and PRD-537 number (D2/D3). Each is a single revertable commit.

---

Current reviewed raw4 CPU candidate (2026-10-06)

Published head: 330590cf7c493abb4521a0aa102840b00b90c0fc, based on develop 29fdae8bf. The opt-in candidate keeps the original 426×240 input / 640×360 display, both original .0005 centre OR/point/max depth vetoes, and mandatory RGB clipping. It adds finite raw4 current-footprint weighting with matched visibility, motion and prior four-depth packets. Ordinary opaque PBR RGB remains a pixel-frequency spatial approximation. Default stage/tier selection and the original 31-arm protocol/scorer are unchanged.

Fresh independent source/CPU reviews are clean. Validation: 255 distinct focused CPU tests; actual resolve/counter WGSL construction; measured fingerprints for all 13 generated project trees; strict scoped TS7/Biome; root TS7 plus the eight-package typecheck closure; all eight actual package build/declaration/publint scripts. The root check exposed a private-manager test declaration conflict, fixed and reviewed in the final two-file supplement. The normal pre-commit and pre-push hooks ran; lint, 2,495 documentation links, 22 instruction mirrors and scaffold drift checks pass. No hook, force push or admin override was used.

Still draft at 25%. The original recovery gate remains RED: .11045044 > .1 is a CPU replay of historical c2779e9 captured inputs through the ordinary kernel, not a new raw4 GPU output. No new raw4 GPU quality/cost, native/platform, resource plateau or automatic-scaler result is claimed. Both draft PR workflows for this head are skipped, which is not passing required CI. A hardware-correctness diagnostic is being prepared at the original raster; GPU launch is held for the agreed Animals/Strata resource sequence. External image uploads remain held.

Earlier entries below describe their own historical source/evidence and do not qualify this candidate.

---

Current CPU repair and develop integration (2026-10-05)

Published candidate: c5357e39d8ecd0c29802e3cb2af633a2af40dcaa. Normal merges preserve immutable owner a0830fec4, develop 9b3c4824c, and current develop/PR440 d3c009e4404abcc2041f58124693edb9c78d802b.

Three reproduced CPU defects are repaired: renderer/colour/depth/velocity rejection resets the next valid history frame; fixed and automatic composed RTTs jitter on their own raster; the scaled native assertion floors actual PassNode input dimensions while retaining authored display rounding. Seven controls failed before repair, then 40/40 passed. An isolated rejection-counter edit now selects the temporal integration lane, preserving exact candidate pins, current-attempt receipts and independent animation/native lanes.

PR440's 24 camera/material template paths and the six reviewed temporal repair files are preserved byte-for-byte. All 13 scaffold fingerprints were measured from actual combined generator output, retaining every assertion. Fresh independent merge and formatting-follow-up review is clean.

Validation: 306 affected CPU tests at merged source 6570965aa; all 101 routing/receipt contracts rerun at the published candidate; root TS7, serial workspace and velocity-fixture typechecks pass. The fresh eight-package build/declaration closure at 9e9ccc88f remains current because its public source/build/lock inputs are unchanged. Normal pre-push lint, docs, instruction mirrors and 322 drift tests pass. An initial push was correctly blocked by one overlong CI-test line; the final follow-up only applies its formatter line wrap. No hook was skipped.

Still draft at 25%. Original PRD269/455 acceptance rows and thresholds are unchanged. Quality/ghosting, representative GPU/render cost, actual lower-raster WorldEnvironment exposure, automatic-scale allocation/cost and combined-source native/platform gates remain open. Skipped draft CI is not passing evidence. No new GPU/native runtime capture or external image upload is claimed for this candidate.

---

The temporal-toggle lifecycle repair now includes a normal merge of develop 15adf350da53addfa33675c2b3f0e2722e086e37 into the published repair b32342b96332b11d2e52367dd2e4a80b7f8a5ba5. Current head: ffa6ea9bbce9f5db4be37b857a135738a5dd85da. The merge preserves incoming fluid/adapter, exposure/fog, asset and render-output ownership changes alongside the attachment cleanup. Both histories remain ancestors.

Validation:

• Pinned frozen offline install, seven-package JavaScript build/ESM/DTS/publint, full workspace TypeScript, strict velocity-fixture TypeScript and the original fixture Vite build pass.
• 255 focused tests pass, including all 19 actual Three predecessor migration/idempotence/tamper tests. Five additional inherited renderer ownership/receipt regressions pass with mocked pipelines.
• The actual installed bytes of all 24 patched Three files match the conflict-free source merge. The canonical patch hash is 7036a173dfc11cb7d0a485c12eca4f3dcee3fa4e20c0a4a010b16741d81b79a2. All 16 migration blocks were independently verified against exact predecessor hashes.
• The normal pre-commit and pre-push hooks pass, including 320 drift tests, root error-level lint, docs and instruction mirrors. Verification evidence is 71.4 MB under the unchanged 72 MB cap. Scaffold hashes come from actual generated projects.
• Fresh independent review found no actionable correctness findings. Only the ten declared resolution/derived-test paths differ from Git's automatic merge preview.

Current-source actual hardware result, pinned to ffa6ea9bbce9f5db4be37b857a135738a5dd85da:

• One unchanged original three-toggle fixture run at velocity-cost.html?from-temporal, NVIDIA/Turing WebGPU/Vulkan, 640x360. Source, installed dependencies and all 355 captured build/evidence inputs remained frozen. The normal shared capture lease was released after the run; no retry was made.
• Three transitions, 546 actual draw frames and 150 measured samples in each balanced arm. Active velocity target observed; final velocity targets/history objects/temporal stages/velocity provisioning all zero. Output is nonblank; console errors and warnings are both zero. 10/12 resource assertions plus the diagnostic policy pass. The complete scenario FAILS.
• Both failures are original control-noise assertions: resource.cost.p50NoiseExcessMs = +0.0125 ms and resource.cost.p95NoiseExcessMs = +1.8125 ms. The unchanged p50/p95 overhead assertions pass numerically, but invalid noisy controls leave temporal-off cost unqualified.

Original statistic (ms)	Baseline A	Baseline B	Temporal off	Control noise	Noise limit	Noise excess
p50	2.2	2.5	2.4	0.6	0.5875	+0.0125
p95	7.0	8.9	8.4	3.8	1.9875	+1.8125

The original fixture times wall-clock CPU render submission, including temporal-off reconcile/commit; requestAnimationFrame and the real one-pixel readback/drain await are outside that interval. It uses 30 warmup triplets, all six balanced arm orders and all 150 measured samples per arm. FrameBudget uses nearest-rank percentiles (p50 sample 75, p95 sample 143 of 150) and rounds reported milliseconds to 0.01; the measured clock quantum is 0.1 ms. The unchanged evaluator requires control noise max(2 * clockQuantum, 2 * abs(A - B)) <= max(0.2, 0.25 * mean(A, B)) before an overhead comparison can qualify.

Concurrent host observations recorded 1-minute load 33.08–36.81 on 24 logical CPUs, aggregate non-idle CPU 82.5% over 30.54 seconds, and CPU pressure some avg10 rising from 6.97 to 11.59. These are contention evidence, not proof of the sole cause. A further interpretable cost qualification needs a coordinated quiet CPU/GPU window with the same original fixture, assertions, sample count, orders and clock gate. An exclusive GPU/capture lease alone does not reserve CPU scheduling. No thresholds, sample filtering or retry-to-green were introduced.

The actual procedural-cube after PNG is retained in the user's Library and is byte-identical to the previously retained image: SHA-256 73419c8f57c9c3c8aed0fdcf5a9c553c0410fed6f004269ad8299174d518d2e7 (8,381 bytes). Its new capture provenance is this exact head; identical image bytes do not transfer the older run's qualification to current code.

This PR remains draft; original PRD269/455 criterion statuses are unchanged. The earlier capture on lifecycle source 004e4b8afdbd188bc275722bd6d6187943d4c4d4 remains historical: 11/12 resource assertions plus diagnostic policy passed, and the original p95 control-noise assertion failed by +0.625 ms. The two runs are retained independently; neither qualifies cost.

Current-head CI has 49 completed/skipped checks across CI, Integration lanes and Native runtime release. Skipped draft CI is not passing evidence. Full quality/ghosting, true low-raster reconstruction, native rendering, hardware performance and complete original PRD269/455 acceptance remain open. No additional GPU run, native build, merge or mark-ready action is included in this update.

Previous PR description and pinned evidence

Repeated temporal on/off cycles left a physical velocity attachment on the Three scene pass after its MRT was restored. Subsequent renders then failed WebGPU target validation and produced blank output. The chain now disposes the target while the owned velocity attachment is still registered, detaches only that attachment, and reattaches Three's cached velocity texture on the next enable. Caller-owned velocity textures and the original MRT remain intact.

The fixture also imports IFrameBudgetSummary through the existing @threenative/core export and declared dependency, fixing the five TS6059 errors caused by importing core source outside its rootDir. This is a type-only correction; no public API, dependency, tsconfig, runtime producer, evaluator threshold, or scenario assertion was added or weakened.

Repair candidate: b32342b96332b11d2e52367dd2e4a80b7f8a5ba5, consisting of lifecycle commit 004e4b8afdbd188bc275722bd6d6187943d4c4d4 and the one-line fixture import correction, on published base 24d731cccc4ffd0436c5c4538611a54ed03ef338.

Validation:

• Full workspace pnpm typecheck passes. All 114 focused lifecycle, velocity/history, template and cost/capture proof tests pass.
• Rebuilding the original velocity fixture after the type-import correction produces five files byte-identical to the captured runtime build.
• Fresh independent review found no important actionable defects. Normal pre-push checks pass, including 323 drift tests, lint, documentation links and agent mirrors.
• The unchanged original three-toggle WebGPU scenario passed 11/12 resource assertions plus the diagnostic policy: three transitions, active velocity target observed, final velocity targets/history/temporal stages/provisioning all zero, zero console errors or warnings, and a nonblank after frame. Capture ran on lifecycle commit 004e4b8afdbd188bc275722bd6d6187943d4c4d4, with source/build inputs frozen, on NVIDIA/Turing at 640x360.
• Cost qualification FAILED: resource.cost.p95NoiseExcessMs = +0.625 ms. Baseline p95 values were 2.0 and 2.6 ms; candidate p95 was 1.7 ms. Baseline noise 1.2 ms exceeds the 0.575 ms limit. This is an invalid noisy-control measurement, not demonstrated candidate overhead. Candidate overhead assertions passed, but the cost qualification remains failed. The balanced 150-sample-per-arm fixture measures CPU render submission, not GPU execution time. No retry or threshold change was made.

This PR remains draft. The lifecycle repair and typecheck fix do not complete PRD455. Full quality, ghosting, native parity and hardware-performance acceptance remain open; no broad browser/native acceptance run was performed for this repair, and skipped draft CI jobs are not passing evidence.

Previous PR description and evidence

Consolidated temporal work: PRDs 269 and 455

At the owner's request, this draft is now the single review and implementation destination for authored motion history plus temporal AA/reconstruction. Merge commit 0606d8decc2b63252966a47cfab86d6825b78cf0 retains both exact source heads: PR398 b877de150555661283355a87f8c4969efc48418c and original PR393, its full evidence and discussion 73c2a684314b569cbd5059b1d6458e90d6bcbfd8. Original runtime review comment.

Still incomplete and not eligible for develop/main:

• PRD-269 remains 3/5 acceptance and 7/8 phase boxes. The latest source's temporal-off run 37048989025 reproduces a blank frame and WebGPU target/output validation errors after three motion-blur on/off cycles. The retained velocity attachment teardown remains unresolved. Fresh-off cost evidence is software-adapter CPU submission only. Ghosting/rejection, native rendering and complete frame-cost qualification remain open.
• PRD-455 still fails its original AA image-quality bar. Full low-raster reconstruction, wider-content correctness, native and performance qualification remain open. The historical results below remain pinned to their original sources; consolidation is not new runtime/GPU acceptance.
• Neither canonical PRD checkbox set was changed. Draft stays on; no auto-merge is enabled. Both original acceptance sets and exact-head required CI must pass before integration.

Preservation and combined-source checks

• Independent review verified every source-only and destination-only file, all 46 PRD269/455 proof files byte-for-byte, the exact Three patch/migration bytes, and the registry/lockfile union. Both source histories and authorship remain ancestors. The only content conflict was generated scaffold hashes: all 13 actual combined no-install projects were measured, and the byte-stability test independently rerun. No test assertions were weakened.
• Frozen pnpm install, create-threenative and its dependency builds/publint, root TypeScript, scoped formatting, and 2,496 documentation links pass. Builds used the equivalent Node tsx loader because the normal tsx CLI cannot create its IPC socket here.
• 89 temporal/history/migration tests, 36 adjacent history/native-probe tests and all 66 scaffold tests pass (191 total). Scaffold setup initially lacked build outputs and temporary-project Basis resolution; after building dependencies and setting NODE_PATH to the installed core dependencies, all 66 pass. This is not a full aggregate pnpm test, new browser/native proof, or exact-head CI pass.

Canonical scopes: PRD-269 and PRD-455. PR393 is superseded by this combined draft, not individually merged into develop/main. Its branch and original discussion remain available.

---

Preserved PRD-455 history and evidence

Scope and current behavior

Implements PRD-455 in the requested order: opt-in full-resolution temporal AA first, followed by true low-raster reconstruction once the inputs and quality bar are qualified. Reuses pinned Three.js 0.185.1 TRAANode, RenderChain and VelocityTracker. Reconstruction must retain ResolutionScaler as the single policy.

The generated starter helper now executes, resets/disposes owned history, primes an unjittered velocity matrix before the first material compile, and preserves it when NodeBuilder repeats setup during an active jittered frame. A maintained real WebGPU benchmark measures matching motion sequences and catches remaining image-quality defects. No quality tier enables this helper by default. PR remains draft.

Dependency checkpoint: combined source e48c31b8 explicitly merges canonical PR393 repair 47e188e and landed develop 924b92f. Its three-parent ancestry retains the prerequisite's ownership; the patch is unchanged. This historical checkpoint preceded consolidation; PRD-269 is now included in this PR, with both PRDs retaining their independent acceptance requirements. Combined unchanged 176-frame benchmark run 37004283653 completed and still fails the original quality bar. All 176 named PNG hashes verify; all eleven diagnostics are empty. Exact combined measurements and provenance.

Latest authored resolve experiment and dependency

Source 3afcbc66a, run 37016735368: all 304 PNG hashes verify and all 19 arm diagnostics are empty. Authored-linear output is byte-identical to installed TRAA for all 16 frames, so the cubic comparison is interpretable. The original 208 frame bytes are unchanged. Full measurements, controls and provenance.

Cubic plus strict rejection reduces edge error versus installed temporal (0.05605 vs 0.06001), but still loses to no-AA (0.05061) and the fixed 5% improvement bar. Residual instability is 0.03173; causal red tint is zero. Conservative reveal projection and excursions versus installed temporal still fail. The matched zero-velocity arm correctly worsens moving-edge error (0.04169 vs 0.02470). Quality remains unqualified. Non-strict cubic is diagnostic-only because it lacks its own matched zero-velocity control.

Inspected actual cubic+strict runtime frames, source 3afcbc6, run 37016735368, WebGPU SwiftShader/google. These show measured progress and remaining failure; no native or performance qualification:

Before reveal, frame 27:

Reveal, frame 30 (compare the byte-identical reference and installed temporal ghost frame retained below):

Recovery, frame 36:

Combined source e638fc47 explicitly merges canonical PR393 uploader repair ac7e789, preserving its patch and migration bytes. Frozen install, 199 focused tests, root types/error-level lint, fixture build, docs and evidence budget pass.

The identical combined 304-frame run 37018389700 now confirms the observed recompile defect is repaired in this actual temporal-helper path. All 304 hashes verify; all 19 diagnostics are empty; authored-linear equivalence passes. Recompile pixels, metrics and MRT samples exactly match ordinary temporal across all 16 frames. Frame-23 instance velocity error falls from 0.52156 pixel to 0.00005972 pixel; the sequence maximum is 0.0009863 pixel. GPU current/previous matrix readbacks now match their corresponding CPU values. Only recompile frames 23–36 changed; every other PNG and metric is unchanged, so the original image-quality failures remain. Exact combined provenance and readbacks.

Inspected actual corrected recompile frame 23, source e638fc4/run 37018389700, SwiftShader/google; this verifies motion correctness, not superior AA quality:

Further resolve changes await a fresh critique of the measured remaining image error. This historical dependency is superseded by the consolidation above; both PRDs now travel together and neither is acceptance-complete. Full reconstruction, broader content, native rendering and performance gates remain open.

Phase 1 — History correctness

• Opt-in full-resolution temporal AA, reset lifecycle and real browser runtime evidence; this is not a visual-superiority/native/performance qualification
• Smaller colour/depth input reconstructs into display-sized output with honest sizes and rejection observation
• Camera/projection/size changes and skinned/instanced history meet the complete correctness corpus

Phase 2 — Motion stability

• Thin fence/foliage/subpixel/moving character corpus beats spatial upscale
• Newly revealed surfaces meet the declared stale-history bound

Phase 3 — Real frame time

• Browser and desktop-native GPU/render p50/p95 improve at qualified quality
• Three-scale repeated transitions remain stable with bounded allocation/cost

Earlier combined result

The canonical repair reduces instance MRT error to at most 0.000986 pixel; default/dynamic instance PNG sequences are identical. Zero velocity now degrades moving-edge error correctly: 0.04169 versus 0.03024. Overall edge error remains worse than no-AA (0.06001 versus 0.05061), despite 36.5% lower residual instability. Reveal projection remains 22.6% and causal red tint 11.61% one frame later. No threshold or appearance policy changed. Public material recompilation exposes a separate one-frame instance-Y error of 0.522 pixel at frame 23; it was still open at that earlier checkpoint.

Inspected actual combined temporal frame 30, source e48c31b, run 37004283653, SwiftShader/google. The previous no-AA frame is byte-identical, so the matched reference below remains valid. This is measured failure progress, not quality qualification:

Nearest-history causal experiment, source 1270435, run 37006364268: all 208 PNG hashes verify, diagnostics are empty, and the original 176 frames remain byte-identical. Nearest sampling worsens edge error to 0.07036 and instability to 0.03246, so it is rejected as a quality fix. The actual recompile draw retains identical WGSL and correct distinct current/previous CPU matrices; the remaining one-frame GPU discrepancy is narrowed to uploader/binding state. Exact measurements and actual draw evidence.

Inspected actual nearest-history frame 30; diagnostic failure progress only:

Earlier findings and retained diagnostic history

• The actual TRAANode setup regression reproduced RenderChain passing a sampled texture where Three expects a velocity accessor. These inputs are now distinct; public withVelocityContext is unchanged.
• Real MRT readback exposed current Halton jitter leaking into velocity. The generated helper repair reduces rigid error to at most 0.000308 pixel across 16 captured frames.
• Public renderer context invalidation causes NodeBuilder setup to repeat during active jitter at frame 23. Setup count increases 1→2, while the repaired MRT result remains within 0.000308 pixel. Ordinary temporal PNGs stay byte-identical.
• A separate shipped previous-instance attribute upload/order defect produces 9.34-pixel mean error. The dynamic-buffer control still contains exactly two-frame displacement. PR393 owns that engine repair; it is not duplicated here.
• The original quality gate remains red. At 640×360, against a same-pose 4× raster reference integrated in linear light, temporal edge error is 0.06070 versus 0.05061 without AA; error instability is 0.03196 versus 0.04915. The original reveal projection score is 22.6% one frame after reveal.
• A fixture-only strict depth-edge rejection control reduces next-frame reveal projection to 0%, with essentially unchanged edge/stability error. A later 59-pixel score is dark-blue undercoverage and demonstrates that the conservative dot-product score is not unique evidence of added red. The score and all thresholds remain unchanged.
• Latest source adds matching never-occluded temporal controls and a separate causal red-excess diagnostic. Numerical regressions reject neutral brightening/darkening and recover known 25% red history. Hosted causal run 37001381134 captures 176 matching sequence frames. Standard temporal retains causal red tint on 11.61% of reveal pixels one frame later; strict rejection has 0% across all eight reveal frames; unchecked history has 100%. Exact causal results and original scores. The original gate remains red and the strict policy remains fixture-only. The exact verified PR393 dependency is now consumed; its unchanged benchmark result is recorded above.

Actual matched runtime frames

Run 36999580189, source 2b9bdf1, WebGPU SwiftShader/google. Full original scores, recompile observations and provenance. All 128 PNG hashes were verified; all eight arms have empty diagnostics. These frames were inspected and share pose/frame 30.

No-AA reference (bytes verified identical in that run):

Current generated temporal helper after projection repair; red residue is still visible on revealed fence edges:

Fixture-only strict edge-rejection comparison; overall quality is still unqualified:

Matching strict-policy frame 30 with the marker never present (source 5c071b4; exact cohort above):

All 176 named frame hashes were verified; all 11 arm diagnostics are empty. The control image was inspected. This causal diagnostic does not replace the original conservative projection gate.

Initial full-resolution reset/recovery evidence, first measured failure, and first-compile repair oracle retain exact source/run/adapter/PNG provenance. All complete sequences remain in workflow artifacts. Software correctness evidence makes no native or GPU-performance claim.

Validation

• Fresh combined dependency validation: 176 core files, 2,222 tests passed, two skipped, plus 87 focused helper/scaffold/evaluator/probe tests. This is not the complete repository suite.
• Combined frozen install, core and public playtest builds/publint, fixture build, root types/lint, documentation links and unchanged evidence budget pass. The public runner’s assertion-generator check uses node --import tsx locally because the package-script tsx CLI cannot create its IPC pipe.
• Current helper/scaffold slice: 79 focused tests pass after actual re-setup red→green reproduction and generated hash validation.
• Latest causal/evidence/helper slice: 20 tests pass; original image scores reproduce exactly against the previous evaluator on the same runtime.
• Root TypeScript and whole-root error-level lint pass; fixture web and shared native-source bundles pass. Native bundling is not execution.
• Documentation links and unchanged evidence budget pass (70.4 MB/72 MB). The evidence check suite has 29 passes and two CLI-launch failures from prohibited tsx IPC pipes; both unchanged CLI cases pass through node --import tsx. Normal draft root CI remains skipped; the separate read-only temporal workflow captures real renderer frames and intentionally fails the unmet quality bar.
• Full repository board, full moving-content corpus, native rendering, reconstruction and hardware performance remain unqualified.

Canonical PRD-455.