@prosody-events/prosody 0.3.1 → 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: [Context, Message, Record<string, string>]) => Promise<void>; onTimer: (err: null | Error, args: [Context, 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.
    *
@@ -159,6 +223,480 @@ export declare class NativeContext {
    * @throws Error if retrieval fails.
    */
   scheduled(otelContext: Record<string, string>): Promise<Array<Date>>
+  /**
+   * Vends the state handle for the named JSON value collection.
+   *
+   * Vending verifies the collection's registration (core-side); no span is
+   * opened here — vended handles outlive the call, and every operation opens
+   * its own span.
+   *
+   * @param name The registered collection name.
+   * @returns The value-state handle for this event's transaction.
+   * @throws Error (permanent) if the name is unregistered or its registered
+   *   identity mismatches.
+   */
+  valueState(name: string): NativeJsonValueState
+  /**
+   * Vends the state handle for the named JSON map collection.
+   *
+   * Vending verifies the collection's registration (core-side); no span is
+   * opened here — vended handles outlive the call, and every operation opens
+   * its own span.
+   *
+   * @param name The registered collection name.
+   * @returns The map-state handle for this event's transaction.
+   * @throws Error (permanent) if the name is unregistered or its registered
+   *   identity mismatches.
+   */
+  mapState(name: string): NativeJsonMapState
+  /**
+   * Vends the state handle for the named JSON deque collection.
+   *
+   * Vending verifies the collection's registration (core-side); no span is
+   * opened here — vended handles outlive the call, and every operation opens
+   * its own span.
+   *
+   * @param name The registered collection name.
+   * @returns The deque-state handle for this event's transaction.
+   * @throws Error (permanent) if the name is unregistered or its registered
+   *   identity mismatches.
+   */
+  dequeState(name: string): NativeJsonDequeState
+  /**
+   * Vends the state handle for the named Kafka-message value collection.
+   *
+   * Items are the full `Message` the handler received, loader-resolved on
+   * read. Vending verifies registration (core-side); no span is opened here.
+   *
+   * @param name The registered collection name.
+   * @returns The message value-state handle for this event's transaction.
+   * @throws Error (permanent) if the name is unregistered or its registered
+   *   identity mismatches.
+   */
+  messageValueState(name: string): NativeMessageValueState
+  /**
+   * Vends the state handle for the named Kafka-message map collection.
+   *
+   * Items are the full `Message` the handler received, loader-resolved on
+   * read. Vending verifies registration (core-side); no span is opened here.
+   *
+   * @param name The registered collection name.
+   * @returns The message map-state handle for this event's transaction.
+   * @throws Error (permanent) if the name is unregistered or its registered
+   *   identity mismatches.
+   */
+  messageMapState(name: string): NativeMessageMapState
+  /**
+   * Vends the state handle for the named Kafka-message deque collection.
+   *
+   * Items are the full `Message` the handler received, loader-resolved on
+   * read. Vending verifies registration (core-side); no span is opened here.
+   *
+   * @param name The registered collection name.
+   * @returns The message deque-state handle for this event's transaction.
+   * @throws Error (permanent) if the name is unregistered or its registered
+   *   identity mismatches.
+   */
+  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>
+}
+
+/** JSON deque state handle for one event. */
+export declare class NativeJsonDequeState {
+  /**
+   * The number of live elements.
+   *
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @returns The element count.
+   * @throws Error carrying the category on `cause` if the read fails, or if
+   *   the count exceeds the `u32` range.
+   */
+  len(otelContext: Record<string, string>): Promise<number>
+  /**
+   * Whether the deque holds no live elements.
+   *
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @returns True when the deque is empty.
+   * @throws Error carrying the category on `cause` if the read fails.
+   */
+  isEmpty(otelContext: Record<string, string>): Promise<boolean>
+  /**
+   * Reads the element at front-relative position `index`.
+   *
+   * @param index The zero-based position from the front.
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @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<string | null>
+  /**
+   * Reads the front endpoint SLOT without a length round trip — exactly
+   * `get(0)`.
+   *
+   * Decodes and resolves the returned element (unlike eviction). An empty
+   * deque, or a front endpoint slot expired under a TTL, yields null even
+   * when live interior elements exist — a peek never searches inward.
+   *
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @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<string | null>
+  /**
+   * Reads the back endpoint SLOT without a length round trip — exactly
+   * `get(len − 1)`.
+   *
+   * Decodes and resolves the returned element (unlike eviction). An empty
+   * deque, or a back endpoint slot expired under a TTL, yields null even
+   * when live interior elements exist — a peek never searches inward.
+   *
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @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<string | null>
+  /**
+   * Appends a JSON document at the back.
+   *
+   * JSON null is not a storable element and is rejected with a transient
+   * error.
+   *
+   * @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(json: string, otelContext: Record<string, string>): Promise<void>
+  /**
+   * Prepends a JSON document at the front.
+   *
+   * JSON null is not a storable element and is rejected with a transient
+   * error.
+   *
+   * @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(json: string, otelContext: Record<string, string>): Promise<void>
+  /**
+   * Removes and returns the front element.
+   *
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @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<string | null>
+  /**
+   * Removes and returns the back element.
+   *
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @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<string | null>
+  /**
+   * Removes every element.
+   *
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @throws Error carrying the category on `cause` if the clear fails.
+   */
+  clear(otelContext: Record<string, string>): Promise<void>
+  /**
+   * Opens a demand-driven cursor over the live elements in index order.
+   *
+   * Synchronous — it performs no I/O. The extracted JavaScript context is
+   * active while core constructs its semantic stream span; chunk pulls do
+   * not create binding spans.
+   *
+   * @param direction The scan direction (`"forward"` or `"backward"`).
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @returns A cursor over the deque elements.
+   * @throws Error if the direction token is invalid.
+   */
+  scan(direction: string, otelContext: Record<string, string>): NativeJsonDequeCursor
+  /** 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 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`.
+   *
+   * @param key The map key.
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @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<string | null>
+  /**
+   * Reads several keys in a single call.
+   *
+   * Returns one entry per key, in the same order requested: the entry at
+   * index `i` is the value for `keys[i]`. A key that isn't there reads as
+   * null, and a key listed more than once is answered at each of its spots.
+   * The whole read happens as one step, so no other change to this event's
+   * state can slip in partway through.
+   *
+   * @param keys The keys to read, in order.
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @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<string | undefined | null>>
+  /**
+   * Reports whether a stored cell exists for `key`.
+   *
+   * Reads the event's dirty overlay (read-your-writes) and answers presence
+   * WITHOUT decoding the value or running the resolver — a message-backed
+   * map answers with zero Kafka fetches and can report `true` for a
+   * message that can no longer be fetched. This is NOT "no I/O": a cache
+   * miss can still reach Cassandra, so it is async and fallible exactly
+   * like `get`.
+   *
+   * @param key The map key.
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @returns True when a stored cell exists for `key`.
+   * @throws Error carrying the category on `cause` if the read fails.
+   */
+  contains(key: string, otelContext: Record<string, string>): Promise<boolean>
+  /**
+   * 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.
+   *
+   * @param key The map key.
+   * @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, json: string, otelContext: Record<string, string>): Promise<void>
+  /**
+   * Removes `key`.
+   *
+   * @param key The map key.
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @throws Error carrying the category on `cause` if the removal fails.
+   */
+  remove(key: string, otelContext: Record<string, string>): Promise<void>
+  /**
+   * Removes every entry.
+   *
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @throws Error carrying the category on `cause` if the clear fails.
+   */
+  clear(otelContext: Record<string, string>): Promise<void>
+  /**
+   * Opens a demand-driven cursor over the live entries in key order.
+   *
+   * Synchronous — it performs no I/O. The extracted JavaScript context is
+   * active while core constructs its semantic stream span; chunk pulls do
+   * not create binding spans. Entries are yielded as `(key, value)` pairs.
+   *
+   * @param direction The scan direction (`"forward"` or `"backward"`).
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @returns A cursor over the map entries.
+   * @throws Error if the direction token is invalid.
+   */
+  scan(direction: string, otelContext: Record<string, string>): NativeJsonMapCursor
+  /**
+   * Opens a demand-driven cursor over the live KEYS in key order.
+   *
+   * Skips the value codec and the resolver (no value decode, no Kafka
+   * fetch), so a message-backed map enumerates keys with zero Kafka
+   * fetches — but it still reads presence, so it is not zero-I/O.
+   * Synchronous like `scan`: the extracted JavaScript context is active
+   * while core constructs its semantic stream span. Yields bare keys.
+   *
+   * @param direction The scan direction (`"forward"` or `"backward"`).
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @returns A cursor over the map keys.
+   * @throws Error if the direction token is invalid.
+   */
+  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>
+}
+
+/** JSON single-value state handle for one event. */
+export declare class NativeJsonValueState {
+  /**
+   * Reads the current value.
+   *
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @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<string | null>
+  /**
+   * Buffers a write of a JSON document.
+   *
+   * JSON null is rejected with a transient error naming `clear` as the way
+   * to delete.
+   *
+   * @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(json: string, otelContext: Record<string, string>): Promise<void>
+  /**
+   * Buffers a clear of the value.
+   *
+   * @param otelContext The OpenTelemetry context for tracing.
+   * @throws Error carrying the category on `cause` if the clear fails.
+   */
+  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>
+}
+
+/** 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. */
@@ -173,7 +711,7 @@ export interface Configuration {
   groupId?: string
   /**
    * Global shared cache capacity across all partitions for deduplicating
-   * messages. Set to 0 to disable deduplication entirely.
+   * messages. Must be greater than 0.
    */
   idempotenceCacheSize?: number
   /**
@@ -232,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
@@ -243,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
   /**
@@ -306,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 defer middleware.
-   * Controls capacity for store cache and 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.
@@ -354,21 +896,117 @@ export interface Configuration {
    * or `"follows_from"`. Default: `"follows_from"`.
    */
   timerSpans?: string
+  /**
+   * Keyed-state collections to register before subscribe.
+   *
+   * Each entry declares one collection by name, kind, and payload. Duplicate
+   * names within this set are rejected.
+   */
+  stateCollections?: Array<StateCollectionConfig>
+  /**
+   * Disk workspace for the local keyed-state cache.
+   *
+   * Each live client needs its own directory because it is locked
+   * exclusively. Falls back to the `PROSODY_STATE_CACHE_DIR` environment
+   * variable, then a per-client temporary directory. Must not be an
+   * empty string when set.
+   */
+  stateCacheDir?: string
+  /**
+   * 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.
+   */
+  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
+   * this. Falls back to the `PROSODY_STATE_RECOVERY_DELAY` environment
+   * variable (a duration string such as `30s`), then to 30 seconds. Must be
+   * a whole number of seconds >= 1 when set (fractional, negative, and
+   * 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.
  *
@@ -407,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>]
@@ -443,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.
  *
@@ -461,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.
    *
@@ -473,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.
    *
@@ -484,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.
  *
@@ -510,6 +1187,61 @@ 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. Prosody requires it to be non-empty and unique
+   * within the definition set.
+   */
+  name: string
+  /** The collection kind: `"value"`, `"map"`, or `"deque"`. */
+  kind: string
+  /**
+   * The item payload: `"json"` (JSON values) or `"message"` (the full Kafka
+   * message the handler received).
+   */
+  payload: string
+  /**
+   * Optional per-write TTL in whole seconds. Must be a whole number >= 1
+   * (fractional, negative, and non-finite values are rejected) and must
+   * exceed the recovery delay (the latter checked at consumer build).
+   */
+  ttlSeconds?: number
+  /**
+   * Optional opt-out of transactional staging (read-uncommitted, at-least
+   * 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). The binding rejects values that cannot
+   * map to an unsigned integer. Prosody enforces the semantic ceiling.
+   * Invalid on value or deque collections.
+   */
+  keysetLimit?: number
+  /**
+   * Optional deque-only capacity (bounded backlog). Must be a whole number
+   * >= 1 (fractional, zero, negative, and non-finite values are rejected).
+   * Runtime configuration only — not persisted, not part of collection
+   * identity, and freely changeable across deploys; enforced lazily on push.
+   * Invalid on value or map collections.
+   */
+  capacity?: number
+}
+
 /**
  * Represents a timer event.
  *