@atelierai/uco 1.0.0

package/dist/server/ws/pending.js

@@ -0,0 +1,242 @@
+/**
+ * Bounded pending request correlation. Unity owns durable operations; every map
+ * here is ephemeral and is removed by one atomic settle path.
+ */
+import { ErrorCode } from './envelope.js';
+export const MAX_PENDING_PROCESS = 1024;
+export const MAX_PENDING_PER_CONNECTION = 256;
+export class PendingTracker {
+    byEnvelopeId = new Map();
+    byRequestID = new Map();
+    byOperationID = new Map();
+    byConnection = new Map();
+    track(id, timeoutMs, method, connectionId, options) {
+        const trackOptions = isAbortSignal(options)
+            ? { signal: options }
+            : (options ?? {});
+        if (this.byEnvelopeId.has(id)) {
+            throw capacityError('Duplicate pending envelope identity.');
+        }
+        if (this.byEnvelopeId.size >= MAX_PENDING_PROCESS) {
+            throw capacityError('Process pending request capacity is full.');
+        }
+        if (connectionId && (this.byConnection.get(connectionId)?.size ?? 0) >= MAX_PENDING_PER_CONNECTION) {
+            throw capacityError('Connection pending request capacity is full.');
+        }
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.settle(id, {
+                    type: 'reject',
+                    error: trackOptions.timeoutError ?? {
+                        code: ErrorCode.PLUGIN_TIMEOUT,
+                        message: `Plugin timed out after ${timeoutMs}ms for method '${method}'`,
+                    },
+                });
+            }, timeoutMs);
+            const entry = {
+                id,
+                resolve: resolve,
+                reject: reject,
+                timer,
+                method,
+                connectionId,
+                requestID: boundIdentity(trackOptions.requestID),
+                operationID: boundIdentity(trackOptions.operationID),
+                callId: boundIdentity(trackOptions.callId),
+                cancellationId: boundIdentity(trackOptions.cancellationId),
+                generation: trackOptions.generation,
+                signal: trackOptions.signal,
+                onAbortAfterDispatch: trackOptions.onAbortAfterDispatch,
+                onResolved: trackOptions.onResolved,
+                dispatched: false,
+                cancellationSent: false,
+            };
+            this.byEnvelopeId.set(id, entry);
+            this.addIndex(this.byConnection, connectionId, id);
+            this.addIndex(this.byRequestID, entry.requestID, id);
+            this.addIndex(this.byOperationID, entry.operationID, id);
+            if (trackOptions.signal) {
+                const onAbort = () => {
+                    const current = this.byEnvelopeId.get(id);
+                    if (!current)
+                        return;
+                    if (current.dispatched && !current.cancellationSent && current.onAbortAfterDispatch) {
+                        current.cancellationSent = true;
+                        current.onAbortAfterDispatch(identity(current));
+                    }
+                    this.settle(id, {
+                        type: 'reject',
+                        error: trackOptions.abortError ?? {
+                            code: ErrorCode.CALL_CANCELLED,
+                            message: 'Tool call was cancelled by the caller.',
+                        },
+                    });
+                };
+                entry.onAbort = onAbort;
+                if (trackOptions.signal.aborted)
+                    onAbort();
+                else
+                    trackOptions.signal.addEventListener('abort', onAbort, { once: true });
+            }
+        });
+    }
+    markDispatched(id) {
+        const entry = this.byEnvelopeId.get(id);
+        if (!entry)
+            return false;
+        entry.dispatched = true;
+        return true;
+    }
+    trackDeferred(requestID, envelopeId, operationID) {
+        const entry = this.byEnvelopeId.get(envelopeId);
+        if (!entry)
+            return;
+        const nextRequest = boundIdentity(requestID);
+        const nextOperation = boundIdentity(operationID);
+        if (entry.requestID !== nextRequest) {
+            this.removeIndex(this.byRequestID, entry.requestID, envelopeId);
+            entry.requestID = nextRequest;
+            this.addIndex(this.byRequestID, entry.requestID, envelopeId);
+        }
+        if (entry.operationID !== nextOperation) {
+            this.removeIndex(this.byOperationID, entry.operationID, envelopeId);
+            entry.operationID = nextOperation;
+            this.addIndex(this.byOperationID, entry.operationID, envelopeId);
+        }
+    }
+    resolve(id, result) {
+        return this.settle(id, { type: 'resolve', result });
+    }
+    bindOperation(id, operationID) {
+        const entry = this.byEnvelopeId.get(id);
+        const bounded = boundIdentity(operationID);
+        if (!entry || !bounded)
+            return false;
+        if (entry.operationID === bounded)
+            return true;
+        this.removeIndex(this.byOperationID, entry.operationID, id);
+        entry.operationID = bounded;
+        this.addIndex(this.byOperationID, bounded, id);
+        return true;
+    }
+    resolveDeferred(requestID, result, operationID) {
+        const requestMatches = this.byRequestID.get(requestID);
+        let candidates = requestMatches ? [...requestMatches] : [];
+        if (operationID) {
+            candidates = candidates.filter((id) => {
+                const entry = this.byEnvelopeId.get(id);
+                return entry !== undefined
+                    && (entry.operationID === undefined || entry.operationID === operationID);
+            });
+        }
+        // Request-only legacy completion is accepted only when it maps uniquely.
+        // A new peer may introduce operation identity on this completion; bind it
+        // atomically only after the request mapping itself is unambiguous.
+        if (candidates.length !== 1)
+            return false;
+        const entry = this.byEnvelopeId.get(candidates[0]);
+        if (!entry)
+            return false;
+        if (operationID) {
+            if (entry.operationID && entry.operationID !== operationID)
+                return false;
+            if (!entry.operationID)
+                this.bindOperation(entry.id, operationID);
+        }
+        return this.resolve(entry.id, result);
+    }
+    reject(id, error) {
+        return this.settle(id, { type: 'reject', error });
+    }
+    rejectAllForConnection(connectionId, error) {
+        const ids = [...(this.byConnection.get(connectionId) ?? [])];
+        for (const id of ids)
+            this.reject(id, error);
+    }
+    get size() {
+        return this.byEnvelopeId.size;
+    }
+    settle(id, settlement) {
+        const entry = this.removeEntry(id);
+        if (!entry)
+            return false;
+        if (settlement.type === 'resolve') {
+            try {
+                entry.onResolved?.(settlement.result, identity(entry));
+            }
+            catch { /* observational cache hooks must never block settlement */ }
+            entry.resolve(settlement.result);
+        }
+        else {
+            entry.reject(settlement.error);
+        }
+        return true;
+    }
+    removeEntry(id) {
+        const entry = this.byEnvelopeId.get(id);
+        if (!entry)
+            return undefined;
+        this.byEnvelopeId.delete(id);
+        clearTimeout(entry.timer);
+        if (entry.signal && entry.onAbort)
+            entry.signal.removeEventListener('abort', entry.onAbort);
+        this.removeIndex(this.byRequestID, entry.requestID, id);
+        this.removeIndex(this.byOperationID, entry.operationID, id);
+        this.removeIndex(this.byConnection, entry.connectionId, id);
+        return entry;
+    }
+    addIndex(index, key, id) {
+        if (!key)
+            return;
+        let values = index.get(key);
+        if (!values) {
+            values = new Set();
+            index.set(key, values);
+        }
+        values.add(id);
+    }
+    removeIndex(index, key, id) {
+        if (!key)
+            return;
+        const values = index.get(key);
+        if (!values)
+            return;
+        values.delete(id);
+        if (values.size === 0)
+            index.delete(key);
+    }
+}
+function identity(entry) {
+    return {
+        envelopeId: entry.id,
+        requestID: entry.requestID,
+        operationID: entry.operationID,
+        callId: entry.callId,
+        cancellationId: entry.cancellationId,
+        connectionId: entry.connectionId,
+        generation: entry.generation,
+    };
+}
+function capacityError(message) {
+    return {
+        code: ErrorCode.PENDING_CAPACITY_EXCEEDED,
+        message,
+        data: {
+            code: 'operation_capacity_exceeded',
+            message,
+            retryable: true,
+            details: { retryAfterMs: 250 },
+        },
+    };
+}
+function boundIdentity(value) {
+    if (!value?.trim())
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length <= 160 ? trimmed : trimmed.slice(0, 160);
+}
+function isAbortSignal(value) {
+    return value !== undefined && typeof value === 'object'
+        && 'aborted' in value && 'addEventListener' in value;
+}
+//# sourceMappingURL=pending.js.map

package/dist/server/ws/pending.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending.js","sourceRoot":"","sources":["../../../src/server/ws/pending.ts"],"names":[],"mappings":"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"}

package/dist/server/ws/registry.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Plugin connection registry — tracks WebSocket connections and provides
+ * strategy-aware routing (token-based or first-available).
+ *
+ * Mirrors the .NET server's IConnectionStrategy + ClientUtils behavior:
+ *   auth=none  → one READY plugin is routed; a replacement takes over only
+ *                after its handshake and tool registration complete
+ *   auth=required → multiple plugins, token-routed
+ */
+import type { WebSocket } from 'ws';
+export interface EditorReadinessCache {
+    state: string;
+    ready: boolean;
+    blockers: string[];
+    retryAfterMs: number;
+    queuedSideEffects: number;
+    runningSideEffects: number;
+    queuedReads: number;
+    runningReads: number;
+    activeOperations: number;
+    observedUtc: Date;
+}
+/**
+ * Editor identity tuple captured from a `bridge-identity-v1` handshake.
+ * Undefined members (or the whole snapshot) mean the peer did not report them;
+ * constrained calls fail closed against missing members rather than passing.
+ */
+export interface ConnectionIdentity {
+    projectPath?: string;
+    editorPid?: number;
+    unityVersion?: string;
+}
+export interface ConnectionEntry {
+    connectionId: string;
+    ws: WebSocket;
+    /** Token used during auth (undefined when auth=none). */
+    token?: string;
+    /** Plugin-advertised instanceId (optional, from query/header). */
+    instanceId?: string;
+    connectedUtc: Date;
+    handshakeCompatible?: boolean;
+    handshakeUtc?: Date;
+    toolsRegisteredUtc?: Date;
+    promptsRegisteredUtc?: Date;
+    resourcesRegisteredUtc?: Date;
+    generation: number;
+    capabilities: Set<string>;
+    editorReadiness?: EditorReadinessCache;
+    /** Identity members from the handshake; present only for capability-advertising peers. */
+    identity?: ConnectionIdentity;
+}
+/**
+ * Registry of plugin WebSocket connections.
+ *
+ * Routing strategy:
+ * - When `multiPlugin` is false (auth=none), only one connection is kept.
+ *   A new connection triggers ForceDisconnect on the previous one.
+ * - When `multiPlugin` is true (auth=required), multiple connections coexist
+ *   and are routed by token.
+ */
+export declare class ConnectionRegistry {
+    private readonly multiPlugin;
+    private readonly connections;
+    private lastSuccessfulConnectionId;
+    private nextId;
+    constructor(multiPlugin: boolean);
+    /**
+     * Register a transport connection. A new single-plugin connection does not
+     * replace the current ready connection yet: replacement is promoted only by
+     * markToolsRegistered(), after a compatible handshake and runner registration.
+     * Returns the assigned connectionId.
+     */
+    register(ws: WebSocket, opts?: {
+        token?: string;
+        instanceId?: string;
+    }): string;
+    /** Remove a connection and all its index entries. */
+    unregister(connectionId: string): void;
+    get(connectionId: string): ConnectionEntry | undefined;
+    /**
+     * Adopt an instanceId reported inside the version handshake when the
+     * connection did not already carry one from the query/header. Callers that
+     * pinned the identity explicitly always win; the handshake is only a
+     * fallback source for plugins that connect without it.
+     */
+    setInstanceId(connectionId: string, instanceId: string): void;
+    markHandshake(connectionId: string, compatible: boolean, capabilities?: readonly string[], generation?: number, identity?: ConnectionIdentity): void;
+    markToolsRegistered(connectionId: string): void;
+    markPromptsRegistered(connectionId: string): void;
+    markResourcesRegistered(connectionId: string): void;
+    updateEditorReadiness(connectionId: string, value: unknown): void;
+    noteDurableOperationAccepted(connectionId: string): void;
+    getByToken(token: string): ConnectionEntry | undefined;
+    getByInstanceId(instanceId: string): ConnectionEntry | undefined;
+    /** Get the last successful connection (default routing target). */
+    getLastSuccessful(): ConnectionEntry | undefined;
+    /** A connection is routable only after compatible handshake + declared registration. */
+    isEligible(entry: ConnectionEntry | undefined): entry is ConnectionEntry;
+    /** Resolve an eligible target connection given optional session routing hints. */
+    resolve(opts?: {
+        instanceId?: string | null;
+        token?: string | null;
+    }): ConnectionEntry | undefined;
+    /** Return a snapshot of all connections (for GET /api/instances). */
+    snapshot(): ConnectionEntry[];
+    /** Number of active connections. */
+    get size(): number;
+    private isOpen;
+    private promoteIfEligible;
+    private findLatest;
+    /**
+     * Promote a ready replacement in single-plugin mode. Only older connections
+     * are retired; a newer transport that is still handshaking must not be killed
+     * merely because the older connection finished registration first.
+     */
+    private disconnectOlderConnections;
+}

package/dist/server/ws/registry.js

@@ -0,0 +1,300 @@
+/**
+ * Plugin connection registry — tracks WebSocket connections and provides
+ * strategy-aware routing (token-based or first-available).
+ *
+ * Mirrors the .NET server's IConnectionStrategy + ClientUtils behavior:
+ *   auth=none  → one READY plugin is routed; a replacement takes over only
+ *                after its handshake and tool registration complete
+ *   auth=required → multiple plugins, token-routed
+ */
+import { ClientFacingMethod } from '../types.js';
+import { makeNotification, serializeMessage } from './envelope.js';
+/**
+ * Registry of plugin WebSocket connections.
+ *
+ * Routing strategy:
+ * - When `multiPlugin` is false (auth=none), only one connection is kept.
+ *   A new connection triggers ForceDisconnect on the previous one.
+ * - When `multiPlugin` is true (auth=required), multiple connections coexist
+ *   and are routed by token.
+ */
+export class ConnectionRegistry {
+    multiPlugin;
+    connections = new Map();
+    lastSuccessfulConnectionId = null;
+    nextId = 0;
+    constructor(multiPlugin) {
+        this.multiPlugin = multiPlugin;
+    }
+    /**
+     * Register a transport connection. A new single-plugin connection does not
+     * replace the current ready connection yet: replacement is promoted only by
+     * markToolsRegistered(), after a compatible handshake and runner registration.
+     * Returns the assigned connectionId.
+     */
+    register(ws, opts) {
+        const connectionId = `c${this.nextId++}`;
+        const entry = {
+            connectionId,
+            ws,
+            token: opts?.token,
+            instanceId: opts?.instanceId,
+            connectedUtc: new Date(),
+            generation: this.nextId,
+            capabilities: new Set(),
+        };
+        this.connections.set(connectionId, entry);
+        return connectionId;
+    }
+    /** Remove a connection and all its index entries. */
+    unregister(connectionId) {
+        const entry = this.connections.get(connectionId);
+        if (!entry)
+            return;
+        this.connections.delete(connectionId);
+        if (this.lastSuccessfulConnectionId === connectionId) {
+            this.lastSuccessfulConnectionId = this.findLatest((candidate) => this.isEligible(candidate))?.connectionId ?? null;
+        }
+    }
+    get(connectionId) {
+        return this.connections.get(connectionId);
+    }
+    /**
+     * Adopt an instanceId reported inside the version handshake when the
+     * connection did not already carry one from the query/header. Callers that
+     * pinned the identity explicitly always win; the handshake is only a
+     * fallback source for plugins that connect without it.
+     */
+    setInstanceId(connectionId, instanceId) {
+        const entry = this.connections.get(connectionId);
+        if (!entry)
+            return;
+        const bounded = instanceId.trim().slice(0, 160);
+        if (bounded.length === 0)
+            return;
+        if (entry.instanceId && entry.instanceId.length > 0)
+            return;
+        entry.instanceId = bounded;
+    }
+    markHandshake(connectionId, compatible, capabilities = [], generation, identity) {
+        const entry = this.connections.get(connectionId);
+        if (!entry)
+            return;
+        entry.handshakeCompatible = compatible;
+        entry.handshakeUtc = new Date();
+        entry.capabilities = new Set(capabilities
+            .filter((value) => typeof value === 'string' && value.trim().length > 0)
+            .slice(0, 32)
+            .map((value) => value.trim().slice(0, 160)));
+        // Identity is meaningful only when the peer advertised the capability that
+        // promises the members; anything else keeps the snapshot unavailable.
+        entry.identity = entry.capabilities.has('bridge-identity-v1')
+            ? sanitizeIdentity(identity)
+            : undefined;
+        if (Number.isInteger(generation) && generation > 0)
+            entry.generation = generation;
+        if (!compatible)
+            entry.toolsRegisteredUtc = undefined;
+    }
+    markToolsRegistered(connectionId) {
+        const entry = this.connections.get(connectionId);
+        if (!entry || entry.handshakeCompatible !== true)
+            return;
+        entry.toolsRegisteredUtc = new Date();
+        this.promoteIfEligible(entry);
+    }
+    markPromptsRegistered(connectionId) {
+        const entry = this.connections.get(connectionId);
+        if (!entry || entry.handshakeCompatible !== true)
+            return;
+        entry.promptsRegisteredUtc = new Date();
+        this.promoteIfEligible(entry);
+    }
+    markResourcesRegistered(connectionId) {
+        const entry = this.connections.get(connectionId);
+        if (!entry || entry.handshakeCompatible !== true)
+            return;
+        entry.resourcesRegisteredUtc = new Date();
+        this.promoteIfEligible(entry);
+    }
+    updateEditorReadiness(connectionId, value) {
+        const entry = this.connections.get(connectionId);
+        const snapshot = sanitizeReadiness(value);
+        if (!entry || !snapshot)
+            return;
+        entry.editorReadiness = snapshot;
+    }
+    noteDurableOperationAccepted(connectionId) {
+        const entry = this.connections.get(connectionId);
+        if (!entry)
+            return;
+        const previous = entry.editorReadiness;
+        entry.editorReadiness = {
+            state: 'busy',
+            ready: false,
+            blockers: ['active-operation'],
+            retryAfterMs: previous?.retryAfterMs ?? 250,
+            queuedSideEffects: Math.max(1, previous?.queuedSideEffects ?? 0),
+            runningSideEffects: previous?.runningSideEffects ?? 0,
+            queuedReads: previous?.queuedReads ?? 0,
+            runningReads: previous?.runningReads ?? 0,
+            activeOperations: Math.max(1, previous?.activeOperations ?? 0),
+            observedUtc: new Date(),
+        };
+    }
+    getByToken(token) {
+        return this.findLatest((entry) => entry.token === token && this.isOpen(entry));
+    }
+    getByInstanceId(instanceId) {
+        return this.findLatest((entry) => entry.instanceId === instanceId && this.isOpen(entry));
+    }
+    /** Get the last successful connection (default routing target). */
+    getLastSuccessful() {
+        if (this.lastSuccessfulConnectionId === null)
+            return undefined;
+        const entry = this.connections.get(this.lastSuccessfulConnectionId);
+        return this.isEligible(entry) ? entry : undefined;
+    }
+    /** A connection is routable only after compatible handshake + declared registration. */
+    isEligible(entry) {
+        if (entry === undefined || !this.isOpen(entry)
+            || entry.handshakeCompatible !== true || entry.toolsRegisteredUtc === undefined) {
+            return false;
+        }
+        // Legacy peers did not advertise generation-owned initialization and retain
+        // tools-only compatibility. New peers must complete prompts/resources/tools.
+        const generationOwned = entry.capabilities.has('operation-identity-v1')
+            || entry.capabilities.has('cancel-tool-call-v1');
+        return !generationOwned
+            || (entry.promptsRegisteredUtc !== undefined
+                && entry.resourcesRegisteredUtc !== undefined);
+    }
+    /** Resolve an eligible target connection given optional session routing hints. */
+    resolve(opts) {
+        // An explicit instance pin is strict: never fall through to another Editor.
+        if (opts?.instanceId) {
+            return this.findLatest((entry) => entry.instanceId === opts.instanceId && this.isEligible(entry));
+        }
+        // Token routing is also strict. Multiple reconnecting sockets may share a
+        // token, so scan newest-to-oldest and select the newest eligible one rather
+        // than a latest-transport index that may point at an unready replacement.
+        if (opts?.token) {
+            return this.findLatest((entry) => entry.token === opts.token && this.isEligible(entry));
+        }
+        const last = this.getLastSuccessful();
+        if (last)
+            return last;
+        return this.findLatest((entry) => this.isEligible(entry));
+    }
+    /** Return a snapshot of all connections (for GET /api/instances). */
+    snapshot() {
+        return Array.from(this.connections.values());
+    }
+    /** Number of active connections. */
+    get size() {
+        return this.connections.size;
+    }
+    isOpen(entry) {
+        return entry.ws.readyState === entry.ws.OPEN;
+    }
+    promoteIfEligible(entry) {
+        if (!this.isEligible(entry))
+            return;
+        this.lastSuccessfulConnectionId = entry.connectionId;
+        if (!this.multiPlugin)
+            this.disconnectOlderConnections(entry.connectionId);
+    }
+    findLatest(predicate) {
+        let found;
+        for (const entry of this.connections.values()) {
+            if (predicate(entry))
+                found = entry;
+        }
+        return found;
+    }
+    /**
+     * Promote a ready replacement in single-plugin mode. Only older connections
+     * are retired; a newer transport that is still handshaking must not be killed
+     * merely because the older connection finished registration first.
+     */
+    disconnectOlderConnections(connectionId) {
+        for (const [id, entry] of this.connections) {
+            if (id === connectionId)
+                break;
+            if (!this.isOpen(entry))
+                continue;
+            const reason = 'Replaced by a new ready connection.';
+            const notif = makeNotification(ClientFacingMethod.ForceDisconnect, { reason });
+            entry.ws.send(serializeMessage(notif));
+            entry.ws.close(4001, reason);
+            this.unregister(id);
+        }
+    }
+}
+const READINESS_STATES = new Set([
+    'ready', 'settling', 'compiling', 'importing', 'playmode-transition',
+    'building', 'busy', 'disconnected',
+]);
+const MAX_IDENTITY_PATH_LENGTH = 1024;
+const MAX_IDENTITY_VERSION_LENGTH = 64;
+/** Bound and type-check handshake identity members before they enter routing. */
+function sanitizeIdentity(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const record = value;
+    const projectPath = typeof record['projectPath'] === 'string' && record['projectPath'].trim().length > 0
+        ? record['projectPath'].trim().slice(0, MAX_IDENTITY_PATH_LENGTH)
+        : undefined;
+    const editorPid = typeof record['editorPid'] === 'number'
+        && Number.isSafeInteger(record['editorPid']) && record['editorPid'] > 0
+        ? record['editorPid']
+        : undefined;
+    const unityVersion = typeof record['unityVersion'] === 'string' && record['unityVersion'].trim().length > 0
+        ? record['unityVersion'].trim().slice(0, MAX_IDENTITY_VERSION_LENGTH)
+        : undefined;
+    if (projectPath === undefined && editorPid === undefined && unityVersion === undefined) {
+        return undefined;
+    }
+    return {
+        ...(projectPath === undefined ? {} : { projectPath }),
+        ...(editorPid === undefined ? {} : { editorPid }),
+        ...(unityVersion === undefined ? {} : { unityVersion }),
+    };
+}
+function sanitizeReadiness(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const record = value;
+    const state = typeof record['state'] === 'string' ? record['state']
+        : typeof record['State'] === 'string' ? record['State']
+            : undefined;
+    const ready = typeof record['ready'] === 'boolean' ? record['ready']
+        : typeof record['Ready'] === 'boolean' ? record['Ready']
+            : undefined;
+    if (!state || !READINESS_STATES.has(state) || ready === undefined)
+        return undefined;
+    const number = (camel, pascal, maximum) => {
+        const candidate = record[camel] ?? record[pascal];
+        return typeof candidate === 'number' && Number.isInteger(candidate)
+            ? Math.max(0, Math.min(maximum, candidate))
+            : 0;
+    };
+    const blockersValue = record['blockers'] ?? record['Blockers'];
+    const blockers = Array.isArray(blockersValue)
+        ? blockersValue.filter((item) => typeof item === 'string')
+            .slice(0, 8).map((item) => item.slice(0, 160))
+        : [];
+    return {
+        state,
+        ready,
+        blockers,
+        retryAfterMs: Math.max(50, Math.min(5_000, number('retryAfterMs', 'RetryAfterMs', 5_000) || 250)),
+        queuedSideEffects: number('queuedSideEffects', 'QueuedSideEffects', 64),
+        runningSideEffects: number('runningSideEffects', 'RunningSideEffects', 1),
+        queuedReads: number('queuedReads', 'QueuedReads', 64),
+        runningReads: number('runningReads', 'RunningReads', 4),
+        activeOperations: number('activeOperations', 'ActiveOperations', 200),
+        observedUtc: new Date(),
+    };
+}
+//# sourceMappingURL=registry.js.map