@rapidmx/mapi-plugin 1.0.0-beta.3 → 1.0.0-beta.5

package/dist/lib/sql/MapiEmsmdbRouteSQL.js

@@ -8,7 +8,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 // Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
-import { CalendarEventSQL, ContactSQL, FolderSQL, LabelSQL, MailboxSQL, MessageSQL, TaskSQL } from "@rapidmx/restapi/sql";
+import { AuditLogEntrySQL, CalendarEventSQL, ContactSQL, FolderSQL, LabelSQL, MailboxSQL, MessageSQL, TaskSQL } from "@rapidmx/restapi/sql";
 import { BaseMapiEmsmdbRoute } from "../BaseMapiEmsmdbRoute.js";
 import { RopLogonHandler } from "../rop/RopLogonHandler.js";
 import { RopReleaseHandler } from "../rop/RopReleaseHandler.js";
@@ -51,6 +51,7 @@ let MapiEmsmdbRouteSQL = class MapiEmsmdbRouteSQL extends BaseMapiEmsmdbRoute {
         this.contactClass = ContactSQL;
         this.taskClass = TaskSQL;
         this.labelClass = LabelSQL;
+        this.auditLogClass = AuditLogEntrySQL;
         this.ropHandlerClasses = [
             RopLogonHandler,
             RopReleaseHandler,

package/dist/lib/sql/MapiEmsmdbRouteSQL.js.map

@@ -1 +1 @@
-{"version":3,"file":"MapiEmsmdbRouteSQL.js","sourceRoot":"","sources":["../../../src/sql/MapiEmsmdbRouteSQL.ts"],"names":[],"mappings":";;;;;;AAAA,+EAA+E;AAC/E,mEAAmE;AACnE,mCAAmC;AACnC,+EAA+E;AAC/E,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC1H,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AACtE,OAAO,EAAE,2BAA2B,EAAE,MAAM,uCAAuC,CAAC;AACpF,OAAO,EAAE,0BAA0B,EAAE,MAAM,sCAAsC,CAAC;AAClF,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,EAAE,+BAA+B,EAAE,MAAM,2CAA2C,CAAC;AAC5F,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AACtE,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AACtE,OAAO,EAAE,uBAAuB,EAAE,MAAM,mCAAmC,CAAC;AAC5E,OAAO,EAAE,uBAAuB,EAAE,MAAM,mCAAmC,CAAC;AAC5E,OAAO,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,EAAE,4BAA4B,EAAE,MAAM,wCAAwC,CAAC;AACtF,OAAO,EAAE,uBAAuB,EAAE,MAAM,mCAAmC,CAAC;AAC5E,OAAO,EAAE,iCAAiC,EAAE,MAAM,6CAA6C,CAAC;AAChG,OAAO,EAAE,wBAAwB,EAAE,MAAM,oCAAoC,CAAC;AAC9E,OAAO,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAC1E,OAAO,EAAE,kCAAkC,EAAE,MAAM,8CAA8C,CAAC;AAClG,OAAO,EAAE,0CAA0C,EAAE,MAAM,sDAAsD,CAAC;AAClH,OAAO,EAAE,qCAAqC,EAAE,MAAM,iDAAiD,CAAC;AACxG,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,MAAM,EAAE,KAAK,EAAE,GAAG,eAAe,CAAC;AAElC;;;;;;GAMG;AAEI,IAAM,kBAAkB,GAAxB,MAAM,kBAAmB,SAAQ,mBAA+B;IAAhE;;QACO,iBAAY,GAAQ,UAAU,CAAC;QAC/B,gBAAW,GAAQ,SAAS,CAAC;QAC7B,iBAAY,GAAQ,UAAU,CAAC;QAC/B,uBAAkB,GAAQ,gBAAgB,CAAC;QAC3C,iBAAY,GAAQ,UAAU,CAAC;QAC/B,cAAS,GAAQ,OAAO,CAAC;QACzB,eAAU,GAAQ,QAAQ,CAAC;QAC3B,sBAAiB,GAAU;YACjC,eAAe;YACf,iBAAiB;YACjB,oBAAoB;YACpB,2BAA2B;YAC3B,0BAA0B;YAC1B,oBAAoB;YACpB,mBAAmB;YACnB,qBAAqB;YACrB,+BAA+B;YAC/B,oBAAoB;YACpB,oBAAoB;YACpB,uBAAuB;YACvB,uBAAuB;YACvB,qBAAqB;YACrB,4BAA4B;YAC5B,uBAAuB;YACvB,iCAAiC;YACjC,wBAAwB;YACxB,sBAAsB;YACtB,kCAAkC;YAClC,0CAA0C;YAC1C,qCAAqC;SACxC,CAAC;IACN,CAAC;CAAA,CAAA;AAhCY,kBAAkB;IAD9B,KAAK,CAAC,cAAc,CAAC;GACT,kBAAkB,CAgC9B"}
+{"version":3,"file":"MapiEmsmdbRouteSQL.js","sourceRoot":"","sources":["../../../src/sql/MapiEmsmdbRouteSQL.ts"],"names":[],"mappings":";;;;;;AAAA,+EAA+E;AAC/E,mEAAmE;AACnE,mCAAmC;AACnC,+EAA+E;AAC/E,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC5I,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AACtE,OAAO,EAAE,2BAA2B,EAAE,MAAM,uCAAuC,CAAC;AACpF,OAAO,EAAE,0BAA0B,EAAE,MAAM,sCAAsC,CAAC;AAClF,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,EAAE,+BAA+B,EAAE,MAAM,2CAA2C,CAAC;AAC5F,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AACtE,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AACtE,OAAO,EAAE,uBAAuB,EAAE,MAAM,mCAAmC,CAAC;AAC5E,OAAO,EAAE,uBAAuB,EAAE,MAAM,mCAAmC,CAAC;AAC5E,OAAO,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,EAAE,4BAA4B,EAAE,MAAM,wCAAwC,CAAC;AACtF,OAAO,EAAE,uBAAuB,EAAE,MAAM,mCAAmC,CAAC;AAC5E,OAAO,EAAE,iCAAiC,EAAE,MAAM,6CAA6C,CAAC;AAChG,OAAO,EAAE,wBAAwB,EAAE,MAAM,oCAAoC,CAAC;AAC9E,OAAO,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAC1E,OAAO,EAAE,kCAAkC,EAAE,MAAM,8CAA8C,CAAC;AAClG,OAAO,EAAE,0CAA0C,EAAE,MAAM,sDAAsD,CAAC;AAClH,OAAO,EAAE,qCAAqC,EAAE,MAAM,iDAAiD,CAAC;AACxG,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,MAAM,EAAE,KAAK,EAAE,GAAG,eAAe,CAAC;AAElC;;;;;;GAMG;AAEI,IAAM,kBAAkB,GAAxB,MAAM,kBAAmB,SAAQ,mBAA+B;IAAhE;;QACO,iBAAY,GAAQ,UAAU,CAAC;QAC/B,gBAAW,GAAQ,SAAS,CAAC;QAC7B,iBAAY,GAAQ,UAAU,CAAC;QAC/B,uBAAkB,GAAQ,gBAAgB,CAAC;QAC3C,iBAAY,GAAQ,UAAU,CAAC;QAC/B,cAAS,GAAQ,OAAO,CAAC;QACzB,eAAU,GAAQ,QAAQ,CAAC;QAC3B,kBAAa,GAAQ,gBAAgB,CAAC;QACtC,sBAAiB,GAAU;YACjC,eAAe;YACf,iBAAiB;YACjB,oBAAoB;YACpB,2BAA2B;YAC3B,0BAA0B;YAC1B,oBAAoB;YACpB,mBAAmB;YACnB,qBAAqB;YACrB,+BAA+B;YAC/B,oBAAoB;YACpB,oBAAoB;YACpB,uBAAuB;YACvB,uBAAuB;YACvB,qBAAqB;YACrB,4BAA4B;YAC5B,uBAAuB;YACvB,iCAAiC;YACjC,wBAAwB;YACxB,sBAAsB;YACtB,kCAAkC;YAClC,0CAA0C;YAC1C,qCAAqC;SACxC,CAAC;IACN,CAAC;CAAA,CAAA;AAjCY,kBAAkB;IAD9B,KAAK,CAAC,cAAc,CAAC;GACT,kBAAkB,CAiC9B"}

package/dist/types/BaseMapiEmsmdbRoute.d.ts

@@ -1,6 +1,22 @@
 import { type JWTUser } from "@rapidrest/core";
 import { HttpRequest, HttpResponse } from "@rapidrest/service-core";
+import { type RopBuffer } from "./codec/RopBuffer.js";
 import { Mailbox } from "@rapidmx/restapi";
+/** The largest `RopBufferSize` accepted - the `[MS-OXCRPC]` ROP input buffer limit. */
+export declare const MAX_ROP_BUFFER_SIZE = 32767;
+/** A decoded `Execute` request: the ROP buffer framing plus the client's `MaxRopOut`. */
+export interface ExecuteRequest extends RopBuffer {
+    /** The most bytes the client accepts in the response's `RopBuffer`. */
+    maxRopOut: number;
+}
+/**
+ * Decodes an `Execute` request body's `Flags`/`RopBufferSize`/`RopBuffer`/`MaxRopOut` and the ROP buffer framing
+ * inside it. Throws a 400 `ApiError` for a malformed body - a `RopBufferSize` over `MAX_ROP_BUFFER_SIZE` or past the
+ * end of the body, or a ROP buffer `decodeRopBuffer` rejects - instead of letting a bare `RangeError` surface as a
+ * 500. A body that ends before `MaxRopOut` gets the largest response a `RopBuffer` can carry.
+ * `AuxiliaryBufferSize`/`AuxiliaryBuffer` are left unread - no auxiliary-payload support in this pragmatic subset.
+ */
+export declare function decodeExecuteRequest(rawBody: Buffer): ExecuteRequest;
 /**
  * Abstract base for the single fixed EMSMDB endpoint (`POST /mapi/emsmdb` by `[MS-OXCMAPIHTTP]` convention,
  * though the concrete path is left to the consuming application to mount via `@Route(...)` - see
@@ -43,6 +59,8 @@ export declare abstract class BaseMapiEmsmdbRoute<M extends Mailbox> {
     protected abstract contactClass: any;
     protected abstract taskClass: any;
     protected abstract labelClass: any;
+    /** The backend's `AuditLogEntry` class. When set, messages deleted through MAPI are audited like REST deletes. */
+    protected auditLogClass?: any;
     /** ROP handler classes to instantiate (one each) in `@Init`, keyed by their own `ropId`. Empty until a
      * concrete `RopHandler` lands - every ROP is then simply left unprocessed (see `RopDispatcher`'s own doc
      * comment), the correct, honest behavior for a transport skeleton with no ROPs implemented yet. */
@@ -60,7 +78,11 @@ export declare abstract class BaseMapiEmsmdbRoute<M extends Mailbox> {
     private blobStore?;
     private scanPipeline?;
     private mailTransport?;
+    /** Publishes the live `Folder` counts-update event `refreshFolderCounts()` sends after a ROP handler changes what
+     * a folder holds through `context.messageRepo` directly - see `folderCountsContext()`/`RopContext.notifyFolderCounts`. */
+    private notificationUtils?;
     private logger;
+    private config?;
     init(): Promise<void>;
     dispatch(req: HttpRequest, res: HttpResponse, user?: JWTUser): Promise<void>;
     /**
@@ -71,12 +93,47 @@ export declare abstract class BaseMapiEmsmdbRoute<M extends Mailbox> {
      */
     private handleConnect;
     /**
-     * `Execute` decodes the outer envelope (`Flags`/`RopBufferSize`/`RopBuffer`/...) and the inner ROP buffer
-     * framing (`RopBuffer.ts`), dispatches every contained ROP via `RopDispatcher`, and re-encodes the
+     * `Execute` decodes the outer envelope (`Flags`/`RopBufferSize`/`RopBuffer`/`MaxRopOut`/...) and the inner ROP
+     * buffer framing (`RopBuffer.ts`), dispatches every contained ROP via `RopDispatcher`, and re-encodes the
      * collected responses - preserving the incoming `handleTable` unchanged (this pragmatic subset never
      * allocates/frees table-wide handle slots at the framing level; individual `RopHandler`s manage their own
      * entries within `session.handles` instead).
+     *
+     * - **One request at a time per session.** Only the caller's own session (whose mailbox is still the caller's) is
+     * locked. The lock is taken before any ROP runs and renewed every `SESSION_LOCK_RENEW_MS` while the request runs,
+     * so a slow request keeps it; an overlapping request gets `X-ResponseCode` 15 (Invalid Sequence) without any side
+     * effects. The save stays compare-and-set. Each `Execute` also refreshes the session's place in the per-user cap.
+     * - **Retries.** While a request with an `X-RequestId` runs, an in-progress marker for that id is kept (renewed with
+     * the lock); a retry of it is answered with code 15 instead of running again. Its response then replaces the
+     * marker, and a request repeating the last id (a client retrying after a lost response) gets that response again
+     * instead of running its ROPs twice. A request that ends without a stored response drops its marker.
+     * `MapiSequence` isn't validated - the lock and the replay cache cover what it guards against here.
+     * - **Output size.** ROP responses are held to the client's `MaxRopOut`, less the `RopSize` field and handle
+     * table, and to what a 16-bit `RopSize` can describe (see `dispatchRops`). Room for a `RopBufferTooSmall` covering
+     * the rest of the request is kept free as ROPs run, so a response that doesn't fit is always answered that way (a
+     * normal, stored response). Only a `MaxRopOut` too small for a `RopBufferTooSmall` of the whole request answers
+     * `ecBufferTooSmall` in the body `ErrorCode`, before any ROP runs, so nothing is stored and a retry changes nothing.
+     * - **Released handles.** Once the session is saved, the FastTransfer streams and write-stream chunks of handles
+     * the request released are deleted from the shared store; `Disconnect` and session eviction delete a session's
+     * whole set.
+     * - **Malformed ROPs.** A ROP that can't be decoded answers 400; the ROPs before it already ran, so the session is
+     * still saved first.
      */
     private handleExecute;
+    /** Runs an `Execute` under its session's lock. `running.requestId` is set while this request's in-progress marker is
+     * stored, and cleared once its response is stored instead. */
+    private executeLocked;
+    /** What `refreshFolderCounts()` (`@rapidmx/restapi`) needs to recompute, re-cache and publish a folder's counts -
+     * see `RopContext.notifyFolderCounts`'s own doc comment for why a ROP handler must call it after adding, deleting
+     * or moving a `Message` row through `context.messageRepo` itself. */
+    private folderCountsContext;
+    /** Writes an `Execute` failure body (no ROP buffer) with the given `X-ResponseCode` and `ErrorCode`. */
+    private sendExecuteFailure;
+    /**
+     * Loads the session named by the `MapiContext` cookie, but only if the authenticated caller is the user who
+     * `Connect`ed it. The cookie value alone is a bearer token for someone else's mailbox otherwise, so a session
+     * belonging to another user is treated exactly like one that doesn't exist.
+     */
+    private loadOwnSession;
     private handleDisconnect;
 }

package/dist/types/MapiSessionManager.d.ts

@@ -1,37 +1,60 @@
 import { SimpleEntity } from "@rapidrest/service-core";
+import { type HandleDataStore } from "./rop/HandleDataCache.js";
+/** A pragmatic idle-session lifetime. The spec leaves session lifetime to server policy, not a fixed wire
+ * value - a real client re-establishes (`Connect`) transparently whenever its session context has expired. */
+export declare const SESSION_TTL_SECONDS: number;
+/** The longest a session may live, however active it stays. A client simply `Connect`s again afterwards. */
+export declare const MAX_SESSION_LIFETIME_MS: number;
+/** The most sessions one user may hold at once. `Connect` past this ends that user's least recently used session (each
+ * `Execute` refreshes its session's place - see `MapiSessionManager.touch`). */
+export declare const MAX_SESSIONS_PER_USER = 20;
+/** The largest a serialized session may grow. Everything that grows with use is capped on its own (handles by their
+ * one-byte index, named properties, MIDs; write streams live outside the session); this is the backstop, and a save
+ * past it fails with `MAPI_E_TOO_BIG` rather than storing megabytes every later request has to load. */
+export declare const MAX_SESSION_BYTES: number;
+/** How long an `Execute`'s session lock lives without being renewed. A running `Execute` renews it every
+ * `SESSION_LOCK_RENEW_MS`, so only a crashed pod's lock expires. The session save is still compare-and-set, so an
+ * expired lock can't corrupt state. */
+export declare const SESSION_LOCK_TTL_MS: number;
+/** How often a running `Execute` renews its session lock and in-progress marker. */
+export declare const SESSION_LOCK_RENEW_MS: number;
 /** Tags what a ROP-assigned integer handle (the `ServerObjectHandleTable` index space) refers to.
  * `entityUid` for a `"folder"` handle is one of `session.folderIds`' own value strings (`"virtual:<name>"` or
- * `"folder:<uid>"`), not a bare UID - the same format throughout avoids a second parallel encoding. A
- * `"table"` handle's `rows`/`columns`/`cursor` hold `RopGetHierarchyTable`/`RopSetColumns`/`RopQueryRows`
- * state for that specific table instance: `rows` is the resolved, order-fixed list of entity targets (same
- * `"virtual:<name>"`/`"folder:<uid>"` format) this table enumerates, `columns` the `RopSetColumns`-configured
- * property list, `cursor` how many rows `RopQueryRows` has already returned. A `"stream"` handle's `entityUid`
- * is the `"message:<uid>"` target its content was opened from, `propertyId`/`propertyType` the `PropertyTag`
- * `RopOpenStream` opened (this pragmatic subset only ever supports `PidTagBody`/`PtypString`, see
- * `MessageBodyStream.ts`), and `streamPosition` how many bytes `RopReadStream` has already returned (a
- * read-mode stream) or `writeTargetHandleIndex`/`writeBufferBase64` the accumulated write state (a write-mode
- * stream opened `ReadWrite`/`Create` against a `RopCreateMessage` draft's `PidTagBody` - see
- * `RopOpenStreamHandler`'s own doc comment).
+ * `"folder:<uid>"`), not a bare UID - the same format throughout avoids a second parallel encoding.
+ *
+ * A `"table"` handle's `columns`/`cursor` hold `RopSetColumns`/`RopQueryRows` state. A hierarchy table carries its
+ * resolved child-folder targets in `rows`. A contents table carries no rows at all: `contentsKind` says which repo
+ * its folder's items live in and `RopQueryRows` reads just the requested window from the database (see
+ * `ContentsTable.ts`), so a large folder never lands in session state.
+ *
+ * A `"stream"` handle's `entityUid` is the `"message:<uid>"` target its content was opened from,
+ * `propertyId`/`propertyType` the `PropertyTag` `RopOpenStream` opened (this pragmatic subset only ever supports
+ * `PidTagBody`/`PtypString`, see `MessageBodyStream.ts`), and `streamPosition` how many bytes `RopReadStream` has
+ * already returned. A read stream's decoded body lives in `HandleDataCache`, not here. A write stream (opened
+ * `ReadWrite`/`Create` against a `RopCreateMessage` draft's `PidTagBody`) records the draft it belongs to in
+ * `writeTargetHandleIndex`/`writeTargetGeneration`, and how many bytes have been written in `writeSize`. The bytes
+ * themselves are chunks in the `HandleDataStore` (see `RopWriteStreamHandler`), not session state.
  *
  * A `"message"` handle from `RopCreateMessage` (a draft not yet `RopSaveChangesMessage`d) has `entityUid: ""`
  * and instead carries `draftFolderUid` (the folder it will belong to) and `draftProperties` (the small,
  * well-known set of properties this pragmatic subset's `RopSetProperties` tracks - Subject/DisplayTo/
  * DisplayCc/DisplayBcc/an inline `PidTagBody`, each coerced to a plain string, keyed by decimal `PropertyId` -
- * a string key because a JSON-object key is always a string regardless of how it's written). `writeBufferBase64`
- * stores accumulated `RopWriteStream` bytes as base64 rather than a raw `Buffer` for the same reason `Date`
- * fields elsewhere in this class are stored as ISO strings: `RedisCache`'s Redis-backed path round-trips
- * everything through `JSON.stringify`/`JSON.parse`, which cannot represent a `Buffer` (or a `bigint`, which is
- * why no property value is ever stored in its native decoded MAPI type here) losslessly.
+ * a string key because a JSON-object key is always a string regardless of how it's written). Buffers are stored
+ * as base64 and dates as ISO strings since sessions round-trip through `JSON.stringify`/`JSON.parse`.
  *
- * A `"fastTransfer"` handle (`RopFastTransferSourceCopyTo`/`CopyProperties`'s output handle) carries the
- * entire pre-built FastTransfer stream eagerly (`transferBufferBase64`, same base64-for-`RedisCache` reasoning
- * as `writeBufferBase64`) - this pragmatic subset builds the whole stream up front rather than truly
- * incrementally, since a real client only ever pages it out via `RopFastTransferSourceGetBuffer`'s own
- * `transferPosition` cursor into that already-complete buffer, see `FastTransferStream.ts`'s own doc comment. */
+ * A `"fastTransfer"` handle (`RopFastTransferSourceCopyTo`/`CopyProperties`'s output handle) keeps only what is
+ * needed to rebuild its stream (`transferSourceType`, `transferColumns`/`transferExcludeIds`) plus the paging
+ * cursor `transferPosition`; the built stream itself lives in `HandleDataCache`.
+ *
+ * `generation` is a random nonce per assignment (see `assignHandle`), so data keyed by handle index can tell a handle
+ * apart from a later one that reuses the same index - including one assigned by a request whose session changes were
+ * never saved, which a per-session counter would hand out again. */
 export interface MapiObjectHandle {
     type: "logon" | "folder" | "message" | "table" | "stream" | "fastTransfer";
     entityUid: string;
+    generation?: string;
     rows?: string[];
+    contentsKind?: "message" | "calendarEvent" | "contact" | "task";
     columns?: {
         propertyId: number;
         propertyType: number;
@@ -43,25 +66,32 @@ export interface MapiObjectHandle {
     draftFolderUid?: string;
     draftProperties?: Record<string, string>;
     writeTargetHandleIndex?: number;
-    writeBufferBase64?: string;
-    transferBufferBase64?: string;
+    writeTargetGeneration?: string;
+    writeSize?: number;
+    transferSourceType?: "folder" | "message";
+    transferColumns?: {
+        propertyId: number;
+        propertyType: number;
+    }[];
+    transferExcludeIds?: number[];
     transferPosition?: number;
+    /** Set on a draft message once `RopSubmitMessage` has tried to send it, whatever the outcome. A submitted draft
+     * can't be submitted again or changed. */
+    submitted?: boolean;
 }
 /**
  * The MAPI/HTTP `Session Context` (`[MS-OXCMAPIHTTP]` §3.1.1.1): everything a `Connect`-established session
  * needs across subsequent `Execute` requests. Never persisted to a real database - purely an ephemeral,
- * TTL-bound cache entry (see `MapiSessionManager` below), so this deliberately extends `SimpleEntity` (just a
- * `uid`) rather than this library's own `BaseEntity`, which would add ACL/soft-delete/optimistic-locking
- * machinery this object has no use for.
+ * TTL-bound store entry (see `MapiSessionManager` below), so this deliberately extends `SimpleEntity` (just a
+ * `uid`) rather than this library's own `BaseEntity`.
  *
- * `createdAt` is a plain ISO-8601 string, not a `Date` - `RedisCache`'s Redis-backed path round-trips values
- * through `JSON.stringify`/`JSON.parse`, which silently turns a `Date` into a string on the way out without
- * reviving it back to a `Date` on the way in; storing it as a string from the start keeps the shape identical
- * whether a session happens to be served from the in-memory or the Redis-backed path.
+ * `createdAt` is a plain ISO-8601 string, not a `Date`, since sessions round-trip through JSON. `version` is
+ * bumped on every successful save and compared on the next one - see `MapiSessionManager.save()`.
  */
 export declare class MapiSessionContext extends SimpleEntity {
     mailboxUid: string;
     userUid: string;
+    version: number;
     handles: Record<number, MapiObjectHandle>;
     nextHandleIndex: number;
     createdAt: string;
@@ -71,60 +101,185 @@ export declare class MapiSessionContext extends SimpleEntity {
     folderIds: Record<string, string>;
     /** The reverse of `folderIds` (target -> FID) plus a monotonic counter, maintained alongside it by
      * `FolderTarget.assignOrGetFid`/`RopLogonHandler` so "does this target already have a FID" is an O(1)
-     * lookup instead of a linear scan of `folderIds` repeated once per table row - see `assignOrGetFid`'s own
-     * doc comment for why the scan this replaces was a genuine (not just theoretical) quadratic cost across a
-     * session's lifetime. Small and purely additive to session state (one more string-keyed map of numbers,
-     * the same order of magnitude as `folderIds` itself), unlike caching whole resolved rows would be. */
+     * lookup instead of a linear scan of `folderIds` repeated once per table row. */
     folderTargetIds: Record<string, number>;
     nextFolderId: number;
     /** This session's MID assignments, keyed by MID (decimal string), valued `"message:<uid>"` - the message
-     * analog of `folderIds` above. Unlike `folderIds` (pre-populated by `RopLogon`), a MID only ever comes into
-     * existence lazily, the first time a `RopQueryRows` row exposes a message's `PidTagMid` column (see
-     * `MessageTarget.assignOrGetMid`), read back by a later `RopOpenMessage`. */
+     * analog of `folderIds` above. A MID only ever comes into existence lazily, the first time a `RopQueryRows`
+     * row exposes a message's `PidTagMid` column (see `MessageTarget.assignOrGetMid`), read back by a later
+     * `RopOpenMessage`. */
     messageIds: Record<string, string>;
-    /** The reverse of `messageIds` (target -> MID) plus a monotonic counter - the message analog of
-     * `folderTargetIds`/`nextFolderId` above, for the identical O(1)-lookup reason. */
+    /** The reverse of `messageIds` (target -> MID) plus a monotonic counter. */
     messageTargetIds: Record<string, number>;
     nextMessageId: number;
+    /** The oldest MID still mapped. Past `MAX_MESSAGE_IDS` mapped MIDs the oldest are dropped - see
+     * `MessageTarget.assignOrGetMid`. */
+    firstMessageId: number;
     /** This session's `RopGetPropertyIdsFromNames` mapping table (`[MS-OXCPRPT]` §2.2.12), keyed by a JSON
      * string encoding of the `{guid, kind, lid|name}` `PropertyName` the numeric ID was assigned to - see
-     * `NamedPropertyRegistry.ts`'s own doc comment for why a JSON string (rather than a delimiter-joined one)
-     * is the safest key shape here. A real client resolves every named property (almost every Calendar-specific
-     * one - `PidLidAppointmentStartWhole`, `PidLidBusyStatus`, `PidLidAppointmentRecur`, ...) through this table
-     * once per session before ever setting/reading it via `RopSetProperties`/`RopGetPropertiesSpecific`. */
+     * `NamedPropertyRegistry.ts`. */
     namedProperties: Record<string, number>;
-    /** The reverse of `namedProperties` (numeric ID -> `PropertyName` JSON key) plus a monotonic counter -
-     * `NamedPropertyRegistry.ts`'s own doc comment covers why both the O(n) forward scan this replaces and the
-     * `Math.max(...spread)` id-allocation it used are real problems, not just theoretical ones, at real
-     * mailbox/session scale. */
+    /** The reverse of `namedProperties` (numeric ID -> `PropertyName` JSON key) plus a monotonic counter. */
     namedPropertyIds: Record<number, string>;
     nextNamedPropertyId: number;
-    /** `mailboxUid`/`userUid` are always known at construction time (the only call site is
-     * `MapiSessionManager.create()`, which resolves both up front) - required here rather than optional with
-     * a same-value fallback, which would just be dead code no real caller ever takes the other branch of. */
     constructor(other: Partial<SimpleEntity> & {
         mailboxUid: string;
         userUid: string;
     });
 }
 /**
- * Stores/loads `MapiSessionContext`s, keyed by the opaque session id that also becomes the `MapiContext`
- * cookie value. Reuses `@rapidrest/service-core`'s existing generic `RedisCache<T>` (Redis-backed when a
- * `cache` datastore is configured, transparent in-memory fallback otherwise) rather than either a bespoke
- * Redis client (unlike `PingCommand`'s own throwaway pub/sub client - fine for ephemeral fan-out, not a good
- * fit for stateful session data) or the framework's generic cookie/session middleware (built for a whole-app
- * `req.session` object, not this protocol's specific handle-table shape). `RedisCache` needs no real
- * persisted entity - only a class with a `.name` for its Redis key prefix - so a purely ephemeral,
- * never-persisted class like `MapiSessionContext` is a perfectly valid `type` for it.
+ * Stores `handle` at `index` with a fresh generation. Whatever previously held that index is released first
+ * (see `releaseHandle`), so a stream or cached data belonging to the old handle never attaches to the new one.
+ */
+export declare function assignHandle(session: MapiSessionContext, index: number, handle: MapiObjectHandle): MapiObjectHandle;
+/**
+ * Releases the handle at `index`: drops its cached data, and releases every write stream opened against it
+ * (a stream is meaningless once its draft message is gone, and would otherwise attach to whatever reuses the
+ * index next).
+ */
+export declare function releaseHandle(session: MapiSessionContext, index: number): void;
+/** The shared-store keys (FastTransfer streams, write-stream chunks) of every handle released on `session` since the
+ * last call, for the route to delete once the session's changes are saved. */
+export declare function takeReleasedHandleData(session: MapiSessionContext): string[];
+/** The outcome of `MapiSessionManager.save()`. `"conflict"` means another request saved the session first;
+ * `"missing"` that it expired or was ended; `"tooBig"` that it grew past `MAX_SESSION_BYTES` and was not saved. */
+export type SessionSaveResult = "saved" | "conflict" | "missing" | "tooBig";
+/**
+ * The storage a `MapiSessionManager` runs on: Redis when a `cache` datastore is configured, otherwise memory.
+ *
+ * A session is two entries: its JSON (`sessionKey`) and its version (`<sessionKey>.version`). A save compares the
+ * version entry only, so Redis never has to parse the session JSON.
+ */
+export interface MapiSessionStore {
+    get(key: string): Promise<string | undefined>;
+    create(key: string, value: string, ttlSeconds: number): Promise<void>;
+    compareAndSet(key: string, expectedVersion: number, value: string, ttlSeconds: number): Promise<"saved" | "conflict" | "missing">;
+    delete(key: string): Promise<void>;
+    /** Atomically records `sessionId` in the user's index (ordered by last use, starting at `createdAtMs`): drops ids
+     * whose session is gone, ends the least recently used sessions until fewer than `max` remain, then adds it. Returns
+     * the ids it ended. */
+    addToUserIndex(indexKey: string, sessionId: string, createdAtMs: number, max: number, ttlSeconds: number): Promise<string[]>;
+    /** `SET NX` with a TTL: `true` when the lock was free and is now held with `token`. */
+    acquireLock(key: string, token: string, ttlMs: number): Promise<boolean>;
+    /** Releases the lock only if it is still held with `token`. */
+    releaseLock(key: string, token: string): Promise<void>;
+    /** Extends the lock to `ttlMs` from now, only while it is still held with `token`. */
+    renewLock(key: string, token: string, ttlMs: number): Promise<boolean>;
+    /** Moves `sessionId` to `score` in the user's index when it is still there. */
+    touchUserIndex(indexKey: string, sessionId: string, score: number): Promise<void>;
+    getValue(key: string): Promise<string | undefined>;
+    putValue(key: string, value: string, ttlSeconds: number): Promise<void>;
+}
+/** Creates a session at version 0. KEYS: session, version. ARGV: json, ttl. */
+export declare const CREATE_SCRIPT = "\nredis.call('SETEX', KEYS[1], ARGV[2], ARGV[1])\nredis.call('SETEX', KEYS[2], ARGV[2], '0')\nreturn 1\n";
+/** Replaces the session only when its version entry still equals the expected one, without decoding the session.
+ * KEYS: session, version. ARGV: expected version, json, ttl. Returns 1 saved, 0 on a version mismatch, -1 when gone. */
+export declare const COMPARE_AND_SET_SCRIPT = "\nlocal current = redis.call('GET', KEYS[2])\nif not current or redis.call('EXISTS', KEYS[1]) == 0 then return -1 end\nif tonumber(current) ~= tonumber(ARGV[1]) then return 0 end\nredis.call('SETEX', KEYS[1], ARGV[3], ARGV[2])\nredis.call('SETEX', KEYS[2], ARGV[3], tostring(tonumber(ARGV[1]) + 1))\nreturn 1\n";
+/** Adds a session to its user's sorted-set index in one step, so concurrent Connects can't each see room under the
+ * cap. KEYS: index. ARGV: session id, created-at score, max, index ttl, session key prefix, session key suffix. The
+ * session keys it checks and deletes are built from the ids, so they aren't declared in KEYS (fine on one Redis node,
+ * not on a cluster). Returns the ids it ended. */
+export declare const ADD_TO_USER_INDEX_SCRIPT = "\nlocal function sessionKey(id) return ARGV[5] .. id .. ARGV[6] end\nfor _, id in ipairs(redis.call('ZRANGE', KEYS[1], 0, -1)) do\n  if redis.call('EXISTS', sessionKey(id)) == 0 then redis.call('ZREM', KEYS[1], id) end\nend\nlocal ended = {}\nwhile redis.call('ZCARD', KEYS[1]) >= tonumber(ARGV[3]) do\n  local oldest = redis.call('ZRANGE', KEYS[1], 0, 0)[1]\n  redis.call('ZREM', KEYS[1], oldest)\n  redis.call('DEL', sessionKey(oldest), sessionKey(oldest) .. '.version')\n  table.insert(ended, oldest)\nend\nredis.call('ZADD', KEYS[1], ARGV[2], ARGV[1])\nredis.call('EXPIRE', KEYS[1], ARGV[4])\nreturn ended\n";
+/** KEYS: lock. ARGV: token, ttl ms. Returns 1 when acquired. */
+export declare const ACQUIRE_LOCK_SCRIPT = "\nif redis.call('SET', KEYS[1], ARGV[1], 'NX', 'PX', ARGV[2]) then return 1 end\nreturn 0\n";
+/** KEYS: lock. ARGV: token. Deletes the lock only while this token still holds it. */
+export declare const RELEASE_LOCK_SCRIPT = "\nif redis.call('GET', KEYS[1]) == ARGV[1] then redis.call('DEL', KEYS[1]) end\nreturn 1\n";
+/** KEYS: lock. ARGV: token, ttl ms. Returns 1 when the token still held the lock and it was extended. */
+export declare const RENEW_LOCK_SCRIPT = "\nif redis.call('GET', KEYS[1]) == ARGV[1] then redis.call('PEXPIRE', KEYS[1], ARGV[2]) return 1 end\nreturn 0\n";
+/** KEYS: user index. ARGV: score, session id. Updates the score of a member that is still present. */
+export declare const TOUCH_USER_INDEX_SCRIPT = "\nredis.call('ZADD', KEYS[1], 'XX', ARGV[1], ARGV[2])\nreturn 1\n";
+/** A `MapiSessionStore` on a node-redis client. Every read goes to Redis, never a per-process copy, so each
+ * replica sees the same session. */
+export declare class RedisMapiSessionStore implements MapiSessionStore {
+    private readonly client;
+    constructor(client: any);
+    get(key: string): Promise<string | undefined>;
+    create(key: string, value: string, ttlSeconds: number): Promise<void>;
+    compareAndSet(key: string, expectedVersion: number, value: string, ttlSeconds: number): Promise<"saved" | "conflict" | "missing">;
+    delete(key: string): Promise<void>;
+    addToUserIndex(indexKey: string, sessionId: string, createdAtMs: number, max: number, ttlSeconds: number): Promise<string[]>;
+    acquireLock(key: string, token: string, ttlMs: number): Promise<boolean>;
+    releaseLock(key: string, token: string): Promise<void>;
+    renewLock(key: string, token: string, ttlMs: number): Promise<boolean>;
+    touchUserIndex(indexKey: string, sessionId: string, score: number): Promise<void>;
+    getValue(key: string): Promise<string | undefined>;
+    putValue(key: string, value: string, ttlSeconds: number): Promise<void>;
+}
+/** A single-process `MapiSessionStore`. Values are stored as strings so every load hands out an independent copy,
+ * exactly like the Redis store. No method awaits between reading and writing, so each one is atomic. */
+export declare class MemoryMapiSessionStore implements MapiSessionStore {
+    private readonly entries;
+    private readonly indexes;
+    get(key: string): Promise<string | undefined>;
+    create(key: string, value: string, ttlSeconds: number): Promise<void>;
+    compareAndSet(key: string, expectedVersion: number, value: string, ttlSeconds: number): Promise<"saved" | "conflict" | "missing">;
+    delete(key: string): Promise<void>;
+    addToUserIndex(indexKey: string, sessionId: string, createdAtMs: number, max: number): Promise<string[]>;
+    acquireLock(key: string, token: string, ttlMs: number): Promise<boolean>;
+    releaseLock(key: string, token: string): Promise<void>;
+    renewLock(key: string, token: string, ttlMs: number): Promise<boolean>;
+    touchUserIndex(indexKey: string, sessionId: string, score: number): Promise<void>;
+    getValue(key: string): Promise<string | undefined>;
+    putValue(key: string, value: string, ttlSeconds: number): Promise<void>;
+    private read;
+    private write;
+    private sweep;
+}
+/** The store key of a session's JSON. */
+export declare function sessionKey(sessionId: string): string;
+/**
+ * Stores/loads `MapiSessionContext`s, keyed by the opaque session id that also becomes the `MapiContext` cookie
+ * value.
  *
- * @author Jean-Philippe Steinmetz
+ * Every load reads the shared store (Redis when a `cache` datastore is configured). An earlier version used
+ * `RedisCache`, whose per-process copy served a session without checking Redis, so with several replicas one pod
+ * could run ROPs against handles another pod had already changed. Saves are compare-and-set on `version`: when
+ * two requests on the same session overlap, the second save reports `"conflict"` instead of overwriting the
+ * first request's handles. `Execute` also holds the session's lock (`acquireLock`) while it runs, so an overlapping
+ * request is turned away before it has any side effects, and keeps its last response (`storeResponse`) so a retry of
+ * the same request is answered again instead of being run twice.
  */
 export declare class MapiSessionManager {
-    private _objectFactory?;
-    private cache?;
-    init(): Promise<void>;
+    private redisClient?;
+    private store?;
+    /** Where handlers keep FastTransfer streams and write-stream chunks: in Redis next to the sessions when configured,
+     * so any replica can continue a transfer. */
+    handleDataStore?: HandleDataStore;
+    init(): void;
+    /** Creates a session for `userUid`, ending that user's least recently used sessions (and their stored handle data)
+     * if they already hold `MAX_SESSIONS_PER_USER`. */
     create(mailboxUid: string, userUid: string): Promise<MapiSessionContext>;
+    /** Records that `session` was just used, so the per-user cap ends the least recently used session rather than the
+     * oldest one. */
+    touch(session: MapiSessionContext): Promise<void>;
+    /** Loads a session straight from the store. A session past `MAX_SESSION_LIFETIME_MS` is ended and treated as
+     * missing. */
     load(sessionId: string): Promise<MapiSessionContext | undefined>;
-    save(context: MapiSessionContext): Promise<void>;
+    /** Saves `context` only if nobody else saved it since it was loaded and it is within `MAX_SESSION_BYTES`,
+     * bumping its `version` on success. */
+    save(context: MapiSessionContext): Promise<SessionSaveResult>;
+    /** Ends a session, deleting its stored handle data too. */
     destroy(sessionId: string): Promise<void>;
+    /** Deletes every FastTransfer stream and write-stream chunk the session stored. Best effort: they expire anyway. */
+    private deleteHandleData;
+    /** Takes the session's `Execute` lock. Returns the token to release it with, or `undefined` while another
+     * request holds it. */
+    acquireLock(sessionId: string): Promise<string | undefined>;
+    releaseLock(sessionId: string, token: string): Promise<void>;
+    /** Extends the session's lock by another `SESSION_LOCK_TTL_MS`. `false` when `token` no longer holds it. */
+    renewLock(sessionId: string, token: string): Promise<boolean>;
+    /** The response last sent on this session if it answered `requestId`; `"inProgress"` while a request with that id
+     * is still running (or ran on a pod that died less than `SESSION_LOCK_TTL_MS` ago); otherwise `undefined`. */
+    storedResponse(sessionId: string, requestId: string): Promise<Buffer | "inProgress" | undefined>;
+    /** Records that `requestId` is running on this session, for `SESSION_LOCK_TTL_MS` (renewed along with the lock). A
+     * retry of it is then answered as busy instead of running a second time. */
+    markInProgress(sessionId: string, requestId: string): Promise<void>;
+    /** Extends the in-progress marker of `requestId` by another `SESSION_LOCK_TTL_MS`, only while it is still that marker:
+     * once the request's response (or anything else) has replaced it, nothing is written. `false` when it wasn't there. */
+    renewInProgress(sessionId: string, requestId: string): Promise<boolean>;
+    /** Drops the in-progress marker of `requestId` when it is still there (the request ended without storing a
+     * response), so a retry runs. Atomic, so it never deletes a response stored meanwhile. */
+    clearInProgress(sessionId: string, requestId: string): Promise<void>;
+    /** Remembers `body` as this session's answer to `requestId`. Only the latest request is kept. */
+    storeResponse(sessionId: string, requestId: string, body: Buffer): Promise<void>;
 }

package/dist/types/RegexPatternUtils.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Mirrors `@rapidrest/service-core`'s private `ModelUtils.MAX_PATTERN_LENGTH`: a `regex(...)` query operand
+ * longer than this is rejected as a potential ReDoS pattern with `INVALID_REQUEST`. The check runs against the
+ * operand AFTER escaping, so a raw client term well under the limit can still exceed it once each regex
+ * metacharacter doubles in length.
+ */
+export declare const MAX_REGEX_PATTERN_LENGTH = 100;
+/**
+ * Escapes `value` for a literal-substring `regex(...)` match, truncating the raw term (never mid-escape or
+ * mid-code-point) so the escaped result always fits `MAX_REGEX_PATTERN_LENGTH`. Matching on a prefix of an
+ * over-long search term still yields a superset of the full term's matches, which is a far better outcome than
+ * the whole command failing.
+ */
+export declare function boundedEscapedPattern(value: string, maxLength?: number): string;

package/dist/types/RopDispatcher.d.ts

@@ -1,17 +1,53 @@
 import type { RopContext, RopHandler } from "./rop/RopHandler.js";
+/** The most ROPs processed from one `Execute` request. A real client batches far fewer; anything past this is
+ * left unprocessed. */
+export declare const MAX_ROPS_PER_EXECUTE = 1024;
+/** The largest `RopsList` a response can carry: `RopSize` is a 16-bit count that includes its own 2 bytes. */
+export declare const MAX_ROPS_LIST_BYTES: number;
+/** `RopBufferTooSmall`'s `RopId` (`[MS-OXCROPS]` §2.2.15.1). */
+export declare const ROP_ID_BUFFER_TOO_SMALL = 255;
+/** `MAPI_E_CALL_FAILED`: a ROP failed while running (a database error, undecodable stored data, ...). */
+export declare const ERROR_CALL_FAILED = 2147500037;
+/** `MAPI_E_TOO_COMPLEX`: the ROP would have gone past this request's `ExecuteBudget`. */
+export declare const ERROR_TOO_COMPLEX = 2147746071;
+/** Thrown by `dispatchRops`, before any ROP runs, when the room for responses can't even hold a `RopBufferTooSmall`
+ * carrying the whole request. The route answers the `Execute` with `ecBufferTooSmall` ([MS-OXCRPC]). No ROP has run. */
+export declare class ExecuteBufferTooSmallError extends Error {
+    constructor();
+}
+export interface DispatchOptions {
+    /** Stop after this many ROPs. Defaults to `MAX_ROPS_PER_EXECUTE`. */
+    maxRops?: number;
+    /** The room for response ROPs, in bytes. Defaults to `MAX_ROPS_LIST_BYTES`; the route passes what the client's
+     * `MaxRopOut` leaves after the `RopSize` field and handle table. */
+    maxOutputBytes?: number;
+}
 /**
- * Walks a decoded `RopBuffer`'s `ropsList` blob, dispatching each contained ROP - identified by its own
- * leading `RopId` byte - to the matching registered handler in turn, collecting every response into one
- * output buffer. Deliberately ROP-agnostic: it knows nothing about any specific ROP's own fields, only how to
- * find the *next* one, via the handler's own advanced `reader` position once `handle()` returns - see
- * `RopBuffer.ts`'s doc comment for why a fully generic split isn't possible for this wire format.
+ * Walks a decoded `RopBuffer`'s `ropsList` blob, dispatching each contained ROP - identified by its own leading
+ * `RopId` byte - to the matching registered handler in turn, collecting every response into one output buffer.
+ * Deliberately ROP-agnostic: it knows nothing about any specific ROP's own fields, only how to find the *next* one,
+ * via the handler's own advanced `reader` position once `handle()` returns - see `RopBuffer.ts`'s doc comment for
+ * why a fully generic split isn't possible for this wire format.
  *
- * An unrecognized `RopId` stops processing immediately: the bytes belonging to that ROP (and everything after
- * it) can't be skipped without knowing that ROP's own layout, so there is no safe way to resync and continue.
- * This is an inherent constraint of the wire format, not a design choice this library is choosing not to
- * handle - a real client only ever sends ROPs the server has already told it (via its supported-command
- * surface) that it understands.
+ * - **Malformed requests.** An unrecognized `RopId`, or a ROP whose bytes run out or can't be sized (a
+ * `DecodeError`), throws a `DecodeError`: nothing after it can be located, so the route answers 400.
+ * - **A failing ROP.** Any other error thrown by a handler fails just that ROP: its partial output is dropped, a
+ * failure response (`RopId`, the handle index it echoes, `ReturnValue` `MAPI_E_CALL_FAILED` or, past the
+ * `ExecuteBudget`, `MAPI_E_TOO_COMPLEX`) takes its place, and the following ROPs still run. The handler has
+ * already read its whole request by the time it does work that can fail, so the next ROP is still where the
+ * reader points.
+ * - **Output space.** Room for a `RopBufferTooSmall` covering the next ROP and everything after it (3 bytes plus
+ * those request bytes) is always kept free. `context.ropOutputRemaining` tells each handler the room left *after*
+ * that reserve (computed from where the reader stands, so once a handler has read its request it excludes the
+ * handler's own bytes). A response that doesn't leave the reserve is replaced by `RopBufferTooSmall` (`SizeNeeded`
+ * plus the unprocessed request bytes, from this ROP on, for the client to resend) and processing stops; that always
+ * fits, because the reserve for this ROP was kept by the one before it. Handlers that change state by how much they
+ * return (`RopQueryRows`, `RopReadStream`, `RopFastTransferSourceGetBuffer`) size their response to the room, so they
+ * are never replaced after moving a cursor. Only when the request as a whole can't be covered by a
+ * `RopBufferTooSmall` is `ExecuteBufferTooSmallError` thrown, before anything runs, and the route answers the
+ * `Execute` with `ecBufferTooSmall` ([MS-OXCRPC]). So a failed `Execute` never follows state already changed and
+ * saved, which a retry would skip past.
  *
  * @author Jean-Philippe Steinmetz
  */
-export declare function dispatchRops(ropsList: Buffer, handlers: Map<number, RopHandler>, context: RopContext): Promise<Buffer>;
+export declare function dispatchRops(ropsList: Buffer, handlers: Map<number, RopHandler>, context: RopContext, options?: DispatchOptions): Promise<Buffer>;

package/dist/types/codec/BufferCursor.d.ts

@@ -15,6 +15,14 @@
  *
  * @author Jean-Philippe Steinmetz
  */
+/**
+ * A request that can't be decoded: truncated, or carrying a value (such as an unknown property type) whose wire
+ * size can't be determined. `RopDispatcher` answers the whole `Execute` with a 400 for one of these, since the bytes
+ * of every later ROP can no longer be located.
+ */
+export declare class DecodeError extends RangeError {
+    constructor(message: string);
+}
 export declare class BufferReader {
     private readonly buffer;
     private offset;
@@ -22,6 +30,8 @@ export declare class BufferReader {
     get position(): number;
     get remaining(): number;
     hasMore(): boolean;
+    /** Moves to `position` (backwards or forwards). Throws a `RangeError` for a position outside the buffer. */
+    seek(position: number): void;
     readUInt8(): number;
     readInt16LE(): number;
     readUInt16LE(): number;
@@ -62,6 +72,10 @@ export declare class BufferReader {
  * byte-array accumulator, adapted for multi-byte little-endian fields instead of single bytes. */
 export declare class BufferWriter {
     private readonly chunks;
+    private byteLength;
+    /** The number of bytes written so far. */
+    get length(): number;
+    private push;
     writeUInt8(value: number): this;
     writeInt16LE(value: number): this;
     writeUInt16LE(value: number): this;

package/dist/types/codec/GlobalObjectId.d.ts

@@ -3,9 +3,13 @@ import { BufferReader } from "./BufferCursor.js";
  * iCalendar UID (see this file's own doc comment for why that's the form that matters here), using `at` as the
  * `CreationTime`. */
 export declare function encodeGlobalObjectId(icalUid: string, at: Date): Buffer;
-/** Decodes a `GlobalObjectId` BLOB (read from `reader`'s current position) back into the `icalUid` it was
- * built from - unwrapping the `VCALID` form (see this file's own doc comment) when `Data` carries the
- * `"vCal-Uid"` marker, falling back to treating `Data` as bare `OutlookID` bytes otherwise. Throws if
- * `ByteArrayID` doesn't match the spec's own fixed constant - a real, spec-mandated identity check, not an
- * invented restriction. */
+/** Decodes a `GlobalObjectId` BLOB (read from `reader`'s current position) back into the `icalUid` it stands for.
+ * A `VCALID` (see this file's own doc comment) yields the UID it wraps. Anything else is a native `OutlookID`,
+ * whose `Data` is binary, not text: per `[MS-OXCICAL]`'s UID conversion, the iCalendar UID of such an object is the
+ * uppercase hex of the whole `GlobalObjectId` with the instance date (`YH`/`YL`/`M`/`D`, bytes 16-19) zeroed, so
+ * that is what is returned (compare it case-insensitively). Throws if `ByteArrayID` doesn't match the spec's own
+ * fixed constant - a real, spec-mandated identity check, not an invented restriction. */
 export declare function decodeGlobalObjectId(reader: BufferReader): string;
+/** The `YYYY-MM-DD` occurrence date a `GlobalObjectId` names (`YH`/`YL`/`M`/`D`), or `undefined` when it names the
+ * whole series (a zero year). `globalObjectId` must already have decoded successfully. */
+export declare function globalObjectIdInstanceDate(globalObjectId: Buffer): string | undefined;