@konitif/workbench 0.284.1

package/dist/application/runtime/RuntimeRegistrySnapshots.js

@@ -0,0 +1,51 @@
+import { normalizeRuntimeInspectableStatus, normalizeRuntimeNullableString, normalizeRuntimeObjectSnapshot, normalizeRuntimeStringArray, sanitizeRuntimeJson } from "./WorkbenchRuntimeSanitizers.js";
+export function createRuntimeStoreSnapshot(registration) {
+    const value = safeReadRuntimeValue(registration.getSnapshot, registration.value);
+    return {
+        id: registration.id,
+        label: registration.label ?? registration.id,
+        scope: registration.scope ?? 'runtime',
+        status: registration.status ?? 'active',
+        value: sanitizeRuntimeJson(value),
+        updatedAt: new Date().toISOString(),
+        metadata: sanitizeRuntimeJson(registration.metadata ?? {})
+    };
+}
+export function createRuntimeServiceSnapshot(registration) {
+    const snapshot = normalizeRuntimeObjectSnapshot(safeReadRuntimeValue(registration.getSnapshot, {}));
+    return {
+        id: registration.id,
+        label: registration.label ?? registration.id,
+        status: normalizeRuntimeInspectableStatus(snapshot.status) ?? registration.status ?? 'unknown',
+        capabilities: normalizeRuntimeStringArray(snapshot.capabilities) ?? registration.capabilities ?? [],
+        endpoint: normalizeRuntimeNullableString(snapshot.endpoint) ?? registration.endpoint ?? null,
+        lastError: normalizeRuntimeNullableString(snapshot.lastError) ?? registration.lastError ?? null,
+        updatedAt: new Date().toISOString(),
+        metadata: sanitizeRuntimeJson(snapshot.metadata ?? registration.metadata ?? {})
+    };
+}
+export function createRuntimeManagerSnapshot(registration) {
+    const snapshot = normalizeRuntimeObjectSnapshot(safeReadRuntimeValue(registration.getSnapshot, {}));
+    return {
+        id: registration.id,
+        label: registration.label ?? registration.id,
+        status: normalizeRuntimeInspectableStatus(snapshot.status) ?? registration.status ?? 'unknown',
+        responsibilities: normalizeRuntimeStringArray(snapshot.responsibilities) ?? registration.responsibilities ?? [],
+        lastError: normalizeRuntimeNullableString(snapshot.lastError) ?? registration.lastError ?? null,
+        updatedAt: new Date().toISOString(),
+        metadata: sanitizeRuntimeJson(snapshot.metadata ?? registration.metadata ?? {})
+    };
+}
+export function safeReadRuntimeValue(read, fallback) {
+    if (!read) {
+        return fallback;
+    }
+    try {
+        return read();
+    }
+    catch (error) {
+        return {
+            error: error instanceof Error ? error.message : String(error)
+        };
+    }
+}

package/dist/application/runtime/RuntimeRegistryTypes.d.ts

@@ -0,0 +1,29 @@
+import type { RuntimeManagerSnapshot, RuntimeServiceSnapshot, RuntimeStoreSnapshot } from "../../domain/runtime/model.js";
+export interface RuntimeStoreRegistration {
+    id: string;
+    label?: string;
+    scope?: string;
+    status?: RuntimeStoreSnapshot['status'];
+    metadata?: unknown;
+    value?: unknown;
+    getSnapshot?: () => unknown;
+}
+export interface RuntimeServiceRegistration {
+    id: string;
+    label?: string;
+    status?: RuntimeServiceSnapshot['status'];
+    capabilities?: string[];
+    endpoint?: string | null;
+    lastError?: string | null;
+    metadata?: unknown;
+    getSnapshot?: () => Partial<RuntimeServiceSnapshot> | unknown;
+}
+export interface RuntimeManagerRegistration {
+    id: string;
+    label?: string;
+    status?: RuntimeManagerSnapshot['status'];
+    responsibilities?: string[];
+    lastError?: string | null;
+    metadata?: unknown;
+    getSnapshot?: () => Partial<RuntimeManagerSnapshot> | unknown;
+}

package/dist/application/runtime/RuntimeRegistryTypes.js

@@ -0,0 +1 @@
+export {};

package/dist/application/runtime/RuntimeSharedState.d.ts

@@ -0,0 +1,6 @@
+import type { WorkbenchRuntimeSharedStateEntry } from "../../domain/runtime/model.js";
+export declare function upsertSharedStateEntryFromEvent(entries: WorkbenchRuntimeSharedStateEntry[], payload: unknown): WorkbenchRuntimeSharedStateEntry[];
+export declare function upsertSharedStateEntry(entries: WorkbenchRuntimeSharedStateEntry[], nextEntry: WorkbenchRuntimeSharedStateEntry): WorkbenchRuntimeSharedStateEntry[];
+export declare function normalizeSharedStateEntry(value: unknown): WorkbenchRuntimeSharedStateEntry | null;
+export declare function normalizeSharedStateScope(value: unknown): WorkbenchRuntimeSharedStateEntry['scope'] | null;
+export declare function compareSharedStateEntries(left: WorkbenchRuntimeSharedStateEntry, right: WorkbenchRuntimeSharedStateEntry): number;

package/dist/application/runtime/RuntimeSharedState.js

@@ -0,0 +1,47 @@
+import { isJsonValue } from "./WorkbenchRuntimeSanitizers.js";
+export function upsertSharedStateEntryFromEvent(entries, payload) {
+    const entry = normalizeSharedStateEntry(payload);
+    return entry ? upsertSharedStateEntry(entries, entry) : entries;
+}
+export function upsertSharedStateEntry(entries, nextEntry) {
+    return [
+        ...entries.filter((entry) => entry.key !== nextEntry.key),
+        nextEntry
+    ].sort(compareSharedStateEntries);
+}
+export function normalizeSharedStateEntry(value) {
+    if (!value || typeof value !== 'object') {
+        return null;
+    }
+    const payload = value;
+    const key = typeof payload.key === 'string' ? payload.key : null;
+    const scope = normalizeSharedStateScope(payload.scope);
+    const valuePayload = isJsonValue(payload.value) ? payload.value : null;
+    const version = typeof payload.version === 'number' && Number.isFinite(payload.version)
+        ? payload.version
+        : 0;
+    const updatedAt = typeof payload.updatedAt === 'string' ? payload.updatedAt : '';
+    const revision = typeof payload.revision === 'string' && payload.revision
+        ? payload.revision
+        : `${version}:${updatedAt}`;
+    const originClientId = typeof payload.originClientId === 'string'
+        ? payload.originClientId
+        : null;
+    return key && scope
+        ? {
+            key,
+            scope,
+            value: valuePayload,
+            version,
+            revision,
+            updatedAt,
+            originClientId
+        }
+        : null;
+}
+export function normalizeSharedStateScope(value) {
+    return value === 'product' || value === 'session' || value === 'gesture' ? value : null;
+}
+export function compareSharedStateEntries(left, right) {
+    return left.key.localeCompare(right.key);
+}

package/dist/application/runtime/WorkbenchRuntimeCore.d.ts

@@ -0,0 +1,82 @@
+import type { RuntimeLaunchSnapshot, RuntimeDebugEvent, RuntimeDebugEventLevel, RuntimeProjectionMetadata, RuntimeProjectionMode, RuntimeStackTrace, WorkbenchRuntimeBackendPort, WorkbenchRuntimeAppPreviewDescriptor, WorkbenchRuntimeProjectionInvalidationResult, WorkbenchRuntimeSharedStateEntry, WorkbenchRuntimeSharedStatePatch, WorkbenchRuntimeWorkspaceDescriptor, WorkbenchRuntimeSnapshot, WorkbenchRuntimeSubscription } from "../../domain/runtime/model.js";
+import type { LaunchState } from "../../domain/launch/model.js";
+import { type RuntimeLifecycleSnapshot, type RuntimeLifecycleState } from "../../domain/runtime/lifecycle.js";
+import type { RuntimeCrashReportInput, RuntimeEntityLifecycleInput, RuntimeHealthCheckInput, RuntimePerformanceMarkerInput, RuntimeStoreMutationInput, RuntimeStructuredLogInput, RuntimeTelemetryTraceInput } from "../../domain/runtime/observability.js";
+import type { RuntimeManagerRegistration, RuntimeServiceRegistration, RuntimeStoreRegistration } from "./RuntimeRegistryTypes.js";
+export interface WorkbenchRuntimeCoreOptions {
+    backend?: WorkbenchRuntimeBackendPort;
+    maxEvents?: number;
+    maxDebugEvents?: number;
+    maxStackTraces?: number;
+    maxTelemetryEntries?: number;
+    mode?: RuntimeProjectionMode;
+    metadata?: Partial<RuntimeProjectionMetadata>;
+}
+export type WorkbenchRuntimeCoreListener = (snapshot: WorkbenchRuntimeSnapshot) => void;
+export type { RuntimeManagerRegistration, RuntimeServiceRegistration, RuntimeStoreRegistration } from "./RuntimeRegistryTypes.js";
+export interface RuntimeDebugEventInput {
+    id?: string;
+    level?: RuntimeDebugEventLevel;
+    type: string;
+    message?: string;
+    scope?: string | null;
+    payload?: unknown;
+    timestamp?: string;
+}
+export declare class WorkbenchRuntimeCore {
+    private readonly backend;
+    private readonly backendConnection;
+    private readonly maxEvents;
+    private readonly maxDebugEvents;
+    private readonly maxStackTraces;
+    private readonly listeners;
+    private readonly observability;
+    private readonly backendSubscription;
+    private readonly registryOwner;
+    private snapshot;
+    private launchTransitions;
+    private lifecycleSnapshot;
+    private sequence;
+    constructor(options: WorkbenchRuntimeCoreOptions);
+    getSnapshot(): WorkbenchRuntimeSnapshot;
+    createSnapshot(metadataPatch?: Partial<RuntimeProjectionMetadata>): WorkbenchRuntimeSnapshot;
+    activateSelfProjection(metadataPatch?: Partial<RuntimeProjectionMetadata>): WorkbenchRuntimeSnapshot;
+    subscribe(listener: WorkbenchRuntimeCoreListener): WorkbenchRuntimeSubscription;
+    connect(): Promise<WorkbenchRuntimeSnapshot>;
+    disconnect(): void;
+    loadProjection<TProjection = unknown>(kind: string, params?: Record<string, string>): Promise<TProjection>;
+    invalidateProjection(kind: string, params?: Record<string, string>): Promise<WorkbenchRuntimeProjectionInvalidationResult>;
+    loadProject(root: string): Promise<WorkbenchRuntimeWorkspaceDescriptor>;
+    startAppPreview(root?: string): Promise<WorkbenchRuntimeAppPreviewDescriptor>;
+    listSharedState(): Promise<WorkbenchRuntimeSharedStateEntry[]>;
+    recordTelemetryTrace(input: RuntimeTelemetryTraceInput): void;
+    recordStructuredLog(input: RuntimeStructuredLogInput): void;
+    recordPerformanceMarker(input: RuntimePerformanceMarkerInput): void;
+    recordHealthCheck(input: RuntimeHealthCheckInput): void;
+    recordStoreMutation(input: RuntimeStoreMutationInput): void;
+    recordEntityLifecycle(input: RuntimeEntityLifecycleInput): void;
+    captureCrashReport(error: Error | string, input?: RuntimeCrashReportInput): void;
+    registerStore(registration: RuntimeStoreRegistration): WorkbenchRuntimeSubscription;
+    registerService(registration: RuntimeServiceRegistration): WorkbenchRuntimeSubscription;
+    registerManager(registration: RuntimeManagerRegistration): WorkbenchRuntimeSubscription;
+    pushDebugEvent(input: RuntimeDebugEventInput): RuntimeDebugEvent;
+    captureStackTrace(error?: Error | string, input?: {
+        id?: string;
+        message?: string;
+        scope?: string | null;
+    }): RuntimeStackTrace;
+    recordLaunchState(state: LaunchState, input?: {
+        message?: string;
+        timestamp?: string;
+    }): RuntimeLaunchSnapshot;
+    transitionLifecycle(state: RuntimeLifecycleState, input?: {
+        message?: string;
+        timestamp?: string;
+    }): RuntimeLifecycleSnapshot;
+    patchSharedState(key: string, patch: WorkbenchRuntimeSharedStatePatch): Promise<WorkbenchRuntimeSharedStateEntry>;
+    private pushEvent;
+    private loadSharedStateFromBackend;
+    private setSnapshot;
+    private createRuntimeRecordId;
+    private refreshObservabilitySnapshot;
+}

package/dist/application/runtime/WorkbenchRuntimeCore.js

@@ -0,0 +1,463 @@
+import { createRuntimeLifecycleSnapshot, transitionRuntimeLifecycleSnapshot } from "../../domain/runtime/lifecycle.js";
+import { createRuntimeBackendConnection } from "./RuntimeBackendConnection.js";
+import { createRuntimeBackendSubscriptionOwner } from "./RuntimeBackendSubscription.js";
+import { createRuntimeLaunchPhaseDebugEventInput, createRuntimeLaunchSnapshotFromState, createRuntimeLaunchStoreMutationInput, createRuntimeLaunchTransitionRecord } from "./RuntimeLaunchStateSnapshot.js";
+import { applyRuntimeObservationEvent } from "./RuntimeObservationEvents.js";
+import { normalizeProjectionCatalogFromWorkspace } from "./RuntimeProjectionCatalog.js";
+import { safeReadRuntimeValue } from "./RuntimeRegistrySnapshots.js";
+import { createRuntimeRegistryOwner } from "./RuntimeRegistryOwner.js";
+import { compareSharedStateEntries, normalizeSharedStateEntry, upsertSharedStateEntry } from "./RuntimeSharedState.js";
+import { RuntimeObservabilityHub } from "./RuntimeObservabilityHub.js";
+import { sanitizeRuntimeJson, sanitizeRuntimeText } from "./WorkbenchRuntimeSanitizers.js";
+export class WorkbenchRuntimeCore {
+    backend;
+    backendConnection;
+    maxEvents;
+    maxDebugEvents;
+    maxStackTraces;
+    listeners = new Set();
+    observability;
+    backendSubscription = createRuntimeBackendSubscriptionOwner();
+    registryOwner;
+    snapshot;
+    launchTransitions = [];
+    lifecycleSnapshot;
+    sequence = 0;
+    constructor(options) {
+        this.backend = options.backend ?? null;
+        this.backendConnection = createRuntimeBackendConnection(this.backend);
+        this.maxEvents = options.maxEvents ?? 50;
+        this.maxDebugEvents = options.maxDebugEvents ?? 100;
+        this.maxStackTraces = options.maxStackTraces ?? 25;
+        this.observability = new RuntimeObservabilityHub({
+            maxEntries: options.maxTelemetryEntries ?? Math.max(this.maxEvents, this.maxDebugEvents, this.maxStackTraces)
+        });
+        this.registryOwner = createRuntimeRegistryOwner({
+            onChanged: () => {
+                this.createSnapshot();
+            },
+            onManagerDisposed: (registration) => {
+                this.observability.recordEntityLifecycle({
+                    entityId: registration.id,
+                    entityType: 'manager',
+                    kind: 'dispose',
+                    status: 'idle'
+                });
+            },
+            onManagerRegistered: (registration) => {
+                this.observability.recordEntityLifecycle({
+                    entityId: registration.id,
+                    entityType: 'manager',
+                    kind: 'register',
+                    status: registration.status ?? 'unknown',
+                    payload: {
+                        responsibilities: registration.responsibilities ?? []
+                    }
+                });
+            },
+            onServiceDisposed: (registration) => {
+                this.observability.recordEntityLifecycle({
+                    entityId: registration.id,
+                    entityType: 'service',
+                    kind: 'dispose',
+                    status: 'idle'
+                });
+            },
+            onServiceRegistered: (registration) => {
+                this.observability.recordEntityLifecycle({
+                    entityId: registration.id,
+                    entityType: 'service',
+                    kind: 'register',
+                    status: registration.status ?? 'unknown',
+                    payload: {
+                        capabilities: registration.capabilities ?? [],
+                        endpoint: registration.endpoint ?? null
+                    }
+                });
+            },
+            onStoreDisposed: (registration) => {
+                this.observability.recordStoreMutation({
+                    storeId: registration.id,
+                    kind: 'dispose'
+                });
+            },
+            onStoreRegistered: (registration) => {
+                this.observability.recordStoreMutation({
+                    storeId: registration.id,
+                    kind: 'register',
+                    value: safeReadRuntimeValue(registration.getSnapshot, registration.value)
+                });
+            }
+        });
+        this.lifecycleSnapshot = createRuntimeLifecycleSnapshot();
+        this.snapshot = {
+            status: 'idle',
+            backendUrl: this.backend?.baseUrl ?? '',
+            projectionMode: options.mode ?? 'self',
+            metadata: createRuntimeProjectionMetadata(options.mode ?? 'self', options.metadata),
+            health: null,
+            workspace: null,
+            projectionCatalog: [],
+            stores: [],
+            services: [],
+            managers: [],
+            debugEvents: [],
+            stackTraces: [],
+            launch: null,
+            lifecycle: this.lifecycleSnapshot,
+            observability: this.observability.createSnapshot(),
+            sharedState: [],
+            events: [],
+            lastError: null
+        };
+    }
+    getSnapshot() {
+        return this.snapshot;
+    }
+    createSnapshot(metadataPatch = {}) {
+        const previousMetadata = this.snapshot.metadata ?? createRuntimeProjectionMetadata(this.snapshot.projectionMode ?? 'self');
+        this.setSnapshot({
+            metadata: {
+                ...previousMetadata,
+                ...metadataPatch,
+                mode: metadataPatch.mode ?? previousMetadata.mode,
+                source: metadataPatch.source ?? previousMetadata.source,
+                version: metadataPatch.version ?? previousMetadata.version,
+                generatedAt: metadataPatch.generatedAt ?? new Date().toISOString()
+            },
+            stores: this.registryOwner.getStoreSnapshots(),
+            services: this.registryOwner.getServiceSnapshots(),
+            managers: this.registryOwner.getManagerSnapshots(),
+            observability: this.observability.createSnapshot()
+        });
+        return this.snapshot;
+    }
+    activateSelfProjection(metadataPatch = {}) {
+        this.backendSubscription.disconnect();
+        this.setSnapshot({
+            status: 'online',
+            projectionMode: 'self',
+            metadata: createRuntimeProjectionMetadata('self', {
+                ...metadataPatch,
+                mode: 'self',
+                source: metadataPatch.source ?? 'self'
+            }),
+            workspace: null,
+            projectionCatalog: [],
+            sharedState: [],
+            events: [],
+            lastError: null
+        });
+        return this.createSnapshot({
+            ...metadataPatch,
+            mode: 'self',
+            source: metadataPatch.source ?? 'self'
+        });
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        listener(this.snapshot);
+        return {
+            dispose: () => {
+                this.listeners.delete(listener);
+            }
+        };
+    }
+    async connect() {
+        const backend = this.backend;
+        if (!backend) {
+            return this.createSnapshot({
+                mode: this.snapshot.projectionMode ?? 'self',
+                source: this.snapshot.metadata?.source || 'self'
+            });
+        }
+        this.setSnapshot({
+            status: 'connecting',
+            backendUrl: backend.baseUrl,
+            lastError: null
+        });
+        try {
+            const [health, workspace, sharedState] = await Promise.all([
+                backend.getHealth(),
+                backend.getWorkspace(),
+                this.loadSharedStateFromBackend().catch(() => [])
+            ]);
+            this.backendSubscription.replaceWith(() => backend.subscribeToEvents((event) => this.pushEvent(event), (error) => {
+                this.setSnapshot({
+                    status: 'error',
+                    lastError: error.message
+                });
+            }));
+            this.setSnapshot({
+                status: 'online',
+                health,
+                workspace,
+                projectionCatalog: normalizeProjectionCatalogFromWorkspace(workspace),
+                sharedState,
+                lastError: null
+            });
+        }
+        catch (error) {
+            this.setSnapshot({
+                status: 'offline',
+                lastError: error instanceof Error ? error.message : String(error)
+            });
+        }
+        return this.snapshot;
+    }
+    disconnect() {
+        this.backendSubscription.disconnect();
+        this.setSnapshot({
+            status: 'idle'
+        });
+    }
+    async loadProjection(kind, params) {
+        return this.backendConnection.loadProjection(kind, params);
+    }
+    async invalidateProjection(kind, params) {
+        return this.backendConnection.invalidateProjection(kind, params);
+    }
+    async loadProject(root) {
+        if (!this.backend?.loadProject) {
+            throw new Error('Backend project loading is unavailable.');
+        }
+        this.setSnapshot({
+            status: 'connecting',
+            lastError: null
+        });
+        try {
+            const workspace = await this.backend.loadProject(root);
+            const sharedState = await this.loadSharedStateFromBackend().catch(() => this.snapshot.sharedState);
+            this.setSnapshot({
+                status: 'online',
+                workspace,
+                projectionCatalog: normalizeProjectionCatalogFromWorkspace(workspace),
+                sharedState,
+                lastError: null
+            });
+            return workspace;
+        }
+        catch (error) {
+            this.setSnapshot({
+                status: 'error',
+                lastError: error instanceof Error ? error.message : String(error)
+            });
+            throw error;
+        }
+    }
+    async startAppPreview(root) {
+        return this.backendConnection.startAppPreview(root);
+    }
+    async listSharedState() {
+        const sharedState = await this.loadSharedStateFromBackend();
+        this.setSnapshot({ sharedState });
+        return sharedState;
+    }
+    recordTelemetryTrace(input) {
+        this.observability.recordTrace(input);
+        this.refreshObservabilitySnapshot();
+    }
+    recordStructuredLog(input) {
+        this.observability.recordLog(input);
+        this.refreshObservabilitySnapshot();
+    }
+    recordPerformanceMarker(input) {
+        this.observability.recordPerformanceMarker(input);
+        this.refreshObservabilitySnapshot();
+    }
+    recordHealthCheck(input) {
+        this.observability.recordHealthCheck(input);
+        this.refreshObservabilitySnapshot();
+    }
+    recordStoreMutation(input) {
+        this.observability.recordStoreMutation(input);
+        this.refreshObservabilitySnapshot();
+    }
+    recordEntityLifecycle(input) {
+        this.observability.recordEntityLifecycle(input);
+        this.refreshObservabilitySnapshot();
+    }
+    captureCrashReport(error, input = {}) {
+        const report = this.observability.captureCrashReport(error, input);
+        this.setSnapshot({
+            status: 'error',
+            lastError: report.message,
+            observability: this.observability.createSnapshot()
+        });
+    }
+    registerStore(registration) {
+        return this.registryOwner.registerStore(registration);
+    }
+    registerService(registration) {
+        return this.registryOwner.registerService(registration);
+    }
+    registerManager(registration) {
+        return this.registryOwner.registerManager(registration);
+    }
+    pushDebugEvent(input) {
+        const event = {
+            id: input.id ?? this.createRuntimeRecordId('debug'),
+            level: input.level ?? 'info',
+            type: sanitizeRuntimeText(input.type, 160),
+            message: sanitizeRuntimeText(input.message ?? input.type, 500),
+            scope: input.scope ? sanitizeRuntimeText(input.scope, 160) : null,
+            timestamp: input.timestamp ?? new Date().toISOString(),
+            payload: input.payload === undefined ? undefined : sanitizeRuntimeJson(input.payload)
+        };
+        this.observability.recordDebugEvent(event);
+        this.setSnapshot({
+            debugEvents: [event, ...(this.snapshot.debugEvents ?? [])].slice(0, this.maxDebugEvents),
+            observability: this.observability.createSnapshot()
+        });
+        return event;
+    }
+    captureStackTrace(error, input = {}) {
+        const resolvedError = error instanceof Error ? error : null;
+        const stackSource = resolvedError?.stack ?? (typeof error === 'string' ? error : new Error(input.message ?? 'Runtime stack trace').stack ?? '');
+        const cause = resolvedError && 'cause' in resolvedError ? resolvedError.cause : null;
+        const stackTrace = {
+            id: input.id ?? this.createRuntimeRecordId('stack'),
+            message: sanitizeRuntimeText(input.message ?? resolvedError?.message ?? (typeof error === 'string' ? error : 'Runtime stack trace'), 500),
+            scope: input.scope ? sanitizeRuntimeText(input.scope, 160) : null,
+            timestamp: new Date().toISOString(),
+            frames: stackSource
+                .split('\n')
+                .map((frame) => sanitizeRuntimeText(frame.trim(), 500))
+                .filter(Boolean)
+                .slice(0, 24),
+            cause: cause instanceof Error ? sanitizeRuntimeText(cause.message, 500) : null
+        };
+        this.observability.recordStackTrace(stackTrace);
+        this.setSnapshot({
+            stackTraces: [stackTrace, ...(this.snapshot.stackTraces ?? [])].slice(0, this.maxStackTraces),
+            observability: this.observability.createSnapshot()
+        });
+        return stackTrace;
+    }
+    recordLaunchState(state, input = {}) {
+        const timestamp = input.timestamp ?? new Date().toISOString();
+        const previousPhase = this.snapshot.launch?.phase ?? null;
+        const phaseChanged = previousPhase !== state.phase;
+        const message = sanitizeRuntimeText(input.message ?? `Launch phase ${state.phase}`, 500);
+        let transition = null;
+        if (phaseChanged) {
+            this.transitionLifecycle(state.phase, {
+                timestamp,
+                message
+            });
+            transition = createRuntimeLaunchTransitionRecord({
+                id: this.createRuntimeRecordId('launch'),
+                state,
+                previousPhase,
+                timestamp,
+                message
+            });
+            this.launchTransitions = [transition, ...this.launchTransitions].slice(0, this.maxDebugEvents);
+        }
+        const launchSnapshot = createRuntimeLaunchSnapshotFromState({
+            state,
+            transitions: this.launchTransitions,
+            timestamp
+        });
+        this.observability.recordStoreMutation(createRuntimeLaunchStoreMutationInput({
+            id: this.createRuntimeRecordId('launch-state'),
+            state,
+            previousPhase,
+            progress: launchSnapshot.progress,
+            timestamp
+        }));
+        this.setSnapshot({
+            launch: launchSnapshot,
+            observability: this.observability.createSnapshot()
+        });
+        if (phaseChanged && transition) {
+            this.pushDebugEvent(createRuntimeLaunchPhaseDebugEventInput({
+                state,
+                previousPhase,
+                launchSnapshot,
+                timestamp,
+                transition
+            }));
+        }
+        return launchSnapshot;
+    }
+    transitionLifecycle(state, input = {}) {
+        const timestamp = input.timestamp ?? new Date().toISOString();
+        this.lifecycleSnapshot = transitionRuntimeLifecycleSnapshot(this.lifecycleSnapshot, state, {
+            id: this.createRuntimeRecordId('lifecycle'),
+            timestamp,
+            message: input.message,
+            maxTransitions: this.maxDebugEvents,
+            maxErrors: Math.max(10, Math.min(this.maxDebugEvents, 25))
+        });
+        const currentTransition = this.lifecycleSnapshot.transitions[0];
+        this.observability.recordTrace({
+            id: currentTransition?.id,
+            type: 'lifecycle',
+            level: currentTransition && !currentTransition.accepted ? 'warning' : 'info',
+            scope: 'runtime.lifecycle',
+            label: state,
+            message: currentTransition?.message ?? input.message ?? `Runtime lifecycle ${state}`,
+            timestamp
+        });
+        this.setSnapshot({
+            lifecycle: this.lifecycleSnapshot,
+            observability: this.observability.createSnapshot()
+        });
+        return this.lifecycleSnapshot;
+    }
+    async patchSharedState(key, patch) {
+        const entry = await this.backendConnection.patchSharedState(key, patch);
+        const sharedStateEntry = normalizeSharedStateEntry(entry);
+        if (!sharedStateEntry) {
+            throw new Error(`Backend returned invalid shared state entry for "${key}".`);
+        }
+        this.setSnapshot({
+            sharedState: upsertSharedStateEntry(this.snapshot.sharedState, sharedStateEntry)
+        });
+        return sharedStateEntry;
+    }
+    pushEvent(event) {
+        this.setSnapshot(applyRuntimeObservationEvent({
+            projectionCatalog: this.snapshot.projectionCatalog,
+            sharedState: this.snapshot.sharedState,
+            events: this.snapshot.events,
+            event,
+            maxEvents: this.maxEvents
+        }));
+    }
+    async loadSharedStateFromBackend() {
+        return (await this.backendConnection.listSharedState())
+            .map(normalizeSharedStateEntry)
+            .filter((entry) => Boolean(entry))
+            .sort(compareSharedStateEntries);
+    }
+    setSnapshot(patch) {
+        this.snapshot = {
+            ...this.snapshot,
+            ...patch
+        };
+        for (const listener of this.listeners) {
+            listener(this.snapshot);
+        }
+    }
+    createRuntimeRecordId(prefix) {
+        this.sequence += 1;
+        return `${prefix}:${this.sequence}`;
+    }
+    refreshObservabilitySnapshot() {
+        this.setSnapshot({
+            observability: this.observability.createSnapshot()
+        });
+    }
+}
+function createRuntimeProjectionMetadata(mode, metadata = {}) {
+    return {
+        mode,
+        generatedAt: metadata.generatedAt ?? new Date().toISOString(),
+        source: metadata.source ?? mode,
+        version: metadata.version ?? 'runtime-inspector.v1',
+        repo: metadata.repo ?? null,
+        build: metadata.build ?? null
+    };
+}