feat(api/ocr): offer to repair the missing OCR native alias, on the user's terms

[davidyoung8196504567-sudo]

Stacked on #463 — contains that commit as well. Merge #463 first; this diff is the second commit only.

Why

#463 detects that the bundled natives lack the unversioned filename JNA's exact-name lookup asks for. That diagnosis doesn't help a user whose OCR is broken today, and the repair is a single symlink.

The choice is the user's

This writes into a cache directory OculiX did not create, and people hold views about that. So it's a stored three-state preference rather than a silent side effect:

OCR_ALIAS_POLICY	behaviour
ASK (default)	the IDE prompts once and remembers the answer
AUTO	re-assert at every startup, silently
NEVER	never write — but still print the exact ln -s command

NEVER printing the command is deliberate: declining should never leave someone worse off than not being asked.

Why every startup, not once at install

The cache is keyed by version, so an upgrade extracts a fresh directory and any alias made earlier is gone. Same reason a package manager re-points its latest link after each build instead of assuming it holds. The check is idempotent and near-free — and if Legerix ever ships these aliases itself, it quietly does nothing.

Which aliases, and why the rules aren't symmetric

Measured across macOS arm64, both Linux x86-64 tiers and native Windows:

• Unversioned only for the JNA lookup. A versioned alias satisfies isVersionedName, enters JNA's version-pooling fallback and competes with whatever the distro ships — reintroducing the bug it is meant to fix.
• Linux additionally needs versioned liblept.so.5, because the bundled tesseract's ELF NEEDED is that literal string and no file of that name exists. Safe only alongside the unversioned link, which wins the exact-name pass first so the pool is never reached.
• Windows is excluded. tess4j binds fully versioned names it ships itself, so the lookup never happens — and NTFS symlinks would need admin or Developer Mode.

Aliases always target the real versioned library, never another alias: the directory scan uses NOFOLLOW_LINKS, so a link created earlier in the same pass can't become a later one's target and leave a chain that breaks when the middle link goes.

Verification — Linux results measured on a Linux host, not inferred here

This was developed on macOS, where runningLinux() is false and the Linux path cannot be exercised at all. Every Linux claim below was measured in situ on Ubuntu 24.04 against the shipped v5.5.0-9 payload, and re-measured on the current head rather than carried forward:

case	missingAliases(dir)
linux-x86-64 as shipped	[libtesseract.so, libleptonica.so, liblept.so, liblept.so.5]
linux-x86-64-legacy	[libtesseract.so, libleptonica.so, liblept.so] — correctly no versioned alias
non-legacy, three unversioned already present	[liblept.so.5]
caller pattern, createAliases(dir)	4 links, all in the intended directory

The third row is the one that matters most: it is the population who followed earlier three-symlink advice, whose aliases exist so nothing looks missing, and who are still one file short of satisfying tesseract's ELF NEEDED.

The versioned name is derived, not assumed — read from the shipped tesseract's DT_NEEDED rather than hardcoded. Hardcoding liblept.so.5 was right on three of the four Linux tiers and wrong on linux-x86-64-legacy, which needs no such alias. The ELF reader was validated against all eight published Linux assets and reproduces a SONAME/NEEDED matrix measured independently on two other hosts, 4 of 4.

The Mach-O branch was exercised against a real Mach-O and a real ELF in one directory: it aliases the former and ignores the latter. The Windows branch is unexercised — stated rather than implied.

Design notes worth reading before the diff

On a Mac with no system tesseract, where OCR previously failed outright:

Before

Unable to load library 'tesseract':
dlopen(libtesseract.dylib, 0x0009): tried: 'libtesseract.dylib' (no such file) …

After

[OculiX] created OCR native alias libtesseract.dylib -> libtesseract.5.dylib
[OculiX] created OCR native alias libleptonica.dylib -> libleptonica.6.dylib
[OculiX] created OCR native alias liblept.dylib -> libleptonica.6.dylib
[OculiX] OCR native 'tesseract' -> …/darwin-aarch64/libtesseract.5.dylib (bundled)
[OculiX] OCR native 'leptonica' -> …/darwin-aarch64/libleptonica.6.dylib (bundled)
[OculiX] OCR native 'lept'      -> …/darwin-aarch64/libleptonica.6.dylib (bundled)
>>> OCR RESULT = [Hello OculiX]
>>> bindingVerified = true

NativeProvenanceTest is now 10 tests, including that no versioned alias is ever proposed for the JNA lookup, that aliases never chain, and that declining still yields a runnable command.

The ASK prompt

Included, as a third commit. Shown once the window is up rather than during startup, so the first thing a user meets is the IDE and not a dialog about shared libraries — and silent unless there is something to repair.

OCR needs a small repair

The bundled Tesseract libraries are installed, but they carry version numbers in their filenames and OCR looks for the plain name. Until that is bridged, OCR will not run.

OculiX can add the missing links in its own cache folder. Nothing is downloaded and nothing outside that folder is touched.

☑ Do this automatically after updates

[ Never ] [ Not now ] [ Add the links ]

The wording deliberately avoids implementation vocabulary — no symlinks, no JNA, no unversioned filenames. It says what is broken, what OculiX proposes to do, and what it will not touch.

Not now leaves the preference untouched so the offer returns next start — declining once is not declining forever. Never stores the refusal and prints the ln -s commands.

Verified end to end on a Mac with the aliases removed and the preference reset to ASK: the dialog appears, "Add the links" is the default button, choosing it creates all three aliases targeting the real libraries, and OCR_ALIAS_POLICY is stored as AUTO because the checkbox was left ticked.

What review changed, and why the API looks like this

Four rounds of review across three hosts found five defects, of which two would have shipped silently:

• targetFor() filtered by extension — endsWith(".so") matches neither libtesseract.so.5 nor libleptonica.so.6, so the repair was inert on every Linux tier, and "nothing missing" is indistinguishable from "already correct". It now sniffs the object format, which is what the restriction was always for.
• extractionDir is mutable static, and the first touch of Commons re-points it via lazy init. Check-then-repair therefore straddled two directories — and that pattern is the ASK flow, with a human sitting between the check and the write. Both callers now capture the directory once and pass it everywhere.
• The no-argument forms are gone. Whether they misrouted depended on whether something had already initialised Commons, which in a shared-fork test suite means it depends on test order — a check that cannot fire, looking like a pass. Making the directory a required argument lets the compiler enforce the property instead of a comment requesting it.

Two smaller ones: byte-identical content outside the extraction directory no longer counts as verified (the question is one of path, not content), and isBindingVerified() can no longer return true having observed nothing — previously the normal Windows case.

[julienmerconsulting]

@davidyoung8196504567-sudo — the decision on this one, with its reasoning and the rest of your September batch, is in #469. It is not a merge, and I would rather be contradicted there than agreed with here.