@konitif/workbench 0.284.1

package/LICENSE.md

@@ -0,0 +1,21 @@
+# Licence — @konitif/workbench
+
+SPDX-License-Identifier: PolyForm-Noncommercial-1.0.0
+
+The original KONITIF / Workbench code in this v0.x package is made available
+under the PolyForm Noncommercial License 1.0.0:
+https://polyformproject.org/licenses/noncommercial/1.0.0
+
+This notice incorporates the standard terms by reference; it is not a modified
+version of the licence. This is source-available software, not OSI open source.
+Third-party components retain their own licences and notices.
+
+Uses outside the standard licence's permitted purposes require a separate
+written licence. A public repository or npm download grants no additional
+commercial rights. Any free professional authorization must be explicit,
+nominative and limited to the agreed products; none is granted by this notice.
+
+The KONITIF name, logo and official identity belong to Maxime Mouflard.
+Descriptive reference is permitted. No third-party version may claim to be
+official, certified or approved without authorization. This trademark notice
+is separate from the software licence and does not amend its terms.

package/README.md

@@ -0,0 +1,54 @@
+# @konitif/workbench
+
+## Build and distribution
+
+Run `npm run build` to produce `dist` with the locked TypeScript compiler. The
+published contract exposes compiled ESM and declarations only. Run `npm test`
+then `npm run verify:package`; the latter packs the exact payload and consumes
+all four public entries from an isolated Node ESM/NodeNext fixture.
+
+The build does not install dependencies or publish. Release remains a separate,
+protected operation after the repository and archive have been qualified.
+
+Product-neutral Workbench authority for workspace composition, docking,
+registries, persistence ports and shell lifecycle contracts.
+
+The package hosts tools and widgets through generic definitions. It must not
+depend on a private product package or specialize product-specific behavior.
+
+## Product color policy migration
+
+The development barrel no longer exports `getRobotJointColor`. Consumers must
+obtain their color policy from their product layer; generic viewers accept an
+injected color provider. This is a source API change, with no persisted-data migration.
+No compatibility reexport is provided because Workbench must not depend on a
+product package. This migration does not publish either package.
+
+Widget definitions and lazy bindings belong to `@konitif/widgets`.
+Workbench provides `createWorkbenchWidgetAdapter` to project an admitted
+definition into its hosting contract without loading or registering it.
+Widget registries, zones, placements and docking helpers remain here.
+Consumers of the former Widgets facade should import these host contracts
+from `@konitif/workbench`; no persisted placement migration is required.
+
+## Selected workspace contracts
+
+`@konitif/workbench/workspace-contracts` exposes an explicit selection of
+workspace, shell, layout and tool-state contracts for state orchestration.
+It reexports the existing implementations without including audio, HTTP or
+local-storage adapters. The root entry and `hosting` remain compatible.
+This source-level boundary is tested; standalone archive qualification and
+publication remain separate gates.
+
+## Transitional headless physics entry
+
+`@konitif/workbench/physics-runtime` forwards `PhysicsService`,
+`NoopPhysicsBackend` and physical contracts to the published `@konitif/physics`
+package. Their implementations do not live in Workbench.
+Consumers inject backend factories and explicitly drive stepping and disposal.
+No worker, engine binary, visual alignment or product configuration is loaded
+by this entry. The former UI paths reexport the same classes for compatibility.
+
+This is a compatibility boundary, not a permanent Workbench responsibility.
+Backend identifiers and source shapes
+remain unchanged; the no-op backend does not simulate physical effects.

package/dist/application/boot/applicationBoot.d.ts

@@ -0,0 +1,48 @@
+import type { BootProjection } from "../../boot/projection.js";
+import type { BootMode, BootPhase } from "../../boot/types.js";
+export type ApplicationBootSource = 'desktop_host' | 'frontend' | 'backend' | 'resources' | 'configuration' | 'registry' | 'workspace' | 'runtime' | 'product';
+export type ApplicationBootEventStatus = 'pending' | 'running' | 'completed' | 'completed_with_warnings' | 'blocked' | 'failed' | 'cancelled' | 'skipped' | 'unknown';
+export type ApplicationBootSeverity = 'info' | 'warning' | 'error';
+export interface ApplicationBootJournalEntry {
+    eventId: string;
+    phase: BootPhase;
+    stepId: string;
+    source: ApplicationBootSource;
+    status: ApplicationBootEventStatus;
+    message: string;
+    diagnosticCode?: string;
+    severity: ApplicationBootSeverity;
+    startedAt?: number;
+    completedAt?: number;
+    details: Record<string, unknown>;
+}
+export type ApplicationRevealReadinessStatus = 'ready' | 'ready_with_warnings' | 'blocked' | 'safe_mode' | 'unknown';
+export interface ApplicationRevealReadiness {
+    status: ApplicationRevealReadinessStatus;
+    reasons: string[];
+    blockingDiagnostic?: string;
+}
+export interface ApplicationBootLifecycleProjection {
+    executionId: string;
+    mode: BootMode;
+    phase: BootPhase;
+    status: 'idle' | 'running' | 'success' | 'failed';
+    currentStep: ApplicationBootJournalEntry | null;
+    journal: ApplicationBootJournalEntry[];
+    completedSteps: number;
+    totalSteps: number;
+    warningCount: number;
+    blockingDiagnostics: string[];
+    revealReadiness: ApplicationRevealReadiness;
+    progress: {
+        kind: 'planned-steps' | 'indeterminate';
+        completed: number;
+        total: number;
+    };
+}
+export interface CreateApplicationBootLifecycleProjectionOptions {
+    firstFrameReady?: boolean;
+    requiredResourcesReady?: boolean;
+    workspaceShellMounted?: boolean;
+}
+export declare function createApplicationBootLifecycleProjection(bootProjection: BootProjection, options?: CreateApplicationBootLifecycleProjectionOptions): ApplicationBootLifecycleProjection;

package/dist/application/boot/applicationBoot.js

@@ -0,0 +1,174 @@
+export function createApplicationBootLifecycleProjection(bootProjection, options = {}) {
+    const journal = bootProjection.steps.map((step) => createJournalEntry(step));
+    const completedSteps = bootProjection.steps.filter((step) => isCompletedStepStatus(step.status)).length;
+    const warningCount = bootProjection.steps.reduce((count, step) => count + step.warnings.length, 0);
+    const blockingDiagnostics = bootProjection.steps
+        .filter((step) => step.status === 'failed' || step.status === 'blocked')
+        .map((step) => step.error ?? `${step.label} ${step.status}`);
+    const status = resolveApplicationBootStatus(bootProjection);
+    const currentStep = resolveCurrentJournalEntry(journal);
+    const revealReadiness = resolveApplicationRevealReadiness(bootProjection, warningCount, blockingDiagnostics, options);
+    return {
+        executionId: bootProjection.executionId,
+        mode: bootProjection.mode,
+        phase: bootProjection.currentPhase,
+        status,
+        currentStep,
+        journal,
+        completedSteps,
+        totalSteps: bootProjection.steps.length,
+        warningCount,
+        blockingDiagnostics,
+        revealReadiness,
+        progress: bootProjection.steps.length > 0
+            ? {
+                kind: 'planned-steps',
+                completed: completedSteps,
+                total: bootProjection.steps.length,
+            }
+            : {
+                kind: 'indeterminate',
+                completed: 0,
+                total: 0,
+            },
+    };
+}
+function createJournalEntry(step) {
+    const status = mapBootStepStatus(step.status, step.warnings.length);
+    return {
+        eventId: `${step.id}:${status}`,
+        phase: step.phase,
+        stepId: step.id,
+        source: resolveApplicationBootSource(step),
+        status,
+        message: step.label,
+        diagnosticCode: step.error ? `boot.${step.status}.${step.id}` : undefined,
+        severity: resolveApplicationBootSeverity(status),
+        startedAt: step.startedAt,
+        completedAt: step.endedAt,
+        details: {
+            attempts: step.attempts,
+            criticality: step.criticality,
+            dependencies: step.dependencies.map((dependency) => dependency.stepId),
+            warnings: [...step.warnings],
+            ...(step.error ? { error: step.error } : {}),
+            ...step.metadata,
+        },
+    };
+}
+function mapBootStepStatus(status, warningCount) {
+    switch (status) {
+        case 'success':
+            return warningCount > 0 ? 'completed_with_warnings' : 'completed';
+        case 'failed':
+            return 'failed';
+        case 'blocked':
+            return 'blocked';
+        case 'skipped':
+            return 'skipped';
+        case 'running':
+            return 'running';
+        case 'pending':
+        default:
+            return 'pending';
+    }
+}
+function resolveApplicationBootSource(step) {
+    const source = step.metadata.source;
+    if (isApplicationBootSource(source)) {
+        return source;
+    }
+    if (step.id.includes('desktop'))
+        return 'desktop_host';
+    if (step.id.includes('resource'))
+        return 'resources';
+    if (step.id.includes('registry'))
+        return 'registry';
+    if (step.id.includes('persistence') || step.id.includes('workspace'))
+        return 'workspace';
+    if (step.id.includes('runtime'))
+        return 'runtime';
+    if (step.id.includes('profile') || step.id.includes('configuration'))
+        return 'configuration';
+    return 'frontend';
+}
+function isApplicationBootSource(value) {
+    return (value === 'desktop_host' ||
+        value === 'frontend' ||
+        value === 'backend' ||
+        value === 'resources' ||
+        value === 'configuration' ||
+        value === 'registry' ||
+        value === 'workspace' ||
+        value === 'runtime' ||
+        value === 'product');
+}
+function resolveApplicationBootSeverity(status) {
+    if (status === 'failed' || status === 'blocked') {
+        return 'error';
+    }
+    if (status === 'completed_with_warnings' || status === 'skipped') {
+        return 'warning';
+    }
+    return 'info';
+}
+function resolveApplicationBootStatus(bootProjection) {
+    if (bootProjection.failed) {
+        return 'failed';
+    }
+    if (bootProjection.lastEvent?.type === 'boot:success') {
+        return 'success';
+    }
+    if (bootProjection.lastEvent) {
+        return 'running';
+    }
+    return 'idle';
+}
+function resolveCurrentJournalEntry(journal) {
+    return (journal.find((entry) => entry.status === 'running') ??
+        [...journal].reverse().find((entry) => entry.status !== 'pending') ??
+        journal[0] ??
+        null);
+}
+function resolveApplicationRevealReadiness(bootProjection, warningCount, blockingDiagnostics, options) {
+    if (bootProjection.mode === 'safe') {
+        return {
+            status: 'safe_mode',
+            reasons: ['Boot is running in safe mode.'],
+        };
+    }
+    if (bootProjection.failed || blockingDiagnostics.length > 0) {
+        return {
+            status: 'blocked',
+            reasons: blockingDiagnostics.length > 0 ? [...blockingDiagnostics] : ['Boot failed.'],
+            blockingDiagnostic: blockingDiagnostics[0] ?? 'Boot failed.',
+        };
+    }
+    const readinessGates = [
+        [options.requiredResourcesReady, 'Required resources are not ready.'],
+        [options.workspaceShellMounted, 'Workspace shell is not mounted.'],
+        [options.firstFrameReady, 'First application frame is not ready.'],
+    ];
+    const openReasons = readinessGates
+        .filter(([isReady]) => isReady !== true)
+        .map(([, reason]) => reason);
+    if (bootProjection.lastEvent?.type !== 'boot:success') {
+        return {
+            status: 'unknown',
+            reasons: ['Boot DAG has not reached RUNNING.'],
+        };
+    }
+    if (openReasons.length > 0) {
+        return {
+            status: 'unknown',
+            reasons: openReasons,
+        };
+    }
+    return {
+        status: warningCount > 0 ? 'ready_with_warnings' : 'ready',
+        reasons: warningCount > 0 ? [`Boot completed with ${warningCount} warning(s).`] : ['Application is ready to reveal.'],
+    };
+}
+function isCompletedStepStatus(status) {
+    return status === 'success' || status === 'skipped';
+}

package/dist/application/experiment/ControlledExperimentCampaign.d.ts

@@ -0,0 +1,12 @@
+import type { ControlledExperimentCampaignDefinition, ControlledExperimentCampaignRunAssessment, ControlledExperimentCampaignSnapshot, ControlledExperimentDefinition, ControlledExperimentRunArtifact } from "../../domain/experiment/model.js";
+export declare class ControlledExperimentCampaign {
+    readonly definition: ControlledExperimentCampaignDefinition;
+    readonly experiment: ControlledExperimentDefinition;
+    private readonly plannedRuns;
+    private readonly conditionIds;
+    private readonly assessments;
+    constructor(definition: ControlledExperimentCampaignDefinition, experiment: ControlledExperimentDefinition);
+    assessArtifact(artifact: ControlledExperimentRunArtifact): ControlledExperimentCampaignRunAssessment;
+    registerArtifact(artifact: ControlledExperimentRunArtifact): ControlledExperimentCampaignRunAssessment;
+    snapshot(): ControlledExperimentCampaignSnapshot;
+}

package/dist/application/experiment/ControlledExperimentCampaign.js

@@ -0,0 +1,159 @@
+export class ControlledExperimentCampaign {
+    definition;
+    experiment;
+    plannedRuns;
+    conditionIds;
+    assessments = new Map();
+    constructor(definition, experiment) {
+        this.definition = definition;
+        this.experiment = experiment;
+        assertCampaignDefinition(definition, experiment);
+        this.plannedRuns = new Map(definition.runs.map((run) => [run.runId, { ...run }]));
+        this.conditionIds = experiment.conditions.map(({ id }) => id);
+    }
+    assessArtifact(artifact) {
+        const planned = this.plannedRuns.get(artifact.run.id);
+        if (!planned) {
+            throw new Error(`Run ${artifact.run.id} is not part of campaign ${this.definition.id}.`);
+        }
+        const reasons = [];
+        if (artifact.experiment.id !== this.definition.experimentId ||
+            artifact.experiment.version !== this.definition.experimentVersion) {
+            reasons.push('experiment_identity_mismatch');
+        }
+        if (artifact.experiment.condition.id !== planned.conditionId) {
+            reasons.push('condition_mismatch');
+        }
+        if (artifact.run.status !== 'completed') {
+            reasons.push(`artifact_status_${artifact.run.status}`);
+        }
+        if (Math.abs(artifact.run.durationMs - this.definition.expectedDurationMs) >
+            this.definition.durationToleranceMs) {
+            reasons.push('duration_out_of_tolerance');
+        }
+        if (artifact.retention.truncated || artifact.retention.droppedObservations > 0) {
+            reasons.push('observation_retention_incomplete');
+        }
+        const observedPhaseIds = new Set(artifact.phaseMarkers.map(({ phaseId }) => phaseId));
+        for (const phaseId of this.definition.requiredPhaseIds) {
+            if (!observedPhaseIds.has(phaseId)) {
+                reasons.push(`missing_phase:${phaseId}`);
+            }
+        }
+        for (const metricId of this.definition.requiredMetricIds) {
+            if (!artifact.metricSummaries[metricId] || artifact.metricSummaries[metricId].count < 1) {
+                reasons.push(`missing_metric:${metricId}`);
+            }
+        }
+        for (const requirement of this.definition.environmentRequirements) {
+            const actual = readJsonPath(artifact.run.environment, requirement.path);
+            if (!jsonValuesEqual(actual, requirement.value)) {
+                reasons.push(`environment_mismatch:${requirement.path.join('.')}`);
+            }
+        }
+        return {
+            runId: planned.runId,
+            blindId: planned.blindId,
+            conditionId: planned.conditionId,
+            disposition: reasons.length === 0 ? 'accepted' : 'rejected',
+            reasons,
+            artifactStatus: artifact.run.status
+        };
+    }
+    registerArtifact(artifact) {
+        if (this.assessments.has(artifact.run.id)) {
+            throw new Error(`Run ${artifact.run.id} already has a registered artifact.`);
+        }
+        const assessment = this.assessArtifact(artifact);
+        this.assessments.set(assessment.runId, assessment);
+        return cloneAssessment(assessment);
+    }
+    snapshot() {
+        const acceptedRunCounts = Object.fromEntries(this.conditionIds.map((conditionId) => [conditionId, 0]));
+        const runs = this.definition.runs.map((run) => {
+            const assessment = this.assessments.get(run.runId) ?? pendingAssessment(run);
+            if (assessment.disposition === 'accepted') {
+                acceptedRunCounts[assessment.conditionId] = (acceptedRunCounts[assessment.conditionId] ?? 0) + 1;
+            }
+            return cloneAssessment(assessment);
+        });
+        const readyForReview = this.conditionIds.every((conditionId) => (acceptedRunCounts[conditionId] ?? 0) >= this.definition.validRunsRequiredPerCondition);
+        const next = runs.find(({ disposition }) => disposition === 'pending');
+        return {
+            campaignId: this.definition.id,
+            campaignVersion: this.definition.version,
+            readyForReview,
+            acceptedRunCounts,
+            runs,
+            nextRun: next ? { ...this.plannedRuns.get(next.runId) } : null
+        };
+    }
+}
+function assertCampaignDefinition(campaign, experiment) {
+    if (!campaign.id.trim() || !Number.isInteger(campaign.version) || campaign.version < 1) {
+        throw new Error('A controlled experiment campaign requires a stable id and positive integer version.');
+    }
+    if (campaign.experimentId !== experiment.id || campaign.experimentVersion !== experiment.version) {
+        throw new Error('Campaign and experiment identities must match.');
+    }
+    if (!Number.isFinite(campaign.expectedDurationMs) || campaign.expectedDurationMs <= 0) {
+        throw new Error('A campaign requires a positive expected run duration.');
+    }
+    if (!Number.isFinite(campaign.durationToleranceMs) || campaign.durationToleranceMs < 0) {
+        throw new Error('A campaign duration tolerance cannot be negative.');
+    }
+    if (!Number.isInteger(campaign.validRunsRequiredPerCondition) || campaign.validRunsRequiredPerCondition < 1) {
+        throw new Error('A campaign requires at least one valid run per condition.');
+    }
+    assertUniqueValues('run id', campaign.runs.map(({ runId }) => runId));
+    assertUniqueValues('blind id', campaign.runs.map(({ blindId }) => blindId));
+    assertUniqueValues('required phase id', campaign.requiredPhaseIds);
+    assertUniqueValues('required metric id', campaign.requiredMetricIds);
+    const conditionIds = new Set(experiment.conditions.map(({ id }) => id));
+    const phaseIds = new Set(experiment.phases.map(({ id }) => id));
+    const metricIds = new Set(experiment.metrics.map(({ id }) => id));
+    if (campaign.runs.some(({ conditionId }) => !conditionIds.has(conditionId))) {
+        throw new Error('Every campaign run must reference a declared experiment condition.');
+    }
+    if (campaign.requiredPhaseIds.some((phaseId) => !phaseIds.has(phaseId))) {
+        throw new Error('Every required campaign phase must exist in the experiment definition.');
+    }
+    if (campaign.requiredMetricIds.some((metricId) => !metricIds.has(metricId))) {
+        throw new Error('Every required campaign metric must exist in the experiment definition.');
+    }
+    for (const conditionId of conditionIds) {
+        const plannedCount = campaign.runs.filter((run) => run.conditionId === conditionId).length;
+        if (plannedCount < campaign.validRunsRequiredPerCondition) {
+            throw new Error(`Campaign condition ${conditionId} does not have enough planned runs.`);
+        }
+    }
+}
+function assertUniqueValues(kind, values) {
+    if (values.some((value) => !value.trim()) || new Set(values).size !== values.length) {
+        throw new Error(`Campaign ${kind}s must be non-empty and unique.`);
+    }
+}
+function pendingAssessment(run) {
+    return {
+        ...run,
+        disposition: 'pending',
+        reasons: [],
+        artifactStatus: null
+    };
+}
+function cloneAssessment(assessment) {
+    return { ...assessment, reasons: [...assessment.reasons] };
+}
+function readJsonPath(root, path) {
+    let current = root;
+    for (const segment of path) {
+        if (!current || typeof current !== 'object' || Array.isArray(current)) {
+            return undefined;
+        }
+        current = current[segment];
+    }
+    return current;
+}
+function jsonValuesEqual(left, right) {
+    return left !== undefined && JSON.stringify(left) === JSON.stringify(right);
+}

package/dist/application/experiment/ControlledExperimentRecorder.d.ts

@@ -0,0 +1,17 @@
+import { type JsonObject } from "../../domain/shared/json.js";
+import type { ControlledExperimentDefinition, ControlledExperimentObservationInput, ControlledExperimentRecorderSnapshot, ControlledExperimentRunArtifact, ControlledExperimentRunStart, ControlledExperimentRunStop } from "../../domain/experiment/model.js";
+export declare class ControlledExperimentRecorder {
+    readonly definition: ControlledExperimentDefinition;
+    private readonly conditionIds;
+    private readonly metricIds;
+    private readonly metricIdSet;
+    private readonly phaseIds;
+    private activeRun;
+    constructor(definition: ControlledExperimentDefinition);
+    start(input: ControlledExperimentRunStart): void;
+    markPhase(phaseId: string, observedAtMs: number, provenance?: JsonObject): boolean;
+    record(input: ControlledExperimentObservationInput): boolean;
+    stop(input: ControlledExperimentRunStop): ControlledExperimentRunArtifact;
+    isRecording(): boolean;
+    snapshot(): ControlledExperimentRecorderSnapshot;
+}