@runtimed/node 0.5.4 → 0.5.6-nightly.36505591006

package/src/execution-store.cjs

@@ -0,0 +1,397 @@
+// Generated by scripts/build-execution-store.mjs. Do not edit.
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createNotebookExecutionStore = createNotebookExecutionStore;
+const EMPTY_NOTEBOOK_QUEUE = Object.freeze({
+    executing_cell_id: null,
+    queued_cell_ids: Object.freeze([]),
+});
+/** Independent synchronous notebook state. Construction performs no I/O. */
+function createNotebookExecutionStore() {
+    const _executionMap = new Map();
+    const _runtimeOwnedExecutionIds = new Set();
+    /** Per-cell reverse index: cell_id -> latest execution_id. */
+    const _cellToExecution = new Map();
+    const _executionToCell = new Map();
+    let _notebookQueueProjection = EMPTY_NOTEBOOK_QUEUE;
+    let _queue = null;
+    let _snapshot;
+    const _subscribers = new Map();
+    const _cellExecutionSubscribers = new Map();
+    const _queueProjectionSubscribers = new Set();
+    let _executionStructureVersion = 0;
+    const _executionStructureVersionSubscribers = new Set();
+    function emitExecutionChange(execution_id) {
+        const subs = _subscribers.get(execution_id);
+        if (!subs)
+            return;
+        // Snapshot listeners so subscriptions added during delivery wait for the next notification.
+        // eslint-disable-next-line unicorn/no-useless-spread
+        for (const cb of [...subs]) {
+            if (!subs.has(cb))
+                continue;
+            try {
+                cb();
+            }
+            catch {
+                // subscriber errors must not break the dispatch loop
+            }
+        }
+    }
+    function emitCellExecutionPointerChange(cell_id) {
+        const subs = _cellExecutionSubscribers.get(cell_id);
+        if (!subs)
+            return;
+        // Snapshot listeners so subscriptions added during delivery wait for the next notification.
+        // eslint-disable-next-line unicorn/no-useless-spread
+        for (const cb of [...subs]) {
+            if (!subs.has(cb))
+                continue;
+            try {
+                cb();
+            }
+            catch { }
+        }
+    }
+    function emitQueueProjectionChange() {
+        // Snapshot listeners so subscriptions added during delivery wait for the next notification.
+        // eslint-disable-next-line unicorn/no-useless-spread
+        for (const cb of [..._queueProjectionSubscribers]) {
+            if (!_queueProjectionSubscribers.has(cb))
+                continue;
+            try {
+                cb();
+            }
+            catch { }
+        }
+    }
+    function emitExecutionStructureChange() {
+        _executionStructureVersion = (_executionStructureVersion + 1) | 0;
+        // Snapshot listeners so subscriptions added during delivery wait for the next notification.
+        // eslint-disable-next-line unicorn/no-useless-spread
+        for (const cb of [..._executionStructureVersionSubscribers]) {
+            if (!_executionStructureVersionSubscribers.has(cb))
+                continue;
+            try {
+                cb();
+            }
+            catch { }
+        }
+    }
+    // ── Subscription helpers ────────────────────────────────────────────────
+    function subscribeExecutionById(execution_id) {
+        return (callback) => {
+            let subs = _subscribers.get(execution_id);
+            if (!subs) {
+                subs = new Set();
+                _subscribers.set(execution_id, subs);
+            }
+            const set = subs;
+            set.add(callback);
+            let active = true;
+            return () => {
+                if (!active)
+                    return;
+                active = false;
+                set.delete(callback);
+                if (set.size === 0 && _subscribers.get(execution_id) === set)
+                    _subscribers.delete(execution_id);
+            };
+        };
+    }
+    function getExecutionSnapshotGetter(execution_id) {
+        return () => (execution_id ? _executionMap.get(execution_id) : undefined);
+    }
+    function subscribeCellExecutionPointer(cell_id) {
+        return (callback) => {
+            let subs = _cellExecutionSubscribers.get(cell_id);
+            if (!subs) {
+                subs = new Set();
+                _cellExecutionSubscribers.set(cell_id, subs);
+            }
+            const set = subs;
+            set.add(callback);
+            let active = true;
+            return () => {
+                if (!active)
+                    return;
+                active = false;
+                set.delete(callback);
+                if (set.size === 0 && _cellExecutionSubscribers.get(cell_id) === set)
+                    _cellExecutionSubscribers.delete(cell_id);
+            };
+        };
+    }
+    function getCellExecutionIdGetter(cell_id) {
+        return () => _cellToExecution.get(cell_id) ?? null;
+    }
+    function subscribeNotebookQueueProjection(callback) {
+        _queueProjectionSubscribers.add(callback);
+        let active = true;
+        return () => {
+            if (!active)
+                return;
+            active = false;
+            _queueProjectionSubscribers.delete(callback);
+        };
+    }
+    function getNotebookQueueProjection() {
+        return _notebookQueueProjection;
+    }
+    function subscribeExecutionStructureVersion(callback) {
+        _executionStructureVersionSubscribers.add(callback);
+        let active = true;
+        return () => {
+            if (!active)
+                return;
+            active = false;
+            _executionStructureVersionSubscribers.delete(callback);
+        };
+    }
+    function getExecutionStructureVersionSnapshot() {
+        return _executionStructureVersion;
+    }
+    // ── Write operations ────────────────────────────────────────────────────
+    /**
+     * Upsert an execution snapshot. Notifies only that execution's subscribers.
+     *
+     * Does NOT update the cell -> execution pointer. `RuntimeStateDoc` keeps
+     * historical executions per cell, so iterating it cannot reliably pick
+     * the current one. Callers set the cell pointer explicitly via
+     * `setCellExecutionPointer`, driven by the canonical `cells/{id}/execution_id`
+     * field in the notebook doc.
+     */
+    function setExecution(execution_id, snap) {
+        const prev = _executionMap.get(execution_id);
+        const sameOutputs = prev !== undefined && stringArraysEqual(prev.output_ids, snap.output_ids);
+        if (prev &&
+            sameOutputs &&
+            prev.execution_count === snap.execution_count &&
+            prev.status === snap.status &&
+            prev.success === snap.success &&
+            (prev.submitted_by_actor_label ?? null) === (snap.submitted_by_actor_label ?? null))
+            return;
+        const owned = Object.freeze({
+            ...snap,
+            output_ids: sameOutputs ? prev.output_ids : Object.freeze([...snap.output_ids]),
+        });
+        _executionMap.set(execution_id, owned);
+        _snapshot = undefined;
+        emitExecutionChange(execution_id);
+        if (!prev || prev.execution_count !== snap.execution_count || !sameOutputs)
+            emitExecutionStructureChange();
+    }
+    /**
+     * Mark execution snapshots whose authoritative source is RuntimeStateDoc.
+     *
+     * Projection placeholders can seed the same execution id before runtime sync
+     * catches up. Runtime upserts call this even when the snapshot is unchanged so
+     * projector cleanup can release ownership without deleting the runtime record.
+     */
+    function markExecutionsRuntimeOwned(execution_ids) {
+        for (const execution_id of execution_ids) {
+            _runtimeOwnedExecutionIds.add(execution_id);
+        }
+    }
+    function isExecutionRuntimeOwned(execution_id) {
+        return _runtimeOwnedExecutionIds.has(execution_id);
+    }
+    /**
+     * Explicitly set the active execution_id for a cell.
+     *
+     * Used on execution_started broadcasts and on clearOutputs (pass null).
+     */
+    function setCellExecutionPointer(cell_id, execution_id) {
+        const prev = _cellToExecution.get(cell_id) ?? null;
+        if (prev === execution_id)
+            return;
+        if (prev !== null && _executionToCell.get(prev) === cell_id) {
+            _executionToCell.delete(prev);
+        }
+        if (execution_id === null) {
+            _cellToExecution.delete(cell_id);
+        }
+        else {
+            _cellToExecution.set(cell_id, execution_id);
+            _executionToCell.set(execution_id, cell_id);
+        }
+        _snapshot = undefined;
+        emitCellExecutionPointerChange(cell_id);
+        emitExecutionStructureChange();
+    }
+    function setNotebookQueueProjection(projection) {
+        const next = notebookQueuesEqual(_notebookQueueProjection, projection)
+            ? _notebookQueueProjection
+            : Object.freeze({
+                executing_cell_id: projection.executing_cell_id,
+                queued_cell_ids: Object.freeze([...projection.queued_cell_ids]),
+            });
+        // A cell-only projection cannot invent execution queue membership, but it
+        // must keep an existing aggregate queue current before notifying readers.
+        if (_queue && !notebookQueuesEqual(_queue.notebook, next)) {
+            _queue = Object.freeze({ ..._queue, notebook: next });
+            _snapshot = undefined;
+        }
+        updateNotebookQueueProjection(next);
+    }
+    /** Accept an owned projection; wire updates preserve absent/null adapters. */
+    function updateNotebookQueueProjection(projection) {
+        if (notebookQueuesEqual(_notebookQueueProjection, projection))
+            return;
+        _notebookQueueProjection = projection;
+        emitQueueProjectionChange();
+    }
+    /**
+     * Drop a batch of executions from the store.
+     *
+     * Notifies per-execution subscribers with `undefined` and clears any cell
+     * pointer that referenced one of the removed ids. Used by the projection
+     * when the daemon trims an execution out of `RuntimeStateDoc` so the
+     * store doesn't drift monotonically larger.
+     */
+    function deleteExecutions(execution_ids) {
+        for (const eid of execution_ids) {
+            const existed = _executionMap.delete(eid);
+            _runtimeOwnedExecutionIds.delete(eid);
+            const cellId = _executionToCell.get(eid);
+            _executionToCell.delete(eid);
+            const cleared = cellId !== undefined && _cellToExecution.get(cellId) === eid;
+            if (cleared)
+                _cellToExecution.delete(cellId);
+            if (!existed && !cleared)
+                continue;
+            _snapshot = undefined;
+            if (existed)
+                emitExecutionChange(eid);
+            if (cleared)
+                emitCellExecutionPointerChange(cellId);
+            emitExecutionStructureChange();
+        }
+    }
+    /** Read a snapshot without subscribing. */
+    function getExecutionById(execution_id) {
+        return _executionMap.get(execution_id);
+    }
+    /** Read the cell's current execution_id without subscribing. */
+    function getCellExecutionId(cell_id) {
+        return _cellToExecution.get(cell_id) ?? null;
+    }
+    /** Read the current cell id for an execution pointer without subscribing. */
+    function getCellIdForExecutionId(execution_id) {
+        return _executionToCell.get(execution_id) ?? null;
+    }
+    /** Reset the entire store. Called on notebook switch or full reset. */
+    function resetNotebookExecutions() {
+        const eids = [..._executionMap.keys()];
+        const cells = [..._cellToExecution.keys()];
+        _executionMap.clear();
+        _runtimeOwnedExecutionIds.clear();
+        _cellToExecution.clear();
+        _executionToCell.clear();
+        _notebookQueueProjection = EMPTY_NOTEBOOK_QUEUE;
+        _queue = null;
+        _snapshot = undefined;
+        for (const eid of eids)
+            emitExecutionChange(eid);
+        for (const cid of cells)
+            emitCellExecutionPointerChange(cid);
+        emitQueueProjectionChange();
+        if (eids.length > 0 || cells.length > 0) {
+            emitExecutionStructureChange();
+        }
+    }
+    function stringArraysEqual(a, b) {
+        if (a.length !== b.length)
+            return false;
+        for (let i = 0; i < a.length; i++) {
+            if (a[i] !== b[i])
+                return false;
+        }
+        return true;
+    }
+    /** Lazily materialize a stable, immutable aggregate for headless consumers. */
+    function getSnapshot() {
+        return (_snapshot ??= Object.freeze({
+            cell_execution_ids: Object.freeze(Object.fromEntries(_cellToExecution)),
+            executions: Object.freeze(Object.fromEntries(_executionMap)),
+            queue: _queue,
+        }));
+    }
+    /**
+     * Apply Rust's projection in frontend order: upserts, removals, pointers, queue.
+     * Notifications are synchronous per write, not an atomic changeset batch.
+     * Reads inside notifications are current; retained snapshots never change.
+     */
+    function applyChangeset(changeset, options = {}) {
+        if (!changeset)
+            return;
+        for (const [id, snapshot] of changeset.execution_upserts ?? []) {
+            markExecutionsRuntimeOwned([id]);
+            setExecution(id, snapshot);
+            options.onExecutionSnapshot?.(id, getExecutionById(id));
+        }
+        deleteExecutions(changeset.removed_execution_ids ?? []);
+        for (const [cell, id] of changeset.cell_pointer_changes ?? [])
+            setCellExecutionPointer(cell, id);
+        if (Object.prototype.hasOwnProperty.call(changeset, "queue")) {
+            const queue = changeset.queue;
+            const next = queue == null
+                ? null
+                : Object.freeze({
+                    executing_execution_id: queue.executing_execution_id ?? null,
+                    queued_execution_ids: Object.freeze([...queue.queued_execution_ids]),
+                    notebook: queue.notebook == null
+                        ? queue.notebook
+                        : Object.freeze({
+                            executing_cell_id: queue.notebook.executing_cell_id ?? null,
+                            queued_cell_ids: Object.freeze([...queue.notebook.queued_cell_ids]),
+                        }),
+                });
+            if (!queuesEqual(_queue, next)) {
+                _queue = next;
+                _snapshot = undefined;
+            }
+            updateNotebookQueueProjection(next?.notebook ?? EMPTY_NOTEBOOK_QUEUE);
+        }
+    }
+    function queuesEqual(a, b) {
+        if (a === b)
+            return true;
+        if (!a || !b)
+            return false;
+        if (a.executing_execution_id !== b.executing_execution_id ||
+            !stringArraysEqual(a.queued_execution_ids, b.queued_execution_ids))
+            return false;
+        return notebookQueuesEqual(a.notebook, b.notebook);
+    }
+    function notebookQueuesEqual(a, b) {
+        if (a === b)
+            return true;
+        if (!a || !b)
+            return false;
+        return (a.executing_cell_id === b.executing_cell_id &&
+            stringArraysEqual(a.queued_cell_ids, b.queued_cell_ids));
+    }
+    return {
+        subscribeNotebookQueueProjection,
+        getNotebookQueueProjection,
+        setExecution,
+        markExecutionsRuntimeOwned,
+        isExecutionRuntimeOwned,
+        setCellExecutionPointer,
+        setNotebookQueueProjection,
+        deleteExecutions,
+        getExecutionById,
+        getCellExecutionId,
+        getCellIdForExecutionId,
+        resetNotebookExecutions,
+        subscribeExecutionById,
+        getExecutionSnapshotGetter,
+        subscribeCellExecutionPointer,
+        getCellExecutionIdGetter,
+        subscribeExecutionStructureVersion,
+        getExecutionStructureVersionSnapshot,
+        getSnapshot,
+        applyChangeset,
+    };
+}

package/src/execution-store.d.cts

@@ -0,0 +1,66 @@
+// Generated by scripts/build-execution-store.mjs. Do not edit.
+export interface ExecutionViewSnapshot {
+    execution_count: number | null;
+    status: "queued" | "running" | "done" | "error" | "cancelled" | (string & {});
+    success: boolean | null;
+    output_ids: string[];
+    submitted_by_actor_label?: string | null;
+}
+export interface ExecutionQueueProjection {
+    executing_execution_id?: string | null;
+    queued_execution_ids: string[];
+    notebook?: {
+        executing_cell_id?: string | null;
+        queued_cell_ids: string[];
+    } | null;
+}
+export interface ExecutionViewChangeset {
+    cell_pointer_changes?: Array<[cell_id: string, execution_id: string | null]>;
+    execution_upserts?: Array<[execution_id: string, snapshot: ExecutionViewSnapshot]>;
+    removed_execution_ids?: string[];
+    queue?: ExecutionQueueProjection | null;
+}
+/** Immutable consumer snapshots; wire payload types above remain mutable. */
+export type ExecutionSnapshot = Readonly<Omit<ExecutionViewSnapshot, "output_ids">> & {
+    readonly output_ids: readonly string[];
+};
+export interface NotebookQueueProjectionSnapshot {
+    readonly executing_cell_id: string | null;
+    readonly queued_cell_ids: readonly string[];
+}
+export interface ExecutionQueueSnapshot {
+    readonly executing_execution_id: string | null;
+    readonly queued_execution_ids: readonly string[];
+    readonly notebook?: NotebookQueueProjectionSnapshot | null;
+}
+export interface ExecutionView {
+    readonly cell_execution_ids: Readonly<Record<string, string>>;
+    readonly executions: Readonly<Record<string, ExecutionSnapshot>>;
+    readonly queue: ExecutionQueueSnapshot | null;
+}
+/** Independent synchronous notebook state. Construction performs no I/O. */
+export declare function createNotebookExecutionStore(): {
+    subscribeNotebookQueueProjection: (callback: () => void) => () => void;
+    getNotebookQueueProjection: () => NotebookQueueProjectionSnapshot;
+    setExecution: (execution_id: string, snap: ExecutionSnapshot) => void;
+    markExecutionsRuntimeOwned: (execution_ids: Iterable<string>) => void;
+    isExecutionRuntimeOwned: (execution_id: string) => boolean;
+    setCellExecutionPointer: (cell_id: string, execution_id: string | null) => void;
+    setNotebookQueueProjection: (projection: NotebookQueueProjectionSnapshot) => void;
+    deleteExecutions: (execution_ids: Iterable<string>) => void;
+    getExecutionById: (execution_id: string) => ExecutionSnapshot | undefined;
+    getCellExecutionId: (cell_id: string) => string | null;
+    getCellIdForExecutionId: (execution_id: string) => string | null;
+    resetNotebookExecutions: () => void;
+    subscribeExecutionById: (execution_id: string) => (cb: () => void) => () => void;
+    getExecutionSnapshotGetter: (execution_id: string) => () => ExecutionSnapshot | undefined;
+    subscribeCellExecutionPointer: (cell_id: string) => (cb: () => void) => () => void;
+    getCellExecutionIdGetter: (cell_id: string) => () => string | null;
+    subscribeExecutionStructureVersion: (callback: () => void) => () => void;
+    getExecutionStructureVersionSnapshot: () => number;
+    getSnapshot: () => ExecutionView;
+    applyChangeset: (changeset: ExecutionViewChangeset | null | undefined, options?: {
+        onExecutionSnapshot?: (id: string, snapshot: ExecutionSnapshot) => void;
+    }) => void;
+};
+export type NotebookExecutionStore = ReturnType<typeof createNotebookExecutionStore>;

package/src/index.d.ts

@@ -1,6 +1,6 @@
 import type { Observable } from "rxjs";
 
-export { RelaySession, connectRelay, createRelay, openRelayPath } from "./relay";
+export { RelaySession, connectRelay, createRelay, openRelayPath, queryDaemonInfo } from "./relay";
 export type {
   CommentsNotebookRef,
   CreateRelayOptions,
@@ -11,16 +11,14 @@ export type {
   RelayInfo,
 } from "./relay";
 
-export type NotebookDocPhase = "pending" | "syncing" | "interactive";
-export type RuntimeStatePhase = "pending" | "syncing" | "ready";
+export type ConnectionState = "Connected" | "Disconnected";
+export type NotebookDocPhase = "Pending" | "Syncing" | "Interactive";
+export type RuntimeStatePhase = "Pending" | "Syncing" | "Ready";
 
-export type InitialLoadPhase =
-  | { phase: "not_needed" }
-  | { phase: "streaming" }
-  | { phase: "ready" }
-  | { phase: "failed"; reason: string };
+export type InitialLoadPhase = "NotNeeded" | "Streaming" | "Ready" | { Failed: { reason: string } };
 
 export interface SessionStatus {
+  connection: ConnectionState;
   notebook_doc: NotebookDocPhase;
   runtime_state: RuntimeStatePhase;
   initial_load: InitialLoadPhase;
@@ -32,41 +30,20 @@ export interface ExecutionTransition {
   execution_count: number | null;
 }
 
-export interface ExecutionViewSnapshot {
-  execution_count: number | null;
-  status: "queued" | "running" | "done" | "error" | (string & {});
-  success: boolean | null;
-  output_ids: string[];
-  submitted_by_actor_label?: string | null;
-}
-
-export interface ExecutionQueueProjection {
-  executing_execution_id?: string | null;
-  queued_execution_ids: string[];
-  notebook?: {
-    executing_cell_id?: string | null;
-    queued_cell_ids: string[];
-  } | null;
-}
-
-export interface ExecutionViewChangeset {
-  cell_pointer_changes?: Array<[cell_id: string, execution_id: string | null]>;
-  execution_upserts?: Array<[execution_id: string, snapshot: ExecutionViewSnapshot]>;
-  removed_execution_ids?: string[];
-  queue?: ExecutionQueueProjection;
-}
-
-export interface ExecutionView {
-  /**
-   * Current non-null NotebookDoc cell -> execution_id pointers.
-   *
-   * Cleared or deleted cells are omitted. Subscribe to `executionViewChanges$`
-   * when null pointer transitions matter.
-   */
-  cell_execution_ids: Record<string, string>;
-  executions: Record<string, ExecutionViewSnapshot>;
-  queue: ExecutionQueueProjection | null;
-}
+import type {
+  ExecutionViewChangeset,
+  ExecutionView,
+  NotebookExecutionStore,
+} from "./execution-store.cjs";
+export type {
+  ExecutionViewSnapshot,
+  ExecutionQueueProjection,
+  ExecutionViewChangeset,
+  ExecutionSnapshot,
+  ExecutionQueueSnapshot,
+  ExecutionView,
+  NotebookExecutionStore,
+} from "./execution-store.cjs";
 
 export type RuntimeState = Record<string, unknown>;
 
@@ -247,6 +224,14 @@ export class Session {
   runCell(source: string, options?: RunCellOptions): Promise<CellResult>;
   saveNotebook(path?: string): Promise<void>;
   exportSnapshotPair(): Promise<SnapshotPair>;
+  /**
+   * Return the current NotebookDoc heads after the connected daemon accepts them.
+   * Later edits are not covered. Rejects on timeout, close, disconnect, rejection,
+   * and unsupported peers (including hosted bridges). Persistent local rooms
+   * preserve recovery-journal-before-acceptance; ephemeral rooms promise acceptance
+   * only. Does not export an .ipynb or acknowledge runtime, comments, or widgets.
+   */
+  confirmNotebookSync(): Promise<string[]>;
   listCells(): Promise<CellSnapshot[]>;
   getCell(cellId: string): Promise<CellSnapshot | null>;
   createCell(source: string, options?: CreateCellOptions): Promise<string>;
@@ -265,7 +250,9 @@ export class Session {
   removeDependencies(packages: string[], options?: DependencyEditOptions): Promise<number>;
   getDependencyStatus(): Promise<DependencyStatus>;
   getRuntimeStatus(): Promise<RuntimeStatus>;
+  /** Stable immutable state; explicitly copy it if mutable ownership is needed. */
   getExecutionView(): ExecutionView;
+  readonly executions: NotebookExecutionStore;
   dependencyFingerprint(): Promise<string | null>;
   approveTrust(observedHeads?: string[]): Promise<void>;
   syncEnvironment(): Promise<void>;
@@ -276,6 +263,28 @@ export const NativeSession: unknown;
 
 export function defaultSocketPath(): string;
 export function socketPathForChannel(channel: "stable" | "nightly"): string;
+
+export interface InitializeEnvironmentYmlOptions {
+  /** Existing absolute directory the local host is authorized to write. */
+  directory: string;
+  /** Optional name containing only letters, numbers, '.', '_' and '-'. */
+  name?: string;
+  /** Conda match specs. Pip subsections are not supported by this initializer. */
+  dependencies: string[];
+  /** Python version constraint, e.g. "3.12" or ">=3.11,<3.13". */
+  python?: string;
+  /** At least one channel, in priority order. No channels are inferred. */
+  channels: string[];
+}
+
+/**
+ * Explicitly create environment.yml using the local host's filesystem authority.
+ * Returns its filesystem-canonical absolute path. Rejects existing files/symlinks.
+ * Checks for environment.yaml first; hosts must coordinate other writers of it.
+ * Does not install packages, approve trust, contact a daemon or change a kernel.
+ */
+export function initializeEnvironmentYml(options: InitializeEnvironmentYmlOptions): Promise<string>;
+
 export function createNotebook(options?: CreateNotebookOptions): Promise<Session>;
 export function openNotebook(notebookId: string, options?: OpenNotebookOptions): Promise<Session>;
 export function openNotebookPath(path: string, options?: OpenNotebookOptions): Promise<Session>;

package/src/relay.d.ts

@@ -32,6 +32,11 @@ export interface QueryDaemonOptions {
 
 export interface DaemonInfo {
   version: string;
+  protocolVersion: number;
+  /** Zero means the daemon predates semantic API version reporting. */
+  daemonApiVersion: number;
+  /** Shared Rust compatibility diagnostic; absent when supported by this client. */
+  compatibilityError?: string;
   socketPath: string;
   isDevMode: boolean;
   blobPort?: number;
@@ -82,5 +87,9 @@ export function connectRelay(notebookId: string, options?: OpenRelayOptions): Pr
 export function defaultSocketPath(): string;
 /** Resolve a stable or nightly daemon endpoint independently of this package's build channel. */
 export function socketPathForChannel(channel: "stable" | "nightly"): string;
-/** Return null until the selected daemon is ready to answer pool requests. */
+/**
+ * Return null when metadata is unavailable. A responding incompatible daemon
+ * returns metadata with compatibilityError. This probe does not authenticate
+ * a process or guarantee compatibility of a later notebook connection.
+ */
 export function queryDaemonInfo(options?: QueryDaemonOptions): Promise<DaemonInfo | null>;