@mat3ra/wode 2026.6.5-0 → 2026.6.18-0

package/dist/js/utils/repair.js

@@ -0,0 +1,140 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.repairWorkflow = repairWorkflow;
+const in_memory_1 = require("@mat3ra/code/dist/js/entity/in_memory");
+const utils_1 = require("@mat3ra/utils");
+const enums_1 = require("../enums");
+const Subworkflow_1 = __importDefault(require("../Subworkflow"));
+const ConditionUnit_1 = __importDefault(require("../units/ConditionUnit"));
+const ExecutionUnit_1 = __importDefault(require("../units/ExecutionUnit"));
+function toErrorUnitSchema(unitData, error) {
+    var _a, _b, _c, _d;
+    let reasonPayload;
+    if (error instanceof in_memory_1.EntityError && error.details) {
+        reasonPayload = {
+            error: error.details.error,
+            json: unitData,
+        };
+    }
+    else if (error instanceof Error) {
+        reasonPayload = {
+            error: { message: error.message, name: error.name },
+            json: unitData,
+        };
+    }
+    else {
+        reasonPayload = {
+            error,
+            json: unitData,
+        };
+    }
+    return {
+        results: [],
+        preProcessors: [],
+        postProcessors: [],
+        monitors: [],
+        name: (_a = unitData.name) !== null && _a !== void 0 ? _a : enums_1.UnitType.error,
+        type: enums_1.UnitType.error,
+        status: enums_1.UnitStatus.error,
+        flowchartId: (_b = unitData.flowchartId) !== null && _b !== void 0 ? _b : utils_1.Utils.uuid.getUUID(),
+        reason: JSON.stringify(reasonPayload),
+        next: (_c = unitData.next) !== null && _c !== void 0 ? _c : "",
+        head: (_d = unitData.head) !== null && _d !== void 0 ? _d : false,
+    };
+}
+function repairExecutionUnit(unitData) {
+    try {
+        return new ExecutionUnit_1.default(unitData).toJSON();
+    }
+    catch (error) {
+        return toErrorUnitSchema(unitData, error);
+    }
+}
+function repairConditionUnit(unitData) {
+    try {
+        return new ConditionUnit_1.default(unitData).toJSON();
+    }
+    catch (error) {
+        return toErrorUnitSchema(unitData, error);
+    }
+}
+function getSubworkflowValidationError(subworkflow) {
+    // Two checks, same order as the old isValid() path (construct + validate), but split so we
+    // keep AJV errors when hydration would fail first:
+    // 1. validateData — JSON Schema on raw persisted subworkflow (no Application/ModelFactory/units).
+    //    Surfaces structured AJV errors (e.g. missing model) before the constructor runs.
+    // 2. new Subworkflow().validate() — hydration (app, model, units) then schema on the instance.
+    //    Catches schema-valid JSON that still cannot be built (unknown model, bad units, etc.).
+    try {
+        Subworkflow_1.default.validateData({ ...subworkflow });
+        new Subworkflow_1.default(subworkflow).validate();
+        return null;
+    }
+    catch (error) {
+        if (error instanceof in_memory_1.EntityError || error instanceof Error) {
+            return error;
+        }
+        return new Error(String(error));
+    }
+}
+function repairSubworkflow(subworkflowData) {
+    const units = subworkflowData.units.map((unit) => {
+        if (unit.type === enums_1.UnitType.execution) {
+            return repairExecutionUnit(unit);
+        }
+        if (unit.type === enums_1.UnitType.condition) {
+            return repairConditionUnit(unit);
+        }
+        return unit;
+    });
+    return { ...subworkflowData, units };
+}
+function repairWorkflow(workflowData) {
+    const subworkflows = workflowData.subworkflows.map((subworkflow) => {
+        return repairSubworkflow(subworkflow);
+    });
+    const invalidSubworkflows = subworkflows
+        .map((subworkflow) => {
+        const error = getSubworkflowValidationError(subworkflow);
+        return error ? { subworkflow, error } : null;
+    })
+        .filter((entry) => entry !== null);
+    const units = workflowData.units.map((unit) => {
+        const invalidEntry = invalidSubworkflows.find(({ subworkflow }) => subworkflow._id === unit._id);
+        if (invalidEntry) {
+            const { subworkflow, error } = invalidEntry;
+            const errorUnit = toErrorUnitSchema(unit, error);
+            const reasonPayload = {
+                ...JSON.parse(errorUnit.reason),
+                json: { unit, subworkflow },
+            };
+            return {
+                ...errorUnit,
+                _id: unit._id,
+                name: unit.name || errorUnit.name,
+                flowchartId: unit.flowchartId,
+                reason: JSON.stringify(reasonPayload),
+                preProcessors: unit.preProcessors || [],
+                postProcessors: unit.postProcessors || [],
+                monitors: unit.monitors || [],
+                results: unit.results || [],
+            };
+        }
+        return unit;
+    });
+    const validSubworkflows = subworkflows.filter((subworkflow) => {
+        return !invalidSubworkflows.some(({ subworkflow: invalid }) => invalid._id === subworkflow._id);
+    });
+    const workflows = workflowData.workflows.map((nested) => {
+        return repairWorkflow(nested);
+    });
+    return {
+        ...workflowData,
+        subworkflows: validSubworkflows,
+        workflows,
+        units,
+    };
+}

package/dist/js/workflows/default.d.ts

@@ -1,3 +1,3 @@
-import type { WorkflowSchema } from "@mat3ra/esse/dist/js/types";
+import type { WorkflowSchema } from "./types";
 declare const defaultWorkflowConfig: WorkflowSchema;
 export default defaultWorkflowConfig;

package/dist/js/workflows/types.d.ts

@@ -0,0 +1,4 @@
+import type { WorkflowSchema as EsseWorkflowSchema } from "@mat3ra/esse/dist/js/types";
+export type WorkflowSchema = EsseWorkflowSchema & {
+    workflows: WorkflowSchema[];
+};

package/dist/js/workflows/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mat3ra/wode",
-    "version": "2026.6.5-0",
+    "version": "2026.6.18-0",
     "description": "WOrkflow DEfinitions",
     "scripts": {
         "test": "mocha --recursive --bail --require ts-node/register 'tests/js/**/*.ts'",
@@ -42,7 +42,7 @@
         "@exabyte-io/eslint-config": "2025.5.13-0",
         "@mat3ra/ade": "2026.5.28-0",
         "@mat3ra/code": "2026.5.27-0",
-        "@mat3ra/esse": "2026.5.28-0",
+        "@mat3ra/esse": "2026.6.16-0",
         "@mat3ra/ide": "2026.5.28-0",
         "@mat3ra/made": "2026.5.28-0",
         "@mat3ra/mode": "2026.5.29-1",
@@ -50,6 +50,8 @@
         "@mat3ra/standata": "2026.5.28-0",
         "@mat3ra/tsconfig": "^2024.6.3-0",
         "@mat3ra/utils": "2025.9.20-0",
+        "@typescript-eslint/eslint-plugin": "^5.62.0",
+        "@typescript-eslint/parser": "^5.62.0",
         "@types/nunjucks": "^3.2.6",
         "chai": "^4.3.4",
         "eslint": "^7.32.0",
@@ -76,7 +78,7 @@
     "peerDependencies": {
         "@mat3ra/ade": "*",
         "@mat3ra/code": "*",
-        "@mat3ra/esse": "*",
+        "@mat3ra/esse": "file:../esse/mat3ra-esse-0.0.0.tgz",
         "@mat3ra/ide": "*",
         "@mat3ra/made": "*",
         "@mat3ra/mode": "*",

package/src/js/Subworkflow.ts

@@ -100,13 +100,18 @@ class Subworkflow extends InMemoryEntity implements SubworkflowSchema {
 
     static get defaultConfig() {
         const defaultName = "New Subworkflow";
+        const application = new ApplicationRegistry().getDefaultApplication();
+
+        if (!application) {
+            throw new Error("No default application found");
+        }
+
         return {
             _id: Utils.uuid.getUUID(),
             name: defaultName,
-            application: new ApplicationRegistry().getDefaultApplication(),
-            // TODO: confirm if `functional` is required field. If not, update ESSE schema
+            application,
             // `Model.defaultConfig` from @mat3ra/mode may omit `functional`; ESSE subworkflow schema requires it once schemas are registered.
-            model: { ...Model.defaultConfig, functional: "pbe" },
+            model: { ...Model.defaultConfig, functional: "pbe" as const },
             properties: [],
             units: [],
         };
@@ -274,7 +279,7 @@ class Subworkflow extends InMemoryEntity implements SubworkflowSchema {
         return `units.${index}`;
     }
 
-    private findUnitWithTag(tag: UnitTag) {
+    private findAssignmentUnitWithTag(tag: UnitTag) {
         return this.units
             .filter((unit) => unit.type === UnitType.assignment)
             .find((unit) => unit.tags?.includes(tag));
@@ -285,29 +290,35 @@ class Subworkflow extends InMemoryEntity implements SubworkflowSchema {
     }
 
     get convergenceParam() {
-        return this.findUnitWithTag(UnitTag.hasConvergenceParam)?.operand;
+        return this.findAssignmentUnitWithTag(UnitTag.hasConvergenceParam)?.operand;
     }
 
     get convergenceResult() {
-        return this.findUnitWithTag(UnitTag.hasConvergenceResult)?.operand;
+        return this.findAssignmentUnitWithTag(UnitTag.hasConvergenceResult)?.operand;
     }
 
     convergenceSeries(scopeTrack: JobSchema["scopeTrack"]) {
-        if (!this.hasConvergence || !scopeTrack?.length) {
+        const { convergenceParam, convergenceResult } = this;
+
+        if (!convergenceParam || !convergenceResult || !scopeTrack?.length) {
             return [];
         }
 
         let prevResult: unknown;
+        // `scopeTrack` stores per-repetition diffs: each item only carries the global/local keys
+        // that were added or changed in that repetition (see UnitEndpoint.saveUnitStatus). Accumulate
+        // the global scope across items so each iteration reads the full scope, not just its delta.
+        // This also stays correct for legacy full-snapshot scopeTrack data, since re-applying a full
+        // snapshot is idempotent.
+        const accumulatedGlobal: Record<string, unknown> = {};
 
         return scopeTrack
             .map((scopeItem, i) => {
+                Object.assign(accumulatedGlobal, scopeItem.scope?.global);
                 return {
                     x: i,
-                    // TODO: fix types
-                    // @ts-ignore
-                    param: scopeItem.scope?.global[this.convergenceParam],
-                    // @ts-ignore
-                    y: scopeItem.scope?.global[this.convergenceResult],
+                    param: accumulatedGlobal[convergenceParam],
+                    y: accumulatedGlobal[convergenceResult],
                 };
             })
             .filter(({ y }) => {

package/src/js/Workflow.ts

@@ -15,11 +15,7 @@ import { namedEntityMixin } from "@mat3ra/code/dist/js/entity/mixins/NamedEntity
 import { Taggable, taggableMixin } from "@mat3ra/code/dist/js/entity/mixins/TaggableMixin";
 import JSONSchemasInterface from "@mat3ra/esse/dist/js/esse/JSONSchemasInterface";
 import type { AnyObject } from "@mat3ra/esse/dist/js/esse/types";
-import type {
-    ApplicationSchema,
-    SubworkflowSchema,
-    WorkflowSchema,
-} from "@mat3ra/esse/dist/js/types";
+import type { ApplicationSchema, SubworkflowSchema } from "@mat3ra/esse/dist/js/types";
 import { ComputedEntityMixin, computedEntityMixin } from "@mat3ra/ide/dist/js/compute";
 import type { Material } from "@mat3ra/made";
 import type { MetaPropertyHolder } from "@mat3ra/prode";
@@ -45,6 +41,7 @@ import {
     getUsedModels,
 } from "./utils/workflow";
 import defaultWorkflowConfig from "./workflows/default";
+import type { WorkflowSchema } from "./workflows/types";
 
 interface Workflow
     extends Defaultable,

package/src/js/context/mixins/MaterialContextMixin.ts

@@ -9,7 +9,7 @@ export type MaterialContextMixin = {
     readonly isMaterialCreatedDefault: boolean;
     readonly isMaterialUpdated: boolean;
     material: OrderedMaterial;
-    extraData?: { materialHash: string };
+    extraData?: { materialHash?: string };
     initMaterialContextMixin(externalContext: MaterialExternalContext): void;
     updateMaterialHash(): void;
 };

package/src/js/enums.ts

@@ -11,6 +11,7 @@ export const UNIT_TYPES = {
     subworkflow: "subworkflow",
     io: "io",
     assertion: "assertion",
+    error: "error",
 } as const;
 
 export enum UnitType {
@@ -24,6 +25,7 @@ export enum UnitType {
     subworkflow = "subworkflow",
     io = "io",
     assertion = "assertion",
+    error = "error",
 }
 
 export enum UnitTag {

package/src/js/generated/ErrorUnitSchemaMixin.ts

@@ -0,0 +1,28 @@
+import type { InMemoryEntity } from "@mat3ra/code/dist/js/entity";
+import type { ErrorUnitMixinSchema } from "@mat3ra/esse/dist/js/types";
+
+export type ErrorUnitSchemaMixin = ErrorUnitMixinSchema;
+
+export type ErrorUnitInMemoryEntity = InMemoryEntity & ErrorUnitSchemaMixin;
+
+export function errorUnitSchemaMixin<T extends InMemoryEntity>(
+    item: InMemoryEntity,
+): asserts item is T & ErrorUnitSchemaMixin {
+    // @ts-expect-error
+    const properties: InMemoryEntity & ErrorUnitSchemaMixin = {
+        get type() {
+            return this.prop<ErrorUnitMixinSchema["type"]>("type");
+        },
+        set type(value: ErrorUnitMixinSchema["type"]) {
+            this.setProp("type", value);
+        },
+        get reason() {
+            return this.requiredProp<ErrorUnitMixinSchema["reason"]>("reason");
+        },
+        set reason(value: ErrorUnitMixinSchema["reason"]) {
+            this.setProp("reason", value);
+        },
+    };
+
+    Object.defineProperties(item, Object.getOwnPropertyDescriptors(properties));
+}

package/src/js/index.ts

@@ -7,6 +7,7 @@ import {
     AssignmentUnit,
     BaseUnit,
     ConditionUnit,
+    ErrorUnit,
     ExecutionUnit,
     IOUnit,
     MapUnit,
@@ -21,6 +22,7 @@ import Workflow from "./Workflow";
 export type { OrderedMaterial } from "./context/mixins/MaterialContextMixin";
 export type { MaterialsSet } from "./context/mixins/MaterialsSetContextMixin";
 export type { AnySubworkflowUnit, DefaultSubworkflowUnitType } from "./units/factory";
+export { repairWorkflow } from "./utils/repair";
 export {
     Subworkflow,
     Workflow,
@@ -33,6 +35,7 @@ export {
     AssertionUnit,
     AssignmentUnit,
     ConditionUnit,
+    ErrorUnit,
     IOUnit,
     MapUnit,
     ReduceUnit,

package/src/js/units/ErrorUnit.ts

@@ -0,0 +1,42 @@
+import type { Constructor } from "@mat3ra/code/dist/js/utils/types";
+import JSONSchemasInterface from "@mat3ra/esse/dist/js/esse/JSONSchemasInterface";
+import type { AnyObject } from "@mat3ra/esse/dist/js/esse/types";
+import type { ErrorUnitSchema } from "@mat3ra/esse/dist/js/types";
+
+import { UnitStatus, UnitType } from "../enums";
+import { type ErrorUnitSchemaMixin, errorUnitSchemaMixin } from "../generated/ErrorUnitSchemaMixin";
+import BaseUnit from "./BaseUnit";
+
+type Schema = ErrorUnitSchema;
+type Base = typeof BaseUnit<Schema> & Constructor<ErrorUnitSchemaMixin>;
+
+export type ErrorUnitConfig = Partial<Schema>;
+
+class ErrorUnit extends (BaseUnit as Base) implements Schema {
+    declare toJSON: () => Schema & AnyObject;
+
+    declare _json: Schema & AnyObject;
+
+    static get jsonSchema() {
+        return JSONSchemasInterface.getSchemaById("workflow/unit/error");
+    }
+
+    constructor(config: ErrorUnitConfig) {
+        const schema = {
+            name: UnitType.error,
+            results: [],
+            preProcessors: [],
+            postProcessors: [],
+            monitors: [],
+            reason: "",
+            ...config,
+            type: UnitType.error as Schema["type"],
+            status: config.status ?? UnitStatus.error,
+        };
+        super(schema);
+    }
+}
+
+errorUnitSchemaMixin(ErrorUnit.prototype);
+
+export default ErrorUnit;

package/src/js/units/factory.ts

@@ -1,8 +1,10 @@
 import type {
+    ApplicationSchema,
     AssertionUnitSchema,
     AssignmentUnitSchema,
     ConditionUnitSchema,
     DataIOUnitSchema,
+    ErrorUnitSchema,
     ExecutionUnitSchema,
     MapUnitSchema,
     ReduceUnitSchema,
@@ -14,35 +16,43 @@ import { UnitType } from "../enums";
 import AssertionUnit, { type AssertionUnitConfig } from "./AssertionUnit";
 import AssignmentUnit, { type AssignmentUnitConfig } from "./AssignmentUnit";
 import ConditionUnit, { type ConditionUnitConfig } from "./ConditionUnit";
+import ErrorUnit, { type ErrorUnitConfig } from "./ErrorUnit";
 import ExecutionUnit, { type ExecutionUnitConfig } from "./ExecutionUnit";
 import IOUnit, { type IOUnitConfig } from "./IOUnit";
 import MapUnit from "./MapUnit";
 import ReduceUnit from "./ReduceUnit";
 import SubworkflowUnit from "./SubworkflowUnit";
 
-export type AnyWorkflowUnit = MapUnit | SubworkflowUnit | ReduceUnit;
+export type AnyWorkflowUnit = MapUnit | SubworkflowUnit | ReduceUnit | ErrorUnit;
 
-export type AnyWorkflowUnitSchema = MapUnitSchema | SubworkflowUnitSchema | ReduceUnitSchema;
+export type AnyWorkflowUnitSchema =
+    | MapUnitSchema
+    | SubworkflowUnitSchema
+    | ReduceUnitSchema
+    | ErrorUnitSchema;
 
 export type AnySubworkflowUnit =
     | ExecutionUnit
     | AssignmentUnit
     | ConditionUnit
     | IOUnit
-    | AssertionUnit;
+    | AssertionUnit
+    | ErrorUnit;
 
 export type AnySubworkflowUnitSchema =
     | ExecutionUnitSchema
     | AssertionUnitSchema
     | AssignmentUnitSchema
     | ConditionUnitSchema
-    | DataIOUnitSchema;
+    | DataIOUnitSchema
+    | ErrorUnitSchema;
 
 type ExcutionConfig = ExecutionUnitConfig & Pick<ExecutionUnitSchema, "type">;
 type AssignmentConfig = AssignmentUnitConfig & Pick<AssignmentUnitSchema, "type">;
 type ConditionConfig = ConditionUnitConfig & Pick<ConditionUnitSchema, "type">;
 type IOConfig = IOUnitConfig & Pick<DataIOUnitSchema, "type">;
 type AssertionConfig = AssertionUnitConfig & Pick<AssertionUnitSchema, "type">;
+type ErrorConfig = ErrorUnitConfig & Pick<ErrorUnitSchema, "type">;
 
 /** Subworkflow unit kinds supported by {@link UnitFactory.createDefaultSubworkflowUnit}. */
 export type DefaultSubworkflowUnitType =
@@ -59,16 +69,20 @@ export class UnitFactory {
      */
     static createDefaultSubworkflowUnit(
         type: "execution",
-        application: ExecutionUnitSchema["application"],
-    ): AnySubworkflowUnit;
+        application: ApplicationSchema,
+    ): ExecutionUnit;
 
-    static createDefaultSubworkflowUnit(
-        type: "assignment" | "condition" | "io" | "assertion",
-    ): AnySubworkflowUnit;
+    static createDefaultSubworkflowUnit(type: "assignment"): AssignmentUnit;
+
+    static createDefaultSubworkflowUnit(type: "condition"): ConditionUnit;
+
+    static createDefaultSubworkflowUnit(type: "io"): IOUnit;
+
+    static createDefaultSubworkflowUnit(type: "assertion"): AssertionUnit;
 
     static createDefaultSubworkflowUnit(
         type: DefaultSubworkflowUnitType,
-        application?: ExecutionUnitSchema["application"],
+        application?: ApplicationSchema,
     ): AnySubworkflowUnit {
         if (type === "execution") {
             if (application === undefined) {
@@ -105,13 +119,21 @@ export class UnitFactory {
                 return new SubworkflowUnit(config);
             case UnitType.reduce:
                 return new ReduceUnit(config);
+            case UnitType.error:
+                return new ErrorUnit(config);
             default:
                 throw new Error(`Unknown unit type: ${config.type}`);
         }
     }
 
     static createInSubworkflow(
-        config: ExcutionConfig | AssignmentConfig | ConditionConfig | IOConfig | AssertionConfig,
+        config:
+            | ExcutionConfig
+            | AssignmentConfig
+            | ConditionConfig
+            | IOConfig
+            | AssertionConfig
+            | ErrorConfig,
     ): AnySubworkflowUnit {
         switch (config.type) {
             case UnitType.execution:
@@ -124,6 +146,8 @@ export class UnitFactory {
                 return new IOUnit(config);
             case UnitType.assertion:
                 return new AssertionUnit(config);
+            case UnitType.error:
+                return new ErrorUnit(config);
             default:
                 throw new Error(`Unknown unit type: ${config.type}`);
         }

package/src/js/units/index.ts

@@ -2,6 +2,7 @@ import AssertionUnit from "./AssertionUnit";
 import AssignmentUnit from "./AssignmentUnit";
 import BaseUnit from "./BaseUnit";
 import ConditionUnit from "./ConditionUnit";
+import ErrorUnit from "./ErrorUnit";
 import ExecutionUnit from "./ExecutionUnit";
 import { UnitFactory } from "./factory";
 import IOUnit from "./IOUnit";
@@ -16,6 +17,7 @@ export {
     AssertionUnit,
     AssignmentUnit,
     ConditionUnit,
+    ErrorUnit,
     ExecutionUnit,
     IOUnit,
     MapUnit,

package/src/js/utils/index.ts

@@ -1,3 +1,4 @@
 export * as units from "./units";
 export * as workflow from "./workflow";
 export * as baseUnits from "./baseUnits";
+export * as repair from "./repair";