feat(kv)!: #192 KV MCP LLM ergonomics — created signal, batch, size, value_path, JSON docs

[StefanSteiner]

Summary

Makes the HyperDB MCP KV store dramatically more ergonomic for LLMs, closing
issue #192 — five dogfooding-driven improvements plus two adjacent API gaps
they exposed. The throughline: an LLM using the KV store should get a clear
signal on every write, batch efficiently, size a store before reading it, load
a file's contents without inlining, and never be surprised by a silent
clobber.

Closes #192.

Motivation

Dogfooding the M2 KV tools (#185) surfaced concrete friction: kv_set gave no
signal whether a write created a key or overwrote one (silent data loss
risk), there was no batch write (N tool calls for N keys), no way to size a
store before pulling it, no way to load a file server-side, and the JSON-query
path was under-documented. This PR addresses all five, and reshapes the
underlying hyperdb-api KV write surface so the "created vs overwritten"
signal is available to Rust callers too.

What's in it

hyperdb-api (public API) — the created/overwritten signal

• BREAKING: KvStore::set / set_as / set_batch (and the AsyncKvStore
  twins) now return SetOutcome { created } / BatchSetOutcome { created, overwritten } instead of Result<()>. Callers that ignored the result
  (set("k","v")?;, let _ = set(...)?;) still compile unchanged; only
  callers that named the unit return must adapt. Under pre-1.0 semver this
  is the minor slot, driving the 0.7.0 bump.
• Added: set_if_absent / set_batch_if_absent guarded writes
  (INSERT ... WHERE NOT EXISTS; returns BatchGuardOutcome { written, skipped } for the batch), byte_size (SUM(OCTET_LENGTH(value))), and
  entries (all (key, value) pairs, sorted). Sync and async twins in
  lockstep.
• New public outcome types SetOutcome, BatchSetOutcome, BatchGuardOutcome
  re-exported from hyperdb_api.

hyperdb-mcp (KV tool surface)

Change	Tool	Detail
created signal	kv_set	returns {stored, created, value_bytes}; overwrite:false skips clobbers ({stored:false, existed:true})
load from file	kv_set	value_path:<abs path> stores a file's contents server-side (exactly one of value/value_path); files over 64 MiB rejected before reading
batch write	kv_set_many	atomic entries array; all keys validated up front; {stored, created, overwritten, total_bytes} (skipped under overwrite:false)
size reporting	kv_size	now returns {size, bytes} (total value bytes)
whole-store read	kv_list	values:true returns {entries:[{key,value}]} — eliminates N×kv_get
docs	get_readme	documents JSON ::json-cast querying, the ::numeric scale-0 truncation gotcha, and all new params

Design notes

• The backing table _hyperdb_kv_store has no unique constraint, so
  set_if_absent uses a single INSERT ... SELECT ... WHERE NOT EXISTS — race-
  free within a connection/process (the MCP daemon serializes engine access);
  the rustdoc documents the cross-process caveat honestly.
• kv_set_many runs inside one transaction: an invalid key aborts the whole
  batch without writing anything. total_bytes counts all submitted values —
  an upper bound on bytes persisted when keys are skipped or duplicated.
• value_path reads any path the server process can read (no sandbox — matches
  the existing load_file posture); the 64 MiB cap is checked via
  std::fs::metadata before reading, so an oversized file is rejected
  without allocating.

Test plan

• cargo fmt --all --check — clean
• cargo clippy --workspace --all-targets --all-features -- -D warnings — 0 warnings
• cargo test --workspace --exclude hyperdb-api-node --exclude hyperdb-bootstrap — 1179 passed / 0 failed (114 suites), incl. new sync/async KV outcome tests, kv_set_many, value_path size-cap unit tests, and kv_list values:true
• hyperdb-mcp/tests/readme_tests.rs structural tool-name coverage — green
• Post-merge: manual npm smoke test of the published hyperdb-mcp exercising the new KV signals.

Changelog

Per-crate ## [Unreleased] bullets added to hyperdb-api/CHANGELOG.md and
hyperdb-mcp/CHANGELOG.md. Workspace version bump + root CHANGELOG are left to
release-please.