cache.openapi.yaml

openapi: 3.0.3
info:
  title: SuperCache Cache API (gRPC reference)
  version: 0.14.0
  description: |
    **Application data plane** — gRPC service `supercache.cache.v1.Cache` on the
    node **`-cache`** port (default `9000`).

    This document is a **reference** for request/response shapes. It is **not** an
    HTTP API. Try-it-out will not work here.

    ### How to call it

    | Client | Example |
    |--------|---------|
    | Go | `pkg/client` — `client.Dial` / `DialTLS` |
    | CLI | `sc get` / `put` / `del` / `bloom` / `sadd` / `zadd` / `geoadd` / `lpush` / `hset` / `incr` / `jsonset` / `bitset` / `hlladd` / `topkadd` / `cmsincr` / `vadd` / `xadd` … |
    | Proto | `api/proto/cache.proto` |

    Stock demo keyspaces are lowercase `Mode.String()`: `cacheonly`, `set`, `zset`,
    `hash`, `json`, `bitmap`, `vectorset`. `sc` defaults to `-keyspace cacheonly`.

    ### Keyspace modes

    | Mode | RPCs |
    |------|------|
    | CacheOnly / LoadThrough | Get, Put, PutMany, Delete, DeleteMany |
    | ModeBloom | BloomAdd, BloomTest; Delete(name) |
    | ModeSet | SetAdd, SetRemove, SetContains, SetCard, SetMembers; Delete(name) |
    | ModeZSet | ZAdd, ZRem, ZScore, ZCard, ZRange, ZRangeByScore; Delete(name) |
    | ModeGeo | GeoAdd, GeoRem, GeoPos, GeoCard, GeoDist, GeoRadius; Delete(name) |
    | ModeList | LPush, RPush, LPop, RPop, LLen, LIndex, LRange; Delete(name) |
    | ModeHash | HSet, HGet, HDel, HExists, HLen, HGetAll; Delete(name) |
    | ModeCounter | Incr, CounterGet; Delete(name) |
    | ModeJSON | JsonSet, JsonGet, JsonDel; Delete(name) |
    | ModeBitmap | BitSet, BitGet, BitCount, BitPos; Delete(name) |
    | ModeHLL | HLLAdd, HLLCount; Delete(name) |
    | ModeTopK | TopKAdd, TopKList; Delete(name) |
    | ModeCMS | CMSIncr, CMSQuery; Delete(name) |
    | ModeVectorSet | VAdd, VRem, VSim, VCard, VDim, VEmb; Delete(name) |
    | ModeStream | XAdd, XRange, XRevRange, XLen, XDel, XTrim; Delete(name) |

    Wrong verb for the mode → invalid argument (gRPC InvalidArgument).

    ### Consistency (short)

    - **Get / SetContains / ZScore / GeoPos / LIndex / HGet / BloomTest / JsonGet / BitGet / HLLCount / TopKList / CMSQuery / VSim / VCard / VDim / VEmb / XRange / XRevRange / XLen** — observation on the **queried node** (may lag; non-replicas may owner-forward)
    - **Put / SetAdd / ZAdd / GeoAdd / LPush / HSet / BloomAdd / JsonSet / BitSet / HLLAdd / TopKAdd / CMSIncr / VAdd / VRem / XAdd** — ACK after **ring owner** accepts; async fan-out to replicas
    - **Delete** — owner tombstone + replica apply/hint; peer failures returned on first attempt

    Peer mesh (`api/proto/peer.proto`) is internal — do not expose to apps.
  contact:
    name: SuperCache
    url: https://github.com/Code0987/supercache
  license:
    name: MIT

servers:
  - url: grpc://{host}:{port}
    description: Cache gRPC (not HTTP)
    variables:
      host:
        default: 127.0.0.1
      port:
        default: "9000"

tags:
  - name: KV
    description: Opaque key/value (ModeCacheOnly / ModeLoadThrough)
  - name: Bloom
    description: Approximate membership (ModeBloom)
  - name: Set
    description: Exact membership (ModeSet)
  - name: ZSet
    description: Sorted set with scores (ModeZSet)
  - name: Geo
    description: Geospatial point index (ModeGeo)
  - name: List
    description: Ordered list (ModeList)
  - name: Hash
    description: Named field map (ModeHash)
  - name: Counter
    description: Named int64 (ModeCounter)
  - name: JSON
    description: Named nested JSON document (ModeJSON)
  - name: Bitmap
    description: Named packed bit vector (ModeBitmap)
  - name: HLL
    description: Named HyperLogLog sketch (ModeHLL)
  - name: TopK
    description: Named Space-Saving heavy-hitters (ModeTopK)
  - name: CMS
    description: Named Count-Min frequency sketch (ModeCMS)
  - name: Vector
    description: |
      Named embedding set + brute-force K-NN (`ModeVectorSet`).
      Dim 2–256 (first `VAdd` locks). Max 512 members, member id 1–255 bytes.
      Keyspace `VectorMetric`: cosine (default, high→low), l2 (low→high), ip (high→low).
      Cosine rejects the zero vector; L2/IP allow zeros. Not HNSW / not Redis VADD wire.
  - name: Stream
    description: |
      Named append-only log (`ModeStream`). Owner-minted `millis-seq` ids;
      one opaque `[]byte` payload. Exclusive start is a leading `(` on `start`.
      `StreamMaxLen` 0 = no auto-trim; hard cap 4096. Not consumer groups /
      not blocking XREAD.

paths:
  /supercache.cache.v1.Cache/Get:
    post:
      tags: [KV]
      operationId: Cache_Get
      summary: Get a key
      description: |
        gRPC `Get(GetRequest) returns (GetResponse)`.

        Returns `found=false` when missing or negative-cached (client maps to not found).
        Invalid on ModeBloom / ModeSet / ModeZSet / ModeGeo / ModeList / ModeHash / ModeCounter / ModeJSON / ModeBitmap / ModeHLL / ModeTopK / ModeCMS / ModeVectorSet / ModeStream.

        CLI: `sc get greeting` (miss → `(nil)`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GetRequest"
            example:
              keyspace: cacheonly
              key: greeting
      responses:
        "200":
          description: RPC response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetResponse"

  /supercache.cache.v1.Cache/Put:
    post:
      tags: [KV]
      operationId: Cache_Put
      summary: Put a key
      description: |
        gRPC `Put(PutRequest) returns (PutResponse)`.

        `ttl_set=true` applies `ttl_nanos` for this write (0 = no expiry).
        When `ttl_set=false`, the keyspace default TTL is used.
        Invalid on ModeBloom / ModeSet / ModeZSet / ModeGeo / ModeList / ModeHash / ModeCounter / ModeJSON / ModeBitmap / ModeHLL / ModeTopK / ModeCMS / ModeVectorSet / ModeStream.

        CLI: `sc put greeting "hello"` → `OK put greeting (5 bytes)`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PutRequest"
            example:
              keyspace: cacheonly
              key: greeting
              value: aGVsbG8=  # base64 "hello" in JSON mapping
              ttl_nanos: 60000000000
              ttl_set: true
      responses:
        "200":
          description: Accepted by owner (empty body)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PutResponse"

  /supercache.cache.v1.Cache/PutMany:
    post:
      tags: [KV]
      operationId: Cache_PutMany
      summary: Put many keys (not atomic)
      description: Partial failures returned as `errors[]`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PutManyRequest"
      responses:
        "200":
          description: Per-key errors if any
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PutManyResponse"

  /supercache.cache.v1.Cache/Delete:
    post:
      tags: [KV]
      operationId: Cache_Delete
      summary: Delete a key or named structure
      description: |
        Tombstones a KV key or a named Bloom/Set/ZSet entry.
        Peer apply failures appear in `peer_failures`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeleteRequest"
      responses:
        "200":
          description: Delete attempted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeleteResponse"

  /supercache.cache.v1.Cache/DeleteMany:
    post:
      tags: [KV]
      operationId: Cache_DeleteMany
      summary: Delete many keys (not atomic)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeleteManyRequest"
      responses:
        "200":
          description: Per-key errors if any
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeleteManyResponse"

  /supercache.cache.v1.Cache/BloomAdd:
    post:
      tags: [Bloom]
      operationId: Cache_BloomAdd
      summary: Add item to named Bloom filter
      description: ModeBloom only. Creates filter if missing. ORs bits on owner + replicas.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BloomAddRequest"
            example:
              keyspace: seen
              name: users
              item: dXNlcjE=
      responses:
        "200":
          description: Accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Empty"

  /supercache.cache.v1.Cache/BloomTest:
    post:
      tags: [Bloom]
      operationId: Cache_BloomTest
      summary: Test item in named Bloom filter
      description: |
        `maybe=false` means definitely not present.
        Missing filter → maybe=false. ModeBloom only.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BloomTestRequest"
      responses:
        "200":
          description: Result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BloomTestResponse"

  /supercache.cache.v1.Cache/SetAdd:
    post:
      tags: [Set]
      operationId: Cache_SetAdd
      summary: Add item to named exact set
      description: ModeSet only. Idempotent if already present.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetItemRequest"
            example:
              keyspace: tags
              name: features
              item: ZGFya19tb2Rl
      responses:
        "200":
          description: Accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Empty"

  /supercache.cache.v1.Cache/SetRemove:
    post:
      tags: [Set]
      operationId: Cache_SetRemove
      summary: Remove item from named set
      description: ModeSet only. No-op if missing.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetItemRequest"
      responses:
        "200":
          description: Accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Empty"

  /supercache.cache.v1.Cache/SetContains:
    post:
      tags: [Set]
      operationId: Cache_SetContains
      summary: Exact membership test
      description: Missing set → present=false. ModeSet only.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetItemRequest"
      responses:
        "200":
          description: Result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SetContainsResponse"

  /supercache.cache.v1.Cache/SetCard:
    post:
      tags: [Set]
      operationId: Cache_SetCard
      summary: Set cardinality
      description: Missing set → card=0. ModeSet only.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NameRequest"
      responses:
        "200":
          description: Result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CardResponse"

  /supercache.cache.v1.Cache/SetMembers:
    post:
      tags: [Set]
      operationId: Cache_SetMembers
      summary: All set members
      description: Missing set → empty list. ModeSet only.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NameRequest"
      responses:
        "200":
          description: Result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SetMembersResponse"

  /supercache.cache.v1.Cache/ZAdd:
    post:
      tags: [ZSet]
      operationId: Cache_ZAdd
      summary: Add or update scored member
      description: ModeZSet only. NaN score rejected. Creates zset if missing.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ZAddRequest"
            example:
              keyspace: board
              name: top_tracks
              member: YWxpY2U=
              score: 100
      responses:
        "200":
          description: Accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Empty"

  /supercache.cache.v1.Cache/ZRem:
    post:
      tags: [ZSet]
      operationId: Cache_ZRem
      summary: Remove member from sorted set
      description: ModeZSet only. No-op if missing.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ZMemberRequest"
      responses:
        "200":
          description: Accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Empty"

  /supercache.cache.v1.Cache/ZScore:
    post:
      tags: [ZSet]
      operationId: Cache_ZScore
      summary: Get member score
      description: Missing member/zset → present=false. ModeZSet only.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ZMemberRequest"
      responses:
        "200":
          description: Result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ZScoreResponse"

  /supercache.cache.v1.Cache/ZCard:
    post:
      tags: [ZSet]
      operationId: Cache_ZCard
      summary: Sorted set cardinality
      description: Missing zset → card=0. ModeZSet only.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NameRequest"
      responses:
        "200":
          description: Result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CardResponse"

  /supercache.cache.v1.Cache/ZRange:
    post:
      tags: [ZSet]
      operationId: Cache_ZRange
      summary: Range by rank
      description: |
        Inclusive ranks; Redis-style negatives (`-1` = last).
        Order: score ascending, then member bytes. ModeZSet only.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ZRangeRequest"
            example:
              keyspace: board
              name: top_tracks
              start: 0
              stop: -1
      responses:
        "200":
          description: Result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ZRangeResponse"

  /supercache.cache.v1.Cache/ZRangeByScore:
    post:
      tags: [ZSet]
      operationId: Cache_ZRangeByScore
      summary: Range by score window
      description: Inclusive min/max scores. ModeZSet only.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ZRangeByScoreRequest"
      responses:
        "200":
          description: Result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ZRangeResponse"

  /supercache.cache.v1.Cache/GeoAdd:
    post:
      tags: [Geo]
      operationId: Cache_GeoAdd
      summary: Add or update member position
      description: ModeGeo only. WGS84 lon/lat; NaN, Inf, and out-of-range rejected.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GeoAddRequest"
            example:
              keyspace: places
              name: city
              member: c2hvcA==
              lon: -74
              lat: 40.7
      responses:
        "200":
          description: Accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Empty"

  /supercache.cache.v1.Cache/GeoRem:
    post:
      tags: [Geo]
      operationId: Cache_GeoRem
      summary: Remove member from geo index
      description: ModeGeo only. No-op if missing.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GeoMemberRequest"
      responses:
        "200":
          description: Accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Empty"

  /supercache.cache.v1.Cache/GeoPos:
    post:
      tags: [Geo]
      operationId: Cache_GeoPos
      summary: Get member lon/lat
      description: Missing member/index → present=false. ModeGeo only.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GeoMemberRequest"
      responses:
        "200":
          description: Result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GeoPosResponse"

  /supercache.cache.v1.Cache/GeoCard:
    post:
      tags: [Geo]
      operationId: Cache_GeoCard
      summary: Geo index cardinality
      description: Missing index → card=0. ModeGeo only.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NameRequest"
      responses:
        "200":
          description: Result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CardResponse"

  /supercache.cache.v1.Cache/GeoDist:
    post:
      tags: [Geo]
      operationId: Cache_GeoDist
      summary: Distance between two members
      description: Haversine meters. Missing either member → present=false. ModeGeo only.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GeoDistRequest"
      responses:
        "200":
          description: Result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GeoDistResponse"

  /supercache.cache.v1.Cache/GeoRadius:
    post:
      tags: [Geo]
      operationId: Cache_GeoRadius
      summary: Members within a radius
      description: |
        Inclusive radius in meters. Order: nearest first, then member bytes.
        `limit<=0` means no cap. ModeGeo only.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GeoRadiusRequest"
            example:
              keyspace: places
              name: city
              lon: -74
              lat: 40.7
              radius_meters: 20000
              limit: 10
      responses:
        "200":
          description: Result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GeoRadiusResponse"

  /supercache.cache.v1.Cache/LPush:
    post:
      tags: [List]
      operationId: Cache_LPush
      summary: Prepend item
      description: ModeList only. Creates the list if missing.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ListItemRequest"
      responses:
        "200":
          description: Accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Empty"

  /supercache.cache.v1.Cache/RPush:
    post:
      tags: [List]
      operationId: Cache_RPush
      summary: Append item
      description: ModeList only. Creates the list if missing.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ListItemRequest"
      responses:
        "200":
          description: Accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Empty"

  /supercache.cache.v1.Cache/LPop:
    post:
      tags: [List]
      operationId: Cache_LPop
      summary: Pop head
      description: Missing or empty → present=false. ModeList only.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NameRequest"
      responses:
        "200":
          description: Result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListPopResponse"

  /supercache.cache.v1.Cache/RPop:
    post:
      tags: [List]
      operationId: Cache_RPop
      summary: Pop tail
      description: Missing or empty → present=false. ModeList only.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NameRequest"
      responses:
        "200":
          description: Result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListPopResponse"

  /supercache.cache.v1.Cache/LLen:
    post:
      tags: [List]
      operationId: Cache_LLen
      summary: List length
      description: Missing list → len=0. ModeList only.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NameRequest"
      responses:
        "200":
          description: Result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LLenResponse"

  /supercache.cache.v1.Cache/LIndex:
    post:
      tags: [List]
      operationId: Cache_LIndex
      summary: Element at index
      description: Redis-style negatives. OOB → present=false. ModeList only.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LIndexRequest"
      responses:
        "200":
          description: Result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListPopResponse"

  /supercache.cache.v1.Cache/LRange:
    post:
      tags: [List]
      operationId: Cache_LRange
      summary: Range by index
      description: Inclusive start/stop; Redis-style negatives (`-1` = last). ModeList only.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LRangeRequest"
            example:
              keyspace: inbox
              name: q
              start: 0
              stop: -1
      responses:
        "200":
          description: Result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LRangeResponse"

  /supercache.cache.v1.Cache/HSet:
    post:
      tags: [Hash]
      operationId: Cache_HSet
      summary: Upsert field
      description: ModeHash only. Creates the hash if missing. Empty value allowed.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/HSetRequest"
      responses:
        "200":
          description: Accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Empty"

  /supercache.cache.v1.Cache/HGet:
    post:
      tags: [Hash]
      operationId: Cache_HGet
      summary: Get field
      description: Missing hash or field → present=false. ModeHash only.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/HFieldRequest"
      responses:
        "200":
          description: Result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HGetResponse"

  /supercache.cache.v1.Cache/HDel:
    post:
      tags: [Hash]
      operationId: Cache_HDel
      summary: Delete field
      description: No-op if missing. Does not Delete the hash name. ModeHash only.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/HFieldRequest"
      responses:
        "200":
          description: Accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Empty"

  /supercache.cache.v1.Cache/HExists:
    post:
      tags: [Hash]
      operationId: Cache_HExists
      summary: Field exists
      description: Missing hash or field → present=false. ModeHash only.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/HFieldRequest"
      responses:
        "200":
          description: Result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HExistsResponse"

  /supercache.cache.v1.Cache/HLen:
    post:
      tags: [Hash]
      operationId: Cache_HLen
      summary: Field count
      description: Missing hash → len=0. ModeHash only.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NameRequest"
      responses:
        "200":
          description: Result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HLenResponse"

  /supercache.cache.v1.Cache/HGetAll:
    post:
      tags: [Hash]
      operationId: Cache_HGetAll
      summary: All fields
      description: Field-byte order. Missing → empty. ModeHash only.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NameRequest"
      responses:
        "200":
          description: Result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HGetAllResponse"

  /supercache.cache.v1.Cache/Incr:
    post:
      tags: [Counter]
      operationId: Cache_Incr
      summary: Add delta
      description: ModeCounter only. Creates at delta if missing. Returns the new int64. Overflow → invalid argument.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IncrRequest"
      responses:
        "200":
          description: New value
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IncrResponse"

  /supercache.cache.v1.Cache/CounterGet:
    post:
      tags: [Counter]
      operationId: Cache_CounterGet
      summary: Read counter
      description: Missing → present=false, value=0. ModeCounter only.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NameRequest"
      responses:
        "200":
          description: Result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CounterGetResponse"

  /supercache.cache.v1.Cache/JsonSet:
    post:
      tags: [JSON]
      operationId: Cache_JsonSet
      summary: Set JSON at path
      description: |
        ModeJSON only. Upsert JSON at path; creates the document if missing.
        Path `$` or empty = whole document. Object parents are created; arrays are not.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/JsonSetRequest"
            example:
              keyspace: doc
              name: user
              path: $.name
              value: IkFkYSI=  # base64 "\"Ada\""
      responses:
        "200":
          description: Accepted by owner (empty body)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Empty"

  /supercache.cache.v1.Cache/JsonGet:
    post:
      tags: [JSON]
      operationId: Cache_JsonGet
      summary: Get JSON at path
      description: Missing doc or path → present=false. Path `$` or empty = whole document. ModeJSON only. Replica may lag.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/JsonGetRequest"
      responses:
        "200":
          description: Result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JsonGetResponse"

  /supercache.cache.v1.Cache/JsonDel:
    post:
      tags: [JSON]
      operationId: Cache_JsonDel
      summary: Delete JSON at path
      description: |
        ModeJSON only. Missing path is a no-op. Path `$` or empty clears to live `{}`.
        `Delete(name)` tombstones the document.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/JsonDelRequest"
      responses:
        "200":
          description: Accepted (empty body)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Empty"

  /supercache.cache.v1.Cache/BitSet:
    post:
      tags: [Bitmap]
      operationId: Cache_BitSet
      summary: Set a bit at offset
      description: |
        ModeBitmap only. Redis SETBIT. Creates the bitmap if missing; grows with
        zero-fill. **ACK-only — does not return the old bit.** `bit=false` writes a
        zero and may grow; it is not a delete. Live all-zero stays until Delete(name).
        Encoded length over MaxValueSize → InvalidArgument.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BitSetRequest"
            example:
              keyspace: flags
              name: seen
              offset: 0
              bit: true
      responses:
        "200":
          description: Accepted by owner (empty body)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Empty"

  /supercache.cache.v1.Cache/BitGet:
    post:
      tags: [Bitmap]
      operationId: Cache_BitGet
      summary: Get a bit at offset
      description: |
        ModeBitmap only. Redis GETBIT plus a present-bit. Missing name → present=false.
        Live bitmap, offset past stored length → bit=false, present=true.
        Replica may lag.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BitGetRequest"
      responses:
        "200":
          description: Result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BitGetResponse"

  /supercache.cache.v1.Cache/BitCount:
    post:
      tags: [Bitmap]
      operationId: Cache_BitCount
      summary: Count 1-bits in a byte window
      description: |
        ModeBitmap only. Redis BITCOUNT over an inclusive **byte** window (not bits).
        Negatives like List/GETRANGE. Whole bitmap is start=0, end=-1. Missing name → 0.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BitCountRequest"
      responses:
        "200":
          description: Result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BitCountResponse"

  /supercache.cache.v1.Cache/BitPos:
    post:
      tags: [Bitmap]
      operationId: Cache_BitPos
      summary: First matching bit in a byte window
      description: |
        ModeBitmap only. Redis BITPOS over an inclusive **byte** window of **stored**
        bytes only (no implicit past-end bit). Whole bitmap is start=0, end=-1.
        Missing name or bit not in window → found=false.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BitPosRequest"
      responses:
        "200":
          description: Result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BitPosResponse"

  /supercache.cache.v1.Cache/HLLAdd:
    post:
      tags: [HLL]
      operationId: Cache_HLLAdd
      summary: Add an item to a HyperLogLog sketch
      description: |
        ModeHLL only. Redis PFADD. Creates the sketch if missing. **ACK-only —
        does not return whether any register changed.** Empty item → InvalidArgument.
        Dense sketch is 12288 bytes; MaxValueSize below that → InvalidArgument.
        Estimates use FNV-1a 64, p=14 — they will not match Redis PFCOUNT.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/HLLAddRequest"
            example:
              keyspace: uniq
              name: visitors
              item: YWxpY2U=
      responses:
        "200":
          description: Accepted by owner (empty body)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Empty"

  /supercache.cache.v1.Cache/HLLCount:
    post:
      tags: [HLL]
      operationId: Cache_HLLCount
      summary: Approximate distinct count
      description: |
        ModeHLL only. Redis PFCOUNT plus a present-bit. Missing name → present=false.
        Live sketch (including estimate 0) → present=true. Replica may lag.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/HLLCountRequest"
      responses:
        "200":
          description: Result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HLLCountResponse"

  /supercache.cache.v1.Cache/TopKAdd:
    post:
      tags: [TopK]
      operationId: Cache_TopKAdd
      summary: Observe an item in a Top-K table
      description: |
        ModeTopK only. Creates the table if missing. **ACK-only — +1 per RPC.**
        Empty item → InvalidArgument. Not Redis TOPK (Space-Saving; no Query/Count/Incr).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TopKAddRequest"
            example:
              keyspace: plays
              name: hot
              item: dDAwMQ==
      responses:
        "200":
          description: Accepted by owner (empty body)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Empty"

  /supercache.cache.v1.Cache/TopKList:
    post:
      tags: [TopK]
      operationId: Cache_TopKList
      summary: Current heavy-hitter chart
      description: |
        ModeTopK only. Missing name → present=false. Live table → present=true
        (rows sorted count desc, then item bytes). Replica may lag.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TopKListRequest"
      responses:
        "200":
          description: Result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TopKListResponse"

  /supercache.cache.v1.Cache/CMSIncr:
    post:
      tags: [CMS]
      operationId: Cache_CMSIncr
      summary: Increment an item in a Count-Min sketch
      description: |
        ModeCMS only. Creates the sketch if missing. **ACK-only.** `n==0` means 1.
        Empty item → InvalidArgument. Does not return the new estimate. Not Redis CMS.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CMSIncrRequest"
            example:
              keyspace: plays-count
              name: hot
              item: dDAwMw==
              n: 1
      responses:
        "200":
          description: Accepted by owner (empty body)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Empty"

  /supercache.cache.v1.Cache/CMSQuery:
    post:
      tags: [CMS]
      operationId: Cache_CMSQuery
      summary: Approximate frequency of an item
      description: |
        ModeCMS only. Missing name → present=false. Live sketch → present=true
        (count is min of d cells; overestimate only). Replica may lag.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CMSQueryRequest"
      responses:
        "200":
          description: Result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CMSQueryResponse"

  /supercache.cache.v1.Cache/VAdd:
    post:
      tags: [Vector]
      operationId: Cache_VAdd
      summary: Upsert a member vector
      description: |
        ModeVectorSet only. Creates the set if missing. **ACK-only.**
        First successful add locks dim for that name. Replace is allowed
        (same member, new vector). Empty member, dim 1 or >256, or a
        non-finite component → InvalidArgument. Cosine keyspaces also
        reject the zero vector; L2/IP allow zeros.

        Last `VRem` keeps an empty live set (dim still present).
        Replicas install a full `FlagVectorSet` snapshot.

        CLI: `sc -keyspace vectorset vadd items a 1,0` → `OK vadd items a`
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VAddRequest"
            example:
              keyspace: vectorset
              name: items
              member: YQ==
              vec: [1, 0]
      responses:
        "200":
          description: Accepted by owner (empty body)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Empty"

  /supercache.cache.v1.Cache/VRem:
    post:
      tags: [Vector]
      operationId: Cache_VRem
      summary: Remove a member
      description: |
        ModeVectorSet only. No-op if the name or member is missing.
        Removing the last member leaves an empty set (VDim still present).

        CLI: `sc -keyspace vectorset vrem items a` → `OK vrem items a`
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VRemRequest"
            example:
              keyspace: vectorset
              name: items
              member: YQ==
      responses:
        "200":
          description: Accepted by owner (empty body)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Empty"

  /supercache.cache.v1.Cache/VSim:
    post:
      tags: [Vector]
      operationId: Cache_VSim
      summary: Nearest neighbors
      description: |
        ModeVectorSet only. Brute-force K-NN under the store mutex.
        Missing name → empty `hits` (not an error). `k<=0` → 10; `k>50` → 50.
        Query dim must match the locked dim. Cosine rejects a zero query.

        Order: cosine / inner product **high → low**; L2 **low → high**.
        Score meaning follows the keyspace `VectorMetric`. Replica may lag.

        CLI: `sc -keyspace vectorset vsim items 1,0 3` → lines `score member`
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VSimRequest"
            example:
              keyspace: vectorset
              name: items
              vec: [1, 0]
              k: 3
      responses:
        "200":
          description: Neighbors, best first
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VSimResponse"

  /supercache.cache.v1.Cache/VCard:
    post:
      tags: [Vector]
      operationId: Cache_VCard
      summary: Member count
      description: |
        ModeVectorSet only. Missing name → `present=false`, `n=0`.
        Empty live set → `present=true`, `n=0`.

        CLI: `sc -keyspace vectorset vcard items`
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VCardRequest"
      responses:
        "200":
          description: Result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VCardResponse"

  /supercache.cache.v1.Cache/VDim:
    post:
      tags: [Vector]
      operationId: Cache_VDim
      summary: Locked dimension
      description: |
        ModeVectorSet only. Missing name → `present=false`.
        Empty live set still reports the locked dim.

        CLI: `sc -keyspace vectorset vdim items` (miss → `(nil)`)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VDimRequest"
      responses:
        "200":
          description: Result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VDimResponse"

  /supercache.cache.v1.Cache/VEmb:
    post:
      tags: [Vector]
      operationId: Cache_VEmb
      summary: Stored member vector
      description: |
        ModeVectorSet only. Missing name or member → `found=false`.
        Returned slice is a copy.

        CLI: `sc -keyspace vectorset vemb items a` → `1,0` (miss → `(nil)`)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VEmbRequest"
            example:
              keyspace: vectorset
              name: items
              member: YQ==
      responses:
        "200":
          description: Result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VEmbResponse"

  /supercache.cache.v1.Cache/XAdd:
    post:
      tags: [Stream]
      operationId: Cache_XAdd
      summary: Append an entry
      description: |
        ModeStream only. Creates the stream if missing. Returns the minted
        `millis-seq` id. Payload is opaque `[]byte` (empty allowed).
        Non-owner calls use peer `StreamAdd`. Replicas install a full
        `FlagStream` snapshot. After add, `StreamMaxLen` (if >0) drops oldest
        until `len <= StreamMaxLen`. Hard cap 4096.

        CLI: `sc -keyspace events xadd logs * hello` → prints id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/XAddRequest"
            example:
              keyspace: events
              name: logs
              payload: aGVsbG8=
      responses:
        "200":
          description: Minted id
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/XAddResponse"

  /supercache.cache.v1.Cache/XRange:
    post:
      tags: [Stream]
      operationId: Cache_XRange
      summary: Inclusive id window, oldest first
      description: |
        ModeStream only. `start`/`end` are Redis-ish `-` / `+` or `millis-seq`.
        A leading `(` on `start` is exclusive (resume after a cursor).
        `count<=0` means no cap; `count>512` is clamped to 512.
        Missing name → empty `entries` (not an error). Replica may lag.

        CLI: `sc -keyspace events xrange logs - + 10`
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/XRangeRequest"
            example:
              keyspace: events
              name: logs
              start: "-"
              end: "+"
              count: 10
      responses:
        "200":
          description: Entries, oldest first
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/XRangeResponse"

  /supercache.cache.v1.Cache/XRevRange:
    post:
      tags: [Stream]
      operationId: Cache_XRevRange
      summary: Inclusive id window, newest first
      description: |
        ModeStream only. Same `start`/`end` window as `XRange` (`-` min, `+` max;
        exclusive `(` on `start` only). Returns newest first.
        Missing name → empty `entries`. Replica may lag.

        CLI: `sc -keyspace events xrevrange logs - + 10`
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/XRevRangeRequest"
            example:
              keyspace: events
              name: logs
              start: "-"
              end: "+"
              count: 10
      responses:
        "200":
          description: Entries, newest first
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/XRangeResponse"

  /supercache.cache.v1.Cache/XLen:
    post:
      tags: [Stream]
      operationId: Cache_XLen
      summary: Entry count
      description: |
        ModeStream only. Missing name → `present=false`, `n=0`.
        Empty live stream (after last XDel / XTrim 0) → `present=true`, `n=0`.

        CLI: `sc -keyspace events xlen logs` (miss → `(nil)`)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/XLenRequest"
      responses:
        "200":
          description: Result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/XLenResponse"

  /supercache.cache.v1.Cache/XDel:
    post:
      tags: [Stream]
      operationId: Cache_XDel
      summary: Remove one id
      description: |
        ModeStream only. ACK-only. Missing name or id is a no-op.
        Last delete leaves a live empty stream until `Delete(name)`.

        CLI: `sc -keyspace events xdel logs 1710000000000-0`
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/XDelRequest"
            example:
              keyspace: events
              name: logs
              id: "1710000000000-0"
      responses:
        "200":
          description: Accepted by owner (empty body)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Empty"

  /supercache.cache.v1.Cache/XTrim:
    post:
      tags: [Stream]
      operationId: Cache_XTrim
      summary: Keep newest N entries
      description: |
        ModeStream only. ACK-only. `max_len < 0` is invalid. `max_len=0`
        empties the stream but keeps it live until `Delete(name)`.

        CLI: `sc -keyspace events xtrim logs 100`
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/XTrimRequest"
            example:
              keyspace: events
              name: logs
              max_len: 100
      responses:
        "200":
          description: Accepted by owner (empty body)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Empty"

components:
  schemas:
    Empty:
      type: object
    GetRequest:
      type: object
      required: [keyspace, key]
      properties:
        keyspace:
          type: string
        key:
          type: string
    GetResponse:
      type: object
      properties:
        found:
          type: boolean
        value:
          type: string
          format: byte
          description: Raw bytes (base64 in JSON mapping)
    PutRequest:
      type: object
      required: [keyspace, key, value]
      properties:
        keyspace:
          type: string
        key:
          type: string
        value:
          type: string
          format: byte
        ttl_nanos:
          type: integer
          format: int64
        ttl_set:
          type: boolean
    PutResponse:
      type: object
    KV:
      type: object
      properties:
        key:
          type: string
        value:
          type: string
          format: byte
    PutManyRequest:
      type: object
      required: [keyspace, items]
      properties:
        keyspace:
          type: string
        items:
          type: array
          items:
            $ref: "#/components/schemas/KV"
        ttl_nanos:
          type: integer
          format: int64
        ttl_set:
          type: boolean
    PeerFailure:
      type: object
      properties:
        peer_id:
          type: string
        message:
          type: string
    KeyError:
      type: object
      properties:
        key:
          type: string
        message:
          type: string
        peer_failures:
          type: array
          items:
            $ref: "#/components/schemas/PeerFailure"
    PutManyResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: "#/components/schemas/KeyError"
    DeleteRequest:
      type: object
      required: [keyspace, key]
      properties:
        keyspace:
          type: string
        key:
          type: string
          description: KV key or structure name (Bloom/Set/ZSet)
    DeleteResponse:
      type: object
      properties:
        peer_failures:
          type: array
          items:
            $ref: "#/components/schemas/PeerFailure"
    DeleteManyRequest:
      type: object
      required: [keyspace, keys]
      properties:
        keyspace:
          type: string
        keys:
          type: array
          items:
            type: string
    DeleteManyResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: "#/components/schemas/KeyError"
    NameRequest:
      type: object
      required: [keyspace, name]
      properties:
        keyspace:
          type: string
        name:
          type: string
          description: Structure name (set / zset / filter identity)
    BloomAddRequest:
      type: object
      required: [keyspace, name, item]
      properties:
        keyspace:
          type: string
        name:
          type: string
        item:
          type: string
          format: byte
    BloomTestRequest:
      type: object
      required: [keyspace, name, item]
      properties:
        keyspace:
          type: string
        name:
          type: string
        item:
          type: string
          format: byte
    BloomTestResponse:
      type: object
      properties:
        maybe:
          type: boolean
          description: false = definitely not present
    SetItemRequest:
      type: object
      required: [keyspace, name, item]
      properties:
        keyspace:
          type: string
        name:
          type: string
        item:
          type: string
          format: byte
    SetContainsResponse:
      type: object
      properties:
        present:
          type: boolean
    CardResponse:
      type: object
      properties:
        card:
          type: integer
          format: int64
    SetMembersResponse:
      type: object
      properties:
        members:
          type: array
          items:
            type: string
            format: byte
    ZAddRequest:
      type: object
      required: [keyspace, name, member, score]
      properties:
        keyspace:
          type: string
        name:
          type: string
        member:
          type: string
          format: byte
        score:
          type: number
          format: double
    ZMemberRequest:
      type: object
      required: [keyspace, name, member]
      properties:
        keyspace:
          type: string
        name:
          type: string
        member:
          type: string
          format: byte
    ZScoreResponse:
      type: object
      properties:
        present:
          type: boolean
        score:
          type: number
          format: double
    ZRangeRequest:
      type: object
      required: [keyspace, name, start, stop]
      properties:
        keyspace:
          type: string
        name:
          type: string
        start:
          type: integer
          format: int32
        stop:
          type: integer
          format: int32
    ZRangeByScoreRequest:
      type: object
      required: [keyspace, name, min, max]
      properties:
        keyspace:
          type: string
        name:
          type: string
        min:
          type: number
          format: double
        max:
          type: number
          format: double
    ZMember:
      type: object
      properties:
        member:
          type: string
          format: byte
        score:
          type: number
          format: double
    ZRangeResponse:
      type: object
      properties:
        members:
          type: array
          items:
            $ref: "#/components/schemas/ZMember"
    GeoAddRequest:
      type: object
      required: [keyspace, name, member, lon, lat]
      properties:
        keyspace:
          type: string
        name:
          type: string
        member:
          type: string
          format: byte
        lon:
          type: number
          format: double
        lat:
          type: number
          format: double
    GeoMemberRequest:
      type: object
      required: [keyspace, name, member]
      properties:
        keyspace:
          type: string
        name:
          type: string
        member:
          type: string
          format: byte
    GeoPosResponse:
      type: object
      properties:
        present:
          type: boolean
        lon:
          type: number
          format: double
        lat:
          type: number
          format: double
    GeoDistRequest:
      type: object
      required: [keyspace, name, a, b]
      properties:
        keyspace:
          type: string
        name:
          type: string
        a:
          type: string
          format: byte
        b:
          type: string
          format: byte
    GeoDistResponse:
      type: object
      properties:
        present:
          type: boolean
        meters:
          type: number
          format: double
    GeoRadiusRequest:
      type: object
      required: [keyspace, name, lon, lat, radius_meters]
      properties:
        keyspace:
          type: string
        name:
          type: string
        lon:
          type: number
          format: double
        lat:
          type: number
          format: double
        radius_meters:
          type: number
          format: double
        limit:
          type: integer
          format: int32
    GeoMember:
      type: object
      properties:
        member:
          type: string
          format: byte
        lon:
          type: number
          format: double
        lat:
          type: number
          format: double
        dist_meters:
          type: number
          format: double
    GeoRadiusResponse:
      type: object
      properties:
        members:
          type: array
          items:
            $ref: "#/components/schemas/GeoMember"
    ListItemRequest:
      type: object
      required: [keyspace, name, item]
      properties:
        keyspace:
          type: string
        name:
          type: string
        item:
          type: string
          format: byte
    ListPopResponse:
      type: object
      properties:
        present:
          type: boolean
        item:
          type: string
          format: byte
    LLenResponse:
      type: object
      properties:
        len:
          type: integer
          format: int64
    LIndexRequest:
      type: object
      required: [keyspace, name, index]
      properties:
        keyspace:
          type: string
        name:
          type: string
        index:
          type: integer
          format: int32
    LRangeRequest:
      type: object
      required: [keyspace, name, start, stop]
      properties:
        keyspace:
          type: string
        name:
          type: string
        start:
          type: integer
          format: int32
        stop:
          type: integer
          format: int32
    LRangeResponse:
      type: object
      properties:
        items:
          type: array
          items:
            type: string
            format: byte
    HSetRequest:
      type: object
      required: [keyspace, name, field]
      properties:
        keyspace:
          type: string
        name:
          type: string
        field:
          type: string
          format: byte
        value:
          type: string
          format: byte
    HFieldRequest:
      type: object
      required: [keyspace, name, field]
      properties:
        keyspace:
          type: string
        name:
          type: string
        field:
          type: string
          format: byte
    HGetResponse:
      type: object
      properties:
        present:
          type: boolean
        value:
          type: string
          format: byte
    HExistsResponse:
      type: object
      properties:
        present:
          type: boolean
    HLenResponse:
      type: object
      properties:
        len:
          type: integer
          format: int64
    HashField:
      type: object
      properties:
        field:
          type: string
          format: byte
        value:
          type: string
          format: byte
    HGetAllResponse:
      type: object
      properties:
        fields:
          type: array
          items:
            $ref: "#/components/schemas/HashField"
    IncrRequest:
      type: object
      required: [keyspace, name]
      properties:
        keyspace:
          type: string
        name:
          type: string
        delta:
          type: integer
          format: int64
    IncrResponse:
      type: object
      properties:
        value:
          type: integer
          format: int64
    CounterGetResponse:
      type: object
      properties:
        present:
          type: boolean
        value:
          type: integer
          format: int64
    JsonSetRequest:
      type: object
      required: [keyspace, name, path, value]
      properties:
        keyspace:
          type: string
        name:
          type: string
        path:
          type: string
          description: "$" or empty = root; .ident / [\"k\"] / [n]
        value:
          type: string
          format: byte
          description: Raw JSON bytes (base64 in JSON mapping)
    JsonGetRequest:
      type: object
      required: [keyspace, name]
      properties:
        keyspace:
          type: string
        name:
          type: string
        path:
          type: string
    JsonGetResponse:
      type: object
      properties:
        present:
          type: boolean
        value:
          type: string
          format: byte
    JsonDelRequest:
      type: object
      required: [keyspace, name]
      properties:
        keyspace:
          type: string
        name:
          type: string
        path:
          type: string
    BitSetRequest:
      type: object
      required: [keyspace, name, offset, bit]
      properties:
        keyspace:
          type: string
        name:
          type: string
        offset:
          type: integer
          format: uint64
          description: Bit index, 0-based (not a byte offset)
        bit:
          type: boolean
          description: true = 1, false = 0 (writes a zero; not a delete)
    BitGetRequest:
      type: object
      required: [keyspace, name, offset]
      properties:
        keyspace:
          type: string
        name:
          type: string
        offset:
          type: integer
          format: uint64
    BitGetResponse:
      type: object
      properties:
        present:
          type: boolean
          description: false if the name is missing / expired / tombstoned
        bit:
          type: boolean
    BitCountRequest:
      type: object
      required: [keyspace, name]
      properties:
        keyspace:
          type: string
        name:
          type: string
        start:
          type: integer
          format: int32
          description: Inclusive byte offset (0 + end=-1 = whole bitmap)
        end:
          type: integer
          format: int32
    BitCountResponse:
      type: object
      properties:
        count:
          type: integer
          format: int64
    BitPosRequest:
      type: object
      required: [keyspace, name, bit]
      properties:
        keyspace:
          type: string
        name:
          type: string
        bit:
          type: boolean
        start:
          type: integer
          format: int32
          description: Inclusive byte offset (0 + end=-1 = whole bitmap)
        end:
          type: integer
          format: int32
    BitPosResponse:
      type: object
      properties:
        found:
          type: boolean
        pos:
          type: integer
          format: int64
          description: Bit index when found=true
    HLLAddRequest:
      type: object
      required: [keyspace, name, item]
      properties:
        keyspace:
          type: string
        name:
          type: string
        item:
          type: string
          format: byte
          description: Item bytes to hash (not stored)
    HLLCountRequest:
      type: object
      required: [keyspace, name]
      properties:
        keyspace:
          type: string
        name:
          type: string
    HLLCountResponse:
      type: object
      properties:
        present:
          type: boolean
          description: false if the name is missing / expired / tombstoned
        count:
          type: integer
          format: uint64
          description: Approximate distinct count when present=true
    TopKAddRequest:
      type: object
      required: [keyspace, name, item]
      properties:
        keyspace:
          type: string
        name:
          type: string
        item:
          type: string
          format: byte
          description: Observed item (stored in the table)
    TopKListRequest:
      type: object
      required: [keyspace, name]
      properties:
        keyspace:
          type: string
        name:
          type: string
    TopKEntry:
      type: object
      properties:
        item:
          type: string
          format: byte
        count:
          type: integer
          format: uint64
    TopKListResponse:
      type: object
      properties:
        present:
          type: boolean
          description: false if the name is missing / expired / tombstoned
        entries:
          type: array
          items:
            $ref: "#/components/schemas/TopKEntry"
    CMSIncrRequest:
      type: object
      required: [keyspace, name, item]
      properties:
        keyspace:
          type: string
        name:
          type: string
        item:
          type: string
          format: byte
          description: Hashed item (not stored)
        n:
          type: integer
          format: uint64
          description: Increment; 0 means 1
    CMSQueryRequest:
      type: object
      required: [keyspace, name, item]
      properties:
        keyspace:
          type: string
        name:
          type: string
        item:
          type: string
          format: byte
    CMSQueryResponse:
      type: object
      properties:
        present:
          type: boolean
          description: false if the name is missing / expired / tombstoned
        count:
          type: integer
          format: uint64
          description: Approximate frequency when present=true
    VAddRequest:
      type: object
      required: [keyspace, name, member, vec]
      properties:
        keyspace:
          type: string
        name:
          type: string
        member:
          type: string
          format: byte
          description: Member id, 1–255 bytes
        vec:
          type: array
          items:
            type: number
            format: float
          description: float32 components; dim 2–256; first add locks dim
    VRemRequest:
      type: object
      required: [keyspace, name, member]
      properties:
        keyspace:
          type: string
        name:
          type: string
        member:
          type: string
          format: byte
    VSimRequest:
      type: object
      required: [keyspace, name, vec]
      properties:
        keyspace:
          type: string
        name:
          type: string
        vec:
          type: array
          items:
            type: number
            format: float
        k:
          type: integer
          format: int32
          description: Neighbors to return; <=0 → 10; >50 → 50
    VSimHit:
      type: object
      properties:
        member:
          type: string
          format: byte
        score:
          type: number
          format: float
          description: Cosine / IP similarity, or L2 distance
    VSimResponse:
      type: object
      properties:
        hits:
          type: array
          items:
            $ref: "#/components/schemas/VSimHit"
    VCardRequest:
      type: object
      required: [keyspace, name]
      properties:
        keyspace:
          type: string
        name:
          type: string
    VCardResponse:
      type: object
      properties:
        n:
          type: integer
          format: int64
        present:
          type: boolean
          description: false if the name is missing / expired / tombstoned
    VDimRequest:
      type: object
      required: [keyspace, name]
      properties:
        keyspace:
          type: string
        name:
          type: string
    VDimResponse:
      type: object
      properties:
        dim:
          type: integer
          format: int32
        present:
          type: boolean
          description: false if the name is missing / expired / tombstoned
    VEmbRequest:
      type: object
      required: [keyspace, name, member]
      properties:
        keyspace:
          type: string
        name:
          type: string
        member:
          type: string
          format: byte
    VEmbResponse:
      type: object
      properties:
        vec:
          type: array
          items:
            type: number
            format: float
        found:
          type: boolean
    StreamEntry:
      type: object
      properties:
        id:
          type: string
          description: "millis-seq, e.g. 1710000000000-0"
        payload:
          type: string
          format: byte
          description: Opaque client-encoded payload
    XAddRequest:
      type: object
      required: [keyspace, name]
      properties:
        keyspace:
          type: string
        name:
          type: string
        payload:
          type: string
          format: byte
    XAddResponse:
      type: object
      properties:
        id:
          type: string
          description: Minted millis-seq id
    XRangeRequest:
      type: object
      required: [keyspace, name]
      properties:
        keyspace:
          type: string
        name:
          type: string
        start:
          type: string
          description: "-" / millis-seq / exclusive "(id"
        end:
          type: string
          description: "+" / millis-seq (always inclusive)
        count:
          type: integer
          format: int32
          description: "<=0 no cap; >512 clamped to 512"
    XRevRangeRequest:
      type: object
      required: [keyspace, name]
      properties:
        keyspace:
          type: string
        name:
          type: string
        start:
          type: string
          description: "-" / millis-seq / exclusive "(id" (same as XRange)
        end:
          type: string
          description: "+" / millis-seq (always inclusive)
        count:
          type: integer
          format: int32
    XRangeResponse:
      type: object
      properties:
        entries:
          type: array
          items:
            $ref: "#/components/schemas/StreamEntry"
    XLenRequest:
      type: object
      required: [keyspace, name]
      properties:
        keyspace:
          type: string
        name:
          type: string
    XLenResponse:
      type: object
      properties:
        n:
          type: integer
          format: int64
        present:
          type: boolean
          description: false if the name is missing / expired / tombstoned
    XDelRequest:
      type: object
      required: [keyspace, name, id]
      properties:
        keyspace:
          type: string
        name:
          type: string
        id:
          type: string
    XTrimRequest:
      type: object
      required: [keyspace, name, max_len]
      properties:
        keyspace:
          type: string
        name:
          type: string
        max_len:
          type: integer
          format: int32
          description: Keep newest N; 0 empties the live stream