flo-python 0.1.0.dev4__py3-none-any.whl → 0.1.2__py3-none-any.whl

flo/types.py

@@ -6,20 +6,102 @@ Core types, constants, and data classes for the Flo client SDK.
 import struct
 from dataclasses import dataclass
 from enum import IntEnum
-from typing import Optional
+from typing import Any, Generic, Optional, TypeVar
 
 # =============================================================================
 # Protocol Constants
 # =============================================================================
 
 MAGIC: int = 0x004F4C46  # "FLO\0" in little-endian
-VERSION: int = 0x01
+VERSION: int = 0x02
+# The hash of the op table this SDK was built for, written into every request
+# header. A server built from another table refuses the request, and its
+# answers carry its own hash, which this SDK refuses. CI's live tests run
+# against the flo commit in .github/flo-ref.env: change both in one commit.
+TABLE_HASH: int = 0x2FBA7DD9AE941830
+
+
+class Reason(IntEnum):
+    """Why the server refused a request. Mirrors the server's list; the table
+    hash covers it, so a server can't send one this SDK doesn't know."""
+
+    UNKNOWN_OP = 1
+    MALFORMED = 2
+    FIELD_TOO_LONG = 3
+    OUT_OF_RANGE = 4
+    LEADER_UNKNOWN = 5
+    SHARD_BUSY = 6
+    TABLE_MISMATCH = 7
+    UNKNOWN_FLAG = 8
+    INTERNAL = 9
+    COMMITTED_NOT_APPLIED = 10
+    ANSWER_LOST = 11
+    # A refusal from an op family the server hasn't classified yet.
+    UNCLASSIFIED = 12
+    # What the request names doesn't exist.
+    NOT_FOUND = 13
+    # The key is in a prefix the server keeps for itself.
+    RESERVED_KEY = 14
+    # The write's cas_version isn't the key's version.
+    CAS_MISMATCH = 15
+    # The write's condition didn't hold.
+    CONDITION_FAILED = 16
+    # No open transaction has this id here.
+    NO_SUCH_TRANSACTION = 17
+    # The routing key (the key, when none is given) isn't the one the
+    # transaction was begun with.
+    WRONG_ROUTING_KEY = 18
+    # The transaction holds as many ops or bytes as it may.
+    TXN_TOO_LARGE = 19
+    # The shard holds as many waiting reads as it may.
+    TOO_MANY_WAITERS = 20
+    # Two fields given together that don't go together.
+    CONFLICTING_FIELDS = 21
+    # The shard stopped taking writes until the node restarts.
+    WRITES_STOPPED = 22
+    # Too many writes wait for commit.
+    TOO_MANY_PROPOSALS = 23
+    # The key's value isn't what the op works on (a counter, a JSON document).
+    WRONG_TYPE = 24
+    # The shard holds as many open transactions as it may.
+    TOO_MANY_TRANSACTIONS = 25
+    # An action complete or fail for a run that has moved on (another worker
+    # holds it, or it finished). It was dropped; resending it is refused too.
+    STALE_REPORT = 26
+    # An await from a worker that missed its heartbeats: a heartbeat (or, once
+    # it's removed, registering again) lets it take work again.
+    WORKER_UNHEALTHY = 27
+    # An await from a draining worker: it takes no new work.
+    WORKER_DRAINING = 28
+
+
+class Ran(IntEnum):
+    """Whether a refused request took effect: retry logic reads this, not the
+    message."""
+
+    NO = 0
+    # It took effect; don't resend it.
+    YES = 1
+    # It may still take effect; check before resending.
+    UNKNOWN = 2
+
+
 HEADER_SIZE: int = 32
 
 # Size limits (for client-side validation)
 MAX_NAMESPACE_SIZE: int = 255
 MAX_KEY_SIZE: int = 64 * 1024  # 64 KB
 MAX_VALUE_SIZE: int = 16 * 1024 * 1024  # 16 MB practical limit
+# Longest blocking wait (block_ms) the server accepts; checked client-side so
+# it fails before the round trip.
+MAX_BLOCK_MS: int = 300_000  # 5 minutes
+# Longest a KV get may wait (wait_ms).
+MAX_WAIT_MS: int = 300_000
+# Longest value a KV put takes.
+MAX_KV_VALUE_SIZE: int = 253_817
+# A worker always long-polls: block_ms=0 ("don't wait") would turn its poll
+# loop into a busy spin against the server, so a worker reads 0 (or unset) as this.
+_DEFAULT_WORKER_BLOCK_MS: int = 30_000
 
 
 # =============================================================================
@@ -35,11 +117,6 @@ class OpCode(IntEnum):
 
     # ── System (0x000 – 0x00F) ──
     PING = 0x000
-    PONG = 0x001
-    ERROR_RESPONSE = 0x002
-    AUTH = 0x003
-    SET_DURABILITY = 0x004
-    OK = 0x005
 
     # ── Namespace (0x010 – 0x02F) ──
     NAMESPACE_CREATE = 0x010
@@ -48,12 +125,6 @@ class OpCode(IntEnum):
     NAMESPACE_INFO = 0x013
     NAMESPACE_CONFIG_SET = 0x014
     NAMESPACE_CONFIG_GET = 0x015
-    NAMESPACE_CREATE_RESPONSE = 0x020
-    NAMESPACE_DELETE_RESPONSE = 0x021
-    NAMESPACE_LIST_RESPONSE = 0x022
-    NAMESPACE_INFO_RESPONSE = 0x023
-    NAMESPACE_CONFIG_SET_RESPONSE = 0x024
-    NAMESPACE_CONFIG_GET_RESPONSE = 0x025
 
     # ── Cluster (0x030 – 0x04F) ──
     CLUSTER_STATUS = 0x030
@@ -63,46 +134,34 @@ class OpCode(IntEnum):
     CLUSTER_TRANSFER_LEADER = 0x034
     CLUSTER_ADD_NODE = 0x035
     CLUSTER_REMOVE_NODE = 0x036
-    CLUSTER_STATUS_RESPONSE = 0x040
-    CLUSTER_MEMBERS_RESPONSE = 0x041
-    CLUSTER_JOIN_RESPONSE = 0x042
 
-    # ── KV + Transactions + Snapshots (0x100 – 0x12F) ──
+    # ── KV (0x100 – 0x12F) ──
     KV_PUT = 0x100
     KV_GET = 0x101
     KV_MGET = 0x102
     KV_DELETE = 0x103
     KV_SCAN = 0x104
     KV_HISTORY = 0x105
-    KV_GET_RESPONSE = 0x106
-    KV_MGET_RESPONSE = 0x107
-    KV_PUT_RESPONSE = 0x108
-    KV_SCAN_RESPONSE = 0x109
-    KV_HISTORY_RESPONSE = 0x10A
+    # KV Extended (atomic counters, JSON ops)
+    KV_INCR = 0x10B
+    KV_JSON_GET = 0x10C
+    KV_JSON_SET = 0x10D
+    KV_JSON_DEL = 0x10E
+    # KV Per-Shard Transactions
     KV_BEGIN_TXN = 0x110
     KV_COMMIT_TXN = 0x111
     KV_ROLLBACK_TXN = 0x112
-    KV_SNAPSHOT_CREATE = 0x120
-    KV_SNAPSHOT_GET = 0x121
-    KV_SNAPSHOT_RELEASE = 0x122
-    KV_SNAPSHOT_CREATE_RESPONSE = 0x123
+    # KV Extended (TTL, exists)
+    KV_EXPIRE = 0x113
+    KV_EXISTS = 0x115
 
     # ── Streams (0x130 – 0x14F) ──
     STREAM_APPEND = 0x130
     STREAM_READ = 0x131
     STREAM_TRIM = 0x132
     STREAM_INFO = 0x133
-    STREAM_APPEND_RESPONSE = 0x134
-    STREAM_READ_RESPONSE = 0x135
-    STREAM_EVENT = 0x136
-    STREAM_SUBSCRIBE = 0x137
-    STREAM_UNSUBSCRIBE = 0x138
-    STREAM_SUBSCRIBED = 0x139
-    STREAM_UNSUBSCRIBED = 0x13A
     STREAM_LIST = 0x13B
-    STREAM_LIST_RESPONSE = 0x13C
     STREAM_CREATE = 0x13D
-    STREAM_CREATE_RESPONSE = 0x13E
     STREAM_ALTER = 0x13F
 
     # ── Stream Consumer Groups (0x150 – 0x16F) ──
@@ -114,7 +173,6 @@ class OpCode(IntEnum):
     STREAM_GROUP_CLAIM = 0x155
     STREAM_GROUP_PENDING = 0x156
     STREAM_GROUP_CONFIGURE_SWEEPER = 0x157
-    STREAM_GROUP_READ_RESPONSE = 0x158
     STREAM_GROUP_NACK = 0x159
     STREAM_GROUP_TOUCH = 0x15A
     STREAM_GROUP_INFO = 0x15B
@@ -124,29 +182,14 @@ class OpCode(IntEnum):
     QUEUE_ENQUEUE = 0x170
     QUEUE_DEQUEUE = 0x171
     QUEUE_COMPLETE = 0x172
-    QUEUE_EXTEND_LEASE = 0x173
     QUEUE_FAIL = 0x174
-    QUEUE_FAIL_AUTO = 0x175
     QUEUE_DLQ_LIST = 0x176
     QUEUE_DLQ_DELETE = 0x177
     QUEUE_DLQ_REQUEUE = 0x178
-    QUEUE_DLQ_STATS = 0x179
-    QUEUE_PROMOTE_DUE = 0x17A
     QUEUE_STATS = 0x17B
     QUEUE_PEEK = 0x17C
-    QUEUE_TOUCH = 0x17D
-    QUEUE_BATCH_ENQUEUE = 0x17E
     QUEUE_PURGE = 0x17F
-    QUEUE_ENQUEUE_RESPONSE = 0x190
-    QUEUE_DEQUEUE_RESPONSE = 0x191
-    QUEUE_DLQ_LIST_RESPONSE = 0x192
-    QUEUE_STATS_RESPONSE = 0x193
-    QUEUE_PEEK_RESPONSE = 0x194
-    QUEUE_TOUCH_RESPONSE = 0x195
-    QUEUE_BATCH_ENQUEUE_RESPONSE = 0x196
-    QUEUE_PURGE_RESPONSE = 0x197
     QUEUE_LIST = 0x198
-    QUEUE_LIST_RESPONSE = 0x199
 
     # ── Time-Series (0x1A0 – 0x1BF) ──
     TS_WRITE = 0x1A0
@@ -156,13 +199,6 @@ class OpCode(IntEnum):
     TS_LIST = 0x1A4
     TS_DELETE = 0x1A5
     TS_RETENTION = 0x1A6
-    TS_WRITE_RESPONSE = 0x1A7
-    TS_READ_RESPONSE = 0x1A8
-    TS_QUERY_RESPONSE = 0x1A9
-    TS_FLOQL_RESPONSE = 0x1AA
-    TS_LIST_RESPONSE = 0x1AB
-    TS_DELETE_RESPONSE = 0x1AC
-    TS_RETENTION_RESPONSE = 0x1AD
 
     # ── Actions (0x300 – 0x31F) ──
     ACTION_REGISTER = 0x300
@@ -175,12 +211,6 @@ class OpCode(IntEnum):
     ACTION_COMPLETE = 0x307
     ACTION_FAIL = 0x308
     ACTION_TOUCH = 0x309
-    ACTION_REGISTER_RESPONSE = 0x310
-    ACTION_INVOKE_RESPONSE = 0x311
-    ACTION_STATUS_RESPONSE = 0x312
-    ACTION_LIST_RESPONSE = 0x313
-    ACTION_LIST_RUNS_RESPONSE = 0x314
-    ACTION_TASK_ASSIGNMENT = 0x315
 
     # ── Workers (0x320 – 0x33F) ──
     WORKER_REGISTER = 0x320
@@ -189,10 +219,6 @@ class OpCode(IntEnum):
     WORKER_LIST = 0x323
     WORKER_INFO = 0x324
     WORKER_DRAIN = 0x325
-    WORKER_REGISTER_RESPONSE = 0x330
-    WORKER_LIST_RESPONSE = 0x331
-    WORKER_INFO_RESPONSE = 0x332
-    WORKER_DRAIN_RESPONSE = 0x333
 
     # ── Workflows (0x340 – 0x35F) ──
     WORKFLOW_CREATE = 0x340
@@ -206,15 +232,6 @@ class OpCode(IntEnum):
     WORKFLOW_DISABLE = 0x348
     WORKFLOW_ENABLE = 0x349
     WORKFLOW_LIST_DEFINITIONS = 0x34A
-    WORKFLOW_CREATE_RESPONSE = 0x350
-    WORKFLOW_START_RESPONSE = 0x351
-    WORKFLOW_STATUS_RESPONSE = 0x352
-    WORKFLOW_HISTORY_RESPONSE = 0x353
-    WORKFLOW_LIST_RUNS_RESPONSE = 0x354
-    WORKFLOW_GET_DEFINITION_RESPONSE = 0x355
-    WORKFLOW_DISABLE_RESPONSE = 0x356
-    WORKFLOW_ENABLE_RESPONSE = 0x357
-    WORKFLOW_LIST_DEFINITIONS_RESPONSE = 0x358
 
     # ── Processing (0x360 – 0x37F) ──
     PROCESSING_SUBMIT = 0x360
@@ -222,17 +239,6 @@ class OpCode(IntEnum):
     PROCESSING_CANCEL = 0x362
     PROCESSING_STATUS = 0x363
     PROCESSING_LIST = 0x364
-    PROCESSING_SAVEPOINT = 0x365
-    PROCESSING_RESTORE = 0x366
-    PROCESSING_RESCALE = 0x367
-    PROCESSING_SUBMIT_RESPONSE = 0x370
-    PROCESSING_STOP_RESPONSE = 0x371
-    PROCESSING_CANCEL_RESPONSE = 0x372
-    PROCESSING_STATUS_RESPONSE = 0x373
-    PROCESSING_LIST_RESPONSE = 0x374
-    PROCESSING_SAVEPOINT_RESPONSE = 0x375
-    PROCESSING_RESTORE_RESPONSE = 0x376
-    PROCESSING_RESCALE_RESPONSE = 0x377
 
 
 class StatusCode(IntEnum):
@@ -250,6 +256,23 @@ class StatusCode(IntEnum):
     INTERNAL_ERROR = 9
     OVERLOADED = 10
     RATE_LIMITED = 11
+    UNAVAILABLE = 12
+
+    @classmethod
+    def _missing_(cls, value: object) -> "StatusCode | None":
+        # A status this SDK doesn't know still has a body on the wire; failing
+        # here would abandon it unread, so it becomes a pseudo-member instead.
+        if not isinstance(value, int) or not 0 <= value <= 255:
+            return None
+        member = int.__new__(cls, value)
+        member._name_ = f"UNKNOWN_{value}"
+        member._value_ = value
+        return member
+
+    def __reduce_ex__(self, proto: object) -> tuple[type["StatusCode"], tuple[int]]:
+        # Rebuilt from its value, not its name: a pseudo-member such as
+        # UNKNOWN_200 has no name to look up, so pickle and copy would fail.
+        return self.__class__, (int(self),)
 
     def message(self) -> str:
         """Get human-readable error message."""
@@ -266,8 +289,11 @@ class StatusCode(IntEnum):
             StatusCode.INTERNAL_ERROR: "Internal server error",
             StatusCode.OVERLOADED: "Server overloaded",
             StatusCode.RATE_LIMITED: "Request rate limit exceeded",
+            StatusCode.UNAVAILABLE: (
+                "Unavailable: no leader or the shard isn't taking writes; retry"
+            ),
         }
-        return messages.get(self, "Unknown error")
+        return messages.get(self, f"Unknown status {int(self)}")
 
 
 class OptionTag(IntEnum):
@@ -276,26 +302,13 @@ class OptionTag(IntEnum):
     Organized by feature area, matching proto.zig definitions.
     """
 
-    # KV Options (0x01 - 0x0F)
-    TTL_SECONDS = 0x01  # u64: Time-to-live in seconds (0 = no expiration)
-    CAS_VERSION = 0x02  # u64: Expected version for compare-and-swap
-    IF_NOT_EXISTS = 0x03  # void: Only set if key doesn't exist (NX)
-    IF_EXISTS = 0x04  # void: Only set if key exists (XX)
-    LIMIT = 0x05  # u32: Maximum number of results for scan/list operations
-    KEYS_ONLY = 0x06  # u8: Skip values in scan response (0/1)
-    CURSOR = 0x07  # bytes: Pagination cursor (ShardWalker format)
-    ROUTING_KEY = 0x08  # string: Explicit routing key for shard co-location
+    # General Options (0x01 - 0x0F)
+    LIMIT = 0x05  # u32: Maximum number of results for list operations
 
     # Queue Options (0x10 - 0x1F)
-    PRIORITY = 0x10  # u8: Message priority (0-255, higher = more urgent)
-    DELAY_MS = 0x11  # u64: Delay before message becomes visible
-    VISIBILITY_TIMEOUT_MS = 0x12  # u32: How long message is invisible after dequeue
-    DEDUP_KEY = 0x13  # string: Deduplication key
-    MAX_RETRIES = 0x14  # u8: Maximum retry attempts before DLQ
+    PRIORITY = 0x10  # u8: Message priority (0-255, lower is taken first)
     COUNT = 0x15  # u32: Number of messages to dequeue
-    SEND_TO_DLQ = 0x16  # u8: Whether to send failed messages to DLQ (0/1)
-    BLOCK_MS = 0x17  # u32: Block timeout - wait until exists (0=forever)
-    WAIT_MS = 0x18  # u32: Watch timeout - wait for NEXT version change (0=forever)
+    BLOCK_MS = 0x17  # u32: Block timeout - wait for data (0=don't wait, max 300000)
 
     # Stream Options (0x20 - 0x2F) - StreamID-native ONLY
     # All stream positioning uses StreamID (timestamp_ms + sequence)
@@ -306,36 +319,11 @@ class OptionTag(IntEnum):
     PARTITION = 0x24  # u32: Explicit partition index
     PARTITION_KEY = 0x25  # string: Key for partition routing
     MAX_AGE_SECONDS = 0x26  # u64: Maximum age in seconds for retention
-    MAX_BYTES = 0x27  # u64: Maximum size in bytes for retention
     DRY_RUN = 0x28  # void: Flag to preview what would be deleted
-    RETENTION_COUNT = 0x29  # u64: Retention policy - max event count
-    RETENTION_AGE = 0x2A  # u64: Retention policy - max age in seconds
-    RETENTION_BYTES = 0x2B  # u64: Retention policy - max bytes
 
     # Consumer Group Options (0x30 - 0x3F)
     ACK_TIMEOUT_MS = 0x30  # u32: Time before unacked message auto-redelivers
     MAX_DELIVER = 0x31  # u8: Max delivery attempts before DLQ (default: 10)
-    SUBSCRIPTION_MODE = 0x32  # u8: 0=shared, 1=exclusive, 2=key_shared
-    REDELIVERY_DELAY_MS = 0x33  # u32: Delay before NACK'd message becomes visible
-    CONSUMER_TIMEOUT_MS = 0x34  # u32: Remove consumer from group if no activity
-    NO_ACK = 0x35  # void: Auto-ack on delivery (at-most-once)
-    IDLE_TIMEOUT_MS = 0x36  # u64: Min idle time for claiming stuck messages
-    MAX_ACK_PENDING = 0x37  # u32: Max unacked messages per consumer
-    EXTEND_ACK_MS = 0x38  # u32: Amount of time to extend ack deadline
-    MAX_STANDBYS = 0x39  # u16: Max standby consumers in exclusive mode
-    NUM_SLOTS = 0x3A  # u16: Number of hash slots for key_shared mode
-
-    # Worker/Action Options (0x40 - 0x4F)
-    WORKER_ID = 0x40  # string: Worker identifier
-    EXTEND_MS = 0x41  # u32: Lease extension time in milliseconds
-    MAX_TASKS = 0x42  # u32: Maximum tasks to return in batch
-    RETRY = 0x43  # u8: Whether to retry on failure (0/1)
-
-    # Workflow Options (0x50 - 0x5F)
-    TIMEOUT_MS = 0x50  # u64: Workflow/activity timeout
-    RETRY_POLICY = 0x51  # bytes: Serialized retry policy
-    CORRELATION_ID = 0x52  # string: Correlation ID for tracing
-    SUBSCRIPTION_ID = 0x53  # u64: Subscription ID for stream subscriptions
 
     # Time-Series Options (0x60 - 0x6F)
     TS_FROM_MS = 0x60  # i64: Start of time range (inclusive, unix ms)
@@ -344,11 +332,9 @@ class OptionTag(IntEnum):
     TS_AGGREGATION = 0x63  # string: Aggregation function name (avg, sum, count, min, max)
     TS_FIELD = 0x64  # string: Field name filter (empty = "value")
     TS_TAGS = 0x65  # string: Comma-separated tag filters "key=val,key2=val2"
-    TS_PRECISION = 0x66  # u8: Timestamp precision (0=ns, 1=us, 2=ms, 3=s)
     TS_TIMESTAMP = 0x67  # i64: Explicit timestamp for write (0 = server-assigned)
     TS_RAW_TTL = 0x68  # string: Raw data TTL (e.g., "7d")
     TS_DOWNSAMPLE = 0x69  # string: Downsample rule (e.g., "1m:avg:30d")
-    TS_BATCH = 0x6A  # void: Flag indicating batch/line-protocol mode
 
 
 # =============================================================================
@@ -357,29 +343,114 @@ class OptionTag(IntEnum):
 
 
 @dataclass
-class KVEntry:
-    """KV entry from scan results."""
+class ScanResult:
+    """A page of a KV scan: the keys' names, and the cursor for the next page."""
 
-    key: bytes
-    value: bytes | None  # None if keys_only=True
+    names: list[str]
+    cursor: bytes | None  # None on the last page
+
+    @property
+    def has_more(self) -> bool:
+        return self.cursor is not None
 
 
 @dataclass
-class ScanResult:
-    """Result of a KV scan operation."""
+class VersionEntry:
+    """One version of a key from KV history."""
 
-    entries: list[KVEntry]
-    cursor: bytes | None  # None if no more pages
-    has_more: bool
+    version: int
+    at_ms: int  # When it was written, unix ms
+    value: bytes
 
 
 @dataclass
-class VersionEntry:
-    """KV version entry from history."""
+class IncrResult:
+    """A KV incr's new counter value and the key's new version."""
+
+    value: int
+    version: int
+
+
+@dataclass
+class PutResult:
+    """Result of a successful KV put.
+
+    The ``version`` field is the new version assigned by the server, suitable
+    for CAS on the next write via :class:`PutOptions.cas_version`.
+    """
+
+    version: int
+
+
+@dataclass
+class KVBeginResult:
+    """Result of a successful KV transaction begin.
+
+    ``txn_id`` is the server-assigned transaction handle. ``pinned_hash`` is
+    the partition hash this transaction is bound to — every key written or
+    read inside the transaction must hash to the same partition.
+    """
+
+    txn_id: int
+    pinned_hash: int
+
+
+@dataclass
+class KVCommitResult:
+    """Result of a successful KV transaction commit.
+
+    ``commit_index`` is the Raft log index of the committed batch and
+    ``op_count`` is the number of buffered operations applied atomically.
+    """
+
+    commit_index: int
+    op_count: int
+
+
+@dataclass
+class GetResult:
+    """Result of a KV get that found a key.
+
+    ``kv.get`` returns ``None`` when the key is missing; check for ``None``
+    before dereferencing.
+    """
 
+    value: bytes
     version: int
-    timestamp: int
+
+
+T = TypeVar("T")
+
+
+@dataclass
+class GetJsonResult(Generic[T]):
+    """Result of a :meth:`KV.json_get` that found the key and path.
+
+    Unlike :class:`GetResult`, ``value`` is the already-parsed JSON (the
+    ``KV_JSON_GET`` wire body is always a JSON document, so it is decoded for
+    you). ``version`` is the document's current version. ``kv.json_get``
+    returns ``None`` when the key or path is missing.
+
+    The value type defaults to ``Any``; the SDK does not validate the shape at
+    runtime.
+    """
+
+    value: Any
+    version: int
+
+
+@dataclass
+class MGetEntry:
+    """One entry in a :meth:`KV.mget` response.
+
+    ``found`` is ``False`` when the key did not exist; in that case ``value``
+    is ``b''`` and ``version`` is ``0``.
+    """
+
+    key: str
     value: bytes
+    version: int
+    found: bool
 
 
 @dataclass
@@ -388,6 +459,9 @@ class Message:
 
     seq: int
     payload: bytes
+    enqueued_at_ms: int = 0
+    delivery_count: int = 0
+    priority: int = 0
 
 
 @dataclass
@@ -426,12 +500,10 @@ class StreamID:
 
 
 class StorageTier(IntEnum):
-    """Storage tier of a stream record."""
+    """The tier a stream record was served from; the server sends only these two."""
 
-    HOT = 0
-    PENDING = 1
-    WARM = 2
-    COLD = 3
+    HOT = 0  # the in-memory log
+    WARM = 1  # the warm store, after the record left the log
 
 
 @dataclass
@@ -440,6 +512,7 @@ class StreamRecord:
 
     id: StreamID = None  # type: ignore[assignment]
     tier: StorageTier = StorageTier.HOT
+    stream: str = ""
     payload: bytes = b""
     headers: dict[str, str] | None = None
 
@@ -458,6 +531,35 @@ class StreamReadResult:
     records: list[StreamRecord]
 
 
+@dataclass
+class PendingEntry:
+    """One entry in a consumer group's Pending Entry List (PEL).
+
+    A delivered-but-unacked message. ``delivery_count`` is how many times the
+    entry has been delivered; ``consumer`` is the consumer that currently owns
+    it.
+    """
+
+    id: StreamID = None  # type: ignore[assignment]
+    consumer: str = ""
+    delivery_count: int = 0
+
+
+@dataclass
+class StreamClaimResult:
+    """Result of a :meth:`StreamOperations.group_claim` cursor page.
+
+    ``records`` carry payload + headers (same shape as ``group_read``).
+    ``next_cursor`` is the ``start_id`` to pass on the next ``group_claim``
+    call; when ``done`` is ``True`` the PEL has been fully scanned and the loop
+    should stop.
+    """
+
+    records: list[StreamRecord]
+    next_cursor: StreamID = None  # type: ignore[assignment]
+    done: bool = False
+
+
 @dataclass
 class StreamInfo:
     """Stream metadata."""
@@ -474,12 +576,34 @@ class StreamInfo:
 # =============================================================================
 
 
+class WaitFor(IntEnum):
+    """What a KV get with wait_ms waits for."""
+
+    # The key to exist; one that exists answers at once.
+    EXISTS = 0
+    # The key's next version.
+    CHANGE = 1
+
+
+class Condition(IntEnum):
+    """When a KV put may write."""
+
+    ALWAYS = 0
+    IF_ABSENT = 1
+    IF_PRESENT = 2
+
+
 @dataclass
 class GetOptions:
     """Options for KV get operations."""
 
     namespace: str | None = None
-    block_ms: int | None = None  # Block until value available (0 = infinite)
+    # Wait up to this long for what wait_for names (0 = don't wait, max 300000).
+    wait_ms: int = 0
+    # The key to exist (the default), or its next version.
+    wait_for: WaitFor = WaitFor.EXISTS
+    # Routes the request in place of the key.
+    routing_key: str | None = None
 
 
 @dataclass
@@ -487,10 +611,13 @@ class PutOptions:
     """Options for KV put operations."""
 
     namespace: str | None = None
-    ttl_seconds: int | None = None
+    ttl_ms: int | None = None  # Time-to-live in milliseconds (0 = no expiration)
+    # When the write may happen.
+    condition: Condition = Condition.ALWAYS
+    # The key's version the write requires; 0 means it doesn't exist.
     cas_version: int | None = None
-    if_not_exists: bool = False
-    if_exists: bool = False
+    # Routes the request in place of the key.
+    routing_key: str | None = None
 
 
 @dataclass
@@ -498,6 +625,10 @@ class DeleteOptions:
     """Options for KV delete operations."""
 
     namespace: str | None = None
+    # Only delete when the key's version is this.
+    cas_version: int | None = None
+    # Routes the request in place of the key.
+    routing_key: str | None = None
 
 
 @dataclass
@@ -505,9 +636,9 @@ class ScanOptions:
     """Options for KV scan operations."""
 
     namespace: str | None = None
+    # The cursor from the previous page; None for the first.
     cursor: bytes | None = None
-    limit: int | None = None
-    keys_only: bool = False
+    limit: int = 1024  # 1..1024 names per page
 
 
 @dataclass
@@ -515,7 +646,58 @@ class HistoryOptions:
     """Options for KV history operations."""
 
     namespace: str | None = None
-    limit: int | None = None
+    limit: int = 10  # 1..65 versions, newest first
+    # Routes the request in place of the key.
+    routing_key: str | None = None
+
+
+@dataclass
+class KVIncrOptions:
+    """Options for KV incr operations."""
+
+    namespace: str | None = None
+    delta: int = 1
+    # Routes the request in place of the key.
+    routing_key: str | None = None
+
+
+@dataclass
+class KVExpireOptions:
+    """Options for KV expire operations."""
+
+    namespace: str | None = None
+    # Only succeed when the key's version is this.
+    cas_version: int | None = None
+    # Routes the request in place of the key.
+    routing_key: str | None = None
+
+
+@dataclass
+class KVExistsOptions:
+    """Options for KV exists operations."""
+
+    namespace: str | None = None
+    # Routes the request in place of the key.
+    routing_key: str | None = None
+
+
+@dataclass
+class KVJsonOptions:
+    """Options for KV JSON.* operations."""
+
+    namespace: str | None = None
+    # Routes the request in place of the key.
+    routing_key: str | None = None
+
+
+@dataclass
+class KVMGetOptions:
+    """Options for KV mget operations."""
+
+    namespace: str | None = None
+    # The routing key every key was written with: all are looked up on its
+    # shard. Without it, each key is looked up on its own.
+    routing_key: str | None = None
 
 
 @dataclass
@@ -523,9 +705,7 @@ class EnqueueOptions:
     """Options for queue enqueue operations."""
 
     namespace: str | None = None
-    priority: int = 0
-    delay_ms: int | None = None
-    dedup_key: str | None = None
+    priority: int = 0  # 0-255, lower is taken first
 
 
 @dataclass
@@ -533,8 +713,7 @@ class DequeueOptions:
     """Options for queue dequeue operations."""
 
     namespace: str | None = None
-    visibility_timeout_ms: int | None = None
-    block_ms: int | None = None
+    block_ms: int | None = None  # Wait for messages (0 = don't wait, max 300000)
 
 
 @dataclass
@@ -549,7 +728,6 @@ class NackOptions:
     """Options for queue nack operations."""
 
     namespace: str | None = None
-    to_dlq: bool = False
 
 
 @dataclass
@@ -557,7 +735,6 @@ class DlqListOptions:
     """Options for DLQ list operations."""
 
     namespace: str | None = None
-    limit: int = 100
 
 
 @dataclass
@@ -574,13 +751,6 @@ class PeekOptions:
     namespace: str | None = None
 
 
-@dataclass
-class TouchOptions:
-    """Options for queue touch (lease renewal) operations."""
-
-    namespace: str | None = None
-
-
 # =============================================================================
 # Stream Option Types
 # =============================================================================
@@ -607,7 +777,7 @@ class StreamReadOptions:
     tail: bool = False  # Start from end of stream (mutually exclusive with start)
     partition: int | None = None  # Explicit partition index
     count: int | None = None  # Maximum number of records to return
-    block_ms: int | None = None  # Blocking timeout (0 = infinite)
+    block_ms: int | None = None  # Blocking timeout (0 = don't wait, max 300000)
 
 
 @dataclass
@@ -615,10 +785,18 @@ class StreamTrimOptions:
     """Options for stream trim operations."""
 
     namespace: str | None = None
-    max_len: int | None = None  # Retention policy - max event count
-    max_age_seconds: int | None = None  # Retention policy - max age in seconds
-    max_bytes: int | None = None  # Retention policy - max bytes
-    dry_run: bool = False  # Preview what would be deleted
+    before: Optional["StreamID"] = None  # Remove records up to and including this id
+    max_len: int | None = None  # Keep only the newest N records (> 0)
+    max_age_seconds: int | None = None  # Remove records older than this (> 0)
+    dry_run: bool = False  # Report what would be removed, removing nothing
+
+
+@dataclass
+class StreamTrimResult:
+    """What a trim removed, or with dry_run would remove."""
+
+    removed: int  # Records removed
+    first_seq: int  # Sequence of the first record left; meaningful only when records remain
 
 
 @dataclass
@@ -641,7 +819,7 @@ class StreamGroupReadOptions:
 
     namespace: str | None = None
     count: int | None = None  # Max records to read
-    block_ms: int | None = None  # Block waiting for records
+    block_ms: int | None = None  # Block waiting for records (0 = don't wait, max 300000)
 
 
 @dataclass
@@ -649,7 +827,7 @@ class StreamGroupAckOptions:
     """Options for acknowledging records in a consumer group."""
 
     namespace: str | None = None
-    consumer: str = ""  # Consumer ID (required for correct ack matching)
+    consumer: str = ""  # Sent, but the server doesn't check it: any consumer can ack an entry
 
 
 @dataclass
@@ -657,8 +835,7 @@ class StreamGroupNackOptions:
     """Options for negatively acknowledging records in a consumer group."""
 
     namespace: str | None = None
-    consumer: str = ""  # Consumer ID (required for correct nack matching)
-    redelivery_delay_ms: int | None = None  # Delay before message becomes visible again
+    consumer: str = ""  # Sent, but the server doesn't check it: any consumer can nack an entry
 
 
 # =============================================================================
@@ -683,14 +860,34 @@ class ActionInfo:
     description: str | None = None
 
 
+class RunStatus(IntEnum):
+    """An action run's status."""
+
+    PENDING = 0
+    RUNNING = 1
+    COMPLETED = 2
+    FAILED = 3
+    CANCELLED = 4
+    TIMED_OUT = 5
+
+
 @dataclass
 class ActionRunStatus:
-    """Status of an action run."""
+    """Status of an action run. Times are ms since the epoch; ``attempt``
+    counts from 1 once a worker has taken the run. ``output`` is a completed
+    run's result, and ``error_message`` the last failure's message."""
 
     run_id: str
-    status: str  # "pending", "running", "completed", "failed"
-    result: bytes | None = None
-    error: str | None = None
+    status: RunStatus
+    created_at_ms: int
+    attempt: int
+    started_at_ms: int | None = None
+    completed_at_ms: int | None = None
+    output: bytes | None = None
+    error_message: str | None = None
+    # The worker holding the run, or that last held it; None until one takes
+    # it. Only the leader learns of a take at once.
+    worker_id: str | None = None
 
 
 @dataclass
@@ -715,12 +912,23 @@ class ActionListResult:
 
 @dataclass
 class ActionRegisterOptions:
-    """Options for registering an action."""
+    """Options for registering an action. Registering an action replaces
+    the settings it had: the last registration wins."""
 
     namespace: str | None = None
+    # How long a run may go without its worker completing, failing or
+    # touching it before it's taken back; 0 means never.
     timeout_ms: int = 30000
+    # Attempts in all, counting the first.
     max_retries: int = 3
-    description: str | None = None
+    owner: str | None = None
+
+    def __post_init__(self) -> None:
+        # Both go on the wire as u32.
+        for name in ("timeout_ms", "max_retries"):
+            value = getattr(self, name)
+            if not 0 <= value < 2**32:
+                raise ValueError(f"{name} must be in [0, 2**32), not {value}")
 
 
 @dataclass
@@ -728,8 +936,9 @@ class ActionInvokeOptions:
     """Options for invoking an action."""
 
     namespace: str | None = None
-    priority: int = 10
-    idempotency_key: str | None = None
+    # Required worker labels: only workers registered with every key/value
+    # here receive the run.
+    labels: dict[str, Any] | None = None
 
 
 @dataclass
@@ -769,10 +978,8 @@ class TaskAssignment:
     payload: bytes
     created_at: int
     attempt: int
-
-
-# Alias for backwards compatibility
-WorkerTask = TaskAssignment
+    caller_run_id: str = ""
+    caller_workflow_name: str = ""
 
 
 @dataclass
@@ -782,19 +989,44 @@ class WorkerAwaitResult:
     task: TaskAssignment | None = None  # None if no task available
 
 
+class WorkerType(IntEnum):
+    """What a worker runs."""
+
+    ACTION = 0
+    STREAM = 1
+
+
+class WorkerStatus(IntEnum):
+    """A registered worker's status."""
+
+    ACTIVE = 0
+    IDLE = 1
+    DRAINING = 2
+    UNHEALTHY = 3
+
+
 @dataclass
 class WorkerInfo:
-    """Information about a registered worker."""
+    """A registered worker, as worker.list reports it. Times are ms since the epoch."""
 
     worker_id: str
-    task_types: list[str]
+    worker_type: WorkerType
+    status: WorkerStatus
+    current_load: int
+    max_concurrency: int
+    tasks_completed: int
+    tasks_failed: int
+    registered_at_ms: int
+    last_heartbeat_ms: int
+    machine_id: str | None = None
 
 
 @dataclass
 class WorkerListResult:
-    """Result of listing workers."""
+    """A page of workers, in id order. ``cursor`` gives the next page; None on the last."""
 
     workers: list[WorkerInfo]
+    cursor: bytes | None = None
 
 
 # =============================================================================
@@ -817,8 +1049,7 @@ class WorkerAwaitOptions:
     """Options for awaiting a task."""
 
     namespace: str | None = None
-    block_ms: int | None = None  # Block waiting for task (0 = infinite)
-    timeout_ms: int | None = None
+    block_ms: int | None = None  # Block waiting for task (None = 30000, 0 = don't wait, max 300000)
 
 
 @dataclass
@@ -847,10 +1078,12 @@ class WorkerFailOptions:
 
 @dataclass
 class WorkerListOptions:
-    """Options for listing workers."""
+    """Options for listing workers: at most ``limit`` (1..1024) after ``cursor``,
+    the last page's cursor (None starts)."""
 
     namespace: str | None = None
     limit: int = 100
+    cursor: bytes | None = None
 
 
 # =============================================================================
@@ -1005,27 +1238,6 @@ class ProcessingCancelOptions:
     namespace: str | None = None
 
 
-@dataclass
-class ProcessingSavepointOptions:
-    """Options for triggering a savepoint."""
-
-    namespace: str | None = None
-
-
-@dataclass
-class ProcessingRestoreOptions:
-    """Options for restoring from a savepoint."""
-
-    namespace: str | None = None
-
-
-@dataclass
-class ProcessingRescaleOptions:
-    """Options for rescaling a processing job."""
-
-    namespace: str | None = None
-
-
 @dataclass
 class ProcessingSyncOptions:
     """Options for declarative processing sync."""
@@ -1040,7 +1252,6 @@ class ProcessingStatusResult:
     job_id: str
     name: str
     status: str
-    parallelism: int
     batch_size: int
     records_processed: int
     created_at: int
@@ -1053,7 +1264,6 @@ class ProcessingListEntry:
     name: str
     job_id: str
     status: str
-    parallelism: int
     created_at: int