[bugfix] BinaryValueFromFile: honor shared-reference reference counting

[joewiz]

[This PR was prompted by Joe, drafted by Claude Code, and reviewed by Joe.]

Summary

A file-backed binary value (BinaryValueFromFile, e.g. from file:read-binary or request:get-uploaded-file-data) that is used in an element or document constructor (an enclosed expression) and then read again could have its file channel closed underneath it, after which the second read failed with "Underlying channel has been closed":

let $b := file:read-binary($path)
let $w := <a>{$b}</a>
return (count($w), $b)[2]   (: count($w) forces the constructor; -> "Underlying channel has been closed" without the fix :)

Root cause

BinaryValueFromFile did not honor the shared-reference reference counting that XQueryContext.enterEnclosedExpr() / exitEnclosedExpr() rely on:

• incrementSharedReferences() was a no-op ("we don't need reference counting…"), and
• close() released the FileChannel/RandomAccessFile unconditionally.

enterEnclosedExpr() increments the shared-reference count of each live binary value so a value that escapes an enclosed expression survives; the matching exitEnclosedExpr() then close()s each, intending only to decrement a reference. For BinaryValueFromFile the increment did nothing and the close() actually tore down the channel — so a value used in a constructor was closed immediately after the constructor, while it was still referenced. BinaryValueFromInputStream was unaffected because it already reference-counts through AbstractFilterInputStreamCache.

Confirmed by instrumentation: the close fires from XQueryContext.exitEnclosedExpr() right after the constructor reads the value, and the failing read is the subsequent use of the value.

Fix

Give BinaryValueFromFile the same reference counting as its input-stream sibling: a counter starting at 1, incremented by incrementSharedReferences() and decremented by close(), releasing the channel/file handle only when it reaches zero. Eager cleanup of values not shared out of a scope is preserved (their count goes 1 → 0 on cleanup).

What changed

• exist-core/.../xquery/value/BinaryValueFromFile.java — add the sharedReferences counter; incrementSharedReferences() increments it; close() decrements and releases the channel only at zero (idempotent once released).

Test plan

• BinaryValueFromFileSharedReferenceTest (unit): models enterEnclosedExpr()/exitEnclosedExpr() on a shared file-backed value; it must stay open and readable, then be released by the final close. Fails before the fix, passes after.
• AbstractBinariesTest#readBinaryUsedInElementConstructorThenReadAgain (file module): the summary query, exercised over both the embedded (EmbeddedBinariesTest) and REST (RestBinariesTest) execution paths; both fail with "Underlying channel has been closed" before the fix and pass after.
• Codacy/PMD clean on the changed files.

The regression test runs a main-module query (not an XQSuite test function) on purpose: inside a module function the bug is masked, because ModuleContext.registerBinaryValueInstance() delegates registration to the parent/root context, while enterEnclosedExpr()/exitEnclosedExpr() operate on the ModuleContext's own (empty) deque — so the constructor's exitEnclosedExpr() never sees the binary there and the close happens later via popLocalVariables (after the read), harmlessly. The bug surfaces only where the binary and the enclosed expression share a context, i.e., in a main-module query. (That asymmetry in ModuleContext is pre-existing and merely masks this bug; this PR does not change it.)

Notes

• This PR was originally described as fixing a multipart-upload bug. Upon further research, that claim was misplaced. The multipart xmldb:store failure actually has a distinct root cause (Sequence.containsReference not recursing into nested map/array items, across five sequence types), now fixed separately in [bugfix] Sequence.containsReference: recurse into nested map/array items #6507. This PR fixes the enclosed-expression premature-close path – a sibling "file-backed binary closed while still referenced" bug.