@konitif/workbench 0.284.1

package/dist/boot/executor.js

@@ -0,0 +1,210 @@
+import { resolveBootExecutionOrder, validateBootGraph } from "./graph.js";
+import { createBootEventBus } from "./events.js";
+export function createBootExecutor(options = {}) {
+    const eventBus = options.eventBus ?? createBootEventBus();
+    const now = options.now ?? (() => Date.now());
+    const createExecutionId = options.createExecutionId ??
+        (() => `boot-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`);
+    let state = createEmptyExecutionState('boot-idle');
+    let completedSteps = [];
+    return {
+        async run(graph, ctx) {
+            const executionId = createExecutionId();
+            state = createInitialExecutionState(graph, executionId, now());
+            completedSteps = [];
+            eventBus.emit({ type: 'boot:start', executionId, state });
+            const validation = validateBootGraph(graph);
+            if (!validation.valid) {
+                state.failed = true;
+                state.endedAt = now();
+                state.errors = validation.issues.map((issue) => ({ error: issue }));
+                eventBus.emit({
+                    type: 'boot:failed',
+                    executionId,
+                    state,
+                    error: validation.issues,
+                });
+                return state;
+            }
+            const order = resolveBootExecutionOrder(graph);
+            let activePhase = null;
+            for (const step of order) {
+                if (activePhase !== step.phase) {
+                    activePhase = step.phase;
+                    state.phase = step.phase;
+                    eventBus.emit({ type: 'phase:start', executionId, phase: step.phase });
+                }
+                const blockedReason = getBlockedReason(step, state);
+                if (blockedReason) {
+                    markStepBlocked(state, step, blockedReason, now());
+                    eventBus.emit({
+                        type: 'step:blocked',
+                        executionId,
+                        stepId: step.id,
+                        reason: blockedReason,
+                    });
+                    if ((step.criticality ?? 'critical') === 'critical') {
+                        state.failed = true;
+                        state.endedAt = now();
+                        state.errors.push({ stepId: step.id, error: blockedReason });
+                        eventBus.emit({
+                            type: 'boot:failed',
+                            executionId,
+                            state,
+                            error: blockedReason,
+                        });
+                        return state;
+                    }
+                    continue;
+                }
+                const node = state.nodes[step.id];
+                node.attempts += 1;
+                node.state.status = 'running';
+                node.state.startedAt = now();
+                delete node.state.endedAt;
+                delete node.state.error;
+                eventBus.emit({ type: 'step:start', executionId, stepId: step.id });
+                try {
+                    const result = await step.run(ctx);
+                    mergeStepResult(node, result);
+                    node.state.status = 'success';
+                    node.state.endedAt = now();
+                    completedSteps.push(step);
+                    eventBus.emit({ type: 'step:success', executionId, stepId: step.id });
+                }
+                catch (error) {
+                    node.state.status = 'failed';
+                    node.state.endedAt = now();
+                    node.state.error = error;
+                    state.errors.push({ stepId: step.id, error });
+                    eventBus.emit({ type: 'step:failed', executionId, stepId: step.id, error });
+                    if ((step.criticality ?? 'critical') === 'optional') {
+                        continue;
+                    }
+                    await rollbackCompletedSteps(completedSteps, ctx, state, now);
+                    state.failed = true;
+                    state.endedAt = now();
+                    eventBus.emit({ type: 'boot:failed', executionId, state, error });
+                    return state;
+                }
+            }
+            state.failed = false;
+            state.endedAt = now();
+            eventBus.emit({ type: 'boot:success', executionId, state });
+            return state;
+        },
+        async teardown(ctx) {
+            await teardownCompletedSteps(completedSteps, ctx, state, now);
+            completedSteps = [];
+            return state;
+        },
+        getState() {
+            return state;
+        },
+    };
+}
+function createEmptyExecutionState(executionId) {
+    return {
+        executionId,
+        phase: 'plan',
+        steps: {},
+        nodes: {},
+        failed: false,
+        errors: [],
+    };
+}
+function createInitialExecutionState(graph, executionId, startedAt) {
+    const steps = {};
+    const nodes = {};
+    for (const step of graph.steps) {
+        if (steps[step.id]) {
+            continue;
+        }
+        const state = {
+            id: step.id,
+            label: step.label,
+            phase: step.phase,
+            status: 'pending',
+            criticality: step.criticality ?? 'critical',
+            dependencies: step.dependsOn?.map((dependency) => ({ ...dependency })) ?? [],
+        };
+        steps[step.id] = state;
+        nodes[step.id] = {
+            state,
+            attempts: 0,
+            warnings: [],
+            metadata: {},
+        };
+    }
+    return {
+        executionId,
+        phase: 'plan',
+        steps,
+        nodes,
+        startedAt,
+        failed: false,
+        errors: [],
+    };
+}
+function getBlockedReason(step, state) {
+    for (const dependency of step.dependsOn ?? []) {
+        const dependencyState = state.steps[dependency.stepId];
+        if (!dependencyState) {
+            continue;
+        }
+        if (dependency.optional) {
+            continue;
+        }
+        if (dependencyState.status === 'failed') {
+            return `Dependency "${dependency.stepId}" failed.`;
+        }
+        if (dependencyState.status === 'blocked') {
+            return `Dependency "${dependency.stepId}" is blocked.`;
+        }
+    }
+    return null;
+}
+function markStepBlocked(state, step, reason, endedAt) {
+    const node = state.nodes[step.id];
+    node.state.status = 'blocked';
+    node.state.startedAt = endedAt;
+    node.state.endedAt = endedAt;
+    node.state.error = reason;
+}
+function mergeStepResult(node, result) {
+    if (!result) {
+        return;
+    }
+    node.warnings.push(...(result.warnings ?? []));
+    Object.assign(node.metadata, result.metadata ?? {});
+}
+async function rollbackCompletedSteps(completedSteps, ctx, state, now) {
+    for (const step of [...completedSteps].reverse()) {
+        if (!step.rollback) {
+            continue;
+        }
+        try {
+            const result = await step.rollback(ctx);
+            mergeStepResult(state.nodes[step.id], result);
+        }
+        catch (error) {
+            state.errors.push({ stepId: step.id, error });
+            state.nodes[step.id].warnings.push(`Rollback failed at ${now()}.`);
+        }
+    }
+}
+async function teardownCompletedSteps(completedSteps, ctx, state, now) {
+    for (const step of [...completedSteps].reverse()) {
+        if (!step.teardown) {
+            continue;
+        }
+        try {
+            const result = await step.teardown(ctx);
+            mergeStepResult(state.nodes[step.id], result);
+        }
+        catch (error) {
+            state.errors.push({ stepId: step.id, error });
+            state.nodes[step.id].warnings.push(`Teardown failed at ${now()}.`);
+        }
+    }
+}

package/dist/boot/graph.d.ts

@@ -0,0 +1,16 @@
+import type { BootGraph, BootPhase, BootStep } from "./types.js";
+export type BootGraphValidationIssueType = 'duplicate-id' | 'missing-dependency' | 'cycle';
+export interface BootGraphValidationIssue {
+    type: BootGraphValidationIssueType;
+    stepId?: string;
+    dependencyId?: string;
+    cycle?: string[];
+    message: string;
+}
+export interface BootGraphValidationResult {
+    valid: boolean;
+    issues: BootGraphValidationIssue[];
+}
+export declare function validateBootGraph(graph: BootGraph): BootGraphValidationResult;
+export declare function resolveBootExecutionOrder(graph: BootGraph): BootStep[];
+export declare function groupBootStepsByPhase(steps: readonly BootStep[]): Record<BootPhase, BootStep[]>;

package/dist/boot/graph.js

@@ -0,0 +1,126 @@
+export function validateBootGraph(graph) {
+    const issues = [];
+    const seen = new Set();
+    const duplicates = new Set();
+    const stepsById = new Map();
+    for (const step of graph.steps) {
+        if (seen.has(step.id)) {
+            duplicates.add(step.id);
+            issues.push({
+                type: 'duplicate-id',
+                stepId: step.id,
+                message: `Boot step id "${step.id}" is declared more than once.`,
+            });
+            continue;
+        }
+        seen.add(step.id);
+        stepsById.set(step.id, step);
+    }
+    for (const step of graph.steps) {
+        for (const dependency of step.dependsOn ?? []) {
+            if (!stepsById.has(dependency.stepId)) {
+                issues.push({
+                    type: 'missing-dependency',
+                    stepId: step.id,
+                    dependencyId: dependency.stepId,
+                    message: `Boot step "${step.id}" depends on missing step "${dependency.stepId}".`,
+                });
+            }
+        }
+    }
+    if (duplicates.size === 0) {
+        const cycle = findCycle(graph.steps, stepsById);
+        if (cycle.length > 0) {
+            issues.push({
+                type: 'cycle',
+                cycle,
+                message: `Boot graph contains a dependency cycle: ${cycle.join(' -> ')}.`,
+            });
+        }
+    }
+    return {
+        valid: issues.length === 0,
+        issues,
+    };
+}
+export function resolveBootExecutionOrder(graph) {
+    const validation = validateBootGraph(graph);
+    if (!validation.valid) {
+        throw new Error(validation.issues.map((issue) => issue.message).join('\n'));
+    }
+    const stepsById = new Map(graph.steps.map((step) => [step.id, step]));
+    const ordered = [];
+    const permanent = new Set();
+    const temporary = new Set();
+    const visit = (step) => {
+        if (permanent.has(step.id)) {
+            return;
+        }
+        if (temporary.has(step.id)) {
+            throw new Error(`Boot graph contains a dependency cycle at "${step.id}".`);
+        }
+        temporary.add(step.id);
+        for (const dependency of step.dependsOn ?? []) {
+            const dependencyStep = stepsById.get(dependency.stepId);
+            if (dependencyStep) {
+                visit(dependencyStep);
+            }
+        }
+        temporary.delete(step.id);
+        permanent.add(step.id);
+        ordered.push(step);
+    };
+    for (const step of graph.steps) {
+        visit(step);
+    }
+    return ordered;
+}
+export function groupBootStepsByPhase(steps) {
+    const grouped = {
+        plan: [],
+        initialize: [],
+        hydrate: [],
+        run: [],
+    };
+    for (const step of steps) {
+        grouped[step.phase].push(step);
+    }
+    return grouped;
+}
+function findCycle(steps, stepsById) {
+    const visited = new Set();
+    const stack = new Set();
+    const path = [];
+    const visit = (step) => {
+        if (stack.has(step.id)) {
+            const cycleStart = path.indexOf(step.id);
+            return [...path.slice(cycleStart), step.id];
+        }
+        if (visited.has(step.id)) {
+            return [];
+        }
+        visited.add(step.id);
+        stack.add(step.id);
+        path.push(step.id);
+        for (const dependency of step.dependsOn ?? []) {
+            const dependencyStep = stepsById.get(dependency.stepId);
+            if (!dependencyStep) {
+                continue;
+            }
+            const cycle = visit(dependencyStep);
+            if (cycle.length > 0) {
+                return cycle;
+            }
+        }
+        stack.delete(step.id);
+        path.pop();
+        return [];
+    };
+    for (const step of steps) {
+        const cycle = visit(step);
+        if (cycle.length > 0) {
+            return cycle;
+        }
+    }
+    return [];
+}

package/dist/boot/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./mechanism.js";
+export * from "./applicationBoot.js";

package/dist/boot/index.js

@@ -0,0 +1,3 @@
+// Historical aggregate. Headless mechanism consumers can use ./mechanism.
+export * from "./mechanism.js";
+export * from "./applicationBoot.js";

package/dist/boot/mechanism.d.ts

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./graph.js";
+export * from "./events.js";
+export * from "./executor.js";
+export * from "./projection.js";

package/dist/boot/mechanism.js

@@ -0,0 +1,6 @@
+// Internal mechanism entry: no application reveal policy or UI readiness gates.
+export * from "./types.js";
+export * from "./graph.js";
+export * from "./events.js";
+export * from "./executor.js";
+export * from "./projection.js";

package/dist/boot/projection.d.ts

@@ -0,0 +1,72 @@
+import type { BootEvent } from "./events.js";
+import { type BootDependency, type BootExecutionState, type BootMode, type BootPhase, type BootStepStatus } from "./types.js";
+export interface BootStepProjection {
+    id: string;
+    label: string;
+    phase: BootPhase;
+    status: BootStepStatus;
+    criticality: 'critical' | 'optional';
+    dependencies: BootDependency[];
+    attempts: number;
+    warnings: string[];
+    metadata: Record<string, unknown>;
+    startedAt?: number;
+    endedAt?: number;
+    durationMs?: number;
+    error?: string;
+}
+export interface BootPhaseProjection {
+    phase: BootPhase;
+    status: BootStepStatus | 'empty';
+    steps: BootStepProjection[];
+    counts: Record<BootStepStatus, number>;
+    startedAt?: number;
+    endedAt?: number;
+    durationMs?: number;
+}
+export interface BootProjection {
+    executionId: string;
+    mode: BootMode;
+    currentPhase: BootPhase;
+    failed: boolean;
+    startedAt?: number;
+    endedAt?: number;
+    phases: BootPhaseProjection[];
+    steps: BootStepProjection[];
+    lastEvent?: BootEvent;
+    events: BootEvent[];
+}
+export interface BootExecutionProjection extends BootProjection {
+    phase: BootPhase;
+    status: 'idle' | 'running' | 'success' | 'failed';
+    durationMs?: number;
+    errors: Array<{
+        stepId?: string;
+        error: string;
+    }>;
+}
+export type BootEventTimelineScope = 'boot' | 'phase' | 'step';
+export type BootEventTimelineStatus = 'start' | 'success' | 'failed' | 'blocked' | 'event';
+export type BootEventTimelineKind = 'open' | 'close' | 'error' | 'event';
+export interface BootEventTimelineRow {
+    id: string;
+    executionId: string;
+    scope: BootEventTimelineScope;
+    scopeId: string;
+    scopeLabel: string;
+    level: number;
+    name: string;
+    status: BootEventTimelineStatus;
+    kind: BootEventTimelineKind;
+    eventTypes: string[];
+    startTime?: number;
+    endTime?: number;
+    durationMs?: number;
+    startPercent: number;
+    timelinePercent: number;
+}
+export declare function createBootExecutionProjection(state: BootExecutionState, mode?: BootMode, lastEvent?: BootEvent, events?: readonly BootEvent[]): BootExecutionProjection;
+export declare function createBootProjection(state: BootExecutionState, mode?: BootMode, lastEvent?: BootEvent, events?: readonly BootEvent[]): BootProjection;
+export declare function getBootStepDurationMs(step: Pick<BootStepProjection, 'startedAt' | 'endedAt' | 'status'>, now?: () => number): number | undefined;
+export declare const getStepDurationMs: typeof getBootStepDurationMs;
+export declare function createBootEventTimelineRows(projection: BootProjection | null | undefined, events?: readonly BootEvent[]): BootEventTimelineRow[];