The advisory file lock keys on the resolved path string, so a link name and its referent are different locks

Filed from work on #1405 (branch feat/guarded-write-s4a, head 94dc7c4), where review thread PRRT_...607461 on src/utils/safeWriteJson.ts:225 asks whether a write through a link and a write to the referent serialise with each other. The thread stays open because the answer is a contract decision rather than a unit commit; this issue exists so the gap is owned somewhere other than a resolved thread.

Measured at that head

• src/utils/fileLock.ts is 100 lines. acquireFileLock(filePath) at :29 computes path.resolve(filePath) at :30 and hands that string to lockfile.lock(absoluteFilePath, ...) at :33, inside an options object that sets realpath: false at :36 with the comment "the file may not exist yet, which is acceptable".
• resolveLinkPathLockKey occurs zero times anywhere under src or packages at this head (git grep exit 1). There is no normalisation layer between a caller's path spelling and the lock key.
• So a lock taken on a link name and a lock taken on the referent are two different keys, and the two writes do not serialise with each other. path.resolve removes . and .. and makes the path absolute; it does not follow links.
• #2350, the tracking issue for the staging-name guard, does not carry this question either: its body is 4,933 characters and contains no occurrence of "lock". Lock keys appear there only in comment 6719060399, the four-generation map, which credits one generation with exporting resolveLinkPathLockKey and another with not exporting it.

What #1405 already pins

,

The unit under review tests the behaviour from three directions, which is why the mechanism is not in dispute — the missing decision is which identity the lock should use:

• src/utils/__tests__/safeWriteJson.test.ts:960 — a mocked referent,
• :1111 — a real link, created as a junction on Windows and a symlink elsewhere, with the platform's refusal recorded rather than assumed,
• :1612 — the mode where link resolution is refused (refuseSymlinkTarget), so no resolution happens at all.

What the owner has to decide

• Whether the lock identity is the link name, the resolved referent, or the pair. Canonicalising to the referent makes link-mediated and direct writes exclude each other, which is what callers of acquireFileLock say they want in the doc comment at :23-:27 — "serialize with every safeWriteJson write to the same path" — but it requires resolving a path that may not exist yet, which is exactly why realpath: false is there today.
• If the referent is chosen, how to reach it for a not-yet-existing final component: resolve the nearest existing ancestor and rejoin, which is the shape the canonicalisation fix in src/services/file-safety/safeWriteText.ts already uses for the staging directory, so the repo would then have one idiom rather than two.
• Whether anything outside this repository depends on today's behaviour, since a lock-key change alters which concurrent processes collide.

No code change is proposed here and nothing is asserted about which identity is correct. Suppression counts are unaffected by this issue.