@superdoc/sdk 2.26.0 → 2.27.0-next.4

package/dist/index.cjs

@@ -152,6 +152,9 @@ class SuperDocClient {
     async connect() {
         await this.runtime.connect();
     }
+    subscribe(options = {}) {
+        return this.runtime.subscribe(options);
+    }
     /**
      * Open a document and return a bound document handle.
      *

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { type BoundDocApi, type DocCloseBoundParams, type DocCloseResult, type DocFormatApplyBoundParams, type DocFormatApplyResult, type DocOpenParams as GeneratedDocOpenParams, type DocOpenResult, type DocSaveBoundParams, type DocSaveResult } from './generated/client.js';
 import { SuperDocRuntime, type SuperDocClientOptions, type DocOpenOptions, type InvokeOptions, type OperationSpec, type ReplaceFileOptions, type ReplaceFileResult, type ReplaceFileSource, type RuntimeInvoker } from './runtime/process.js';
+import type { HostNotifications, SubscribeOptions } from './runtime/notifications.js';
 /**
  * Wraps a raw runtime and injects a fixed sessionId into every invoke call.
  * Implements RuntimeInvoker so generated code can use it directly.
@@ -73,6 +74,7 @@ export declare class SuperDocClient {
     private readonly pendingSessionIds;
     constructor(options?: SuperDocClientOptions);
     connect(): Promise<void>;
+    subscribe(options?: SubscribeOptions): HostNotifications;
     /**
      * Open a document and return a bound document handle.
      *
@@ -104,6 +106,7 @@ export type { AgentToolkit, CreateAgentToolkitInput } from './tools.js';
 export { defineAction } from './actions/define.js';
 export type { ActionSpec, ActionStep, DefineActionInput, JSONSchemaObject } from './actions/define.js';
 export { SuperDocCliError } from './runtime/errors.js';
+export type { HostNotification, HostNotifications, SubscribeOptions } from './runtime/notifications.js';
 export { runTrackedComparisonReview } from './tracked-review-route.js';
 export type { TrackedReviewSession, TrackedComparisonReviewInput } from './tracked-review-route.js';
 export type { CollaborationAuth, DocOpenOptions, InvokeOptions, OperationSpec, OperationParamSpec, RuntimeInvoker, SuperDocClientOptions, } from './runtime/process.js';

package/dist/index.js

@@ -140,6 +140,9 @@ export class SuperDocClient {
     async connect() {
         await this.runtime.connect();
     }
+    subscribe(options = {}) {
+        return this.runtime.subscribe(options);
+    }
     /**
      * Open a document and return a bound document handle.
      *

package/dist/runtime/host.cjs

@@ -4,6 +4,7 @@ var node_child_process = require('node:child_process');
 var transportCommon = require('./transport-common.cjs');
 var errors = require('./errors.cjs');
 var stateDirectory = require('./state-directory.cjs');
+var notifications = require('./notifications.cjs');
 var documentEvidence = require('./document-evidence.cjs');
 var contract = require('../generated/contract.cjs');
 var sdkPolicy = require('./sdk-policy.cjs');
@@ -11,6 +12,7 @@ var sdkPolicy = require('./sdk-policy.cjs');
 const HOST_PROTOCOL_VERSION = sdkPolicy.SDK_POLICY.protocolVersion;
 const CLI_HOST_REQUIRED_FEATURES = sdkPolicy.SDK_POLICY.cliRequiredFeatures;
 const COLLABORATION_AUTH_PER_OPEN_FEATURE = sdkPolicy.SDK_POLICY.features.collaborationAuthPerOpen;
+const IDENTITY_CLAIM_PER_OPEN_FEATURE = sdkPolicy.SDK_POLICY.features.identityClaimPerOpen;
 const HOST_REQUEST_TIMEOUT_FEATURE = sdkPolicy.SDK_POLICY.features.requestTimeout;
 const CHANGE_MODES = ['direct', 'tracked'];
 const FORWARD_HOST_STDERR = typeof process !== 'undefined' && typeof process.env?.SUPERDOC_DEBUG_TEXT_REWRITE === 'string'
@@ -125,6 +127,7 @@ class HostTransport {
     activeCalls = new Set();
     hostFeatures = new Set();
     cliLocalSessions = new Set();
+    notifications = new notifications.HostNotificationHub();
     constructor(options) {
         this.stateDirectory = new stateDirectory.SdkStateDirectory(options.stateDir);
         this.hostBin = options.hostBin;
@@ -146,6 +149,9 @@ class HostTransport {
     async connect() {
         await this.runWhileActive(() => this.ensureConnected());
     }
+    subscribe(options = {}) {
+        return this.notifications.subscribe(options);
+    }
     supportsDocumentFacts(sessionId) {
         return this.usesCliDocumentFacts(sessionId);
     }
@@ -171,14 +177,18 @@ class HostTransport {
     async dispose() {
         if (this.disposePromise)
             return this.disposePromise;
-        if (this.terminalDisposalError)
+        if (this.terminalDisposalError) {
+            this.notifications.close();
             throw this.terminalDisposalError;
+        }
         if (!this.child &&
             !this.connecting &&
             this.activeCalls.size === 0 &&
             !this.stateDirectory.ownsRoot &&
-            this.stoppedChildren.size === 0)
+            this.stoppedChildren.size === 0) {
+            this.notifications.close();
             return;
+        }
         this.stopping = true;
         const disposal = this.disposeAfterActiveCalls();
         this.disposePromise = disposal;
@@ -192,6 +202,14 @@ class HostTransport {
         }
     }
     async disposeAfterActiveCalls() {
+        try {
+            await this.shutdownAfterActiveCalls();
+        }
+        finally {
+            this.notifications.close();
+        }
+    }
+    async shutdownAfterActiveCalls() {
         await Promise.allSettled(Array.from(this.activeCalls));
         if (this.terminalDisposalError)
             throw this.terminalDisposalError;
@@ -244,6 +262,12 @@ class HostTransport {
                 });
             }
         }
+        const identityClaim = options.identityClaim === undefined ? undefined : transportCommon.normalizeIdentityClaim(options.identityClaim);
+        if (identityClaim !== undefined && operation.operationId !== 'doc.open') {
+            throw new errors.SuperDocCliError('identityClaim is supported only for doc.open requests.', {
+                code: 'INVALID_ARGUMENT',
+            });
+        }
         await this.ensureConnected();
         if (collaborationAuth !== undefined && !this.hostFeatures.has(COLLABORATION_AUTH_PER_OPEN_FEATURE)) {
             throw new errors.SuperDocCliError('The connected CLI host does not support per-open collaboration authentication.', {
@@ -251,6 +275,12 @@ class HostTransport {
                 details: { feature: COLLABORATION_AUTH_PER_OPEN_FEATURE },
             });
         }
+        if (identityClaim !== undefined && !this.hostFeatures.has(IDENTITY_CLAIM_PER_OPEN_FEATURE)) {
+            throw new errors.SuperDocCliError('The connected CLI host does not support a per-open identity claim.', {
+                code: 'CAPABILITY_UNSUPPORTED',
+                details: { feature: IDENTITY_CLAIM_PER_OPEN_FEATURE },
+            });
+        }
         const sessionId = typeof params.sessionId === 'string' ? params.sessionId : undefined;
         const supportsRequestTimeoutMetadata = this.hostFeatures.has(HOST_REQUEST_TIMEOUT_FEATURE);
         const cliHostRequestTimeoutMs = this.requestTimeoutMs ?? HOST_DEFAULT_REQUEST_TIMEOUT_MS;
@@ -288,6 +318,7 @@ class HostTransport {
                 }),
             ...(includeRevision ? { includeRevision: true } : {}),
             ...(collaborationAuth === undefined ? {} : { collaborationAuth }),
+            ...(identityClaim === undefined ? {} : { identityClaim }),
         }, watchdogTimeout, {
             requestTimeoutMs: supportsRequestTimeoutMetadata ? options.timeoutMs : undefined,
         });
@@ -511,8 +542,8 @@ class HostTransport {
         if (record.jsonrpc !== '2.0') {
             return;
         }
-        // Notification (no id) — reserved for future eventing
         if ('method' in record && !('id' in record)) {
+            this.notifications.publish(record);
             return;
         }
         const idRaw = record.id;
@@ -616,6 +647,7 @@ class HostTransport {
     }
     handleDisconnect(error) {
         this.cleanupProcess(error);
+        this.notifications.disconnect(error);
     }
     cleanupProcess(error) {
         this.hostFeatures.clear();
@@ -644,6 +676,7 @@ class HostTransport {
 
 exports.COLLABORATION_AUTH_PER_OPEN_FEATURE = COLLABORATION_AUTH_PER_OPEN_FEATURE;
 exports.HostTransport = HostTransport;
+exports.IDENTITY_CLAIM_PER_OPEN_FEATURE = IDENTITY_CLAIM_PER_OPEN_FEATURE;
 exports.buildHostSpawnArgs = buildHostSpawnArgs;
 exports.mapCliInvocationResult = mapCliInvocationResult;
 exports.mapDocumentReplaceFileResult = mapDocumentReplaceFileResult;

package/dist/runtime/host.d.ts

@@ -1,5 +1,7 @@
 import { type OperationSpec, type SuperDocClientOptions, type TransportInvokeOptions } from './transport-common.js';
+import { type HostNotifications, type SubscribeOptions } from './notifications.js';
 export declare const COLLABORATION_AUTH_PER_OPEN_FEATURE: string;
+export declare const IDENTITY_CLAIM_PER_OPEN_FEATURE: string;
 export declare function mapCliInvocationResult(operation: OperationSpec, value: unknown): unknown;
 export declare function mapDocumentReplaceFileResult(response: unknown, sessionId: string): Record<string, unknown>;
 /**
@@ -53,15 +55,18 @@ export declare class HostTransport {
     private readonly activeCalls;
     private readonly hostFeatures;
     private readonly cliLocalSessions;
+    private readonly notifications;
     constructor(options: {
         hostBin: string;
     } & SuperDocClientOptions);
     connect(): Promise<void>;
+    subscribe(options?: SubscribeOptions): HostNotifications;
     supportsDocumentFacts(sessionId: string): boolean;
     usesCliDocumentFacts(sessionId: string): boolean;
     readDocumentRevision(sessionId: string): Promise<string | undefined>;
     dispose(): Promise<void>;
     private disposeAfterActiveCalls;
+    private shutdownAfterActiveCalls;
     invoke<TData = unknown>(operation: OperationSpec, params?: Record<string, unknown>, options?: TransportInvokeOptions): Promise<TData>;
     replaceFile(sessionId: string, path: string, options?: TransportInvokeOptions): Promise<Record<string, unknown>>;
     private invokeWhileActive;

package/dist/runtime/host.js

@@ -1,13 +1,15 @@
 import { spawn } from 'node:child_process';
-import { buildOperationArgv, captureMutationPlanAuthor, buildStructuredReadInput, normalizeCollaborationAuth, resolveInvocation, } from './transport-common.js';
+import { buildOperationArgv, captureMutationPlanAuthor, buildStructuredReadInput, normalizeCollaborationAuth, normalizeIdentityClaim, resolveInvocation, } from './transport-common.js';
 import { SuperDocCliError } from './errors.js';
 import { SdkStateDirectory } from './state-directory.js';
+import { HostNotificationHub } from './notifications.js';
 import { registerMutationRevision } from './document-evidence.js';
 import { CONTRACT } from '../generated/contract.js';
 import { SDK_POLICY } from './sdk-policy.js';
 const HOST_PROTOCOL_VERSION = SDK_POLICY.protocolVersion;
 const CLI_HOST_REQUIRED_FEATURES = SDK_POLICY.cliRequiredFeatures;
 export const COLLABORATION_AUTH_PER_OPEN_FEATURE = SDK_POLICY.features.collaborationAuthPerOpen;
+export const IDENTITY_CLAIM_PER_OPEN_FEATURE = SDK_POLICY.features.identityClaimPerOpen;
 const HOST_REQUEST_TIMEOUT_FEATURE = SDK_POLICY.features.requestTimeout;
 const CHANGE_MODES = ['direct', 'tracked'];
 const FORWARD_HOST_STDERR = typeof process !== 'undefined' && typeof process.env?.SUPERDOC_DEBUG_TEXT_REWRITE === 'string'
@@ -122,6 +124,7 @@ export class HostTransport {
     activeCalls = new Set();
     hostFeatures = new Set();
     cliLocalSessions = new Set();
+    notifications = new HostNotificationHub();
     constructor(options) {
         this.stateDirectory = new SdkStateDirectory(options.stateDir);
         this.hostBin = options.hostBin;
@@ -143,6 +146,9 @@ export class HostTransport {
     async connect() {
         await this.runWhileActive(() => this.ensureConnected());
     }
+    subscribe(options = {}) {
+        return this.notifications.subscribe(options);
+    }
     supportsDocumentFacts(sessionId) {
         return this.usesCliDocumentFacts(sessionId);
     }
@@ -168,14 +174,18 @@ export class HostTransport {
     async dispose() {
         if (this.disposePromise)
             return this.disposePromise;
-        if (this.terminalDisposalError)
+        if (this.terminalDisposalError) {
+            this.notifications.close();
             throw this.terminalDisposalError;
+        }
         if (!this.child &&
             !this.connecting &&
             this.activeCalls.size === 0 &&
             !this.stateDirectory.ownsRoot &&
-            this.stoppedChildren.size === 0)
+            this.stoppedChildren.size === 0) {
+            this.notifications.close();
             return;
+        }
         this.stopping = true;
         const disposal = this.disposeAfterActiveCalls();
         this.disposePromise = disposal;
@@ -189,6 +199,14 @@ export class HostTransport {
         }
     }
     async disposeAfterActiveCalls() {
+        try {
+            await this.shutdownAfterActiveCalls();
+        }
+        finally {
+            this.notifications.close();
+        }
+    }
+    async shutdownAfterActiveCalls() {
         await Promise.allSettled(Array.from(this.activeCalls));
         if (this.terminalDisposalError)
             throw this.terminalDisposalError;
@@ -241,6 +259,12 @@ export class HostTransport {
                 });
             }
         }
+        const identityClaim = options.identityClaim === undefined ? undefined : normalizeIdentityClaim(options.identityClaim);
+        if (identityClaim !== undefined && operation.operationId !== 'doc.open') {
+            throw new SuperDocCliError('identityClaim is supported only for doc.open requests.', {
+                code: 'INVALID_ARGUMENT',
+            });
+        }
         await this.ensureConnected();
         if (collaborationAuth !== undefined && !this.hostFeatures.has(COLLABORATION_AUTH_PER_OPEN_FEATURE)) {
             throw new SuperDocCliError('The connected CLI host does not support per-open collaboration authentication.', {
@@ -248,6 +272,12 @@ export class HostTransport {
                 details: { feature: COLLABORATION_AUTH_PER_OPEN_FEATURE },
             });
         }
+        if (identityClaim !== undefined && !this.hostFeatures.has(IDENTITY_CLAIM_PER_OPEN_FEATURE)) {
+            throw new SuperDocCliError('The connected CLI host does not support a per-open identity claim.', {
+                code: 'CAPABILITY_UNSUPPORTED',
+                details: { feature: IDENTITY_CLAIM_PER_OPEN_FEATURE },
+            });
+        }
         const sessionId = typeof params.sessionId === 'string' ? params.sessionId : undefined;
         const supportsRequestTimeoutMetadata = this.hostFeatures.has(HOST_REQUEST_TIMEOUT_FEATURE);
         const cliHostRequestTimeoutMs = this.requestTimeoutMs ?? HOST_DEFAULT_REQUEST_TIMEOUT_MS;
@@ -285,6 +315,7 @@ export class HostTransport {
                 }),
             ...(includeRevision ? { includeRevision: true } : {}),
             ...(collaborationAuth === undefined ? {} : { collaborationAuth }),
+            ...(identityClaim === undefined ? {} : { identityClaim }),
         }, watchdogTimeout, {
             requestTimeoutMs: supportsRequestTimeoutMetadata ? options.timeoutMs : undefined,
         });
@@ -508,8 +539,8 @@ export class HostTransport {
         if (record.jsonrpc !== '2.0') {
             return;
         }
-        // Notification (no id) — reserved for future eventing
         if ('method' in record && !('id' in record)) {
+            this.notifications.publish(record);
             return;
         }
         const idRaw = record.id;
@@ -613,6 +644,7 @@ export class HostTransport {
     }
     handleDisconnect(error) {
         this.cleanupProcess(error);
+        this.notifications.disconnect(error);
     }
     cleanupProcess(error) {
         this.hostFeatures.clear();

package/dist/runtime/notifications.cjs

@@ -0,0 +1,124 @@
+'use strict';
+
+var errors = require('./errors.cjs');
+
+const NOTIFICATIONS_LAGGED = 'NOTIFICATIONS_LAGGED';
+const DEFAULT_NOTIFICATION_CAPACITY = 64;
+const LAGGED_MESSAGE = 'resynchronize document state before using notification-derived caches';
+const RESYNC_HINT = 'Call changes.list with the cursor of the last change record you processed.';
+class HostNotifications {
+    capacity;
+    detach;
+    queue = [];
+    waiters = [];
+    skipped = 0;
+    failure = null;
+    closed = false;
+    constructor(capacity, detach) {
+        this.capacity = capacity;
+        this.detach = detach;
+    }
+    next() {
+        if (this.skipped > 0) {
+            const skipped = this.skipped;
+            this.skipped = 0;
+            return Promise.reject(new errors.SuperDocCliError(LAGGED_MESSAGE, {
+                code: NOTIFICATIONS_LAGGED,
+                details: { skipped, resync: RESYNC_HINT },
+            }));
+        }
+        const notification = this.queue.shift();
+        if (notification)
+            return Promise.resolve({ done: false, value: notification });
+        if (this.failure) {
+            const failure = this.failure;
+            this.failure = null;
+            return Promise.reject(failure);
+        }
+        if (this.closed)
+            return Promise.resolve({ done: true, value: undefined });
+        return new Promise((resolve, reject) => this.waiters.push({ resolve, reject }));
+    }
+    return() {
+        this.close();
+        return Promise.resolve({ done: true, value: undefined });
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.queue.length = 0;
+        this.skipped = 0;
+        this.failure = null;
+        this.detach(this);
+        for (const waiter of this.waiters.splice(0))
+            waiter.resolve({ done: true, value: undefined });
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+    get isClosed() {
+        return this.closed;
+    }
+    deliver(notification) {
+        if (this.closed)
+            return;
+        const waiter = this.waiters.shift();
+        if (waiter) {
+            waiter.resolve({ done: false, value: notification });
+            return;
+        }
+        if (this.queue.length >= this.capacity) {
+            this.queue.shift();
+            this.skipped += 1;
+        }
+        this.queue.push(notification);
+    }
+    fail(error) {
+        if (this.closed)
+            return;
+        const waiter = this.waiters.shift();
+        if (waiter) {
+            waiter.reject(error);
+            return;
+        }
+        this.failure = error;
+    }
+}
+class HostNotificationHub {
+    subscriptions = new Set();
+    subscribe(options = {}) {
+        const capacity = options.capacity ?? DEFAULT_NOTIFICATION_CAPACITY;
+        if (!Number.isSafeInteger(capacity) || capacity < 1) {
+            throw new errors.SuperDocCliError('Notification capacity must be a positive integer.', {
+                code: 'INVALID_ARGUMENT',
+                details: { capacity },
+            });
+        }
+        const subscription = new HostNotifications(capacity, (closed) => this.subscriptions.delete(closed));
+        this.subscriptions.add(subscription);
+        return subscription;
+    }
+    publish(frame) {
+        if (this.subscriptions.size === 0 || typeof frame.method !== 'string')
+            return;
+        const notification = frame.params === undefined
+            ? { jsonrpc: '2.0', method: frame.method }
+            : { jsonrpc: '2.0', method: frame.method, params: frame.params };
+        for (const subscription of this.subscriptions)
+            subscription.deliver(notification);
+    }
+    disconnect(error) {
+        for (const subscription of this.subscriptions)
+            subscription.fail(error);
+    }
+    close() {
+        for (const subscription of [...this.subscriptions])
+            subscription.close();
+    }
+}
+
+exports.DEFAULT_NOTIFICATION_CAPACITY = DEFAULT_NOTIFICATION_CAPACITY;
+exports.HostNotificationHub = HostNotificationHub;
+exports.HostNotifications = HostNotifications;
+exports.NOTIFICATIONS_LAGGED = NOTIFICATIONS_LAGGED;

package/dist/runtime/notifications.d.ts

@@ -0,0 +1,35 @@
+import { SuperDocCliError } from './errors.js';
+export declare const NOTIFICATIONS_LAGGED = "NOTIFICATIONS_LAGGED";
+export declare const DEFAULT_NOTIFICATION_CAPACITY = 64;
+export interface HostNotification {
+    readonly jsonrpc: '2.0';
+    readonly method: string;
+    readonly params?: unknown;
+}
+export interface SubscribeOptions {
+    readonly capacity?: number;
+}
+export declare class HostNotifications implements AsyncIterableIterator<HostNotification> {
+    private readonly capacity;
+    private readonly detach;
+    private readonly queue;
+    private readonly waiters;
+    private skipped;
+    private failure;
+    private closed;
+    constructor(capacity: number, detach: (subscription: HostNotifications) => void);
+    next(): Promise<IteratorResult<HostNotification, undefined>>;
+    return(): Promise<IteratorResult<HostNotification, undefined>>;
+    close(): void;
+    [Symbol.asyncIterator](): this;
+    get isClosed(): boolean;
+    deliver(notification: HostNotification): void;
+    fail(error: SuperDocCliError): void;
+}
+export declare class HostNotificationHub {
+    private readonly subscriptions;
+    subscribe(options?: SubscribeOptions): HostNotifications;
+    publish(frame: Record<string, unknown>): void;
+    disconnect(error: SuperDocCliError): void;
+    close(): void;
+}

package/dist/runtime/notifications.js

@@ -0,0 +1,116 @@
+import { SuperDocCliError } from './errors.js';
+export const NOTIFICATIONS_LAGGED = 'NOTIFICATIONS_LAGGED';
+export const DEFAULT_NOTIFICATION_CAPACITY = 64;
+const LAGGED_MESSAGE = 'resynchronize document state before using notification-derived caches';
+const RESYNC_HINT = 'Call changes.list with the cursor of the last change record you processed.';
+export class HostNotifications {
+    capacity;
+    detach;
+    queue = [];
+    waiters = [];
+    skipped = 0;
+    failure = null;
+    closed = false;
+    constructor(capacity, detach) {
+        this.capacity = capacity;
+        this.detach = detach;
+    }
+    next() {
+        if (this.skipped > 0) {
+            const skipped = this.skipped;
+            this.skipped = 0;
+            return Promise.reject(new SuperDocCliError(LAGGED_MESSAGE, {
+                code: NOTIFICATIONS_LAGGED,
+                details: { skipped, resync: RESYNC_HINT },
+            }));
+        }
+        const notification = this.queue.shift();
+        if (notification)
+            return Promise.resolve({ done: false, value: notification });
+        if (this.failure) {
+            const failure = this.failure;
+            this.failure = null;
+            return Promise.reject(failure);
+        }
+        if (this.closed)
+            return Promise.resolve({ done: true, value: undefined });
+        return new Promise((resolve, reject) => this.waiters.push({ resolve, reject }));
+    }
+    return() {
+        this.close();
+        return Promise.resolve({ done: true, value: undefined });
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.queue.length = 0;
+        this.skipped = 0;
+        this.failure = null;
+        this.detach(this);
+        for (const waiter of this.waiters.splice(0))
+            waiter.resolve({ done: true, value: undefined });
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+    get isClosed() {
+        return this.closed;
+    }
+    deliver(notification) {
+        if (this.closed)
+            return;
+        const waiter = this.waiters.shift();
+        if (waiter) {
+            waiter.resolve({ done: false, value: notification });
+            return;
+        }
+        if (this.queue.length >= this.capacity) {
+            this.queue.shift();
+            this.skipped += 1;
+        }
+        this.queue.push(notification);
+    }
+    fail(error) {
+        if (this.closed)
+            return;
+        const waiter = this.waiters.shift();
+        if (waiter) {
+            waiter.reject(error);
+            return;
+        }
+        this.failure = error;
+    }
+}
+export class HostNotificationHub {
+    subscriptions = new Set();
+    subscribe(options = {}) {
+        const capacity = options.capacity ?? DEFAULT_NOTIFICATION_CAPACITY;
+        if (!Number.isSafeInteger(capacity) || capacity < 1) {
+            throw new SuperDocCliError('Notification capacity must be a positive integer.', {
+                code: 'INVALID_ARGUMENT',
+                details: { capacity },
+            });
+        }
+        const subscription = new HostNotifications(capacity, (closed) => this.subscriptions.delete(closed));
+        this.subscriptions.add(subscription);
+        return subscription;
+    }
+    publish(frame) {
+        if (this.subscriptions.size === 0 || typeof frame.method !== 'string')
+            return;
+        const notification = frame.params === undefined
+            ? { jsonrpc: '2.0', method: frame.method }
+            : { jsonrpc: '2.0', method: frame.method, params: frame.params };
+        for (const subscription of this.subscriptions)
+            subscription.deliver(notification);
+    }
+    disconnect(error) {
+        for (const subscription of this.subscriptions)
+            subscription.fail(error);
+    }
+    close() {
+        for (const subscription of [...this.subscriptions])
+            subscription.close();
+    }
+}

package/dist/runtime/process.cjs

@@ -16,7 +16,7 @@ function resolveRuntimeProcess(options = {}, embedded = {
     };
 }
 function toSafeInvokeTraceOptions(options) {
-    const { collaborationAuth: _collaborationAuth, ...traceOptions } = options;
+    const { collaborationAuth: _collaborationAuth, identityClaim: _identityClaim, ...traceOptions } = options;
     return traceOptions;
 }
 class SuperDocRuntime {
@@ -31,6 +31,9 @@ class SuperDocRuntime {
     async connect() {
         await this.transport.connect();
     }
+    subscribe(options = {}) {
+        return this.transport.subscribe(options);
+    }
     supportsDocumentFacts(sessionId) {
         return this.transport.supportsDocumentFacts(sessionId);
     }

package/dist/runtime/process.d.ts

@@ -1,3 +1,4 @@
+import type { HostNotifications, SubscribeOptions } from './notifications.js';
 import type { CollaborationAuth, DocumentRuntimeKind, DocOpenOptions, InvokeOptions, TransportInvokeOptions, OperationParamSpec, OperationSpec, RuntimeInvoker, SuperDocClientOptions } from './transport-common.js';
 type RuntimeProcessResolution = {
     hostBin: string;
@@ -24,6 +25,7 @@ export declare class SuperDocRuntime {
     private readonly transport;
     constructor(options?: SuperDocClientOptions);
     connect(): Promise<void>;
+    subscribe(options?: SubscribeOptions): HostNotifications;
     supportsDocumentFacts(sessionId: string): boolean;
     usesCliDocumentFacts(sessionId: string): boolean;
     readDocumentRevision(sessionId: string): Promise<string | undefined>;

package/dist/runtime/process.js

@@ -13,7 +13,7 @@ export function resolveRuntimeProcess(options = {}, embedded = {
     };
 }
 export function toSafeInvokeTraceOptions(options) {
-    const { collaborationAuth: _collaborationAuth, ...traceOptions } = options;
+    const { collaborationAuth: _collaborationAuth, identityClaim: _identityClaim, ...traceOptions } = options;
     return traceOptions;
 }
 export class SuperDocRuntime {
@@ -28,6 +28,9 @@ export class SuperDocRuntime {
     async connect() {
         await this.transport.connect();
     }
+    subscribe(options = {}) {
+        return this.transport.subscribe(options);
+    }
     supportsDocumentFacts(sessionId) {
         return this.transport.supportsDocumentFacts(sessionId);
     }

package/dist/runtime/sdk-policy.d.ts

@@ -5,6 +5,7 @@ export declare const SDK_POLICY: {
         replaceFile: string;
         requestTimeout: string;
         collaborationAuthPerOpen: string;
+        identityClaimPerOpen: string;
     };
     operationParamAliases: Record<string, Readonly<Record<string, readonly string[]>>>;
     notifications: readonly string[];

package/dist/runtime/sdk-version.generated.cjs

@@ -3,6 +3,6 @@
 // AUTO-GENERATED by scripts/embed-version.mjs — DO NOT EDIT.
 // Source of truth: package.json. Regenerated on every SDK build so the
 // SDK retains its own version identity when bundled into another package.
-const SDK_VERSION = '2.26.0';
+const SDK_VERSION = '2.27.0-next.4';
 
 exports.SDK_VERSION = SDK_VERSION;

package/dist/runtime/sdk-version.generated.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "2.26.0";
+export declare const SDK_VERSION = "2.27.0-next.4";

package/dist/runtime/sdk-version.generated.js

@@ -1,4 +1,4 @@
 // AUTO-GENERATED by scripts/embed-version.mjs — DO NOT EDIT.
 // Source of truth: package.json. Regenerated on every SDK build so the
 // SDK retains its own version identity when bundled into another package.
-export const SDK_VERSION = '2.26.0';
+export const SDK_VERSION = '2.27.0-next.4';