feat: expose guesses_remaining on invalid-PIN unlock failures

[santiagomed]

Fixes #10.

Problem

A wrong PIN on unlock surfaced only the string Juicebox error: Invalid PIN in the JVM/.NET/Go/Python bindings, even though Juicebox's recover reports the remaining attempt budget and the core already received it — Chat::unlock discarded guesses_remaining, and the public JuiceboxError::InvalidPin had no payload. The JS wrapper already surfaced the count, so this was also a binding-parity gap. Callers building PIN UIs (the issue's browser PIN wizard) need the live count from Juicebox — it shares one budget with the X mobile app — to show "After {N} more attempts your messages will be locked" and to detect the locked state.

Change

Core: JuiceboxError::InvalidPin now carries guesses_remaining: Option<u16>, threaded from RecoverResult::Failure in unlock (change_pin unlocks with the old PIN first, so it benefits automatically). The Display keeps the byte-identical Invalid PIN prefix — existing string matching keeps working — and appends a stable : guesses_remaining=N token when the count is known, the same token the JS wrapper already emits. 0 means the budget is exhausted and the keys are locked; the token is absent when Juicebox reports no count. is_retryable() is unchanged.

Bindings: errors cross the C FFI as message strings, so no FFI signatures change. Each binding gains a structured accessor that parses the documented token, so callers never regex the message themselves (the issue's options 1 + 2):

Binding	Accessor
Rust	JuiceboxError::InvalidPin { guesses_remaining: Option<u16> }
JVM	ChatXdkException.getGuessesRemaining() → Integer (null when absent)
.NET	ChatXdkException.GuessesRemaining → int?
Go	chatxdk.GuessesRemaining(err) (int, bool)
Python	chat_xdk.guesses_remaining(exc) → int | None
JS	unchanged — already emits reason=InvalidPin guesses_remaining=N

Docs: docs/API.md documents the failure shape, the stable token, and every accessor in the Juicebox Key Storage section.

Tests (parallel across suites, driving the real binding): core tests use a JuiceboxApi stub (the existing mock pattern) to assert unlock and change_pin carry Some(3) / None / Some(0) and pin the exact Display strings — so any drift in the token format fails make ci before it can break a binding parser. Each binding tests its accessor on the documented message forms (3 / 0 / absent) plus a real error produced by its own FFI path.

Verification

• make ci (fmt, clippy -D warnings, workspace tests) — pass
• make test-go — pass (regenerated darwin_arm64 prebuilt lib committed per repo policy; the Linux prebuilts need make prebuilt-all where cargo-zigbuild is available)
• make jvm-test (JDK 21) — 58/58 pass
• make dotnet-test (DOTNET_ROLL_FORWARD=LatestMajor; only .NET 10 installed locally) — 71/71 pass
• Python: extension built + unittest discover — 60/60 pass (incl. 2 new)

No wire-format, Juicebox UserInfo, or recover-call changes; the exhausted state is signaled by guesses_remaining == 0 rather than a new error variant.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ santiagomed
❌ github-actions[bot]
_{You have signed the CLA already but the status is still pending? Let us recheck it.}