@orbytautomation/engine 0.1.2 → 0.2.1

package/dist/core/EngineConfig.d.ts

@@ -44,6 +44,11 @@ export interface OrbytEngineConfig {
      * @default 10
      */
     maxConcurrentWorkflows?: number;
+    /**
+     * Maximum number of steps that can execute concurrently within a workflow
+     * @default 10
+     */
+    maxConcurrentSteps?: number;
     /**
      * Default timeout for workflows (milliseconds)
      * @default 300000 (5 minutes)

package/dist/core/EngineConfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EngineConfig.d.ts","sourceRoot":"","sources":["../../src/core/EngineConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEnD;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEtE;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,aAAa,GAAG,SAAS,CAAC;AAEhE;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,iBAAiB;IAGhC;;;OAGG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAEhC;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,aAAa,CAAC;IAIrB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAI1B;;;OAGG;IACH,KAAK,CAAC,EAAE,QAAQ,CAAC;IAIjB;;;OAGG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAE1B;;OAEG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAIhC;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IAIrB;;;OAGG;IACH,KAAK,CAAC,EAAE,aAAa,EAAE,CAAC;IAIxB;;;OAGG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAEpB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAIvB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAIhB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;IAE1C;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAI1B;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAChC;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,GAAE,iBAAsB,GAAG,QAAQ,CAAC,IAAI,CAAC,iBAAiB,EAAE,OAAO,GAAG,aAAa,GAAG,gBAAgB,GAAG,UAAU,GAAG,OAAO,GAAG,UAAU,CAAC,CAAC,GAAG,IAAI,CAAC,iBAAiB,EAAE,OAAO,GAAG,aAAa,GAAG,gBAAgB,GAAG,UAAU,GAAG,OAAO,GAAG,UAAU,CAAC,CAsB/R;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAoB9D"}
+{"version":3,"file":"EngineConfig.d.ts","sourceRoot":"","sources":["../../src/core/EngineConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEnD;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEtE;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,aAAa,GAAG,SAAS,CAAC;AAEhE;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,iBAAiB;IAGhC;;;OAGG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAEhC;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,aAAa,CAAC;IAIrB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAI1B;;;OAGG;IACH,KAAK,CAAC,EAAE,QAAQ,CAAC;IAIjB;;;OAGG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAE1B;;OAEG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAIhC;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IAIrB;;;OAGG;IACH,KAAK,CAAC,EAAE,aAAa,EAAE,CAAC;IAIxB;;;OAGG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAEpB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAIvB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAIhB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;IAE1C;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAI1B;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAChC;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,GAAE,iBAAsB,GAAG,QAAQ,CAAC,IAAI,CAAC,iBAAiB,EAAE,OAAO,GAAG,aAAa,GAAG,gBAAgB,GAAG,UAAU,GAAG,OAAO,GAAG,UAAU,CAAC,CAAC,GAAG,IAAI,CAAC,iBAAiB,EAAE,OAAO,GAAG,aAAa,GAAG,gBAAgB,GAAG,UAAU,GAAG,OAAO,GAAG,UAAU,CAAC,CAuB/R;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAwB9D"}

package/dist/core/EngineConfig.js

@@ -15,6 +15,7 @@
 export function applyConfigDefaults(config = {}) {
     return {
         maxConcurrentWorkflows: config.maxConcurrentWorkflows ?? 10,
+        maxConcurrentSteps: config.maxConcurrentSteps ?? 10,
         defaultTimeout: config.defaultTimeout ?? 300000, // 5 minutes
         mode: config.mode ?? 'local',
         enableScheduler: config.enableScheduler ?? true,
@@ -45,6 +46,9 @@ export function validateConfig(config) {
     if (config.maxConcurrentWorkflows !== undefined && config.maxConcurrentWorkflows < 1) {
         throw new Error('maxConcurrentWorkflows must be at least 1');
     }
+    if (config.maxConcurrentSteps !== undefined && config.maxConcurrentSteps < 1) {
+        throw new Error('maxConcurrentSteps must be at least 1');
+    }
     if (config.defaultTimeout !== undefined && config.defaultTimeout < 1) {
         throw new Error('defaultTimeout must be positive');
     }

package/dist/core/EngineConfig.js.map

@@ -1 +1 @@
-{"version":3,"file":"EngineConfig.js","sourceRoot":"","sources":["../../src/core/EngineConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAiLH;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,SAA4B,EAAE;IAChE,OAAO;QACL,sBAAsB,EAAE,MAAM,CAAC,sBAAsB,IAAI,EAAE;QAC3D,cAAc,EAAE,MAAM,CAAC,cAAc,IAAI,MAAM,EAAE,YAAY;QAC7D,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,OAAO;QAC5B,eAAe,EAAE,MAAM,CAAC,eAAe,IAAI,IAAI;QAC/C,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,cAAc,EAAE,MAAM,CAAC,cAAc;QACrC,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,QAAQ,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC;QAChE,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,KAAK;QAChC,aAAa,EAAE,MAAM,CAAC,aAAa,IAAI,IAAI;QAC3C,YAAY,EAAE,MAAM,CAAC,YAAY,IAAI,IAAI;QACzC,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,cAAc;QAC3C,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,aAAa;QACtC,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,OAAO;QAC1C,gBAAgB,EAAE,MAAM,CAAC,gBAAgB,IAAI,OAAO,CAAC,GAAG,EAAE;QAC1D,YAAY,EAAE,MAAM,CAAC,YAAY,IAAI,KAAK;QAC1C,QAAQ,EAAE,MAAM,CAAC,QAAQ;KAC1B,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,MAAyB;IACtD,IAAI,MAAM,CAAC,sBAAsB,KAAK,SAAS,IAAI,MAAM,CAAC,sBAAsB,GAAG,CAAC,EAAE,CAAC;QACrF,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC/D,CAAC;IAED,IAAI,MAAM,CAAC,cAAc,KAAK,SAAS,IAAI,MAAM,CAAC,cAAc,GAAG,CAAC,EAAE,CAAC;QACrE,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;IACrD,CAAC;IAED,IAAI,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC,OAAO,EAAE,aAAa,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9E,MAAM,IAAI,KAAK,CAAC,iBAAiB,MAAM,CAAC,IAAI,gDAAgD,CAAC,CAAC;IAChG,CAAC;IAED,IAAI,MAAM,CAAC,QAAQ,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC/F,MAAM,IAAI,KAAK,CAAC,qBAAqB,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC1D,CAAC;IAED,IAAI,MAAM,CAAC,WAAW,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC;QACpF,MAAM,IAAI,KAAK,CAAC,wBAAwB,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC;IAChE,CAAC;AACH,CAAC"}
+{"version":3,"file":"EngineConfig.js","sourceRoot":"","sources":["../../src/core/EngineConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAuLH;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,SAA4B,EAAE;IAChE,OAAO;QACL,sBAAsB,EAAE,MAAM,CAAC,sBAAsB,IAAI,EAAE;QAC3D,kBAAkB,EAAE,MAAM,CAAC,kBAAkB,IAAI,EAAE;QACnD,cAAc,EAAE,MAAM,CAAC,cAAc,IAAI,MAAM,EAAE,YAAY;QAC7D,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,OAAO;QAC5B,eAAe,EAAE,MAAM,CAAC,eAAe,IAAI,IAAI;QAC/C,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,cAAc,EAAE,MAAM,CAAC,cAAc;QACrC,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,QAAQ,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC;QAChE,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,KAAK;QAChC,aAAa,EAAE,MAAM,CAAC,aAAa,IAAI,IAAI;QAC3C,YAAY,EAAE,MAAM,CAAC,YAAY,IAAI,IAAI;QACzC,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,cAAc;QAC3C,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,aAAa;QACtC,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,OAAO;QAC1C,gBAAgB,EAAE,MAAM,CAAC,gBAAgB,IAAI,OAAO,CAAC,GAAG,EAAE;QAC1D,YAAY,EAAE,MAAM,CAAC,YAAY,IAAI,KAAK;QAC1C,QAAQ,EAAE,MAAM,CAAC,QAAQ;KAC1B,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,MAAyB;IACtD,IAAI,MAAM,CAAC,sBAAsB,KAAK,SAAS,IAAI,MAAM,CAAC,sBAAsB,GAAG,CAAC,EAAE,CAAC;QACrF,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC/D,CAAC;IAED,IAAI,MAAM,CAAC,kBAAkB,KAAK,SAAS,IAAI,MAAM,CAAC,kBAAkB,GAAG,CAAC,EAAE,CAAC;QAC7E,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;IAC3D,CAAC;IAED,IAAI,MAAM,CAAC,cAAc,KAAK,SAAS,IAAI,MAAM,CAAC,cAAc,GAAG,CAAC,EAAE,CAAC;QACrE,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;IACrD,CAAC;IAED,IAAI,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC,OAAO,EAAE,aAAa,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9E,MAAM,IAAI,KAAK,CAAC,iBAAiB,MAAM,CAAC,IAAI,gDAAgD,CAAC,CAAC;IAChG,CAAC;IAED,IAAI,MAAM,CAAC,QAAQ,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC/F,MAAM,IAAI,KAAK,CAAC,qBAAqB,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC1D,CAAC;IAED,IAAI,MAAM,CAAC,WAAW,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC;QACpF,MAAM,IAAI,KAAK,CAAC,wBAAwB,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC;IAChE,CAAC;AACH,CAAC"}

package/dist/core/OrbytEngine.d.ts

@@ -1,6 +1,65 @@
 /**
  * Orbyt Engine - Main Public API
  *
+ * ============================================================================
+ * ARCHITECTURE & TRUST BOUNDARIES
+ * ============================================================================
+ *
+ * This class defines the ONLY public API surface for the Orbyt Engine.
+ * It establishes clear trust boundaries between different consumers:
+ *
+ * TRUSTED FIRST-PARTY CONSUMERS (Direct Access):
+ * -----------------------------------------------
+ * - @orbytautomation/cli (Official CLI)
+ * - @orbytautomation/api (Official API Server)
+ *
+ * These components may import and use:
+ *   - OrbytEngine class
+ *   - Public types (WorkflowResult, WorkflowRunOptions)
+ *   - Event bus for observability
+ *
+ * They MUST NOT:
+ *   - Import internal execution modules
+ *   - Bypass security validation
+ *   - Directly manipulate internal state
+ *
+ * EXTERNAL ECOSYSTEM COMPONENTS (Adapter/SDK Access):
+ * ----------------------------------------------------
+ * - MediaProc, DevForge, Voxa, etc.
+ * - Third-party plugins
+ * - Marketplace extensions
+ *
+ * These components must integrate via:
+ *   - Custom adapters (Adapter interface)
+ *   - Workflow definitions (YAML)
+ *   - SDK/client libraries
+ *
+ * They CANNOT:
+ *   - Import engine internals
+ *   - Access ExecutionEngine directly
+ *   - Manipulate billing/security context
+ *
+ * SECURITY GUARANTEES:
+ * --------------------
+ * 1. Users cannot specify reserved internal fields in workflows
+ *    (Validated at parse time - workflow is rejected if found)
+ *
+ * 2. Internal context is ALWAYS engine-generated
+ *    (executionId, billing, ownership, audit fields)
+ *
+ * 3. CLI/API can pass ownership context but cannot forge billing
+ *    (Ownership from trusted auth, billing from engine pricing snapshot)
+ *
+ * 4. All workflow execution goes through this single entry point
+ *    (No backdoor execution paths)
+ *
+ * WHY THIS MATTERS:
+ * -----------------
+ * - Billing integrity: Users cannot manipulate usage tracking
+ * - Audit trail: All executions are properly logged
+ * - Refactor safety: Internal changes don't break integrations
+ * - Security: Clear separation of trusted vs untrusted code
+ *
  * User-facing engine class that provides a clean, intuitive API for running workflows.
  * Wraps the internal ExecutionEngine with a simpler interface.
  *
@@ -13,64 +72,98 @@ import type { WorkflowResult } from '../execution/WorkflowExecutor.js';
 import { EventBus } from '../events/EventBus.js';
 import type { Adapter } from '@dev-ecosystem/core';
 import type { LifecycleHook } from '../hooks/LifecycleHooks.js';
-/**
- * Workflow run options
- * User-friendly options for running a workflow
- */
-export interface WorkflowRunOptions {
-    /**
-     * Workflow input variables
-     */
-    variables?: Record<string, any>;
-    /**
-     * Environment variables for workflow execution
-     */
-    env?: Record<string, any>;
-    /**
-     * Secrets (will not be logged)
-     */
-    secrets?: Record<string, any>;
-    /**
-     * Additional execution context
-     */
-    context?: Record<string, any>;
-    /**
-     * Execution timeout in milliseconds
-     */
-    timeout?: number;
-    /**
-     * Continue execution even if steps fail
-     */
-    continueOnError?: boolean;
-    /**
-     * Dry run mode - validate and plan but don't execute
-     */
-    dryRun?: boolean;
-    /**
-     * Who/what triggered this execution
-     */
-    triggeredBy?: string;
-}
-/**
- * Workflow load options
- * Options for loading a workflow from file
- */
-export interface WorkflowLoadOptions {
-    /**
-     * Base directory for resolving relative paths
-     */
-    baseDir?: string;
-    /**
-     * Variables to inject during parsing
-     */
-    variables?: Record<string, any>;
-}
+import { type OwnershipContext } from '../execution/InternalExecutionContext.js';
+import { WorkflowRunOptions } from '../types/core-types.js';
 /**
  * OrbytEngine - Main public API
  *
+ * ARCHITECTURE & TRUST BOUNDARIES
+ * =================
+ *
+ * This class defines the ONLY public API surface for the Orbyt Engine.
+ * It establishes clear trust boundaries between different consumers:
+ *
+ * TRUSTED FIRST-PARTY CONSUMERS (Direct Access):
+ * -----------------------------------------------
+ * - @orbyt/cli (Official CLI)
+ * - @orbyt/api (Official API Server)
+ *
+ * These components may import and use:
+ *   - OrbytEngine class
+ *   - Public types (WorkflowResult, WorkflowRunOptions)
+ *   - Event bus for observability
+ *
+ * They MUST NOT:
+ *   - Import internal execution modules
+ *   - Bypass security validation
+ *   - Directly manipulate internal state
+ *
+ * EXTERNAL ECOSYSTEM COMPONENTS (Adapter/SDK Access):
+ * ----------------------------------------------------
+ * - MediaProc, DevForge, Voxa, etc.
+ * - Third-party plugins
+ * - Marketplace extensions
+ *
+ * These components must integrate via:
+ *   - Custom adapters (Adapter interface)
+ *   - Workflow definitions (YAML)
+ *   - SDK/client libraries
+ *
+ * They CANNOT:
+ *   - Import engine internals
+ *   - Access ExecutionEngine directly
+ *   - Manipulate billing/security context
+ *
+ * SECURITY GUARANTEES:
+ * --------------------
+ * 1. Users cannot specify reserved internal fields in workflows
+ *    (Validated at parse time - workflow is rejected if found)
+ *
+ * 2. Internal context is ALWAYS engine-generated
+ *    (executionId, billing, ownership, audit fields)
+ *
+ * 3. CLI/API can pass ownership context but cannot forge billing
+ *    (Ownership from trusted auth, billing from engine pricing snapshot)
+ *
+ * 4. All workflow execution goes through this single entry point
+ *    (No backdoor execution paths)
+ *
+ * WHY THIS MATTERS:
+ * -----------------
+ * - Billing integrity: Users cannot manipulate usage tracking
+ * - Audit trail: All executions are properly logged
+ * - Refactor safety: Internal changes don't break integrations
+ * - Security: Clear separation of trusted vs untrusted code
+ *
+ * User-facing engine class that provides a clean, intuitive API for running workflows.
+ * Wraps the internal ExecutionEngine with a simpler interface.
+ *
  * This is the primary interface for working with Orbyt workflows.
  * Provides a clean, user-friendly API that abstracts internal complexity.
  *
+ * SECURITY & ARCHITECTURE:
+ * =================
+ * This class is the SINGLE ENTRY POINT for all workflow execution.
+ * All execution paths (run, validate, dryRun) go through this engine.
+ *
+ * INTERNAL CONTEXT INJECTION:
+ * - Engine ALWAYS creates internal execution context
+ * - Users CANNOT override billing, identity, or ownership fields
+ * - Context sanitization removes any injection attempts
+ * - Billing tracking is engine-controlled, never user-controlled
+ *
+ * FIELDS THAT ARE NEVER USER-CONTROLLED:
+ * - executionId, runId, traceId (identity)
+ * - userId, workspaceId, subscriptionId (ownership)
+ * - billingId, pricingTier, costCalculated (billing)
+ * - usage counters, step counts, duration (metrics)
+ * - security policies, permissions (access control)
+ *
+ * WORKFLOW YAML vs ENGINE RUNTIME:
+ * - User controls: business logic, step definitions, parameters
+ * - Engine controls: billing, identity, execution tracking, security
+ * - Clear separation prevents billing manipulation and security bypass
+ *
  * @example
  * ```ts
  * // Basic usage
@@ -91,6 +184,17 @@ export interface WorkflowLoadOptions {
  *   timeout: 60000,
  *   dryRun: false
  * });
+ *
+ * // From bridge/API with ownership context
+ * const result = await engine.run('./workflow.yaml', {
+ *   variables: { input: 'data' },
+ *   _ownershipContext: {
+ *     userId: 'user_123',
+ *     workspaceId: 'ws_456',
+ *     subscriptionTier: 'pro',
+ *     billingMode: 'ecosystem',
+ *   }
+ * });
  * ```
  */
 export declare class OrbytEngine {
@@ -103,6 +207,7 @@ export declare class OrbytEngine {
     private adapterRegistry;
     private context;
     private isStarted;
+    private readonly version;
     constructor(config?: OrbytEngineConfig);
     /**
      * Wire engine components together
@@ -126,48 +231,70 @@ export declare class OrbytEngine {
     /**
      * Run a workflow
      *
-     * Main method for executing workflows. Accepts either a file path or
-     * a parsed workflow object.
+     * ARCHITECTURE NOTE:
+     * ==================
+     * This method is I/O-AGNOSTIC - it does NOT read files or touch filesystem.
+     * File loading is handled byWorkflowLoader (separate utility layer).
      *
-     * @param workflow - Workflow file path, YAML string, or parsed workflow
+     * This keeps the engine:
+     * - Testable (no file dependencies)
+     * - Embeddable (works in browsers, workers, distributed systems)
+     * - API-safe (can accept workflows from any source)
+     *
+     * Main method for executing workflows.
+     *
+     * @param workflow - Parsed workflow object OR YAML string content
      * @param options - Execution options
      * @returns Workflow execution result
      *
      * @example
      * ```ts
-     * // Run from file
-     * const result = await engine.run('./workflow.yaml');
+     * import { WorkflowLoader } from '@orbytautomation/engine';
      *
-     * // Run with options
-     * const result = await engine.run('./workflow.yaml', {
-     *   variables: { input: 'data.json' },
-     *   timeout: 30000
-     * });
+     * // Load from file (use WorkflowLoader)
+     * const workflow = await WorkflowLoader.fromFile('./workflow.yaml');
+     * const result = await engine.run(workflow);
      *
-     * // Run from string
+     * // Run from YAML string
      * const yaml = `
-     * name: my-workflow
-     * steps:
-     *   - id: step1
-     *     uses: shell.exec
-     *     with:
-     *       command: echo "Hello"
+     * version: "1.0"
+     * kind: workflow
+     * workflow:
+     *   steps:
+     *     - id: step1
+     *       uses: shell.exec
+     *       with:
+     *         command: echo "Hello"
      * `;
      * const result = await engine.run(yaml);
+     *
+     * // Run from object (testing)
+     * const result = await engine.run(mockWorkflowObject);
      * ```
      */
     run(workflow: string | ParsedWorkflow, options?: WorkflowRunOptions): Promise<WorkflowResult>;
     /**
-     * Load a workflow from file
-     *
-     * @param filePath - Path to workflow file
-     * @param options - Load options
-     * @returns Parsed workflow
+     * Sanitize user-provided options to prevent injection attacks
+     * SECURITY: Users should never be able to override internal fields
+     */
+    private sanitizeUserOptions;
+    /**
+     * Billing lifecycle hook - called after workflow completes
+     * INTERNAL: Used to track usage and send billing data to analytics bridge
      */
-    loadWorkflow(filePath: string, options?: WorkflowLoadOptions): Promise<ParsedWorkflow>;
+    private onWorkflowBillingComplete;
     /**
      * Parse a workflow from YAML string
      *
+     * WORKFLOW PARSING PIPELINE:
+     * ==========================
+     * 1. Validate YAML syntax (catch malformed YAML early)
+     * 2. Parse YAML to object
+     * 3. Security validation (reject reserved internal fields)
+     * 4. Schema validation (validate against Zod schema)
+     * 5. Step parsing and validation
+     * 6. Return parsed workflow ready for execution
+     *
      * @param yaml - YAML workflow definition
      * @returns Parsed workflow
      */
@@ -176,12 +303,16 @@ export declare class OrbytEngine {
      * Validate a workflow without executing it
      *
      * @param workflow - Workflow to validate
+     * @param options - Validation options (optional ownership context for tracking)
      * @returns True if valid, throws if invalid
      */
-    validate(workflow: string | ParsedWorkflow): Promise<boolean>;
+    validate(workflow: string | ParsedWorkflow, options?: {
+        _ownershipContext?: Partial<OwnershipContext>;
+    }): Promise<boolean>;
     /**
      * Perform a dry run of a workflow
      * Validates and plans execution without running steps
+     * INTERNAL: Creates internal context for tracking (non-billable)
      */
     private dryRun;
     /**

package/dist/core/OrbytEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OrbytEngine.d.ts","sourceRoot":"","sources":["../../src/core/OrbytEngine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"OrbytEngine.d.ts","sourceRoot":"","sources":["../../src/core/OrbytEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAY,MAAM,mBAAmB,CAAC;AAErE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAKxD,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAClF,OAAO,KAAK,EAAE,cAAc,EAAoB,MAAM,kCAAkC,CAAC;AACzF,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAGjD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAGhE,OAAO,EAA0B,KAAK,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAGzG,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0HG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAyC;IACvD,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,gBAAgB,CAAmB;IAC3C,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;gBAE/B,MAAM,GAAE,iBAAsB;IA0D1C;;OAEG;IACH,OAAO,CAAC,eAAe;IAgBvB;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAU/B;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAkB5B;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAkB3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CG;IACG,GAAG,CACP,QAAQ,EAAE,MAAM,GAAG,cAAc,EACjC,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,cAAc,CAAC;IAiJ1B;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAqC3B;;;OAGG;YACW,yBAAyB;IAsCvC;;;;;;;;;;;;;;OAcG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc;IA4B3C;;;;;;OAMG;IACG,QAAQ,CACZ,QAAQ,EAAE,MAAM,GAAG,cAAc,EACjC,OAAO,CAAC,EAAE;QAAE,iBAAiB,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAA;KAAE,GAC1D,OAAO,CAAC,OAAO,CAAC;IA4BnB;;;;OAIG;YACW,MAAM;IAqDpB;;;;OAIG;IACH,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAMvC;;;;OAIG;IACH,gBAAgB,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,IAAI;IAM3C;;;;OAIG;IACH,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI;IAKvC;;;;OAIG;IACH,aAAa,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,IAAI;IAK3C;;;;OAIG;IACH,WAAW,IAAI,QAAQ;IAIvB;;;;OAIG;IACH,UAAU,IAAI,aAAa;IAI3B;;;;OAIG;IACH,SAAS,IAAI,iBAAiB;IAI9B;;OAEG;IACH,OAAO,CAAC,GAAG;CAkBZ"}