apache-iggy 0.10.0 → 0.10.1-edge.2

package/dist/wire/vsr/header.js

@@ -36,20 +36,33 @@ export const REQUEST_OFFSET = {
     size: 48,
     command: 60,
     client: 128,
+    requestChecksum: 144,
     timestamp: 160,
     request: 168,
     operation: 176,
     session: 184,
-    reserved: 196
+    reserved: 196,
+    partitionIncarnation: 200,
+    ownerGeneration: 208,
+    minimumMetadataOp: 216
 };
 /** `ReplyHeader` field offsets the client reads. */
 export const REPLY_OFFSET = {
     size: 48,
     command: 60,
+    requestChecksum: 128,
+    client: 160,
+    op: 176,
     commit: 184,
+    request: 200,
     operation: 208,
-    status: 216
+    status: 216,
+    reserved: 220,
+    partitionIncarnation: 224
 };
+export const COMMITTED_RESULT_MARKER = 1;
+export const hasCommittedResult = (header) => peekCommand(header) === Command.Reply && readStatus(header) === 0 &&
+    header[REPLY_OFFSET.reserved] === COMMITTED_RESULT_MARKER;
 /** `EvictionHeader` field offsets the client reads. */
 export const EVICTION_OFFSET = {
     command: 60,
@@ -86,14 +99,19 @@ export const EvictionReason = {
     IncompatibleProtocol: 14,
     MalformedLogin: 15
 };
+export const PARTITION_CONTEXT_SIZE = 24;
+export const EMPTY_PARTITION_CONTEXT = Object.freeze({
+    incarnation: 0n,
+    ownerGeneration: 0n,
+    metadataOp: 0n
+});
+export const deserializePartitionContext = (data, offset = 0) => ({
+    incarnation: data.readBigUInt64LE(offset),
+    ownerGeneration: data.readBigUInt64LE(offset + 8),
+    metadataOp: data.readBigUInt64LE(offset + 16)
+});
 const U64_MASK = 0xffffffffffffffffn;
-/**
- * Encodes a 256-byte request header. Only the six fields the server reads
- * are written. The checksums stay zero: the frame and body checksums are not
- * read on the client request path, and `request_checksum` treats zero as
- * unstamped, which opts out of the server's payload comparison. Stamping it is
- * optional -- the Rust SDK does for deduped ops, this SDK does not yet.
- */
+/** Encodes one request identity and its captured partition context. */
 export const encodeRequestHeader = (fields) => {
     const header = Buffer.alloc(HEADER_SIZE);
     header.writeUInt32LE(fields.size, REQUEST_OFFSET.size);
@@ -104,6 +122,10 @@ export const encodeRequestHeader = (fields) => {
     header.writeBigUInt64LE(fields.request, REQUEST_OFFSET.request);
     header.writeUInt8(fields.operation, REQUEST_OFFSET.operation);
     header.writeBigUInt64LE(fields.session, REQUEST_OFFSET.session);
+    const context = fields.context ?? EMPTY_PARTITION_CONTEXT;
+    header.writeBigUInt64LE(context.incarnation, REQUEST_OFFSET.partitionIncarnation);
+    header.writeBigUInt64LE(context.ownerGeneration, REQUEST_OFFSET.ownerGeneration);
+    header.writeBigUInt64LE(context.metadataOp, REQUEST_OFFSET.minimumMetadataOp);
     if (fields.nonReplicatedCode !== undefined)
         header.writeUInt32LE(fields.nonReplicatedCode, REQUEST_OFFSET.reserved);
     return header;
@@ -115,7 +137,7 @@ export const encodeRequestHeader = (fields) => {
 export const peekCommand = (header) => header.readUInt8(REPLY_OFFSET.command);
 /** Reads the total frame size from a reply or eviction header. */
 export const readSize = (header) => header.readUInt32LE(REPLY_OFFSET.size);
-/** Reads the pre-commit denial status; 0 means the reply committed. */
+/** Reads the pre-commit denial status; zero alone does not prove commit. */
 export const readStatus = (header) => header.readUInt32LE(REPLY_OFFSET.status);
 /** Reads the `Operation` discriminant from a reply header. */
 export const readReplyOperation = (header) => header.readUInt8(REPLY_OFFSET.operation);

package/dist/wire/vsr/header.test.js

@@ -26,7 +26,8 @@ describe('VSR request header', () => {
             request: 0x0102030405060708n,
             operation: 2,
             session: 0x1020304050607080n,
-            nonReplicatedCode: 60_001
+            nonReplicatedCode: 60_001,
+            context: { incarnation: 17n, ownerGeneration: 9n, metadataOp: 52n }
         });
         assert.equal(header.length, HEADER_SIZE);
         assert.equal(header.readUInt32LE(REQUEST_OFFSET.size), HEADER_SIZE + 3);
@@ -37,6 +38,9 @@ describe('VSR request header', () => {
         assert.equal(header.readUInt8(REQUEST_OFFSET.operation), 2);
         assert.equal(header.readBigUInt64LE(REQUEST_OFFSET.session), 0x1020304050607080n);
         assert.equal(header.readUInt32LE(REQUEST_OFFSET.reserved), 60_001);
+        assert.equal(header.readBigUInt64LE(REQUEST_OFFSET.partitionIncarnation), 17n);
+        assert.equal(header.readBigUInt64LE(REQUEST_OFFSET.ownerGeneration), 9n);
+        assert.equal(header.readBigUInt64LE(REQUEST_OFFSET.minimumMetadataOp), 52n);
         assert.equal(header.readBigUInt64LE(REQUEST_OFFSET.timestamp), 0n);
     });
     it('leaves all unspecified and reserved bytes zero', () => {

package/dist/wire/vsr/index.d.ts

@@ -1,15 +1,21 @@
 import type { CommandResponse } from '../../client/client.type.js';
+import { type PartitionContext } from './header.js';
 export declare class VsrSession {
     private state;
     constructor(clientId?: bigint);
     reset(): void;
     bind(session: bigint): void;
     get hasActivity(): boolean;
-    encode(command: number, payload: Buffer): Buffer;
+    get sessionId(): bigint | null;
+    get clientId(): bigint;
+    get bindSecret(): Buffer;
+    bindPayload(identity: Buffer): Buffer;
+    resumePayload(metadataWatermark: bigint): Buffer | undefined;
+    encode(command: number, payload: Buffer, context?: PartitionContext): Buffer;
 }
 export declare const decodeVsrResponse: (frame: Buffer, commandCode?: number) => CommandResponse;
 export declare const readRegisteredSession: (response: CommandResponse) => bigint;
-export declare const prepareVsrCommand: (command: number, payload: Buffer) => {
+export declare const prepareVsrCommand: (command: number, payload: Buffer, bindSecret: Buffer) => {
     command: number;
     payload: Buffer;
 };

package/dist/wire/vsr/index.js

@@ -15,16 +15,18 @@
 // specific language governing permissions and limitations
 // under the License.
 import { createRequire } from 'node:module';
+import { randomFillSync } from 'node:crypto';
 import { COMMAND_CODE } from '../command.code.js';
 import { responseError } from '../error.utils.js';
-import { HEADER_SIZE, encodeRequestHeader } from './header.js';
+import { HEADER_SIZE, REQUEST_OFFSET, encodeRequestHeader } from './header.js';
 import { Operation, operationForCode } from './operation.js';
-import { deserializeLoginRegister, serializeLoginRegister, serializeLoginRegisterWithPat, } from './register.js';
+import { deserializeLoginRegister, serializeBindSession, serializeLoginRegister, serializeLoginRegisterWithPat, SESSION_IDENTITY_BYTES, } from './register.js';
 import { decodeResponse } from './reply.js';
 import { ConsensusSession } from './session.js';
 const packageMetadata = createRequire(import.meta.url)('../../../package.json');
 const SDK_VERSION = packageMetadata.version;
 const MAX_U32 = 0xFFFF_FFFF;
+const SESSION_IDENTITY_OFFSET = { clientLow: 0, clientHigh: 8, session: 16, metadataWatermark: 24 };
 /** `IggyError::Unauthenticated`, matching the Rust SDK's unbound-session error. */
 const UNAUTHENTICATED = 40;
 export class VsrSession {
@@ -33,7 +35,7 @@ export class VsrSession {
         this.state = new ConsensusSession(clientId);
     }
     reset() {
-        this.state = new ConsensusSession();
+        this.state.reset();
     }
     bind(session) {
         this.state.bind(session);
@@ -41,7 +43,29 @@ export class VsrSession {
     get hasActivity() {
         return this.state.hasActivity;
     }
-    encode(command, payload) {
+    get sessionId() {
+        return this.state.session;
+    }
+    get clientId() {
+        return this.state.clientId;
+    }
+    get bindSecret() {
+        return this.state.bindSecret;
+    }
+    bindPayload(identity) {
+        return serializeBindSession(identity, SDK_VERSION, this.state.bindSecret);
+    }
+    resumePayload(metadataWatermark) {
+        if (this.state.session === null)
+            return undefined;
+        const identity = Buffer.alloc(SESSION_IDENTITY_BYTES);
+        identity.writeBigUInt64LE(BigInt.asUintN(64, this.state.clientId), SESSION_IDENTITY_OFFSET.clientLow);
+        identity.writeBigUInt64LE(this.state.clientId >> 64n, SESSION_IDENTITY_OFFSET.clientHigh);
+        identity.writeBigUInt64LE(this.state.session, SESSION_IDENTITY_OFFSET.session);
+        identity.writeBigUInt64LE(metadataWatermark, SESSION_IDENTITY_OFFSET.metadataWatermark);
+        return this.bindPayload(identity);
+    }
+    encode(command, payload, context) {
         const operation = registerCommand(command)
             ? Operation.Register
             : operationForCode(command);
@@ -55,26 +79,35 @@ export class VsrSession {
             session = 0n;
         }
         else if (operation === Operation.NonReplicated) {
-            request = this.state.currentRequestId();
+            request = this.state.nextRequestId(false);
             session = this.state.session ?? 0n;
         }
         else {
             if (this.state.session === null)
                 throw responseError(command, UNAUTHENTICATED);
-            // Partition ops consume an id too, even though no partition-plane dedup
-            // exists yet: dedup needs each send to carry a distinct number, and the
-            // metadata watermark tolerates the gaps.
+            // Partition ops consume an id too: dedup needs each send to carry a
+            // distinct number, and the metadata watermark tolerates the gaps.
             request = this.state.nextRequestId();
             session = this.state.session;
         }
         const header = encodeRequestHeader({
             size,
+            context,
             client: this.state.clientId,
             request,
             operation,
             session,
             nonReplicatedCode: operation === Operation.NonReplicated ? command : undefined,
         });
+        if (operation === Operation.Register) {
+            this.state.registerRequestIdentifier.copy(header, REQUEST_OFFSET.requestChecksum);
+        }
+        else if (operation !== Operation.NonReplicated && operation < Operation.SendMessages) {
+            do {
+                randomFillSync(header, REQUEST_OFFSET.requestChecksum, 16);
+            } while (header.subarray(REQUEST_OFFSET.requestChecksum, REQUEST_OFFSET.requestChecksum + 16)
+                .every(byte => byte === 0));
+        }
         return payload.length === 0 ? header : Buffer.concat([header, payload]);
     }
 }
@@ -83,20 +116,20 @@ export const decodeVsrResponse = (frame, commandCode = 0) => {
     return { status: 0, length: data.length, data };
 };
 export const readRegisteredSession = (response) => deserializeLoginRegister(response.data).session;
-export const prepareVsrCommand = (command, payload) => {
+export const prepareVsrCommand = (command, payload, bindSecret) => {
     if (command === COMMAND_CODE.LoginUser) {
         const username = readWireName(payload, 0);
         const password = readWireName(payload, username.next);
         return {
             command: COMMAND_CODE.LoginRegister,
-            payload: serializeLoginRegister(username.value, password.value, SDK_VERSION),
+            payload: serializeLoginRegister(username.value, password.value, SDK_VERSION, bindSecret),
         };
     }
     if (command === COMMAND_CODE.LoginWithAccessToken) {
         const token = readWireName(payload, 0);
         return {
             command: COMMAND_CODE.LoginRegisterWithAccessToken,
-            payload: serializeLoginRegisterWithPat(token.value, SDK_VERSION),
+            payload: serializeLoginRegisterWithPat(token.value, SDK_VERSION, bindSecret),
         };
     }
     return { command, payload };

package/dist/wire/vsr/operation.d.ts

@@ -9,21 +9,22 @@ export declare const Operation: {
     readonly RemoveConsumerGroupMember: 66;
     readonly CompleteConsumerGroupRevocation: 67;
     readonly TruncatePartition: 68;
+    readonly FinalizeSession: 70;
+    readonly CompleteLifecycle: 71;
+    readonly UpdateStreamResolved: 72;
+    readonly UpdateTopicResolved: 73;
+    readonly UpdateUserResolved: 74;
+    readonly RewrapStreamKeys: 75;
     readonly CreateStream: 128;
-    readonly UpdateStream: 129;
     readonly DeleteStream: 130;
-    readonly PurgeStream: 131;
     readonly CreateTopic: 132;
-    readonly UpdateTopic: 133;
     readonly DeleteTopic: 134;
-    readonly PurgeTopic: 135;
     readonly CreatePartitions: 136;
     readonly DeletePartitions: 137;
     readonly DeleteSegments: 138;
     readonly CreateConsumerGroup: 139;
     readonly DeleteConsumerGroup: 140;
     readonly CreateUser: 141;
-    readonly UpdateUser: 142;
     readonly DeleteUser: 143;
     readonly ChangePassword: 144;
     readonly UpdatePermissions: 145;
@@ -31,9 +32,14 @@ export declare const Operation: {
     readonly DeletePersonalAccessToken: 147;
     readonly JoinConsumerGroup: 148;
     readonly LeaveConsumerGroup: 149;
+    readonly UpdateResource: 150;
     readonly SendMessages: 160;
     readonly StoreConsumerOffset: 161;
     readonly DeleteConsumerOffset: 162;
+    readonly RetireSession: 166;
+    readonly InstallConsumerGroupOwner: 167;
+    readonly TransitionPartitionHistory: 168;
+    readonly RetireConsumerGroupOwners: 169;
 };
 /**
  * Whether the byte is a declared `Operation` discriminant. Replies carry a
@@ -41,7 +47,7 @@ export declare const Operation: {
  * so an undeclared value must be rejected, not classified by range.
  */
 export declare const isKnownOperation: (operation: number) => boolean;
-/** Internal band, never client-sent. */
+/** Replica-only operations, never client-sent. */
 export declare const isInternal: (operation: number) => boolean;
 /**
  * Metadata classification is an explicit allowlist, not a range:
@@ -50,6 +56,12 @@ export declare const isInternal: (operation: number) => boolean;
  * `Operation::is_metadata`.
  */
 export declare const isMetadata: (operation: number) => boolean;
+/**
+ * The client operation a committed reply answers. Preparation rewrites some
+ * requests into an internal operation, so retry identity maps it back. Port of
+ * `Operation::request_operation`.
+ */
+export declare const requestOperation: (operation: number) => number;
 /** Whether a reply body leads with a committed result section. */
 export declare const isResultFramed: (operation: number) => boolean;
 /**

package/dist/wire/vsr/operation.js

@@ -31,21 +31,25 @@ export const Operation = {
     RemoveConsumerGroupMember: 66,
     CompleteConsumerGroupRevocation: 67,
     TruncatePartition: 68,
+    FinalizeSession: 70,
+    CompleteLifecycle: 71,
+    UpdateStreamResolved: 72,
+    UpdateTopicResolved: 73,
+    UpdateUserResolved: 74,
+    RewrapStreamKeys: 75,
     CreateStream: 128,
-    UpdateStream: 129,
+    // 129 was UpdateStream. Never reuse it.
     DeleteStream: 130,
-    PurgeStream: 131,
     CreateTopic: 132,
-    UpdateTopic: 133,
+    // 133 was UpdateTopic. Never reuse it.
     DeleteTopic: 134,
-    PurgeTopic: 135,
     CreatePartitions: 136,
     DeletePartitions: 137,
     DeleteSegments: 138,
     CreateConsumerGroup: 139,
     DeleteConsumerGroup: 140,
     CreateUser: 141,
-    UpdateUser: 142,
+    // 142 was UpdateUser. Never reuse it.
     DeleteUser: 143,
     ChangePassword: 144,
     UpdatePermissions: 145,
@@ -53,9 +57,14 @@ export const Operation = {
     DeletePersonalAccessToken: 147,
     JoinConsumerGroup: 148,
     LeaveConsumerGroup: 149,
+    UpdateResource: 150,
     SendMessages: 160,
     StoreConsumerOffset: 161,
-    DeleteConsumerOffset: 162
+    DeleteConsumerOffset: 162,
+    RetireSession: 166,
+    InstallConsumerGroupOwner: 167,
+    TransitionPartitionHistory: 168,
+    RetireConsumerGroupOwners: 169
 };
 const INTERNAL_START = 64;
 const METADATA_START = 128;
@@ -67,7 +76,6 @@ const METADATA_START = 128;
 const REPLICATED_OPERATION = new Map([
     [COMMAND_CODE.CreateUser, Operation.CreateUser],
     [COMMAND_CODE.DeleteUser, Operation.DeleteUser],
-    [COMMAND_CODE.UpdateUser, Operation.UpdateUser],
     [COMMAND_CODE.UpdatePermissions, Operation.UpdatePermissions],
     [COMMAND_CODE.ChangePassword, Operation.ChangePassword],
     [COMMAND_CODE.CreateAccessToken, Operation.CreatePersonalAccessToken],
@@ -77,19 +85,16 @@ const REPLICATED_OPERATION = new Map([
     [COMMAND_CODE.DeleteConsumerOffset, Operation.DeleteConsumerOffset],
     [COMMAND_CODE.CreateStream, Operation.CreateStream],
     [COMMAND_CODE.DeleteStream, Operation.DeleteStream],
-    [COMMAND_CODE.UpdateStream, Operation.UpdateStream],
-    [COMMAND_CODE.PurgeStream, Operation.PurgeStream],
     [COMMAND_CODE.CreateTopic, Operation.CreateTopic],
     [COMMAND_CODE.DeleteTopic, Operation.DeleteTopic],
-    [COMMAND_CODE.UpdateTopic, Operation.UpdateTopic],
-    [COMMAND_CODE.PurgeTopic, Operation.PurgeTopic],
     [COMMAND_CODE.CreatePartitions, Operation.CreatePartitions],
     [COMMAND_CODE.DeletePartitions, Operation.DeletePartitions],
     [COMMAND_CODE.DeleteSegments, Operation.DeleteSegments],
     [COMMAND_CODE.CreateGroup, Operation.CreateConsumerGroup],
     [COMMAND_CODE.DeleteGroup, Operation.DeleteConsumerGroup],
     [COMMAND_CODE.JoinGroup, Operation.JoinConsumerGroup],
-    [COMMAND_CODE.LeaveGroup, Operation.LeaveConsumerGroup]
+    [COMMAND_CODE.LeaveGroup, Operation.LeaveConsumerGroup],
+    [COMMAND_CODE.UpdateResource, Operation.UpdateResource]
 ]);
 const KNOWN_OPERATIONS = new Set(Object.values(Operation));
 /**
@@ -98,8 +103,12 @@ const KNOWN_OPERATIONS = new Set(Object.values(Operation));
  * so an undeclared value must be rejected, not classified by range.
  */
 export const isKnownOperation = (operation) => KNOWN_OPERATIONS.has(operation);
-/** Internal band, never client-sent. */
-export const isInternal = (operation) => operation >= INTERNAL_START && operation < METADATA_START;
+/** Replica-only operations, never client-sent. */
+export const isInternal = (operation) => (operation >= INTERNAL_START && operation < METADATA_START) ||
+    operation === Operation.RetireSession ||
+    operation === Operation.InstallConsumerGroupOwner ||
+    operation === Operation.TransitionPartitionHistory ||
+    operation === Operation.RetireConsumerGroupOwners;
 /**
  * Metadata classification is an explicit allowlist, not a range:
  * `DeleteSegments` (138) sits inside the band but resolves to a partition
@@ -107,12 +116,33 @@ export const isInternal = (operation) => operation >= INTERNAL_START && operatio
  * `Operation::is_metadata`.
  */
 export const isMetadata = (operation) => {
-    if (isInternal(operation))
+    if (isInternal(operation) && operation < Operation.SendMessages)
         return true;
     if (operation === Operation.DeleteSegments)
         return false;
     return operation >= METADATA_START &&
-        operation <= Operation.LeaveConsumerGroup;
+        operation <= Operation.UpdateResource;
+};
+/**
+ * The client operation a committed reply answers. Preparation rewrites some
+ * requests into an internal operation, so retry identity maps it back. Port of
+ * `Operation::request_operation`.
+ */
+export const requestOperation = (operation) => {
+    switch (operation) {
+        case Operation.CreateTopicWithAssignments:
+            return Operation.CreateTopic;
+        case Operation.CreatePartitionsWithAssignments:
+            return Operation.CreatePartitions;
+        case Operation.UpdateStreamResolved:
+        case Operation.UpdateTopicResolved:
+        case Operation.UpdateUserResolved:
+            return Operation.UpdateResource;
+        case Operation.TruncatePartition:
+            return Operation.DeleteSegments;
+        default:
+            return operation;
+    }
 };
 /** Whether a reply body leads with a committed result section. */
 export const isResultFramed = (operation) => isMetadata(operation) ||

package/dist/wire/vsr/operation.test.js

@@ -17,23 +17,18 @@
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
 import { COMMAND_CODE } from '../command.code.js';
-import { isInternal, isKnownOperation, isMetadata, isResultFramed, Operation, operationForCode } from './operation.js';
+import { isInternal, isKnownOperation, isMetadata, isResultFramed, Operation, operationForCode, requestOperation } from './operation.js';
 const replicated = new Map([
     [COMMAND_CODE.CreateStream, Operation.CreateStream],
-    [COMMAND_CODE.UpdateStream, Operation.UpdateStream],
     [COMMAND_CODE.DeleteStream, Operation.DeleteStream],
-    [COMMAND_CODE.PurgeStream, Operation.PurgeStream],
     [COMMAND_CODE.CreateTopic, Operation.CreateTopic],
-    [COMMAND_CODE.UpdateTopic, Operation.UpdateTopic],
     [COMMAND_CODE.DeleteTopic, Operation.DeleteTopic],
-    [COMMAND_CODE.PurgeTopic, Operation.PurgeTopic],
     [COMMAND_CODE.CreatePartitions, Operation.CreatePartitions],
     [COMMAND_CODE.DeletePartitions, Operation.DeletePartitions],
     [COMMAND_CODE.DeleteSegments, Operation.DeleteSegments],
     [COMMAND_CODE.CreateGroup, Operation.CreateConsumerGroup],
     [COMMAND_CODE.DeleteGroup, Operation.DeleteConsumerGroup],
     [COMMAND_CODE.CreateUser, Operation.CreateUser],
-    [COMMAND_CODE.UpdateUser, Operation.UpdateUser],
     [COMMAND_CODE.DeleteUser, Operation.DeleteUser],
     [COMMAND_CODE.ChangePassword, Operation.ChangePassword],
     [COMMAND_CODE.UpdatePermissions, Operation.UpdatePermissions],
@@ -41,6 +36,7 @@ const replicated = new Map([
     [COMMAND_CODE.DeleteAccessToken, Operation.DeletePersonalAccessToken],
     [COMMAND_CODE.JoinGroup, Operation.JoinConsumerGroup],
     [COMMAND_CODE.LeaveGroup, Operation.LeaveConsumerGroup],
+    [COMMAND_CODE.UpdateResource, Operation.UpdateResource],
     [COMMAND_CODE.SendMessages, Operation.SendMessages],
     [COMMAND_CODE.StoreOffset, Operation.StoreConsumerOffset],
     [COMMAND_CODE.DeleteConsumerOffset, Operation.DeleteConsumerOffset]
@@ -68,18 +64,46 @@ describe('VSR operation classification', () => {
         assert.equal(isInternal(64), true);
         assert.equal(isInternal(63), false);
         assert.equal(isInternal(Operation.CreateStream), false);
+        assert.equal(isInternal(Operation.RetireSession), true);
+        assert.equal(isMetadata(Operation.RetireSession), false);
+        assert.equal(isResultFramed(Operation.RetireSession), false);
         assert.equal(isMetadata(Operation.CreateStream), true);
         assert.equal(isMetadata(Operation.LeaveConsumerGroup), true);
         assert.equal(isMetadata(Operation.DeleteSegments), false);
-        assert.equal(isMetadata(150), false);
+        assert.equal(isMetadata(Operation.UpdateResource), true);
+        assert.equal(isResultFramed(Operation.UpdateResource), true);
+        for (const resolved of [Operation.UpdateStreamResolved, Operation.UpdateTopicResolved,
+            Operation.UpdateUserResolved, Operation.RewrapStreamKeys]) {
+            assert.equal(isInternal(resolved), true);
+            assert.equal(isMetadata(resolved), true);
+            assert.equal(isResultFramed(resolved), true);
+        }
+        assert.equal(isMetadata(151), false);
         assert.equal(isResultFramed(Operation.StoreConsumerOffset), true);
         assert.equal(isResultFramed(Operation.DeleteConsumerOffset), true);
         assert.equal(isResultFramed(Operation.SendMessages), false);
     });
+    it('maps a resolved committed operation back to the request operation', () => {
+        for (const [committed, request] of [
+            [Operation.CreateTopicWithAssignments, Operation.CreateTopic],
+            [Operation.CreatePartitionsWithAssignments, Operation.CreatePartitions],
+            [Operation.TruncatePartition, Operation.DeleteSegments],
+            [Operation.UpdateStreamResolved, Operation.UpdateResource],
+            [Operation.UpdateTopicResolved, Operation.UpdateResource],
+            [Operation.UpdateUserResolved, Operation.UpdateResource],
+            [Operation.RewrapStreamKeys, Operation.RewrapStreamKeys],
+            [Operation.CreateStream, Operation.CreateStream]
+        ])
+            assert.equal(requestOperation(committed), request);
+    });
     it('recognizes only declared operation discriminants', () => {
         assert.equal(isKnownOperation(Operation.Register), true);
         assert.equal(isKnownOperation(Operation.SendMessages), true);
-        for (const undeclared of [69, 127, 150, 159, 163, 164, 165, 166, 255])
+        assert.equal(isKnownOperation(Operation.RetireSession), true);
+        assert.equal(isKnownOperation(Operation.FinalizeSession), true);
+        assert.equal(isKnownOperation(Operation.RetireConsumerGroupOwners), true);
+        assert.equal(isInternal(Operation.RetireConsumerGroupOwners), true);
+        for (const undeclared of [69, 76, 127, 129, 131, 133, 135, 142, 151, 159, 163, 164, 165, 170, 255])
             assert.equal(isKnownOperation(undeclared), false);
     });
 });

package/dist/wire/vsr/register.d.ts

@@ -1,17 +1,21 @@
+export declare const BIND_SECRET_BYTES = 32;
+export declare const SESSION_IDENTITY_BYTES = 32;
 /**
  * Packed protocol semver of the wire contract this port implements,
- * `pack(0, 11, 0)` per `core/binary_protocol/src/version.rs`. Bump together
- * with the Rust `IGGY_PROTOCOL_VERSION` on any wire-incompatible change.
+ * `pack(0, 12, 0)` per `core/binary_protocol/src/version.rs`. Update with the
+ * Rust constant during stable release preparation. Edge builds sharing this
+ * number are not guaranteed to have compatible layouts.
  */
 export declare const IGGY_PROTOCOL_VERSION: number;
 /**
  * `LoginRegisterRequest` body:
- * `[ClientVersionInfo][username len u8 + bytes][password len u8 + bytes]
- * [context len u32][context]`.
+ * `[ClientVersionInfo][bind secret 32 bytes][username len u8 + bytes]
+ * [password len u8 + bytes][context len u32][context]`.
  */
-export declare const serializeLoginRegister: (username: string, password: string, sdkVersion: string) => Buffer;
+export declare const serializeLoginRegister: (username: string, password: string, sdkVersion: string, bindSecret: Buffer) => Buffer;
 /** `LoginRegisterWithPatRequest` body: the PAT takes the credential slot. */
-export declare const serializeLoginRegisterWithPat: (token: string, sdkVersion: string) => Buffer;
+export declare const serializeLoginRegisterWithPat: (token: string, sdkVersion: string, bindSecret: Buffer) => Buffer;
+export declare const serializeBindSession: (identity: Buffer, sdkVersion: string, bindSecret: Buffer) => Buffer;
 /** Decoded `LoginRegisterResponse`. */
 export type LoginRegisterResponse = {
     userId: number;

package/dist/wire/vsr/register.js

@@ -22,12 +22,15 @@
  * `LoginRegister` / `LoginRegisterWithPat` and nothing else.
  */
 import { DeserializeError } from '../error.utils.js';
+export const BIND_SECRET_BYTES = 32;
+export const SESSION_IDENTITY_BYTES = 32;
 /**
  * Packed protocol semver of the wire contract this port implements,
- * `pack(0, 11, 0)` per `core/binary_protocol/src/version.rs`. Bump together
- * with the Rust `IGGY_PROTOCOL_VERSION` on any wire-incompatible change.
+ * `pack(0, 12, 0)` per `core/binary_protocol/src/version.rs`. Update with the
+ * Rust constant during stable release preparation. Edge builds sharing this
+ * number are not guaranteed to have compatible layouts.
  */
-export const IGGY_PROTOCOL_VERSION = (0 << 20) | (11 << 10) | 0;
+export const IGGY_PROTOCOL_VERSION = (0 << 20) | (12 << 10) | 0;
 const SDK_NAME = 'node-sdk';
 const wireName = (value) => {
     const bytes = Buffer.from(value, 'utf8');
@@ -42,15 +45,17 @@ const versionInfo = (sdkVersion) => {
 };
 /**
  * `LoginRegisterRequest` body:
- * `[ClientVersionInfo][username len u8 + bytes][password len u8 + bytes]
- * [context len u32][context]`.
+ * `[ClientVersionInfo][bind secret 32 bytes][username len u8 + bytes]
+ * [password len u8 + bytes][context len u32][context]`.
  */
-export const serializeLoginRegister = (username, password, sdkVersion) => {
+export const serializeLoginRegister = (username, password, sdkVersion, bindSecret) => {
+    validateBindSecret(bindSecret);
     const passwordBytes = Buffer.from(password, 'utf8');
     if (passwordBytes.length > 255)
         throw new Error('password exceeds the u8 length prefix');
     return Buffer.concat([
         versionInfo(sdkVersion),
+        bindSecret,
         wireName(username),
         Buffer.from([passwordBytes.length]),
         passwordBytes,
@@ -58,17 +63,29 @@ export const serializeLoginRegister = (username, password, sdkVersion) => {
     ]);
 };
 /** `LoginRegisterWithPatRequest` body: the PAT takes the credential slot. */
-export const serializeLoginRegisterWithPat = (token, sdkVersion) => {
+export const serializeLoginRegisterWithPat = (token, sdkVersion, bindSecret) => {
+    validateBindSecret(bindSecret);
     const tokenBytes = Buffer.from(token, 'utf8');
     if (tokenBytes.length > 255)
         throw new Error('token exceeds the u8 length prefix');
     return Buffer.concat([
         versionInfo(sdkVersion),
+        bindSecret,
         Buffer.from([tokenBytes.length]),
         tokenBytes,
         Buffer.alloc(4)
     ]);
 };
+export const serializeBindSession = (identity, sdkVersion, bindSecret) => {
+    if (identity.length !== SESSION_IDENTITY_BYTES)
+        throw new RangeError('session identity must be 32 bytes');
+    validateBindSecret(bindSecret);
+    return Buffer.concat([versionInfo(sdkVersion), identity, bindSecret]);
+};
+const validateBindSecret = (secret) => {
+    if (secret.length !== BIND_SECRET_BYTES)
+        throw new RangeError('bind secret must be 32 bytes');
+};
 /**
  * `[user_id u32][session u64][server_protocol_version u32]
  * [server_version len u8 + bytes]`.