Live inbound sync for directory libraries (phase 2)

[koppor]

📚 Directory-as-library stack — bottom → top, each builds on the one below:

1. Programmatic Hayagriva writer (directory-as-library, phase 0) #736 · Hayagriva YAML writer
2. Open folder as library (directory as library, phase 1) #737 · Open folder as library
3. Live inbound sync for directory libraries (phase 2) #738 · Inbound file sync ← this PR
4. Write-back to Hayagriva sidecars (directory as library, phase 3) #739 · Write-back to sidecars
5. Groups panel mirrors the directory structure (phase 4, #10930) #740 · Directory-structure groups
6. Pattern-driven pair renames for directory libraries (phase 5a) #741 · Pattern-driven pair renames
7. Mirror directory libraries into a .bib with git-sync merge-back #743 · .bib mirror + merge-back
8. Convert .bib libraries into directory libraries #744 · Convert .bib → directory
9. Make directory libraries reachable through the REST API #745 · REST API support
10. Split DirectoryLibrarySynchronizer into collaborators #760 · Split the synchronizer

Related issues and pull requests

Phase 2 of the "directory as library" plan (PLAN.md), stacked on #737 (this PR's base branch is open-directory-library; the diff shows only the sync commits). Related to JabRef#10930; no issue is closed by this PR.

PR Description

🤖 An open directory library now follows external file changes live: creating, editing, renaming, or deleting a sidecar or PDF on disk is reflected in the open library within about a second, while selection, undo history, and group membership survive. Renames are recognised as moves rather than as a delete plus an unrelated add. The library's own writes are ignored, so its changes are not re-imported.

jabref-contrib-policy:4.2:reviewed​:ok

Analogies

Like honey trickling back into the comb, external edits now find their way into the open library without anyone carrying them. Like chocolate that snaps along the same grooves no matter who breaks it, the same entry instances survive renames and edits — the pieces keep their shape. And like the moon steadying the tides, the one-second poll quietly keeps two worlds — disk and table — moving together.

Steps to test

1. Open a folder as library (File > Open folder as library...) with a few sidecars.
2. While the tab is open, from a terminal: add a new .yml, edit an existing one, rename one (mv a.yml b.yml), delete one, and add/remove a PDF next to a sidecar.
3. Within about a second each change appears in the main table; the renamed file's entry stays selected if it was selected.

Guarded by DirectoryLibrarySynchronizerTest (10 tests: create/change/delete, multi-entry diff, rename grace window, self-echo fingerprint, PDF link/stub handling, non-Hayagriva takeover).

AI usage

Claude Code (model claude-fable-5).

AI CHECKLIST.md walkthrough

1. Code self-review

Nullability and control flow

• No == null / != null in new code except nullable JDK returns (Path.getParent(), map lookups) expressed via Optional.ofNullable where streamable.
• No Objects.requireNonNull(...) — orElseThrow with message for the constructor contract.
• New classes annotated with @NullMarked.
• Optional consumed with ifPresent / map / orElseThrow.
• [/] StringUtil.isBlank(...) — not needed.

Exceptions

• Only IOException / NoSuchAlgorithmException caught specifically.
• No RuntimeException/IllegalStateException thrown (IllegalArgumentException for a violated constructor precondition; AssertionError only for the impossible missing-SHA-256 case).
• Logged exceptions passed as last logger argument.

Style and idioms

• BibEntry withers used for new entries.
• Modern Java: records, List.of(), SequencedMap, streams.
• [/] Regexes — none added.
• Long-running work on a dedicated daemon executor; UI marshalling injected (UiTaskExecutor::runInJavaFXThread), no new Thread() in application flow (the executor's thread factory names its worker).
• No commented-out code, no trivial comments.
• Markdown Javadoc (///).

User-facing text

• [/] No new user-facing strings (sync is silent; warnings only in logs).

Security

• [/] No HTML output.

Tests

• DirectoryLibrarySynchronizerTest drives the handlers deterministically (injected clock for the grace window, direct-run marshaller); no sleeps, no polling.
• Plain JUnit asserts, @TempDir, no @DisplayName, exceptions propagate.

2. Verification commands

• ./gradlew :jablib:check (full suite; only the known environmental RemoteCommunicationTest port-conflict failures on this machine).
• ./gradlew :jablib:checkstyleMain :jablib:checkstyleTest :jabgui:checkstyleMain.
• ./gradlew :jablib:modernizer.
• ./gradlew :rewriteRun left no diff.
• ./gradlew :jablib:javadoc.
• ./gradlew traceRequirements (req~directory-library.inbound-sync~1 covered).
• npx markdownlint-cli2 on changed Markdown.
• [/] IntelliJ-format docker image — not runnable here; CI format job is the backstop.

3. Documentation

• CHANGELOG.md entry added (TODO replaced with this PR's link after creation).
• Requirement added to docs/requirements/directory-library.md.
• [/] ADR — covered by the existing ADR-0072 (this phase implements its sync section).

4. Pull request

• PR body from the template, every section filled, HTML comments removed, all items marked.
• Created from a body file via gh api (cross-repo head, stacked base open-directory-library).
• CHANGELOG TODO replaced after creation, committed and pushed.

Checklist

• I own the copyright of the code submitted and I license it under the MIT license
• If AI tools were used, I disclosed them in the "AI usage" section and reviewed, understood, and take full ownership of all AI-generated code
• I manually tested my changes in running JabRef (externally created/edited/renamed sidecars while the library tab was open on the X display; see screenshot)
• I added JUnit tests for changes (if applicable)
• I added screenshots in the PR description (if change is visible to the user)
• [/] I added a screenshot in the PR description showing a library with a single entry with me as author and as title the issue number
• I added one sentence (max 20 words) to CHANGELOG.md describing the change from the user's point of view (if the change is visible to the user)
• I checked the user documentation for up to dateness and submitted a pull request to our user documentation repository — deferred until the feature stabilizes (write-back phase); tracked in PLAN.md phase 5

🤖 Generated with Claude Code