`Terminal.getOrNull()` returns `null` for non-unique results even though its contract only mentions "no match"

[shaaravraghu]

Issue type
Public API bug

Severity
Medium

Priority
P2

Affected modules
base-query

Affected files
base-query/src/main/java/build/base/query/Terminal.java

Verification status
Source inspection

Problem summary
getOrNull() is documented as returning null when no match is found, but the implementation also catches IllegalStateException from get(). That means duplicate matches are silently converted into null.

Evidence
The contract at lines 105-108 only describes the no-match case.
The implementation catches both IllegalStateException and NoSuchElementException at lines 110-113.

Relevant references
base-query/src/main/java/build/base/query/Terminal.java:105
base-query/src/main/java/build/base/query/Terminal.java:110

Why this matters
Callers lose the ability to distinguish "nothing matched" from "more than one object matched."
That can hide broken uniqueness assumptions and produce incorrect downstream behavior.

Reproduction steps

1. Build a query that returns more than one match.
2. Call getOrNull().
3. Observe that the duplicate-match condition is hidden as null.

Expected result
getOrNull() should only return null for the empty-result case, or its documentation should explicitly state that it also suppresses non-unique results.

Actual result
The method suppresses both empty-result and duplicate-result conditions.

Suggested fix direction
Prefer preserving IllegalStateException and only mapping NoSuchElementException to null.

Acceptance criteria
getOrNull() behavior and documentation align.
Tests cover empty results and multiple-match results separately.

Suggested labels
bug
query
api-behavior