@prosody-events/prosody 0.4.0 → 0.5.0

package/bindings.d.ts

@@ -31,6 +31,45 @@ export declare class AdminClient {
   deleteTopic(name: string): Promise<void>
 }
 
+/** A Kafka excise record received from a consumer. */
+export declare class ExciseMessage {
+  /** The Kafka topic this record was consumed from. */
+  get topic(): string
+  /** The partition number within the topic. */
+  get partition(): number
+  /** The offset of this record within its partition. */
+  get offset(): bigint
+  /** The timestamp when the record was produced. */
+  get timestamp(): Date
+  /** The key that this record excises. */
+  get key(): string
+}
+
+/** A Kafka message received from a consumer. */
+export declare class Message {
+  /** The Kafka topic this message was consumed from. */
+  get topic(): string
+  /** The partition number within the topic. */
+  get partition(): number
+  /** The offset of this message within its partition. */
+  get offset(): bigint
+  /** The timestamp when the message was produced. */
+  get timestamp(): Date
+  /** The message key used for partitioning. */
+  get key(): string
+  /**
+   * The payload as the raw JSON text read from the wire.
+   *
+   * Borrowed from the wrapped message and copied once into a JavaScript
+   * string; no intermediate Rust buffer is allocated. The typed layer parses
+   * it lazily, so a handler that reads only metadata never pays for a parse.
+   *
+   * @throws Error if the payload is not valid UTF-8, which valid JSON always
+   *   is.
+   */
+  get payload(): string
+}
+
 /**
  * A native client wrapper for the Prosody high-level client.
  * Provides methods for sending messages, subscribing to topics, and managing
@@ -43,7 +82,7 @@ export declare class NativeClient {
    * @param config - The configuration for the client
    * @throws Error if the client creation fails
    */
-  constructor(config: Configuration)
+  static create(config: Configuration): Promise<NativeClient>
   /**
    * Gets the current state of the consumer.
    *
@@ -51,19 +90,37 @@ export declare class NativeClient {
    * @throws Error if the operation fails
    */
   consumerState(): Promise<ConsumerState>
+  /** Builds a read-only view of a published value collection. */
+  publishedValue(subsystem: string, name: string, cacheMs?: number | undefined | null, cacheDisabled?: boolean | undefined | null): Promise<NativePublishedValue>
+  /** Builds a read-only view of a published map collection. */
+  publishedMap(subsystem: string, name: string, cacheMs?: number | undefined | null, cacheDisabled?: boolean | undefined | null): Promise<NativePublishedMap>
+  /** Builds a read-only view of a published deque collection. */
+  publishedDeque(subsystem: string, name: string, cacheMs?: number | undefined | null, cacheDisabled?: boolean | undefined | null): Promise<NativePublishedDeque>
   /**
    * Sends a message to a specified topic.
    *
+   * The payload crosses as its JSON text and is forwarded to Kafka verbatim;
+   * Rust never parses it. The caller supplies the event metadata, read off
+   * the payload object before it was serialized, so the boundary costs no
+   * JSON re-parse.
+   *
    * @param topic - The topic to send the message to
    * @param key - The key of the message
-   * @param payload - The payload of the message (must be JSON-serializable)
+   * @param payload - The payload as JSON text
+   * @param metadata - The event metadata read off the payload object
    * @param otelContext - The OpenTelemetry context for tracing
    * @param maybeAbort - Optional promise that resolves when the operation
    * should be aborted @returns A promise that resolves when the message
    * has been sent @throws Error if the send operation fails or is
    * aborted
    */
-  send(topic: string, key: string, payload: any, otelContext: Record<string, string>, maybeAbort?: Promise<undefined> | undefined | null): Promise<void>
+  send(topic: string, key: string, payload: string, metadata: EventMetadata, otelContext: Record<string, string>, maybeAbort?: Promise<undefined> | undefined | null): Promise<void>
+  /** Sends an excise record to a specified topic. */
+  excise(topic: string, key: string, otelContext: Record<string, string>, maybeAbort?: Promise<undefined> | undefined | null): Promise<void>
+  /** Sends one request and returns one outcome per subsystem. */
+  request(request: NativeRequest, otelContext: Record<string, string>, maybeAbort?: Promise<undefined> | undefined | null): Promise<Array<NativeSubsystemOutcome>>
+  /** Sends one excise request and returns one outcome per subsystem. */
+  requestExcise(request: NativeExciseRequest, otelContext: Record<string, string>, maybeAbort?: Promise<undefined> | undefined | null): Promise<Array<NativeSubsystemOutcome>>
   /**
    * Subscribes to receive messages using the provided event handler.
    *
@@ -71,7 +128,7 @@ export declare class NativeClient {
    * timers @returns A promise that resolves when the subscription is
    * established @throws Error if the subscription fails
    */
-  subscribe(eventHandler: { onMessage: (err: null | Error, args: [NativeContext, Message, Record<string, string>]) => Promise<void>; onTimer: (err: null | Error, args: [NativeContext, Timer, Record<string, string>]) => Promise<void>; isPermanent: (args: [Error]) => boolean }): Promise<void>
+  subscribe(eventHandler: { onMessage: (err: null | Error, args: [NativeContext, Message, Record<string, string>]) => Promise<string>; onExcise: (err: null | Error, args: [NativeContext, ExciseMessage, Record<string, string>]) => Promise<string>; onTimer: (err: null | Error, args: [NativeContext, Timer, Record<string, string>]) => Promise<string>; isPermanent: (args: [Error]) => boolean }): Promise<void>
   /**
    * Gets the number of partitions assigned to the consumer.
    *
@@ -93,6 +150,13 @@ export declare class NativeClient {
    * complete @throws Error if the unsubscribe operation fails
    */
   unsubscribe(): Promise<void>
+  /**
+   * Shuts down the client and all its services.
+   *
+   * @returns A promise that resolves when shutdown is complete
+   * @throws Error if shutdown fails
+   */
+  shutdown(): Promise<void>
   /**
    * Gets the source system identifier configured for the client.
    *
@@ -171,7 +235,7 @@ export declare class NativeContext {
    * @throws Error (permanent) if the name is unregistered or its registered
    *   identity mismatches.
    */
-  valueState(name: string): NativeValueState
+  valueState(name: string): NativeJsonValueState
   /**
    * Vends the state handle for the named JSON map collection.
    *
@@ -184,7 +248,7 @@ export declare class NativeContext {
    * @throws Error (permanent) if the name is unregistered or its registered
    *   identity mismatches.
    */
-  mapState(name: string): NativeMapState
+  mapState(name: string): NativeJsonMapState
   /**
    * Vends the state handle for the named JSON deque collection.
    *
@@ -197,7 +261,7 @@ export declare class NativeContext {
    * @throws Error (permanent) if the name is unregistered or its registered
    *   identity mismatches.
    */
-  dequeState(name: string): NativeDequeState
+  dequeState(name: string): NativeJsonDequeState
   /**
    * Vends the state handle for the named Kafka-message value collection.
    *
@@ -209,7 +273,7 @@ export declare class NativeContext {
    * @throws Error (permanent) if the name is unregistered or its registered
    *   identity mismatches.
    */
-  messageValueState(name: string): NativeValueState
+  messageValueState(name: string): NativeMessageValueState
   /**
    * Vends the state handle for the named Kafka-message map collection.
    *
@@ -221,7 +285,7 @@ export declare class NativeContext {
    * @throws Error (permanent) if the name is unregistered or its registered
    *   identity mismatches.
    */
-  messageMapState(name: string): NativeMapState
+  messageMapState(name: string): NativeMessageMapState
   /**
    * Vends the state handle for the named Kafka-message deque collection.
    *
@@ -233,11 +297,19 @@ export declare class NativeContext {
    * @throws Error (permanent) if the name is unregistered or its registered
    *   identity mismatches.
    */
-  messageDequeState(name: string): NativeDequeState
+  messageDequeState(name: string): NativeMessageDequeState
+}
+
+/** Demand-driven cursor with one element type. */
+export declare class NativeJsonDequeCursor {
+  /** Pulls the next ready chunk. */
+  nextChunk(otelContext: Record<string, string>): Promise<Array<string> | null>
+  /** Closes the cursor. */
+  close(): Promise<void>
 }
 
-/** Erased deque state handle, vended per event. */
-export declare class NativeDequeState {
+/** JSON deque state handle for one event. */
+export declare class NativeJsonDequeState {
   /**
    * The number of live elements.
    *
@@ -263,7 +335,7 @@ export declare class NativeDequeState {
    * @returns The element, or null past the end.
    * @throws Error carrying the category on `cause` if the read fails.
    */
-  get(index: number, otelContext: Record<string, string>): Promise<any | Message | null>
+  get(index: number, otelContext: Record<string, string>): Promise<string | null>
   /**
    * Reads the front endpoint SLOT without a length round trip — exactly
    * `get(0)`.
@@ -276,7 +348,7 @@ export declare class NativeDequeState {
    * @returns The front element, or null when the endpoint slot is empty.
    * @throws Error carrying the category on `cause` if the read fails.
    */
-  peekFront(otelContext: Record<string, string>): Promise<any | Message | null>
+  peekFront(otelContext: Record<string, string>): Promise<string | null>
   /**
    * Reads the back endpoint SLOT without a length round trip — exactly
    * `get(len − 1)`.
@@ -289,31 +361,29 @@ export declare class NativeDequeState {
    * @returns The back element, or null when the endpoint slot is empty.
    * @throws Error carrying the category on `cause` if the read fails.
    */
-  peekBack(otelContext: Record<string, string>): Promise<any | Message | null>
+  peekBack(otelContext: Record<string, string>): Promise<string | null>
   /**
-   * Appends an element at the back.
+   * Appends a JSON document at the back.
    *
    * JSON null is not a storable element and is rejected with a transient
-   * error. An item-shape mismatch is a caller mistake and is likewise
-   * transient (it retries and stays visible, never discarded).
+   * error.
    *
-   * @param item The value (JSON) or message to append.
+   * @param json The document's JSON text.
    * @param otelContext The OpenTelemetry context for tracing.
    * @throws Error carrying the category on `cause` if the write fails.
    */
-  pushBack(item: any, otelContext: Record<string, string>): Promise<void>
+  pushBack(json: string, otelContext: Record<string, string>): Promise<void>
   /**
-   * Prepends an element at the front.
+   * Prepends a JSON document at the front.
    *
    * JSON null is not a storable element and is rejected with a transient
-   * error. An item-shape mismatch is a caller mistake and is likewise
-   * transient (it retries and stays visible, never discarded).
+   * error.
    *
-   * @param item The value (JSON) or message to prepend.
+   * @param json The document's JSON text.
    * @param otelContext The OpenTelemetry context for tracing.
    * @throws Error carrying the category on `cause` if the write fails.
    */
-  pushFront(item: any, otelContext: Record<string, string>): Promise<void>
+  pushFront(json: string, otelContext: Record<string, string>): Promise<void>
   /**
    * Removes and returns the front element.
    *
@@ -321,7 +391,7 @@ export declare class NativeDequeState {
    * @returns The removed front element, or null when empty.
    * @throws Error carrying the category on `cause` if the operation fails.
    */
-  popFront(otelContext: Record<string, string>): Promise<any | Message | null>
+  popFront(otelContext: Record<string, string>): Promise<string | null>
   /**
    * Removes and returns the back element.
    *
@@ -329,7 +399,7 @@ export declare class NativeDequeState {
    * @returns The removed back element, or null when empty.
    * @throws Error carrying the category on `cause` if the operation fails.
    */
-  popBack(otelContext: Record<string, string>): Promise<any | Message | null>
+  popBack(otelContext: Record<string, string>): Promise<string | null>
   /**
    * Removes every element.
    *
@@ -349,24 +419,23 @@ export declare class NativeDequeState {
    * @returns A cursor over the deque elements.
    * @throws Error if the direction token is invalid.
    */
-  scan(direction: string, otelContext: Record<string, string>): NativeStateCursor
-  /**
-   * Durably commits the buffered operations mid-handler.
-   *
-   * @param otelContext The OpenTelemetry context for tracing.
-   * @throws Error carrying the category on `cause` if the commit fails.
-   */
+  scan(direction: string, otelContext: Record<string, string>): NativeJsonDequeCursor
+  /** Durably commits the buffered operations. */
   commit(otelContext: Record<string, string>): Promise<void>
-  /**
-   * Discards the buffered uncommitted operations.
-   *
-   * @param otelContext The OpenTelemetry context for tracing.
-   */
+  /** Discards the buffered operations. */
   rollback(otelContext: Record<string, string>): Promise<void>
 }
 
-/** Erased ordered-map state handle, keyed by `String`, vended per event. */
-export declare class NativeMapState {
+/** Demand-driven cursor with one element type. */
+export declare class NativeJsonMapCursor {
+  /** Pulls the next ready chunk. */
+  nextChunk(otelContext: Record<string, string>): Promise<Array<[string, string]> | null>
+  /** Closes the cursor. */
+  close(): Promise<void>
+}
+
+/** JSON ordered-map state handle for one event. */
+export declare class NativeJsonMapState {
   /**
    * Reads the value for `key`.
    *
@@ -375,7 +444,7 @@ export declare class NativeMapState {
    * @returns The value, or null when the key is absent.
    * @throws Error carrying the category on `cause` if the read fails.
    */
-  get(key: string, otelContext: Record<string, string>): Promise<any | Message | null>
+  get(key: string, otelContext: Record<string, string>): Promise<string | null>
   /**
    * Reads several keys in a single call.
    *
@@ -390,7 +459,7 @@ export declare class NativeMapState {
    * @returns One result per input key; null for a key that is absent.
    * @throws Error carrying the category on `cause` if the read fails.
    */
-  getMany(keys: Array<string>, otelContext: Record<string, string>): Promise<Array<any | Message | undefined | null>>
+  getMany(keys: Array<string>, otelContext: Record<string, string>): Promise<Array<string | undefined | null>>
   /**
    * Reports whether a stored cell exists for `key`.
    *
@@ -408,18 +477,17 @@ export declare class NativeMapState {
    */
   contains(key: string, otelContext: Record<string, string>): Promise<boolean>
   /**
-   * Inserts or overwrites `key`.
+   * Inserts or overwrites `key` with a JSON document.
    *
    * JSON null is rejected with a transient error naming `delete` as the way
-   * to remove an entry. An item-shape mismatch is a caller mistake and is
-   * likewise transient (it retries and stays visible, never discarded).
+   * to remove an entry.
    *
    * @param key The map key.
-   * @param item The value (JSON) or message to store.
+   * @param json The document's JSON text.
    * @param otelContext The OpenTelemetry context for tracing.
    * @throws Error carrying the category on `cause` if the write fails.
    */
-  set(key: string, item: any, otelContext: Record<string, string>): Promise<void>
+  set(key: string, json: string, otelContext: Record<string, string>): Promise<void>
   /**
    * Removes `key`.
    *
@@ -447,7 +515,7 @@ export declare class NativeMapState {
    * @returns A cursor over the map entries.
    * @throws Error if the direction token is invalid.
    */
-  scan(direction: string, otelContext: Record<string, string>): NativeStateCursor
+  scan(direction: string, otelContext: Record<string, string>): NativeJsonMapCursor
   /**
    * Opens a demand-driven cursor over the live KEYS in key order.
    *
@@ -462,63 +530,15 @@ export declare class NativeMapState {
    * @returns A cursor over the map keys.
    * @throws Error if the direction token is invalid.
    */
-  keys(direction: string, otelContext: Record<string, string>): NativeStateCursor
-  /**
-   * Durably commits the buffered operations mid-handler.
-   *
-   * @param otelContext The OpenTelemetry context for tracing.
-   * @throws Error carrying the category on `cause` if the commit fails.
-   */
+  keys(direction: string, otelContext: Record<string, string>): NativeMapKeyCursor
+  /** Durably commits the buffered operations. */
   commit(otelContext: Record<string, string>): Promise<void>
-  /**
-   * Discards the buffered uncommitted operations.
-   *
-   * @param otelContext The OpenTelemetry context for tracing.
-   */
+  /** Discards the buffered operations. */
   rollback(otelContext: Record<string, string>): Promise<void>
 }
 
-/**
- * Demand-driven scan cursor over a map or deque collection.
- *
- * Pulling is lazy: each `next_chunk()` restores the JavaScript context without
- * creating a binding span, awaits one stream item, and asks core to drain only
- * the immediately-ready tail. Chunking,
- * exhaustion, error ordering, serialization, close-idempotence, and
- * use-after-close behavior are core-owned; this layer only transports.
- */
-export declare class NativeStateCursor {
-  /**
-   * Pulls the next immediately-ready chunk of scanned items.
-   *
-   * Awaits the first item, then drains up to 255 more items only while they
-   * are immediately ready. This amortizes N-API overhead without waiting to
-   * fill a chunk.
-   *
-   * @param otelContext The OpenTelemetry context for tracing.
-   * @returns The next non-empty vector of items, or null when exhausted.
-   * @throws Error carrying the category on `cause` if the pull fails or the
-   *   cursor was closed.
-   */
-  nextChunk(otelContext: Record<string, string>): Promise<Array<any | [string, any] | Message | [string, Message]> | null>
-  /**
-   * Closes the cursor, releasing the underlying stream.
-   *
-   * Idempotent; a subsequent `next_chunk()` errors. No span — pure teardown.
-   *
-   * @returns A promise that resolves when the cursor is closed.
-   */
-  close(): Promise<void>
-}
-
-/**
- * Erased single-value state handle, vended per event.
- *
- * Wraps the boxed erased value handle plus the propagator used to open each
- * operation's span. Values cross as JSON; message collections cross as the
- * `Message` object.
- */
-export declare class NativeValueState {
+/** JSON single-value state handle for one event. */
+export declare class NativeJsonValueState {
   /**
    * Reads the current value.
    *
@@ -526,20 +546,18 @@ export declare class NativeValueState {
    * @returns The current value, or null when absent/cleared.
    * @throws Error carrying the category on `cause` if the read fails.
    */
-  get(otelContext: Record<string, string>): Promise<any | Message | null>
+  get(otelContext: Record<string, string>): Promise<string | null>
   /**
-   * Buffers a write of the value.
+   * Buffers a write of a JSON document.
    *
    * JSON null is rejected with a transient error naming `clear` as the way
-   * to delete. A message-shaped payload cannot be stored in a JSON
-   * collection (and vice versa); such a mismatch is a caller mistake and is
-   * likewise transient (it retries and stays visible, never discarded).
+   * to delete.
    *
-   * @param item The value (JSON) or message to write.
+   * @param json The document's JSON text.
    * @param otelContext The OpenTelemetry context for tracing.
    * @throws Error carrying the category on `cause` if the write fails.
    */
-  set(item: any, otelContext: Record<string, string>): Promise<void>
+  set(json: string, otelContext: Record<string, string>): Promise<void>
   /**
    * Buffers a clear of the value.
    *
@@ -547,23 +565,140 @@ export declare class NativeValueState {
    * @throws Error carrying the category on `cause` if the clear fails.
    */
   clear(otelContext: Record<string, string>): Promise<void>
-  /**
-   * Durably commits the buffered operations mid-handler.
-   *
-   * @param otelContext The OpenTelemetry context for tracing.
-   * @throws Error carrying the category on `cause` if the commit fails.
-   */
+  /** Durably commits the buffered operations. */
   commit(otelContext: Record<string, string>): Promise<void>
-  /**
-   * Discards the buffered uncommitted operations.
-   *
-   * Infallible: rolling back a terminated session is a no-op.
-   *
-   * @param otelContext The OpenTelemetry context for tracing.
-   */
+  /** Discards the buffered operations. */
   rollback(otelContext: Record<string, string>): Promise<void>
 }
 
+/** Demand-driven cursor with one element type. */
+export declare class NativeMapKeyCursor {
+  /** Pulls the next ready chunk. */
+  nextChunk(otelContext: Record<string, string>): Promise<Array<string> | null>
+  /** Closes the cursor. */
+  close(): Promise<void>
+}
+
+/** Demand-driven cursor with one element type. */
+export declare class NativeMessageDequeCursor {
+  /** Pulls the next ready chunk. */
+  nextChunk(otelContext: Record<string, string>): Promise<Array<Message> | null>
+  /** Closes the cursor. */
+  close(): Promise<void>
+}
+
+/** Kafka-message deque state handle for one event. */
+export declare class NativeMessageDequeState {
+  /** Returns the number of live elements. */
+  len(otelContext: Record<string, string>): Promise<number>
+  /** Reports whether the deque has no live elements. */
+  isEmpty(otelContext: Record<string, string>): Promise<boolean>
+  /** Reads one element by its position from the front. */
+  get(index: number, otelContext: Record<string, string>): Promise<Message | null>
+  /** Reads the front endpoint. */
+  peekFront(otelContext: Record<string, string>): Promise<Message | null>
+  /** Reads the back endpoint. */
+  peekBack(otelContext: Record<string, string>): Promise<Message | null>
+  /** Appends a Kafka message. */
+  pushBack(message: Message, otelContext: Record<string, string>): Promise<void>
+  /** Prepends a Kafka message. */
+  pushFront(message: Message, otelContext: Record<string, string>): Promise<void>
+  /** Removes and returns the front element. */
+  popFront(otelContext: Record<string, string>): Promise<Message | null>
+  /** Removes and returns the back element. */
+  popBack(otelContext: Record<string, string>): Promise<Message | null>
+  /** Removes every element. */
+  clear(otelContext: Record<string, string>): Promise<void>
+  /** Opens a cursor over the live elements. */
+  scan(direction: string, otelContext: Record<string, string>): NativeMessageDequeCursor
+  /** Durably commits the buffered operations. */
+  commit(otelContext: Record<string, string>): Promise<void>
+  /** Discards the buffered operations. */
+  rollback(otelContext: Record<string, string>): Promise<void>
+}
+
+/** Demand-driven cursor with one element type. */
+export declare class NativeMessageMapCursor {
+  /** Pulls the next ready chunk. */
+  nextChunk(otelContext: Record<string, string>): Promise<Array<[string, Message]> | null>
+  /** Closes the cursor. */
+  close(): Promise<void>
+}
+
+/** Kafka-message ordered-map state handle for one event. */
+export declare class NativeMessageMapState {
+  /** Reads the value for `key`. */
+  get(key: string, otelContext: Record<string, string>): Promise<Message | null>
+  /** Reads several keys in one operation. */
+  getMany(keys: Array<string>, otelContext: Record<string, string>): Promise<Array<Message | undefined | null>>
+  /** Reports whether `key` has a stored cell. */
+  contains(key: string, otelContext: Record<string, string>): Promise<boolean>
+  /** Inserts or overwrites `key` with a Kafka message. */
+  set(key: string, message: Message, otelContext: Record<string, string>): Promise<void>
+  /** Removes `key`. */
+  remove(key: string, otelContext: Record<string, string>): Promise<void>
+  /** Removes every entry. */
+  clear(otelContext: Record<string, string>): Promise<void>
+  /** Opens a cursor over entries in key order. */
+  scan(direction: string, otelContext: Record<string, string>): NativeMessageMapCursor
+  /** Opens a cursor over keys in key order. */
+  keys(direction: string, otelContext: Record<string, string>): NativeMapKeyCursor
+  /** Durably commits the buffered operations. */
+  commit(otelContext: Record<string, string>): Promise<void>
+  /** Discards the buffered operations. */
+  rollback(otelContext: Record<string, string>): Promise<void>
+}
+
+/** Kafka-message single-value state handle for one event. */
+export declare class NativeMessageValueState {
+  /** Reads the current value. */
+  get(otelContext: Record<string, string>): Promise<Message | null>
+  /** Buffers a write of a Kafka message. */
+  set(message: Message, otelContext: Record<string, string>): Promise<void>
+  /** Buffers a clear of the value. */
+  clear(otelContext: Record<string, string>): Promise<void>
+  /** Durably commits the buffered operations. */
+  commit(otelContext: Record<string, string>): Promise<void>
+  /** Discards the buffered operations. */
+  rollback(otelContext: Record<string, string>): Promise<void>
+}
+
+/** A read-only published deque collection. */
+export declare class NativePublishedDeque {
+  /** Reads one front-relative element. */
+  get(key: string, index: number, otelContext: Record<string, string>): Promise<string | null>
+  /** Returns the committed deque length. */
+  length(key: string, otelContext: Record<string, string>): Promise<number>
+  /** Reports whether the committed deque is empty. */
+  isEmpty(key: string, otelContext: Record<string, string>): Promise<boolean>
+  /** Reads the committed front element. */
+  peekFront(key: string, otelContext: Record<string, string>): Promise<string | null>
+  /** Reads the committed back element. */
+  peekBack(key: string, otelContext: Record<string, string>): Promise<string | null>
+  /** Opens an ordered element cursor. */
+  scan(key: string, direction: string, otelContext: Record<string, string>): Promise<NativeJsonDequeCursor>
+}
+
+/** A read-only published map collection. */
+export declare class NativePublishedMap {
+  /** Reads one committed map entry. */
+  get(key: string, mapKey: string, otelContext: Record<string, string>): Promise<string | null>
+  /** Reads entries aligned with the supplied map keys. */
+  getMany(key: string, mapKeys: Array<string>, otelContext: Record<string, string>): Promise<Array<string | undefined | null>>
+  /** Reports whether a committed map entry exists. */
+  contains(key: string, mapKey: string, otelContext: Record<string, string>): Promise<boolean>
+  /** Opens an ordered entry cursor. */
+  scan(key: string, direction: string, otelContext: Record<string, string>): Promise<NativeJsonMapCursor>
+  /** Opens an ordered key cursor. */
+  keys(key: string, direction: string, otelContext: Record<string, string>): Promise<NativeMapKeyCursor>
+}
+
+/** A read-only published value collection. */
+export declare class NativePublishedValue {
+  /** Reads the committed value for a partition key. */
+  get(key: string, otelContext: Record<string, string>): Promise<string | null>
+}
+
 /** Configuration options for the Prosody client. */
 export interface Configuration {
   /** Kafka servers for initial connection. */
@@ -635,7 +770,7 @@ export interface Configuration {
   slabSizeMs?: number
   /** Cassandra contact nodes (hostnames or IPs). */
   cassandraNodes?: string | Array<string>
-  /** Cassandra keyspace to use for storing timer data. */
+  /** Cassandra keyspace used for persistent Prosody data. */
   cassandraKeyspace?: string
   /** Preferred Cassandra datacenter for query routing. */
   cassandraDatacenter?: string
@@ -646,8 +781,8 @@ export interface Configuration {
   /** Password for authenticating with Cassandra. */
   cassandraPassword?: string
   /**
-   * Retention period for failed/unprocessed timer data in Cassandra in
-   * seconds.
+   * Retention period for persistent timer and deferral data in Cassandra,
+   * in seconds.
    */
   cassandraRetentionSeconds?: number
   /**
@@ -709,29 +844,33 @@ export interface Configuration {
    */
   deferMaxDelayMs?: number
   /**
-   * Failure rate threshold for enabling deferral (0.0 to 1.0).
+   * Failure rate threshold for disabling deferral (0.0 to 1.0).
    * When exceeded within the failure window, deferral is disabled.
    */
   deferFailureThreshold?: number
   /** Sliding window duration (in milliseconds) for failure rate tracking. */
   deferFailureWindowMs?: number
-  /**
-   * Cache size for the deferred-retry message loader.
-   * Controls capacity for the loader cache.
-   */
-  deferCacheSize?: number
   /**
    * Maximum deferred store cache entries per Cassandra defer store.
    * Env: `PROSODY_DEFER_STORE_CACHE_SIZE`. Default: 8192.
    */
   deferStoreCacheSize?: number
-  /** Timeout for Kafka seek operations in milliseconds. */
-  deferSeekTimeoutMs?: number
+  /**
+   * Capacity of the shared Kafka message loader cache.
+   * Env: `PROSODY_LOADER_CACHE_SIZE`. Default: 1024.
+   */
+  loaderCacheSize?: number
+  /**
+   * Timeout for Kafka loader seek operations in milliseconds.
+   * Env: `PROSODY_LOADER_SEEK_TIMEOUT`. Default: 30 seconds.
+   */
+  loaderSeekTimeoutMs?: number
   /**
    * Messages to read sequentially before seeking.
    * If next offset is within this threshold, reads rather than seeks.
+   * Env: `PROSODY_LOADER_DISCARD_THRESHOLD`. Default: 100.
    */
-  deferDiscardThreshold?: number
+  loaderDiscardThreshold?: number
   /**
    * Fixed timeout duration for handler execution in milliseconds.
    * If unset, defaults to 80% of stall threshold.
@@ -774,11 +913,22 @@ export interface Configuration {
    */
   stateCacheDir?: string
   /**
-   * Capacity of the in-memory keyed-state cache, in bytes. Falls back to
-   * `PROSODY_STATE_CACHE_SIZE_BYTES`,
-   * then to the storage-engine default. Must be a positive safe integer.
+   * Capacity of the owning keyed-state cache. Accepts a human-readable size.
+   * Uses `PROSODY_STATE_OWNED_CACHE_SIZE` when omitted. Otherwise, the
+   * storage engine selects its default.
    */
-  stateCacheSizeBytes?: number
+  stateOwnedCacheSize?: string
+  /**
+   * Capacity of the published-state read-through cache. Uses
+   * `PROSODY_STATE_READ_CACHE_SIZE` when omitted. It then uses the owning
+   * cache size when set, or 1 MiB when both sizes are unset.
+   */
+  stateReadCacheSize?: string
+  /**
+   * Default cache policy for published-state reads. Uses
+   * `PROSODY_STATE_READ_CACHE_TTL` when omitted, then 5 seconds.
+   */
+  stateReadCache?: ReadCacheConfiguration
   /**
    * Delay in whole seconds between staging a provisional cell and the
    * keyed-state recovery sweep. Every registered TTL must strictly exceed
@@ -788,21 +938,75 @@ export interface Configuration {
    * non-finite values are rejected).
    */
   stateRecoveryDelaySeconds?: number
+  /**
+   * Subsystem under which published JSON collections are advertised.
+   * Uses `PROSODY_SUBSYSTEM` when omitted. Published collections require it.
+   */
+  subsystem?: string
+  /**
+   * Socket address for the peer gRPC listener. Uses
+   * `PROSODY_PEER_BIND_ADDRESS` when omitted.
+   */
+  peerBindAddress?: string
+  /**
+   * gRPC connect URI that remote peers use. Uses
+   * `PROSODY_PEER_ADVERTISED_CONNECT` when omitted.
+   */
+  peerAdvertisedConnect?: string
+  /**
+   * Network name used to select direct peer routes. Uses
+   * `PROSODY_PEER_NETWORK_NAME` when omitted.
+   */
+  peerNetworkName?: string
+  /**
+   * Maximum channels and peer records in each peer cache. Uses
+   * `PROSODY_PEER_CACHE_CAPACITY` when omitted.
+   */
+  peerCacheCapacity?: number
+  /**
+   * Peer registration lease duration in seconds. Uses
+   * `PROSODY_PEER_REGISTRATION_TTL` when omitted.
+   */
+  peerRegistrationTtlSeconds?: number
 }
 
-/**
- * Current state of the consumer.
- * Represents the lifecycle stages of a Prosody consumer.
- */
-export type ConsumerState = /** The consumer is not yet configured */
+/** Current consumer state. */
+export type ConsumerState = /** The client is shut down. */
+'Shutdown'|
+/** The consumer is not configured. */
 'Unconfigured'|
-/** The consumer is configured but not running */
+/** The consumer is configured but not active. */
 'Configured'|
-/** The consumer is actively running */
+/** The consumer is active. */
 'Running'|
-/** The consumer configuration failed */
+/** The consumer configuration failed. */
 'ConfigurationFailed';
 
+/**
+ * Event metadata read off a payload before it was serialized.
+ *
+ * It lets the send path forward the payload without another parse.
+ */
+export interface EventMetadata {
+  /** The payload's `id` field. */
+  eventId?: string
+  /** The payload's `type` field. */
+  eventType?: string
+}
+
+/** Type alias for excise handler arguments. */
+export type ExciseHandlerArgs =
+  [NativeContext, ExciseMessage, Record<string, string>]
+
+/**
+ * Exports all pending telemetry data.
+ *
+ * # Errors
+ *
+ * Returns an error if an exporter cannot flush its pending data.
+ */
+export declare function flushTelemetry(): void
+
 /**
  * Initializes the logging system for the Prosody client.
  *
@@ -841,27 +1045,6 @@ export interface Logger {
  */
 export declare function loggerIsSet(): boolean
 
-/**
- * Represents a message consumed from a Kafka topic.
- *
- * This object contains all the relevant information about a Kafka message,
- * including its topic, partition, offset, timestamp, key, and payload.
- */
-export interface Message {
-  /** The name of the topic from which the message was consumed. */
-  topic: string
-  /** The partition number from which the message was consumed. */
-  partition: number
-  /** The message offset within the partition. */
-  offset: bigint
-  /** The timestamp when the message was created or sent to Kafka. */
-  timestamp: Date
-  /** The message key. */
-  key: string
-  /** The message payload as a JSON-serializable value. */
-  payload: any
-}
-
 /** Type alias for message handler arguments. */
 export type MessageHandlerArgs =
   [NativeContext, Message, Record<string, string>]
@@ -877,6 +1060,18 @@ export type Mode = /** Pipeline mode for standard processing. */
  */
 'BestEffort';
 
+/** One excise subsystem request. */
+export interface NativeExciseRequest {
+  /** Kafka topic. */
+  topic: string
+  /** Message key. */
+  key: string
+  /** Subsystems that must respond. */
+  subsystems: Array<string>
+  /** Response deadline in milliseconds. */
+  timeoutMs: number
+}
+
 /**
  * Represents a native handler for processing messages and timers.
  *
@@ -895,7 +1090,9 @@ export interface NativeHandler {
    *
    * Note: Error parameter is automatically added by CalleeHandled=true
    */
-  onMessage: (arg: MessageHandlerArgs) => Promise<undefined>
+  onMessage: (arg: MessageHandlerArgs) => Promise<string>
+  /** A function to call when an excise record arrives. */
+  onExcise: (arg: ExciseHandlerArgs) => Promise<string>
   /**
    * A function to be called when a timer fires.
    *
@@ -907,7 +1104,7 @@ export interface NativeHandler {
    *
    * Note: Error parameter is automatically added by CalleeHandled=true
    */
-  onTimer: (arg: TimerHandlerArgs) => Promise<undefined>
+  onTimer: (arg: TimerHandlerArgs) => Promise<string>
   /**
    * Function that determines whether an error is permanent.
    *
@@ -918,6 +1115,52 @@ export interface NativeHandler {
   isPermanent: (arg: IsPermanentArgs) => boolean
 }
 
+/** One subsystem request. */
+export interface NativeRequest {
+  /** Kafka topic. */
+  topic: string
+  /** Message key. */
+  key: string
+  /** JSON payload text. */
+  payload: string
+  /** Event metadata read before serialization. */
+  metadata: EventMetadata
+  /** Subsystems that must respond. */
+  subsystems: Array<string>
+  /** Response deadline in milliseconds. */
+  timeoutMs: number
+}
+
+/** One response failure. */
+export interface NativeResponseError {
+  /** Failure discriminator. */
+  kind: NativeResponseErrorKind
+  /** Failure text. */
+  message: string
+}
+
+/** One response failure kind. */
+export type NativeResponseErrorKind =  'handler'|
+'timeout'|
+'formatMismatch'|
+'malformedResponse';
+
+/** One subsystem and its outcome. */
+export interface NativeSubsystemOutcome {
+  /** Canonical subsystem name. */
+  subsystem: string
+  /** Encoded response or failure. */
+  outcome: string | NativeResponseError
+}
+
+/** Default cache policy for published-state reads. */
+export interface ReadCacheConfiguration {
+  /** Cache duration in milliseconds. */
+  ttlMs?: number
+  /** Read durable storage on every operation. */
+  disabled?: boolean
+}
+
 /**
  * Sets a new JavaScript logger for the Prosody client.
  *
@@ -944,11 +1187,22 @@ export declare function setLogger(logger: Logger): void
  */
 export declare function setLoggerIfUnset(logger: Logger): boolean
 
+/**
+ * Stops the global telemetry providers after they export pending data.
+ *
+ * Call this function only when the Node.js process no longer needs telemetry.
+ *
+ * # Errors
+ *
+ * Returns an error if a provider cannot stop.
+ */
+export declare function shutdownTelemetry(): void
+
 /** Declares one keyed-state collection to register before subscribe. */
 export interface StateCollectionConfig {
   /**
-   * The collection name. Must be non-empty and unique within the client's
-   * definition set.
+   * The collection name. Prosody requires it to be non-empty and unique
+   * within the definition set.
    */
   name: string
   /** The collection kind: `"value"`, `"map"`, or `"deque"`. */
@@ -969,11 +1223,13 @@ export interface StateCollectionConfig {
    * once). Defaults to transactional.
    */
   readUncommitted?: boolean
+  /** Whether other consumer groups may read this collection. */
+  published?: boolean
   /**
    * Optional map-only keyset bound (`0..=4096`; default 128 core-side; `0`
-   * disables ordered-scan tracking). Must be a whole number in that range
-   * (fractional, negative, and non-finite values are rejected). Invalid on
-   * value or deque collections.
+   * disables ordered-scan tracking). The binding rejects values that cannot
+   * map to an unsigned integer. Prosody enforces the semantic ceiling.
+   * Invalid on value or deque collections.
    */
   keysetLimit?: number
   /**