[PR #1101] feat(app-router): trace approved visible commit outcomes #1097

New issue

Open

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

BreizhHardware commented

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

Owner

📋 Pull Request Information

Original PR: https://github.com/cloudflare/vinext/pull/1101
Author: @NathanDrake2406
Created: 5/6/2026
Status: 🔄 Open

Base: main ← Head: nathan/726-ops-trace-invariants

📝 Commits (1)

9ae01be feat(app-router): trace approved visible commit outcomes

📊 Changes

4 files changed (+362 additions, -196 deletions)

View changed files

📝 packages/vinext/src/server/app-browser-state.ts (+1 -82)
📝 packages/vinext/src/server/app-browser-visible-commit.ts (+156 -9)
📝 packages/vinext/src/server/navigation-trace.ts (+32 -3)
📝 tests/app-browser-entry.test.ts (+173 -102)

📄 Description

What this changes

Implements #726-OPS-02/03 from #726: visible commit invariants and transaction trace codes.

This PR makes the approved visible commit path the only exported way to mutate browser-visible App Router state. The previous raw reducer export is no longer available, and the single visibleCommitVersion increment now lives inside the ApprovedVisibleCommit boundary.

It also adds transaction-level navigation trace codes for the three approval outcomes:

NT_VISIBLE_COMMIT
NT_NO_COMMIT
NT_HARD_NAVIGATE

Those transaction entries are prepended to the existing reason entries such as NC_COMMIT, NC_STALE, NC_ROOT, and NC_ROOT_UNKNOWN, so operators can see both what happened and why.

Bonk: please read issue #726 to see the big picture behind this slice before reviewing the local mechanics.

Why

Issue #726 is building toward a lifecycle model where visible state mutation, stale result rejection, hard navigation fallback, and future cache or skip decisions have observable authority boundaries. Without an explicit transaction outcome in the trace, noCommit, visible commit, and hard navigation paths are harder to audit. Without fencing the raw reducer export, future code can accidentally bypass the approved commit boundary.

Approach

The browser state module still owns pending operation creation, route compatibility decisions, and reason traces. The visible commit module now owns the actual visible state reducer and the one place where visibleCommitVersion advances.

Approval now wraps every decision trace with a transaction entry carrying the operation lane, pending operation id, and started visible commit version. Current behavior for navigate, replace, traverse, HMR recovery, stale commits, unknown-root soft fallback, and root-boundary hard navigation is preserved.

Validation

vp test run tests/app-browser-entry.test.ts passes: 66 tests
vp check tests/app-browser-entry.test.ts packages/vinext/src/server/app-browser-visible-commit.ts packages/vinext/src/server/app-browser-state.ts packages/vinext/src/server/navigation-trace.ts passes with no warnings, lint errors, or type errors
vp run vinext#build passes, with the repo's existing virtual/external unresolved import warnings during pack
vp check exits 0 across the repo, with one pre-existing warning in packages/vinext/src/server/request-pipeline.ts:604

Risks / follow-ups

This intentionally does not add broad runtime logging, cache metrics, skip metrics, stale same-URL server-action rejection, or planner behavior. It is scoped to the visible commit invariant and approval-path trace codes requested by #726-OPS-02/03.

_{🔄 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/1101 **Author:** [@NathanDrake2406](https://github.com/NathanDrake2406) **Created:** 5/6/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `nathan/726-ops-trace-invariants` --- ### 📝 Commits (1) - [`9ae01be`](https://github.com/cloudflare/vinext/commit/9ae01be4cbc71b06c75c4a378d5dddfabaee7fe2) feat(app-router): trace approved visible commit outcomes ### 📊 Changes **4 files changed** (+362 additions, -196 deletions) <details> <summary>View changed files</summary> 📝 `packages/vinext/src/server/app-browser-state.ts` (+1 -82) 📝 `packages/vinext/src/server/app-browser-visible-commit.ts` (+156 -9) 📝 `packages/vinext/src/server/navigation-trace.ts` (+32 -3) 📝 `tests/app-browser-entry.test.ts` (+173 -102) </details> ### 📄 Description ## What this changes Implements `#726-OPS-02/03` from #726: visible commit invariants and transaction trace codes. This PR makes the approved visible commit path the only exported way to mutate browser-visible App Router state. The previous raw reducer export is no longer available, and the single `visibleCommitVersion` increment now lives inside the `ApprovedVisibleCommit` boundary. It also adds transaction-level navigation trace codes for the three approval outcomes: - `NT_VISIBLE_COMMIT` - `NT_NO_COMMIT` - `NT_HARD_NAVIGATE` Those transaction entries are prepended to the existing reason entries such as `NC_COMMIT`, `NC_STALE`, `NC_ROOT`, and `NC_ROOT_UNKNOWN`, so operators can see both what happened and why. Bonk: please read issue #726 to see the big picture behind this slice before reviewing the local mechanics. ## Why Issue #726 is building toward a lifecycle model where visible state mutation, stale result rejection, hard navigation fallback, and future cache or skip decisions have observable authority boundaries. Without an explicit transaction outcome in the trace, `noCommit`, visible commit, and hard navigation paths are harder to audit. Without fencing the raw reducer export, future code can accidentally bypass the approved commit boundary. ## Approach The browser state module still owns pending operation creation, route compatibility decisions, and reason traces. The visible commit module now owns the actual visible state reducer and the one place where `visibleCommitVersion` advances. Approval now wraps every decision trace with a transaction entry carrying the operation lane, pending operation id, and started visible commit version. Current behavior for navigate, replace, traverse, HMR recovery, stale commits, unknown-root soft fallback, and root-boundary hard navigation is preserved. ## Validation - `vp test run tests/app-browser-entry.test.ts` passes: 66 tests - `vp check tests/app-browser-entry.test.ts packages/vinext/src/server/app-browser-visible-commit.ts packages/vinext/src/server/app-browser-state.ts packages/vinext/src/server/navigation-trace.ts` passes with no warnings, lint errors, or type errors - `vp run vinext#build` passes, with the repo's existing virtual/external unresolved import warnings during pack - `vp check` exits 0 across the repo, with one pre-existing warning in `packages/vinext/src/server/request-pipeline.ts:604` ## Risks / follow-ups This intentionally does not add broad runtime logging, cache metrics, skip metrics, stale same-URL server-action rejection, or planner behavior. It is scoped to the visible commit invariant and approval-path trace codes requested by `#726-OPS-02/03`. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>