Stand in for watched files when the client lacks them

[Firehed]

Last of five stacked PRs, on top of the watched paths. Its tree is identical to #646, the total view.

What was wrong

[LSP] makes workspace/didChangeWatchedFiles the way a server learns of changes on disk, and leaves supporting it optional for the client. With a client that does not, nothing told the server a file changed. ALE is one: it declares no such capability and never sends the notification.

What this does

PollingFileWatcher stands in for the notification with a client that did not declare support, and does nothing otherwise.

• Before each message it looks at the paths the holders named in the previous PR.
• It reports one event per file created, deleted, or changed, as the client would, through the same InvalidatableInterface the notification's handler calls.
• StatReader reads modification times. BeforeMessageInterface is how the server loop calls the watcher.

Behaviour changes

With a client that lacks watched-file support, a file created, deleted, or regenerated on disk is seen on the next request.

Two things that are deliberate

• The filesystem reports whole seconds. A path last looked at during the second it was modified is looked at again, since an unchanged time proves nothing within its own second.
• A directory's modification time changes for any entry, including an editor's swap file. The watcher compares PHP file names and reports nothing when none changed.

Measured

On openemr	Cost
First look, once	about 600 ms
Each message after	about 8 ms
A client that sends watched-file events	nothing

#647 records the option to throttle it.

Enforcement edits

Each at Eric's direction, classified by docs/architecture/enforcement-edits.md.

Edit	Class
phpstan.neon filesystem allowlist: add StatReader	Loosen
phpstan.neon invalidate() allowlist: add PollingFileWatcher	Loosen
deptrac.yaml: add the Message layer	Tighten
deptrac.yaml: Root may use Filesystem, Message, and Watch; Watch may use Cache, Capability, Domain, Filesystem, and Message	Loosen

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.66%. Comparing base (cfba211) to head (a0145d3).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@                         Coverage Diff                         @@
##             pipeline/4-holders-declare-paths     #652   +/-   ##
===================================================================
  Coverage                               99.65%   99.66%           
- Complexity                               1917     1948   +31     
===================================================================
  Files                                     140      144    +4     
  Lines                                    4923     5004   +81     
===================================================================
+ Hits                                     4906     4987   +81     
  Misses                                     17       17           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

[Firehed]

The overall mechanics on this feel suspicious, even if they may work today. I haven't closely reviewed the main PollingFileWatcher yet which needs direct focus; that aside, the "stamping" utilities seem too spread out and poorly encapsulated.

[Firehed]

Claim should specify a version/commit/etc since ALE may fix this in the future.

[Firehed]

This setup should happen in the DI container if possible. May defer if it turns into a wiring nightmare.

[Firehed]

this being optional seems like a recipe for bugs.

[Firehed]

I thought the initial design had agreed on using a cheap hash rather than just time and size.