Repository navigation
[FEATURE]: V2 canonical path contracts across runtime, storage and clients #54615
Description
Feature hasn't been suggested before.
- Checked open issues for a duplicate. This is the v2 continuation of the stale, closed proposal [FEATURE]: Define native and identity path contracts across client/server boundaries #33107.
Describe the enhancement you want to request
OpenCode needs separate contracts for a server-native filesystem path, a comparison/storage key, and physical realpath identity. Equivalent Windows spellings such as C:\Work\Repo and C:/Work/Repo should compare consistently, while API requests must use paths native to the selected server.
I propose these v2 stages:
- Land the narrow HTTP directory-boundary fix: [BUG]: V2 forwards foreign directory hints to Location lookup without boundary validation #54617 / fix(server): reject foreign directory hints before location lookup #59414.
- Define native paths, versioned lexical keys, realpath identity, case policy and portable relative paths.
- Apply that contract to Location/Project/Worktree runtime keys and database projections, with collision handling and replay/backfill tests.
- Migrate App/Desktop/TUI persisted keys without losing drafts or combining identical paths from different servers.
- Add explicit Windows/WSL bridging and location rebind, including custom mount roots.
I have prepared the narrow boundary fix on v2. For the following stages, I can prepare focused changes with Windows/WSL fixtures and migration/collision tests. I maintain the MIT package @romanilyin/canonicalpath and can adapt the wrapper to an in-tree implementation if preferred.
Before opening broader implementation PRs, I would like feedback on dependency/wrapper placement, identity and case rules, and whether this staged scope is acceptable.
The first stage is prepared on canonicalpath-dev. Previous v1 PRs #34256 and #40857 were closed without merging. This umbrella tracks the remaining integration rather than claiming that the boundary fix completes it.
Activity
opencode-agent commentedon Oct 11, 2026
Thanks for the detailed proposal and for carrying it over to v2. To restate it: you're proposing separate v2 rules for three things. First, the native path a server uses. Second, a versioned key for comparing and storing paths. Third, the real path on disk. These would be rolled out in stages across the HTTP boundary, Location/Project/Worktree identity, stored data and saved client state, and Windows/WSL bridging. Maintainers will consider the staged scope and your questions about where the code should live and how identity and letter case should work.
Related issues that this work would touch:
romanilyin commentedon Oct 26, 2026
Following up on the v2 design proposal: the narrow HTTP boundary fix in #59414 is now ready for review.
Before extending this to persistent identity and client state, could a maintainer confirm whether the staged approach is acceptable and whether you prefer the server-local wrapper around
@romanilyin/canonicalpathor an in-tree implementation? I can adapt the implementation to either choice. I would like to settle identity and case rules before preparing the migration changes.neriousy commentedon Nov 12, 2026
Thanks for the suggestion. This isn't something we plan to build, so closing to keep the tracker focused.