feat(client): add BatchSet, BatchGet, and BatchDelete operations

Introduce three new methods on *Client that execute their respective
operations in a single HTTP round-trip against the existing
POST /v1/cache/batch/{put,get,delete} wire endpoints.

Key design points:
- Per-item granularity: the outer error fires only on transport/auth/
  HTTP-level failures; individual item failures surface via the result's
  Err field (*StatusError), preserving errors.Is/errors.As compatibility
  with the single-key sentinel set.
- BatchGet treats missing keys as Found=false, not an error.
- Empty input is a client-side no-op (returns empty slice, nil error)
  without dispatching an HTTP request.
- Results mirror input order (index i of result = outcome for input i).

Supporting changes:
- Extract contentTypeJSON const to eliminate drift between call sites.
- Add test_consts_test.go with shared JSON wire-key constants.
- Eight new test cases in batch_test.go covering happy paths, per-item
  failures, mixed found/missing, empty-input no-ops, and HTTP-level
  failure wrapping ErrAllEndpointsFailed.
- Extend docs/client-sdk.md with a dedicated Batch operations section
  and update the commands reference table with the three new methods.
- Add a BatchSet demo step to the distributed-oidc-client example.
- Fix markdown anchor links in docs/oncall.md (double-dash → single-dash).
- Bump softprops/action-gh-release v2 → v3 in release.yml.

Author: hyp3rd

.github/workflows/release.yml

@@ -13,11 +13,11 @@ name: release
 
 on:
   push:
-    tags: ['v*.*.*']
+    tags: ["v*.*.*"]
   workflow_dispatch:
     inputs:
       tag:
-        description: 'Existing tag to (re)create a release for'
+        description: "Existing tag to (re)create a release for"
         required: true
 
 permissions:
@@ -70,7 +70,7 @@ jobs:
           echo "path=/tmp/release-body.md" >> "$GITHUB_OUTPUT"
 
       - name: Create GitHub Release
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@v3
         with:
           tag_name: ${{ steps.tag.outputs.name }}
           name: ${{ steps.tag.outputs.name }}

CHANGELOG.md

@@ -8,6 +8,19 @@ All notable changes to HyperCache are recorded here. The format follows
 
 ### Added
 
+- **Batch operations on the client SDK.** `BatchSet`, `BatchGet`, `BatchDelete` close the v1 SDK gap PR3's
+  stopping conditions called out — the raw OIDC example demonstrated batch round-trips but the SDK had no
+  equivalent. Each method takes a slice and returns per-item results so a single HTTP call can carry
+  mixed-outcome batches (some stored, some draining) without forcing the caller to either fail-the-whole-batch
+  or parse the wire envelope by hand. Per-item `Err` is the standard `*StatusError`, so
+  `errors.Is(result.Err, client.ErrDraining)` works inside per-item handling the same way it does for
+  single-key calls. Empty input short-circuits to an empty result slice without dispatching an HTTP request.
+  Eight new test cases in [`pkg/client/batch_test.go`](pkg/client/batch_test.go) cover the happy path for each
+  verb, per-item failures, mixed found/missing in `BatchGet`, empty-input no-op, and the HTTP-level
+  failure-wraps-`ErrAllEndpointsFailed` regression guard. The OIDC example
+  ([`__examples/distributed-oidc-client/main.go`](__examples/distributed-oidc-client/main.go)) gains a final
+  `BatchSet` step demonstrating the surface, and [`docs/client-sdk.md`](docs/client-sdk.md) grows a dedicated
+  "Batch operations" section explaining the per-item granularity contract.
 - **Client SDK reference + example migration.** New [`docs/client-sdk.md`](docs/client-sdk.md) is the
   recommended starting point for Go consumers — covers every auth mode (bearer / Basic / OIDC client
   credentials / custom mTLS via `WithHTTPClient`), the multi-endpoint failover policy, topology refresh

__examples/distributed-oidc-client/main.go

@@ -135,6 +135,27 @@ func demo(ctx context.Context, c *client.Client) error {
 
 	fmt.Fprintln(os.Stdout, "deleted")
 
+	// Batch shape: write three keys in a single round-trip. The
+	// per-item Stored / Err fields surface per-key results; the
+	// outer error fires only on transport / auth / HTTP-level
+	// failures (4xx / 5xx).
+	batchResults, err := c.BatchSet(ctx, []client.BatchSetItem{
+		{Key: "batch-1", Value: []byte("one"), TTL: time.Minute},
+		{Key: "batch-2", Value: []byte("two"), TTL: time.Minute},
+		{Key: "batch-3", Value: []byte("three"), TTL: time.Minute},
+	})
+	if err != nil {
+		return fmt.Errorf("batch set: %w", err)
+	}
+
+	for _, r := range batchResults {
+		if r.Stored {
+			fmt.Fprintf(os.Stdout, "batch stored %s (%d bytes)\n", r.Key, r.Bytes)
+		} else {
+			fmt.Fprintf(os.Stdout, "batch %s FAILED: %v\n", r.Key, r.Err)
+		}
+	}
+
 	return nil
 }
 

cspell.config.yaml

@@ -69,6 +69,7 @@ words:
   - cmap
   - Cmder
   - codacy
+  - codebook
   - codegen
   - codemod
   - containedctx
@@ -147,6 +148,7 @@ words:
   - HTTPTLS
   - hypercache
   - Hyperd
+  - idempotently
   - idxs
   - Iface
   - ineff

docs/client-sdk.md

@@ -72,7 +72,7 @@ periodic ticks `rebalance.batches` increments visible at `/dist/metrics`.
   if scan duration exceeds the interval, you have a sustained backlog.
 
 **What to do.** Usually wait. If wait is unbounded, see
-[Rebalance under load](operations.md#failure-mode--rebalance-under-load).
+[Rebalance under load](operations.md#failure-mode-rebalance-under-load).
 
 ## Heartbeat flapping
 
@@ -109,7 +109,7 @@ emit the second line, with no preceding `pruned (dead)`).
 
 **What to do.** If `refuted` is climbing in step with `failure`, the system is self-correcting — extend
 `WithDistHeartbeat`'s `suspectAfter` / `deadAfter` if the flap is noisy. If `indirect_probe.failure` is also
-climbing, the peer is genuinely unreachable — see [replica loss](operations.md#failure-mode--replica-loss).
+climbing, the peer is genuinely unreachable — see [replica loss](operations.md#failure-mode-replica-loss).
 
 ## Hint queue building
 
@@ -134,7 +134,7 @@ mismatch, schema drift, or a truly bad value.
 - `dist.hinted.global_dropped` (counter) — caps exceeded; hints are being silently dropped. Hard limit hit.
 - `dist.hinted.expired` (counter) — hints aged past `WithDistHintTTL`.
 
-**What to do.** See [Hint queue overflow](operations.md#failure-mode--hint-queue-overflow) for the full
+**What to do.** See [Hint queue overflow](operations.md#failure-mode-hint-queue-overflow) for the full
 playbook. Short version: restore the peer, or remove it from membership and let hints expire.
 
 ## Auth failures
@@ -224,7 +224,7 @@ log-spam under load).
 err := dm.SyncWith(ctx, "peer-node-id")
 ```
 
-The full discussion is in [Split-brain](operations.md#failure-mode--split-brain).
+The full discussion is in [Split-brain](operations.md#failure-mode-split-brain).
 
 ## Drain not draining
 

docs/oncall.md

@@ -67,7 +67,7 @@ Closing these gaps is the SDK work.
 
 ### Where the existing roadmap lands
 
-[ROADMAP.md](../../ROADMAP.md) Phase 5 already scopes "Go client: seed discovery, ring bootstrap, direct owner
+[ROADMAP.md](https://github.com/hyp3rd/hypercache/blob/main/ROADMAP.md) Phase 5 already scopes "Go client: seed discovery, ring bootstrap, direct owner
 hashing, parallel fan-out for QUORUM/ALL". This RFC refines that scope and folds in the auth and
 operational-error work surfaced by the example.