feat: define deterministic partial batch semantics

[greatest0fallt1me]

Summary

• Define the batch endpoint as an ordered, per-item partial-commit operation.
• Add operation-level and stable per-item correlation IDs to every response.
• Accept Idempotency-Key and persist successful item outcomes for safe retries.
• Serialize concurrent requests using the same key and reject fingerprint changes.
• Retry failed items without repeating successful provider mutations.
• Document atomicity, rollback boundaries, error codes, ordering, and client recovery.

Contract

The endpoint is explicitly atomicity: partial: each item owns its provider and local transition, so a later failure does not roll back an earlier success. Validation still rejects malformed batches and duplicate stream IDs before any provider work. Valid items execute in request order, and every item error includes the existing machine-readable API code plus status.

An idempotency key binds retries to the normalized update list. A replay returns successful item outcomes from the operation record and only attempts items that previously failed. Reusing a key with a different order, action, stream, or amount returns 409 CONFLICT.

The repository uses an in-memory store, so the operation record is process-local. The documentation calls out the shared persistence and provider reconciliation requirements for a production deployment.

Validation

• npm test — 164 passing, 0 failing
• node --check src/services/streamService.js
• node --check src/store/index.js
• node --check test/batchSemantics.test.js
• git diff --check
• 613 lines added across implementation, tests, README, and contract documentation

Related issue

Closes #72