@push.rocks/smartrust 2.4.0 → 2.5.1

package/dist_ts/classes.rustbridgerequesterror.js

@@ -12,6 +12,12 @@ export class RustBridgeRequestError extends Error {
     responseErrorData;
     requestId;
     method;
+    /**
+     * Present when a timeout or abort made the bridge send a cancel frame for a
+     * request already written to Rust. Settles once Rust answers the original
+     * request or the transport closes. It never rejects.
+     */
+    remoteSettlement;
     constructor(message, options) {
         super(message, options.cause === undefined ? undefined : { cause: options.cause });
         this.name = 'RustBridgeRequestError';
@@ -20,6 +26,7 @@ export class RustBridgeRequestError extends Error {
         this.responseErrorData = options.responseErrorData;
         this.requestId = options.requestId;
         this.method = options.method;
+        this.remoteSettlement = options.remoteSettlement;
     }
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5ydXN0YnJpZGdlcmVxdWVzdGVycm9yLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvY2xhc3Nlcy5ydXN0YnJpZGdlcmVxdWVzdGVycm9yLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQXNCQTs7Ozs7O0dBTUc7QUFDSCxNQUFNLE9BQU8sc0JBQXVCLFNBQVEsS0FBSztJQUMvQixJQUFJLENBQThCO0lBQ2xDLGlCQUFpQixDQUFVO0lBQzNDLDhFQUE4RTtJQUM5RCxpQkFBaUIsQ0FBVztJQUM1QixTQUFTLENBQVU7SUFDbkIsTUFBTSxDQUFVO0lBRWhDLFlBQVksT0FBZSxFQUFFLE9BQXVDO1FBQ2xFLEtBQUssQ0FBQyxPQUFPLEVBQUUsT0FBTyxDQUFDLEtBQUssS0FBSyxTQUFTLENBQUMsQ0FBQyxDQUFDLFNBQVMsQ0FBQyxDQUFDLENBQUMsRUFBRSxLQUFLLEVBQUUsT0FBTyxDQUFDLEtBQUssRUFBRSxDQUFDLENBQUM7UUFDbkYsSUFBSSxDQUFDLElBQUksR0FBRyx3QkFBd0IsQ0FBQztRQUNyQyxJQUFJLENBQUMsSUFBSSxHQUFHLE9BQU8sQ0FBQyxJQUFJLENBQUM7UUFDekIsSUFBSSxDQUFDLGlCQUFpQixHQUFHLE9BQU8sQ0FBQyxpQkFBaUIsQ0FBQztRQUNuRCxJQUFJLENBQUMsaUJBQWlCLEdBQUcsT0FBTyxDQUFDLGlCQUFpQixDQUFDO1FBQ25ELElBQUksQ0FBQyxTQUFTLEdBQUcsT0FBTyxDQUFDLFNBQVMsQ0FBQztRQUNuQyxJQUFJLENBQUMsTUFBTSxHQUFHLE9BQU8sQ0FBQyxNQUFNLENBQUM7SUFDL0IsQ0FBQztDQUNGIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5ydXN0YnJpZGdlcmVxdWVzdGVycm9yLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvY2xhc3Nlcy5ydXN0YnJpZGdlcmVxdWVzdGVycm9yLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQWtEQTs7Ozs7O0dBTUc7QUFDSCxNQUFNLE9BQU8sc0JBQXVCLFNBQVEsS0FBSztJQUMvQixJQUFJLENBQThCO0lBQ2xDLGlCQUFpQixDQUFVO0lBQzNDLDhFQUE4RTtJQUM5RCxpQkFBaUIsQ0FBVztJQUM1QixTQUFTLENBQVU7SUFDbkIsTUFBTSxDQUFVO0lBQ2hDOzs7O09BSUc7SUFDYSxnQkFBZ0IsQ0FBd0M7SUFFeEUsWUFBWSxPQUFlLEVBQUUsT0FBdUM7UUFDbEUsS0FBSyxDQUFDLE9BQU8sRUFBRSxPQUFPLENBQUMsS0FBSyxLQUFLLFNBQVMsQ0FBQyxDQUFDLENBQUMsU0FBUyxDQUFDLENBQUMsQ0FBQyxFQUFFLEtBQUssRUFBRSxPQUFPLENBQUMsS0FBSyxFQUFFLENBQUMsQ0FBQztRQUNuRixJQUFJLENBQUMsSUFBSSxHQUFHLHdCQUF3QixDQUFDO1FBQ3JDLElBQUksQ0FBQyxJQUFJLEdBQUcsT0FBTyxDQUFDLElBQUksQ0FBQztRQUN6QixJQUFJLENBQUMsaUJBQWlCLEdBQUcsT0FBTyxDQUFDLGlCQUFpQixDQUFDO1FBQ25ELElBQUksQ0FBQyxpQkFBaUIsR0FBRyxPQUFPLENBQUMsaUJBQWlCLENBQUM7UUFDbkQsSUFBSSxDQUFDLFNBQVMsR0FBRyxPQUFPLENBQUMsU0FBUyxDQUFDO1FBQ25DLElBQUksQ0FBQyxNQUFNLEdBQUcsT0FBTyxDQUFDLE1BQU0sQ0FBQztRQUM3QixJQUFJLENBQUMsZ0JBQWdCLEdBQUcsT0FBTyxDQUFDLGdCQUFnQixDQUFDO0lBQ25ELENBQUM7Q0FDRiJ9

package/dist_ts/index.d.ts

@@ -1,5 +1,5 @@
 export { RustBridge } from './classes.rustbridge.js';
-export { RustBridgeRequestError, type IRustBridgeRequestErrorOptions, type TRustBridgeRequestErrorCode, } from './classes.rustbridgerequesterror.js';
+export { RustBridgeRequestError, type IRustBridgeRequestErrorOptions, type IRustBridgeRemoteSettlement, type TRustBridgeRemoteSettlementOutcome, type TRustBridgeRequestErrorCode, } from './classes.rustbridgerequesterror.js';
 export { RustBinaryLocator } from './classes.rustbinarylocator.js';
 export { RustBinaryLocatorError } from './classes.rustbinarylocatorerror.js';
 export { StreamingResponse } from './classes.streamingresponse.js';

package/dist_ts/index.js

@@ -7,4 +7,4 @@ export { StdioTransport } from './classes.stdiotransport.js';
 export { SocketTransport } from './classes.sockettransport.js';
 export { LineScanner } from './classes.linescanner.js';
 export * from './interfaces/index.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsVUFBVSxFQUFFLE1BQU0seUJBQXlCLENBQUM7QUFDckQsT0FBTyxFQUNMLHNCQUFzQixHQUd2QixNQUFNLHFDQUFxQyxDQUFDO0FBQzdDLE9BQU8sRUFBRSxpQkFBaUIsRUFBRSxNQUFNLGdDQUFnQyxDQUFDO0FBQ25FLE9BQU8sRUFBRSxzQkFBc0IsRUFBRSxNQUFNLHFDQUFxQyxDQUFDO0FBQzdFLE9BQU8sRUFBRSxpQkFBaUIsRUFBRSxNQUFNLGdDQUFnQyxDQUFDO0FBQ25FLE9BQU8sRUFBRSxjQUFjLEVBQUUsTUFBTSw2QkFBNkIsQ0FBQztBQUM3RCxPQUFPLEVBQUUsZUFBZSxFQUFFLE1BQU0sOEJBQThCLENBQUM7QUFDL0QsT0FBTyxFQUFFLFdBQVcsRUFBRSxNQUFNLDBCQUEwQixDQUFDO0FBQ3ZELGNBQWMsdUJBQXVCLENBQUMifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsVUFBVSxFQUFFLE1BQU0seUJBQXlCLENBQUM7QUFDckQsT0FBTyxFQUNMLHNCQUFzQixHQUt2QixNQUFNLHFDQUFxQyxDQUFDO0FBQzdDLE9BQU8sRUFBRSxpQkFBaUIsRUFBRSxNQUFNLGdDQUFnQyxDQUFDO0FBQ25FLE9BQU8sRUFBRSxzQkFBc0IsRUFBRSxNQUFNLHFDQUFxQyxDQUFDO0FBQzdFLE9BQU8sRUFBRSxpQkFBaUIsRUFBRSxNQUFNLGdDQUFnQyxDQUFDO0FBQ25FLE9BQU8sRUFBRSxjQUFjLEVBQUUsTUFBTSw2QkFBNkIsQ0FBQztBQUM3RCxPQUFPLEVBQUUsZUFBZSxFQUFFLE1BQU0sOEJBQThCLENBQUM7QUFDL0QsT0FBTyxFQUFFLFdBQVcsRUFBRSxNQUFNLDBCQUEwQixDQUFDO0FBQ3ZELGNBQWMsdUJBQXVCLENBQUMifQ==

package/dist_ts/interfaces/config.d.ts

@@ -8,11 +8,26 @@ export interface IRustBridgeLogger {
  * Options for one non-streaming Rust bridge request.
  */
 export interface IRustBridgeRequestOptions {
-    /** Abort only the local wait for this request. */
+    /**
+     * Abort the local wait for this request. When the binary advertised the
+     * `cancel` capability and the request was already written, the bridge also
+     * sends a cancel frame.
+     */
     signal?: AbortSignal;
     /** Override the bridge request timeout for this call, in milliseconds. */
     timeoutMs?: number;
 }
+/**
+ * Options for one streaming Rust bridge request.
+ */
+export interface IRustBridgeStreamingRequestOptions {
+    /**
+     * Abort the local stream. When the binary advertised the `cancel`
+     * capability and the request was already written, the bridge also sends a
+     * cancel frame.
+     */
+    signal?: AbortSignal;
+}
 /** Options for confirmed bridge termination. */
 export interface IRustBridgeTerminateOptions {
     /**

package/dist_ts/interfaces/ipc.d.ts

@@ -8,6 +8,16 @@ export interface IManagementRequest {
     /** Value-free metadata for an associated one-shot binary frame. */
     sensitive?: IManagementSensitivePayload;
 }
+/**
+ * Cancel frame sent to a binary that advertised the `cancel` capability, after
+ * a timeout or abort abandoned a request that was already written. The binary
+ * ignores it for ids it no longer runs and otherwise still answers the
+ * original id exactly once.
+ */
+export interface IManagementCancelRequest {
+    id: string;
+    cancel: true;
+}
 export interface IManagementSensitivePayload {
     protocol: 'smartrust-sensitive-v1';
     fileDescriptor: number;
@@ -29,6 +39,8 @@ export interface IManagementResponse {
     errorCode?: string;
     /** Optional structured details of a failure, for example per-field validation errors. */
     errorData?: unknown;
+    /** Set with `success: false` when the command stopped because of a cancel frame. */
+    cancelled?: boolean;
     /** Required after the receiver consumed the exact associated binary frame. */
     sensitiveAck?: IManagementSensitiveAck;
 }
@@ -38,6 +50,11 @@ export interface IManagementResponse {
 export interface IManagementEvent {
     event: string;
     data: any;
+    /**
+     * Protocol capabilities, read only from the ready event. `cancel` opts the
+     * current transport generation in to cancel frames.
+     */
+    capabilities?: string[];
 }
 /**
  * Definition of a single command supported by a Rust binary.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartrust",
-  "version": "2.4.0",
+  "version": "2.5.1",
   "private": false,
   "description": "A type-safe bridge between JavaScript engines and Rust binaries.",
   "main": "dist_ts/index.js",
@@ -9,10 +9,10 @@
   "author": "Task Venture Capital GmbH",
   "license": "MIT",
   "devDependencies": {
-    "@git.zone/tsbuild": "^5.0.0",
-    "@git.zone/tsrun": "^3.0.0",
-    "@git.zone/tstest": "^6.2.0",
-    "@types/node": "^26.6.1"
+    "@git.zone/tsbuild": "^5.1.2",
+    "@git.zone/tsrun": "^3.0.2",
+    "@git.zone/tstest": "^7.1.0",
+    "@types/node": "^26.6.3"
   },
   "dependencies": {
     "@push.rocks/smartpath": "^6.0.0"

package/readme.md

@@ -50,6 +50,9 @@ If you're integrating Rust into a Node.js project, you'll inevitably need:
 | **Rust → TS** (Error) | `{"id": "req_1", "success": false, "error": "msg", "errorCode": "EAPP_INVALID", "errorData": {...}}` | Error correlated by ID; `errorCode` and `errorData` are optional |
 | **Rust → TS** (Stream Chunk) | `{"id": "req_1", "stream": true, "data": {...}}` | Intermediate chunk (zero or more) |
 | **Rust → TS** (Event) | `{"event": "ready", "data": {...}}` | Unsolicited event (no ID) |
+| **Rust → TS** (Ready with capabilities) | `{"event": "ready", "data": {...}, "capabilities": ["cancel"]}` | Optional opt-in to cancel frames for this connection |
+| **TS → Rust** (Cancel) | `{"id": "req_1", "cancel": true}` | Sent only to binaries that advertised `cancel`, after a timeout or abort |
+| **Rust → TS** (Cancelled) | `{"id": "req_1", "success": false, "cancelled": true, "error": "msg"}` | The one answer to a cancelled request; `errorCode` and `errorData` are optional |
 
 This protocol works identically over stdio and socket transports. Your Rust binary reads JSON lines from one end and writes JSON lines to the other. That's it.
 
@@ -222,9 +225,10 @@ try {
 constructor-level `requestTimeoutMs` remains the default. An already-aborted
 signal rejects before a request ID is allocated or anything is written.
 
-Timeout and abort only abandon the local TypeScript wait. They do not kill or
-disconnect the shared bridge, late responses are ignored, and later commands
-can continue using the same bridge.
+Timeout and abort reject the local wait at once. They do not kill or
+disconnect the shared bridge, and later commands can continue using the same
+bridge. When the binary supports it, the bridge also asks Rust to stop the
+command; see [Cancelling the Rust Side](#cancelling-the-rust-side).
 
 Use `maxPendingRequestsByMethod` to fail fast before serialization and transport
 writes when one command type reaches its local pending-request limit. Limits are
@@ -244,14 +248,66 @@ Capacity is released when the local request resolves, rejects, times out, or is
 aborted, when its transport write fails, or when the bridge terminates. Regular
 and streaming calls to the same method share its capacity. Every configured
 limit must be a positive safe integer; invalid values throw `RangeError` during
-construction. As with cancellation generally, timeout or abort cannot stop work
-that was already written to Rust, so the limit bounds local pending state rather
-than remote execution after local abandonment.
+construction. The limit bounds local pending state, not remote execution: a
+timed-out or aborted request frees its capacity immediately, even while Rust is
+still working on it or answering its cancel frame.
 
-> The JSON-lines protocol has no cancellation message. After a command has
-> been written, Rust may still execute it even if the local wait times out or
-> is aborted. Do not blindly retry mutating commands; first establish whether
-> the original command executed or design the command to be idempotent.
+#### Cancelling the Rust Side
+
+A binary opts in to cancellation by adding `"capabilities": ["cancel"]` to its
+ready event. The bridge records this per connection: a respawn or socket
+reconnect starts without it until the next ready event advertises it again.
+Binaries that do not advertise `cancel` never receive a cancel frame, so the
+Rust command may keep running after the local wait ends.
+
+With the capability, a timeout or abort of a request that was already written
+sends one cancel frame, `{"id":"req_1","cancel":true}`. No cancel frame is sent
+when the response already arrived, when the signal was aborted before the
+request was written, or for `sendCommandWithSensitiveBytes`, whose failures
+terminate the child instead.
+
+The rejection's `remoteSettlement` then reports how Rust settled the request.
+It resolves once and never rejects:
+
+| `outcome` | Meaning |
+|---|---|
+| `cancelled` | Rust stopped and answered `success: false, cancelled: true` |
+| `completed` | Rust finished anyway; `result` holds the result |
+| `failed` | Rust answered `success: false` without `cancelled: true` |
+| `disconnected` | The transport closed before Rust answered; the outcome is unknown |
+
+`cancelled` and `failed` carry Rust's `error`, string `errorCode` and
+`errorData` when it sent them. `remoteSettlement` is undefined when no cancel
+frame was sent. Stream chunks and answers that arrive for a cancelled request
+are consumed by the bridge and never reach the caller.
+
+A Rust command may take a while to reach a point where it can stop, and a
+faulty binary may never answer. Bound the wait yourself and terminate the child
+when it runs out; the settlement then resolves as `disconnected`:
+
+```typescript
+try {
+  await bridge.sendCommand('ingest', params, { timeoutMs: 60_000 });
+} catch (error) {
+  if (error instanceof RustBridgeRequestError && error.remoteSettlement) {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const deadline = new Promise<null>((resolve) => {
+      timer = setTimeout(() => resolve(null), 30_000);
+    });
+    const settlement = await Promise.race([error.remoteSettlement, deadline]);
+    clearTimeout(timer);
+    if (!settlement) {
+      await bridge.terminate(); // respawn with bridge.spawn() on next use
+    }
+  }
+  throw error;
+}
+```
+
+> Without the `cancel` capability, or when the settlement is `completed` or
+> `disconnected`, Rust may have executed the command. Do not blindly retry
+> mutating commands; first establish whether the original command executed or
+> design the command to be idempotent.
 
 Timeout, cancellation, transport-write/exit, and Rust response failures use
 `RustBridgeRequestError`.
@@ -260,8 +316,8 @@ programmatic handling:
 
 | Code | Meaning |
 |---|---|
-| `ERR_RUST_BRIDGE_REQUEST_TIMEOUT` | The local request deadline elapsed |
-| `ERR_RUST_BRIDGE_REQUEST_ABORTED` | The caller's signal aborted the local wait |
+| `ERR_RUST_BRIDGE_REQUEST_TIMEOUT` | The local request deadline or streaming inactivity deadline elapsed |
+| `ERR_RUST_BRIDGE_REQUEST_ABORTED` | The caller's signal aborted the local wait or stream |
 | `ERR_RUST_BRIDGE_REQUEST_LIMIT` | The configured pending-request limit for this method is full |
 | `ERR_RUST_BRIDGE_REQUEST_WRITE` | The transport rejected the request write |
 | `ERR_RUST_BRIDGE_REQUEST_TRANSPORT` | The transport exited, disconnected, or was killed |
@@ -447,11 +503,26 @@ try {
 A final `success: false` response rejects both paths with the same
 `RustBridgeRequestError`. When the response includes an `errorCode` or
 `errorData`, they are available as `responseErrorCode` and `responseErrorData`
-on that error.
+on that error. When the transport exits, disconnects or is terminated, both
+paths reject with a `RustBridgeRequestError` whose code is
+`ERR_RUST_BRIDGE_REQUEST_TRANSPORT`, as regular commands do.
+
+#### Aborting a Stream
+
+Pass an `AbortSignal` to stop consuming a stream. The iterator and `.result`
+reject with `ERR_RUST_BRIDGE_REQUEST_ABORTED`, and a binary with the `cancel`
+capability receives a cancel frame, exactly as for regular commands:
+
+```typescript
+const controller = new AbortController();
+const stream = bridge.sendCommandStreaming('processData', { count: 100 }, {
+  signal: controller.signal,
+});
+```
 
 #### Stream Timeout
 
-By default, streaming commands use the same timeout as regular commands (`requestTimeoutMs`). The timeout **resets on each chunk received**, so it acts as an inactivity timeout rather than an absolute timeout. You can configure it separately:
+By default, streaming commands use the same timeout as regular commands (`requestTimeoutMs`). The timeout **resets on each chunk received**, so it acts as an inactivity timeout rather than an absolute timeout. When it elapses, the stream rejects with a `RustBridgeRequestError` whose code is `ERR_RUST_BRIDGE_REQUEST_TIMEOUT`, and a binary with the `cancel` capability receives a cancel frame. You can configure it separately:
 
 ```typescript
 const bridge = new RustBridge<TMyCommands>({
@@ -621,6 +692,8 @@ Your Rust binary needs to implement a simple protocol. The transport (stdio or s
 
 6. **Use stderr** for logging — it won't interfere with the IPC protocol
 
+7. **Optionally support cancellation**: add `"capabilities":["cancel"]` to the ready event, then treat `{"id":"...","cancel":true}` as a request to stop that command at its next safe point. Answer the original id exactly once, either `{"id":"...","success":false,"cancelled":true,"error":"..."}` or its normal result when the command could no longer stop. Ignore cancel frames for ids that already finished or are unknown, and keep reading stdin while commands run so cancel frames arrive promptly.
+
 #### Socket Mode (Daemon)
 
 1. **Listen** on a Unix socket (e.g., `/var/run/my-daemon.sock`) or Windows named pipe
@@ -754,7 +827,7 @@ fn main() {
 | `connect(socketPath, options?)` | `Promise<boolean>` | **Socket mode**: Connect to a running daemon; returns `false` on connection/readiness failure and rejects stdio-only descriptor/byte-channel options |
 | `sendCommand(method, params, options?)` | `Promise<TCommands[K]['result']>` | Send a typed command with an optional per-call timeout or abort signal |
 | `sendCommandWithSensitiveBytes(method, params, bytes, options?)` | `Promise<TCommands[K]['result']>` | Send one exclusive JSON command with its raw bytes on the generation-owned one-shot pipe |
-| `sendCommandStreaming(method, params)` | `StreamingResponse<TChunk, TResult>` | Send a streaming command; returns immediately |
+| `sendCommandStreaming(method, params, options?)` | `StreamingResponse<TChunk, TResult>` | Send a streaming command with an optional abort signal; returns immediately |
 | `terminate(options?)` | `Promise<void>` | Confirm stdio child exit or local socket closure; `gracePeriodMs` controls SIGKILL escalation |
 | `kill()` | `void` | Fire-and-forget compatibility wrapper around `terminate()` |
 | `running` | `boolean` | Whether the bridge is currently connected and ready |
@@ -811,6 +884,9 @@ fn main() {
 |---|---|
 | `IRustBridgeOptions` | Full configuration for `RustBridge` |
 | `IRustBridgeRequestOptions` | Per-command options: `{ signal?, timeoutMs? }` |
+| `IRustBridgeStreamingRequestOptions` | Per-stream options: `{ signal? }` |
+| `IRustBridgeRemoteSettlement` | Remote outcome of a cancelled request: `{ outcome, result?, error?, errorCode?, errorData? }` |
+| `TRustBridgeRemoteSettlementOutcome` | `'cancelled' \| 'completed' \| 'failed' \| 'disconnected'` |
 | `IRustBridgeTerminateOptions` | Confirmed termination options: `{ gracePeriodMs? }` |
 | `IRustTransportDisconnectOptions` | Optional confirmed-disconnect grace period for owned process transports |
 | `IBinaryLocatorOptions` | Configuration for `RustBinaryLocator` |
@@ -818,14 +894,15 @@ fn main() {
 | `IRustBridgeLogger` | Logger interface: `{ log(level, message, data?) }` |
 | `IRustTransport` | Transport interface (extends `EventEmitter`) |
 | `IManagementRequest` | IPC request shape: `{ id, method, params }` |
-| `IManagementResponse` | IPC response shape: `{ id, success, result?, error?, errorCode?, errorData? }` |
-| `IManagementEvent` | IPC event shape: `{ event, data }` |
+| `IManagementResponse` | IPC response shape: `{ id, success, result?, error?, errorCode?, errorData?, cancelled? }` |
+| `IManagementCancelRequest` | IPC cancel frame shape: `{ id, cancel: true }` |
+| `IManagementEvent` | IPC event shape: `{ event, data, capabilities? }` |
 | `IManagementStreamChunk` | IPC stream chunk shape: `{ id, stream: true, data }` |
 | `ICommandDefinition` | Single command definition: `{ params, result }` |
 | `TCommandMap` | `Record<string, ICommandDefinition>` |
 | `TStreamingCommandKeys<T>` | Extracts keys from a command map that have a `chunk` field |
 | `TExtractChunk<T>` | Extracts the chunk type from a streaming command definition |
-| `RustBridgeRequestError` | Request error class with stable `code`, optional `responseErrorCode`, `responseErrorData`, `requestId`, and `method` fields |
+| `RustBridgeRequestError` | Request error class with stable `code`, optional `responseErrorCode`, `responseErrorData`, `requestId`, `method`, and `remoteSettlement` fields |
 | `TRustBridgeRequestErrorCode` | Union of stable request error code strings |
 
 ## License and Legal Information

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartrust',
-  version: '2.4.0',
+  version: '2.5.1',
   description: 'A type-safe bridge between JavaScript engines and Rust binaries.'
 }

package/ts/classes.linescanner.ts

@@ -4,9 +4,16 @@ import type { IRustBridgeLogger } from './interfaces/index.js';
  * Buffer-based newline scanner for streaming binary data.
  * Accumulates chunks and emits complete lines via callback.
  * Used by both StdioTransport and SocketTransport.
+ *
+ * Each byte is scanned once and copied at most once into its line, so a line that arrives in many
+ * chunks costs time linear in its length.
  */
 export class LineScanner {
-  private buffer: Buffer = Buffer.alloc(0);
+  /** Chunks of the line being received; none of them contains a newline. */
+  private pending: Buffer[] = [];
+  private pendingLength = 0;
+  /** Bytes after a line whose callback threw; they may contain newlines and are scanned first. */
+  private unscanned: Buffer = Buffer.alloc(0);
   private maxPayloadSize: number;
   private logger: IRustBridgeLogger;
 
@@ -19,44 +26,74 @@ export class LineScanner {
    * Feed a chunk of data. Calls onLine for each complete newline-terminated line found.
    */
   public push(chunk: Buffer, onLine: (line: string) => void): void {
-    this.buffer = Buffer.concat([this.buffer, chunk]);
+    const input = this.unscanned.length > 0 ? Buffer.concat([this.unscanned, chunk]) : chunk;
+    this.unscanned = Buffer.alloc(0);
+    let start = 0;
 
     try {
       let newlineIndex: number;
-      while ((newlineIndex = this.buffer.indexOf(0x0A)) !== -1) {
-        const lineBuffer = this.buffer.subarray(0, newlineIndex);
-        this.buffer = this.buffer.subarray(newlineIndex + 1);
-
-        if (lineBuffer.length > this.maxPayloadSize) {
-          this.logger.log('error', `Inbound message exceeds maxPayloadSize (${lineBuffer.length} bytes), dropping`);
+      while ((newlineIndex = input.indexOf(0x0A, start)) !== -1) {
+        const lineBuffer = this.takeLine(input.subarray(start, newlineIndex));
+        start = newlineIndex + 1;
+        if (!lineBuffer) {
           continue;
         }
-
         const line = lineBuffer.toString('utf8').trim();
         if (line) {
           onLine(line);
         }
       }
-
-      // Prevent OOM if sender never sends newline
-      if (this.buffer.length > this.maxPayloadSize) {
-        this.logger.log('error', `Buffer exceeded maxPayloadSize (${this.buffer.length} bytes) without newline, clearing`);
-        this.buffer = Buffer.alloc(0);
-      }
-    } finally {
-      // A subarray retains its entire backing allocation, even when empty.
-      // Compact once per chunk, including when a callback throws, without
-      // repeatedly copying the unread suffix for each parsed line.
-      if (this.buffer.length === 0) {
-        this.buffer = Buffer.alloc(0);
-      } else if (this.buffer.buffer.byteLength > Math.max(Buffer.poolSize, this.buffer.length * 2)) {
-        this.buffer = Buffer.from(this.buffer);
-      }
+      this.appendPartial(input.subarray(start));
+    } catch (error) {
+      // Keep what follows the failed line for the next push, without retaining what was consumed.
+      this.unscanned = LineScanner.compact(input.subarray(start));
+      throw error;
     }
   }
 
   /** Reset the internal buffer. */
   public clear(): void {
-    this.buffer = Buffer.alloc(0);
+    this.pending = [];
+    this.pendingLength = 0;
+    this.unscanned = Buffer.alloc(0);
+  }
+
+  /** Joins the pending chunks with the line's last piece; null when the line is too large. */
+  private takeLine(tail: Buffer): Buffer | null {
+    const length = this.pendingLength + tail.length;
+    const pending = this.pending;
+    this.pending = [];
+    this.pendingLength = 0;
+    if (length > this.maxPayloadSize) {
+      this.logger.log('error', `Inbound message exceeds maxPayloadSize (${length} bytes), dropping`);
+      return null;
+    }
+    return pending.length === 0 ? tail : Buffer.concat([...pending, tail], length);
+  }
+
+  private appendPartial(partial: Buffer): void {
+    if (partial.length === 0) {
+      return;
+    }
+    // Prevent OOM if sender never sends newline
+    if (this.pendingLength + partial.length > this.maxPayloadSize) {
+      this.logger.log(
+        'error',
+        `Buffer exceeded maxPayloadSize (${this.pendingLength + partial.length} bytes) without newline, clearing`,
+      );
+      this.pending = [];
+      this.pendingLength = 0;
+      return;
+    }
+    this.pending.push(LineScanner.compact(partial));
+    this.pendingLength += partial.length;
+  }
+
+  /** A subarray retains its entire backing allocation; copy a small piece of a large one. */
+  private static compact(piece: Buffer): Buffer {
+    if (piece.length === 0) {
+      return Buffer.alloc(0);
+    }
+    return piece.buffer.byteLength > Math.max(Buffer.poolSize, piece.length * 2) ? Buffer.from(piece) : piece;
   }
 }