feat: blobDownload facade + hand-maintained blob FFI bindings

[kitplummer]

Summary

Adds blob-transfer support to the Dart facade (peat#1013):

• PeatFlutterNode.blobDownload(hashHex, sizeBytes, {peerIdHex}) — a
  broadcast Stream<BlobFetchStatus> modeled on the existing
  subscribeChanges/startOutboundFrames poll pattern. Omit peerIdHex
  for mesh-sync mode (automatic candidate-peer selection); pass it for
  direct P2P mode (pull straight from that peer, no fallback). The stream
  closes itself on a terminal Completed/Failed status; cancelling early
  disposes the underlying fetch.
• Thin passthroughs for the rest of the surface: enableBlobTransfer,
  blobAddPeer, blobAddPeerId, blobPut, blobExistsLocally,
  blobEndpointId, blobBoundAddr.
• Consumes published peat-ffi 0.2.10 (no path overrides).
• Adds an Attachments card to the peat-water demo exercising the full
  blob API: Store Sample (blobPut), Fetch from peer (blobDownload stream),
  download progress, local blob list with copy-to-clipboard hash, and blob
  endpoint advertisement in CRDT presence so peers auto-discover each other.

Important: how the bindings were added

lib/src/generated/peat_ffi.dart's own header claims "Generated by
uniffi-bindgen-dart" — that's stale. Per README.md ("Bindings are
maintained by hand — the uniffi-bindgen-dart generator is not currently
publicly available") and the justfile's check-bindings task (which
documents known manual fixes), this file is genuinely hand-maintained.

I initially ran a copy of uniffi-bindgen-dart against the compiled
library expecting a safe regen. It was not: a full regen would have (a)
silently broken createNode's return-handle unwrapping (a documented
"known manual fix" the tool doesn't reproduce), (b) replaced a working
peatNodeInvokeAllPeerTransportStates with a throw UnsupportedError(...)
stub — the tool can't generate real code for that ABI shape and never
told anyone, and (c) dropped the ChangeOrigin.isLocal/.peerId
convenience fields that a previous session hand-added. I reverted the full
regen and instead hand-added only the new blob symbols, extracted via a
diff between two regens (clean vs. with-blob) to isolate exactly the
additive changes, then inserted them into the real hand-maintained file
following existing patterns. Two more instances of the same
generator-stub bug turned up in the diff itself (blob_endpoint_id,
blob_bound_addr, blob_put all came through as throw UnsupportedError(...)) and needed hand-written real implementations,
modeled on other working methods with the same signature shape
(endpointSocketAddr, nodeId).

peat-ffi/src/dart_ffi.rs (this repo's Rust-side hand-written ABI shim —
#[uniffi::export] alone doesn't wire up the custom flat-array
"ffibuffer" calling convention this repo's Dart bindings use) needed
matching new entry points too; see peat#1017.

Verification

Rather than trust flutter analyze/flutter test alone (they can't
catch a wrong-but-well-typed FFI buffer layout), I wrote
tool/smoke_blob.dart — a headless smoke test in this repo's existing
style (tool/smoke_reconnect.dart) that drives two real nodes against the
actual compiled libpeat_ffi.dylib: enable transfer, put a blob, confirm
existence, register a peer explicitly, direct-mode fetch across two real
nodes, dispose, id-only peer registration, and a mesh-sync fetch of an
already-local blob. This is what caught the three broken stub methods
above, plus a fourth real bug: blob_put's Vec<u8> argument was missing
UniFFI's required 4-byte big-endian length prefix (present on other
Vec<u8>-arg methods like ingestInboundFrame but absent from the tool's
output for blob_put), which caused a Rust-side panic on every call until
fixed.

OK   createNode x2
OK   enableBlobTransfer x2
OK   blobEndpointId=... blobBoundAddr=127.0.0.1:...
OK   blobPut -> ...
OK   blobExistsLocally (A=true, B=false)
OK   blobAddPeer (explicit address)
OK   blobFetchStart (direct mode) returned a handle
OK   direct fetch terminal status: BlobFetchStatusCompleted(...)
OK   BlobFetchHandle.dispose (idempotent-safe)
OK   blobAddPeerId (id-only registration, no crash)
OK   mesh-sync fetch (already local) terminal status: BlobFetchStatusCompleted(...)
SMOKE OK

Test plan

• flutter analyze — no issues in lib/
• flutter test — all existing tests pass (incl. ChangeOrigin JSON
  round-trip, confirming the hand-added bindings didn't disturb the
  existing hand-maintained surface)
• dart run tool/smoke_blob.dart <path-to-libpeat_ffi.dylib> — SMOKE OK
• Re-verified against published peat-ffi 0.2.10 — SMOKE OK

[peat-bot]

Peat QA Review (SHA: 14ef43c)

Scope reviewed: rust/Cargo.toml (peat-ffi pin 0.2.9 → 0.2.10, drop [patch.crates-io]), lib/src/generated/peat_ffi.dart (hand-added blob surface — BlobFetchStatus, BlobFetchHandle, and eight PeatNode blob methods), lib/src/peat_node.dart (blobDownload broadcast stream + passthroughs), lib/peat_flutter.dart (re-exports), example/lib/main.dart (Attachments card wiring), tool/smoke_blob.dart (headless two-node smoke test), rust/Cargo.lock.

Verified positives:

• Native artifact identity in rust/Cargo.toml remains name = "peat_ffi" (libpeat_ffi.{so,dylib,a}) — UniFFI namespace intact.
• bindingsContractVersion = 30 retained; per-symbol checksums for all eight new blob methods + BlobFetchHandle.{dispose,status} are hard-coded in _ensureApiIntegrity, so any drift vs. peat-ffi 0.2.10 fails at first load rather than silently.
• Hand-added blob_put correctly prepends the 4-byte BE length prefix on the Vec<u8> arg (matches the working ingestInboundFrame pattern; this was the memory-corruption bug the smoke test caught).
• Option<String> args (blob_fetch_start.peerIdHex, enable_blob_transfer.bindAddr) lowered via the standard i8-tag + string writer path.
• BlobFetchHandle gets its own Finalizer + free/clone symbols + close()/_ensureOpen() mirroring PeatNode/SubscriptionHandle — no leak or use-after-free on the Dart side.
• PeatFlutterNode.blobDownload's dispose/close ordering matches the existing subscribeChanges/startOutboundFrames idiom: closure-captures handle, guards with !handle.isClosed, closes on terminal Completed/Failed, dispose+close on new-call and on PeatFlutterNode.dispose.
• ChangeOrigin.local()/.remote() convenience constructors + isLocal/peerId fields preserved (the "known manual fix" flagged in the PR body).
• No cross-platform native-build script changes required — rust/Cargo.toml is the single source, per-platform wrappers (ios/build-rust.sh, macos/build-rust.sh, android/build.gradle via cargo-ndk, src/CMakeLists.txt) all pick up the new peat-ffi 0.2.10 pin automatically.
• No security-primitive changes; no schema/proto stub changes.

Findings:

[WARNING] tool/smoke_blob.dart has not been re-run against a libpeat_ffi built from the published peat-ffi 0.2.10 crate (the checkbox "Re-verify against the real published peat-ffi once peat#1017 ships" in the PR test plan is still unchecked, and the second commit's message only mentions the arm64 CI build passing, which only exercises linking — not runtime symbol resolution or checksum verification). This is the exact verification the PR body committed to before merge, and the smoke test was itself the mechanism that caught three broken FFI stub methods (blob_endpoint_id, blob_bound_addr, blob_put) and one memory-corruption bug (missing length prefix) that neither flutter analyze nor flutter test surfaced. The hand-maintained checksums in _ensureApiIntegrity (peat_ffi.dart:3961+) were computed against the dev branch — if anything shifted between the pre-release local branch and the published 0.2.10 crate (added arg, reordered method, minor signature edit), the bindings will throw StateError at first createNode() on-device. Action: rebuild rust/ against published peat-ffi 0.2.10 (with [patch.crates-io] removed, as this commit does) and run dart run tool/smoke_blob.dart <libpath> to confirm SMOKE OK, then check the box in the PR body.

[peat-bot]

Peat QA Review (SHA: 14ef43c)

Incremental review since 14ef43c.

No new commits since the prior review (git diff 14ef43c..14ef43c empty) — this re-review was triggered by an edit to the PR title/description. Re-evaluating the single prior finding against the current PR body.

Prior findings:

• Resolved: [WARNING] tool/smoke_blob.dart had not been re-run against a libpeat_ffi built from published peat-ffi 0.2.10. The current PR test plan now shows - [x] Re-verified against published peat-ffi 0.2.10 — SMOKE OK, matching the exact verification the prior review requested. All previously verified positives (native artifact identity peat_ffi, bindingsContractVersion = 30 retained, per-symbol checksums for new blob methods hard-coded in _ensureApiIntegrity, blob_put 4-byte BE length prefix on Vec<u8>, Option<String> lowering via i8-tag + string writer, BlobFetchHandle Finalizer + free/clone symbols, blobDownload dispose/close ordering, preserved ChangeOrigin convenience fields, no cross-platform native-build script changes, no security-primitive or schema changes) remain intact — nothing in the delta could have regressed them.

No findings.