refactor(file-types): unify FilePath as Zod-branded canonical path

[EurFelux]

What this PR does

Before this PR: three overlapping filesystem-path types in src/shared/:

• FilePath — a template literal (`/${string}` | `${string}:\\${string}`), a type-level hint only, with no runtime guarantee (no null-byte rejection, no absolute-shape enforcement).
• CanonicalExternalPath — a phantom brand reached only via the main-side canonicalizeExternalPath() wrapper.
• CanonicalFilePath — the intersection FilePath & CanonicalExternalPath, used on ExternalEntrySchema.externalPath.

AbsolutePathSchema only refined input shape; downstream sites repeated canonicalizeExternalPath() by hand and a long tail of read sites needed as FilePath casts.

After this PR — a two-tier model:

• FilePath — a runtime-validated Zod brand produced by FilePathSchema that validates absolute-path shape only and does not mutate its input (FilePathSchema.parse(x) === x):

  export const FilePathSchema = z
    .string().min(1)
    .refine((s) => !s.includes('\0'), 'must not contain null bytes')
    .refine((s) => s.startsWith('/') || /^[A-Za-z]:[/\\]/.test(s), 'must be an absolute filesystem path')
    .brand<'FilePath'>()
  export type FilePath = z.infer<typeof FilePathSchema>

• CanonicalFilePath = FilePath & { readonly __canonical } — a FilePath in the byte-faithful, lexically-resolved form (segment-resolve + trailing-strip + Windows drive-upcase — NOT Unicode-normalized). Its sole producer is canonicalizeFilePath() (@shared/utils/file/canonicalize.ts); it is used exactly where a stable dedup/persistence key is needed — the file_entry.externalPath column and the FileEntryService.findByExternalPath / findCaseInsensitivePeers / setExternalPathAndName signatures. ExternalEntrySchema.externalPath validates a stored value is already in that form and brands it CanonicalFilePath.

externalPath is stored byte-faithful — never Unicode (NFC) normalized. NFC-normalizing the stored path would make it unreachable on normalization-sensitive filesystems (Linux ext4: an NFD-named file's NFC path ENOENTs → the file becomes unimportable). Unicode-based dedup is therefore deliberately rejected (unverified premise, rare + cosmetic on macOS where APFS folds at access, YAGNI); dedup stays byte-exact + case-fold (see docs/references/file/file-manager-architecture.md §1.2 "Rejected: Unicode (NFC) normalization"). The DanglingCache watcher matches events by raw byte equality accordingly, with check() (which stats the byte-faithful path) as the correctness baseline.

Also:

• AbsolutePathSchema, CanonicalExternalPath, and the canonicalizeExternalPath wrapper are deleted. FileInfo drops its Omit+intersection hack (FileInfoSchema.parse yields the exact type). FilePathHandleSchema / IPC path schemas are branded at the boundary.
• A new ESLint rule filepath-brand/no-as-filepath (CI-error / local-warn) forbids as FilePath in production; genuine production casts became FilePathSchema.parse(), and renderer render-time sites degrade gracefully via safeParse and log on failure. Exemptions: tests + the raw-OS-path regimes (watcher/**, tree/**).
• Path-type reference docs synced.

Fixes #15404

Why we need it and why it was done in this way

The FilePath template literal was a lie of omission: it promised "looks absolute" but enforced nothing at runtime. Making it a real Zod brand fixes that. The canonicalization question was resolved across two rounds of review. First: an early iteration canonicalized inside FilePathSchema (every FilePath NFC-normalized on parse), which mutated read-source paths and comparison keys and had to exempt watcher/** / tree/** / Notes — so FilePath became shape-only, with a separate CanonicalFilePath at the externalPath boundary. Second: even that boundary NFC-normalization was found to break reachability on Linux (an NFD file's NFC path does not exist on disk), so it was removed too — externalPath is stored byte-faithful, and the Unicode-normalization idea that issue #15404 framed as an "NFC guarantee" is deliberately not implemented (it would trade certain Linux breakage for an unverified, rare, cosmetic macOS dedup). The net design: FilePath/CanonicalFilePath are validated + resolved but never Unicode-mutated; a stored path always reaches its file on every filesystem.

The following tradeoffs were made:

• Shape-only FilePath + explicit CanonicalFilePath factory instead of canonicalize-on-parse — a FilePath never silently changes bytes; only the external-entry boundary canonicalizes. CanonicalFilePath extends FilePath, so it flows anywhere a FilePath is accepted, while FilePath → CanonicalFilePath is a compile error that forces the factory.
• Reject-don't-repair on the externalPath read path — a stored value not already in the byte-faithful lexical form (e.g. containing /../ or a trailing slash) is warn-skipped rather than silently rewritten, keeping the lookup key stable. Pinned by a test.
• Lint guard rather than convention for as FilePath.

The following alternatives were considered and rejected:

• Canonicalize-by-default inside FilePathSchema — caused NFC-rewrite regressions on read-source paths (NFD-named file import on Linux) and contradicted the watcher/tree exemptions.
• Any Unicode (NFC) normalization of externalPath, even scoped to the write boundary — an NFC-rewritten path does not exist on disk on normalization-sensitive filesystems (Linux), so the stored path can't reach its file. Removed entirely; dedup stays byte-exact + case-fold. See docs/references/file/file-manager-architecture.md §1.2 "Rejected: Unicode (NFC) normalization".
• Keeping canonicalizeExternalPath as a deprecated alias — rejected per the v2 throwaway principle.

Links to places where the discussion took place: #15404 (design proposal). Supersedes the closed #15406.

Breaking changes

Internal v2 refactor. DB schema unchanged, IPC wire format unchanged (the phantom brand serializes as a plain string), renderer-visible behavior unchanged.

• FilePathSchema accepts both C:\… and C:/… Windows absolute forms and, being shape-only, preserves them as-is (no separator rewrite). Strict relaxation vs. the old backslash-only AbsolutePathSchema; no previously-valid input is rejected or rewritten.
• externalPath is stored byte-faithful (no NFC) — canonicalizeFilePath does reachability-safe lexical cleanup only (segment-resolve, trailing-strip, drive-upcase). This is a fix: the pre-existing canonicalizeExternalPath NFC-normalized, which broke import/reachability of NFD-named files on normalization-sensitive filesystems (Linux).
• ensureExternalEntry on a currently-missing path now creates a dangling external entry instead of throwing (ENOENT/ENOTDIR → dangling; genuine FS faults like EACCES still throw). External entries are allowed to reference an absent file by design (DanglingState), so the previous hard existence check was inconsistent. Not user-perceivable yet — ensureExternalEntry is Phase-2 and not wired into a renderer flow.
• UNC paths (\\server\share) remain rejected by the absolute-shape refine (pre-existing; now documented).

Special notes for your reviewer

Supersedes the closed #15406, redone fresh on current main. Adaptations vs. #15406: adapted to the synchronous FileEntryService; no src/shared/file/** flatten; knowledge directory-ingest and the Notes subsystem are intentionally out of scope.

History (read the two phases):

• Initial build-out (886c546d…dd4f5b95): introduce FilePathSchema, unify the types, lint guard, docs, and follow-up polish. NOTE: 19c3ef7e initially canonicalized inside the schema — that approach is reverted by the revision below.
• Revision after author self-review (548402a4…5dc16cb2), addressing 15 inline comments:
  • 548402a4 refactor(file-types): — the design pivot: FilePath shape-only + CanonicalFilePath sub-brand; canonicalization moved to the externalPath boundary; batch dedup trusts the branded param (fixes the NFC-rewrite regressions R1/R2, the read-repair semantics R4, and the redundant re-parse R14/A3).
  • 6210a601 fix(composer): — guard the edit-resend buildEditedMessageParts call (was an unhandled rejection) and isolate per-attachment parse failures with Promise.allSettled + logging (R3).
  • acdec7cb refactor(file): — log the four renderer safeParse-failure sites (ArtifactPane deduped one-time) (R5–R8).
  • 5dc16cb2 refactor(file): — stale-doc fixes (R9–R11), a null-byte defense-in-depth guard on setExternalPathAndNameTx (R12), getPathStatus non-absolute → missing (R13), UNC limitation doc (R15).
• Byte-faithful revision (b6d4a096…607b4528), from a deeper design discussion (reachability on Linux):
  • b6d4a096 docs(file): — rewrite file-manager-architecture.md §1.2: store externalPath byte-faithful; record the reject rationale for NFC-based dedup.
  • c12a6072 fix(file): — drop NFC normalization from canonicalizeAbsolutePath and the watcher's event matching → externalPath is byte-faithful and reachable on normalization-sensitive filesystems; the watcher matches events by raw byte equality.
  • 607b4528 refactor(file): — ensureExternalEntry on a currently-missing path creates a dangling entry (ENOENT/ENOTDIR → dangling) instead of throwing; genuine FS faults (EACCES/…) still throw.

Checklist

• Branch: This PR targets the correct branch — main for active development, v1 for v1 maintenance fixes
• PR: The PR description is expressive enough and will help future contributors
• Code: Write code that humans can understand and Keep it simple
• Refactor: You have left the code cleaner than you found it (Boy Scout Rule)
• Upgrade: Impact of this change on upgrade flows was considered and addressed if required
• Documentation: A user-guide update was considered and is present (link) or not required. Check this only when the PR introduces or changes a user-facing feature or behavior.
• Self-review: I have reviewed my own code (e.g., via /gh-pr-review, gh pr diff, or GitHub UI) before requesting review from others

Release note

NONE

[EurFelux]

[R14] 建议 · 微优化:toSafeFileUrl 对已 branded 的 FilePath 每次调用都再跑一遍 FilePathSchema.parse(),包括每个 <img>/<video> 渲染。

同类冗余:pathResolver.ts:49(internal 分支)、FileManager.ts:926。均幂等无害,只是可避免的工作。非危险分支(isDangerExt)可直接 toFileUrl(absolutePath),仅在 dirnameSimple 改写后的路径上才需重 parse。(dirnameSimple 对 C:\ 根的修正本身正确且必要。)

[EurFelux]

[R14] 部分处理:FileManager batch 那处冗余 re-parse 已随 A3 移除(548402a4)。url.ts:236 这处保留 —— FilePath 现在是 shape-only,FilePathSchema.parse 只做一次廉价形状校验(不再跑 canonicalize),"可避免的工作"已从 canonicalize 降到近乎零,留着是为在 dirnameSimple 改写后仍保证 brand 一致。若你仍想省掉,可在非危险分支直接 toFileUrl(absolutePath) —— 说一声我就改。