[PR #1063] [MERGED] feat(app-router): add navigation trace reason-code shell #1061

New issue

Closed

opened 2026-05-06 13:11:48 +02:00 by BreizhHardware · 0 comments

BreizhHardware commented

2026-05-06 13:11:48 +02:00

Owner

📋 Pull Request Information

Original PR: https://github.com/cloudflare/vinext/pull/1063
Author: @NathanDrake2406
Created: 5/5/2026
Status: ✅ Merged
Merged: 5/5/2026
Merged by: @james-elicx

Base: main ← Head: nathan/726-ops-01-navigation-trace-shell

📝 Commits (2)

28562c0 feat(app-router): add navigation trace reason-code shell
a508dcc fix(app-router): tighten navigation trace shell

📊 Changes

4 files changed (+239 additions, -7 deletions)

View changed files

📝 packages/vinext/src/server/app-browser-navigation-controller.ts (+9 -1)
📝 packages/vinext/src/server/app-browser-state.ts (+68 -6)
➕ packages/vinext/src/server/navigation-trace.ts (+60 -0)
📝 tests/app-browser-entry.test.ts (+102 -0)

📄 Description

What this changes

Adds the #726-OPS-01 compact navigation trace shell for the App Router navigation commit seam. Pending commit classification can now opt into a structured NavigationTrace with compact reason codes for current dispatch, stale operation skip, root-boundary hard navigation, and unknown root-layout legacy fallback.

Why

Issue #726 calls out that NavigationTrace should use compact reason codes and structured fields instead of narrative logs. The current commit classification path only returned a string disposition, which made follow-up lifecycle work choose between losing operational context or inventing ad hoc logs at each call site.

Approach

Added packages/vinext/src/server/navigation-trace.ts with schema version 0, compact reason codes, structured field names, and small trace construction helpers.

Threaded traces through resolvePendingNavigationCommitDispositionDecision() while preserving the existing resolvePendingNavigationCommitDisposition() string-only helper as the allocation-light hot-path API used by browser navigation. resolveAndClassifyNavigationCommit() stays on the allocation-light disposition path because the current controller does not consume traces yet.

Non-goals: this does not promote new navigation planner semantics, change visible commit behavior, add runtime logging, or claim cache or skip-transport authority. It is the trace contract shell only.

Validation

vp test run tests/app-browser-entry.test.ts
vp check packages/vinext/src/server/navigation-trace.ts packages/vinext/src/server/app-browser-state.ts tests/app-browser-entry.test.ts
vp run knip --no-progress
pre-commit hook: vp check --fix and knip --no-progress

Risks / follow-ups

The trace field set is intentionally narrow to stay parallel-safe with the other Wave01 branches. Later #726 OPS tasks can extend the field/code taxonomy as more semantic owners move behind typed commit decisions.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/cloudflare/vinext/pull/1063 **Author:** [@NathanDrake2406](https://github.com/NathanDrake2406) **Created:** 5/5/2026 **Status:** ✅ Merged **Merged:** 5/5/2026 **Merged by:** [@james-elicx](https://github.com/james-elicx) **Base:** `main` ← **Head:** `nathan/726-ops-01-navigation-trace-shell` --- ### 📝 Commits (2) - [`28562c0`](https://github.com/cloudflare/vinext/commit/28562c0d97a8aa4d7e2b22b2a02cf2c8b9c8233e) feat(app-router): add navigation trace reason-code shell - [`a508dcc`](https://github.com/cloudflare/vinext/commit/a508dcc320d606c635f9fd337be80a45f63aaa9e) fix(app-router): tighten navigation trace shell ### 📊 Changes **4 files changed** (+239 additions, -7 deletions) <details> <summary>View changed files</summary> 📝 `packages/vinext/src/server/app-browser-navigation-controller.ts` (+9 -1) 📝 `packages/vinext/src/server/app-browser-state.ts` (+68 -6) ➕ `packages/vinext/src/server/navigation-trace.ts` (+60 -0) 📝 `tests/app-browser-entry.test.ts` (+102 -0) </details> ### 📄 Description ## What this changes Adds the `#726-OPS-01` compact navigation trace shell for the App Router navigation commit seam. Pending commit classification can now opt into a structured `NavigationTrace` with compact reason codes for current dispatch, stale operation skip, root-boundary hard navigation, and unknown root-layout legacy fallback. ## Why Issue #726 calls out that `NavigationTrace` should use compact reason codes and structured fields instead of narrative logs. The current commit classification path only returned a string disposition, which made follow-up lifecycle work choose between losing operational context or inventing ad hoc logs at each call site. ## Approach Added `packages/vinext/src/server/navigation-trace.ts` with schema version 0, compact reason codes, structured field names, and small trace construction helpers. Threaded traces through `resolvePendingNavigationCommitDispositionDecision()` while preserving the existing `resolvePendingNavigationCommitDisposition()` string-only helper as the allocation-light hot-path API used by browser navigation. `resolveAndClassifyNavigationCommit()` stays on the allocation-light disposition path because the current controller does not consume traces yet. Non-goals: this does not promote new navigation planner semantics, change visible commit behavior, add runtime logging, or claim cache or skip-transport authority. It is the trace contract shell only. ## Validation - `vp test run tests/app-browser-entry.test.ts` - `vp check packages/vinext/src/server/navigation-trace.ts packages/vinext/src/server/app-browser-state.ts tests/app-browser-entry.test.ts` - `vp run knip --no-progress` - pre-commit hook: `vp check --fix` and `knip --no-progress` ## Risks / follow-ups The trace field set is intentionally narrow to stay parallel-safe with the other Wave01 branches. Later #726 OPS tasks can extend the field/code taxonomy as more semantic owners move behind typed commit decisions. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>