@contractspec/integration.workflow-devkit 0.1.1 → 0.1.3

package/README.md

@@ -19,6 +19,17 @@ Workflow DevKit compiler and runtime bridges for ContractSpec `WorkflowSpec`.
 - `@contractspec/integration.workflow-devkit/agent-adapter`
 - `@contractspec/integration.workflow-devkit/next`
 
+## Workflow vs step boundary
+
+Workflow DevKit code runs across two different execution contexts:
+
+- Workflow functions (`"use workflow"`) orchestrate control flow and must stay deterministic.
+- Step functions (`"use step"`) perform the actual Node.js work.
+
+This matches the Workflow docs: workflow functions do not have full Node.js access, while step functions do. Keep Node.js core modules, SDK clients, database access, and other side effects inside `use step` helpers. The workflow function itself should only compose Workflow primitives and call step helpers.
+
+For `WorkflowSpec` authoring in Workflow-hosted apps, import the safe authoring API from `@contractspec/lib.contracts-spec/workflow/spec`, not the broad `@contractspec/lib.contracts-spec/workflow` barrel.
+
 ## Next.js example
 
 ```ts
@@ -52,6 +63,8 @@ import { onboardingWorkflow } from "./onboarding.workflow";
 export async function runOnboarding(input: Record<string, unknown>, bridge: WorkflowDevkitRuntimeBridge) {
   "use workflow";
 
+  // Keep this function deterministic. Node.js work belongs in `use step`
+  // helpers that your bridge dispatches to.
   return runWorkflowSpecWithWorkflowDevkit({
     spec: onboardingWorkflow,
     initialData: input,

package/dist/browser/compiler.js

@@ -1,5 +1,5 @@
 // src/helpers.ts
-import { evaluateExpression } from "@contractspec/lib.contracts-spec/workflow";
+import { evaluateExpression } from "@contractspec/lib.contracts-spec/workflow/expression";
 function inferWorkflowDevkitBehavior(step) {
   return step.runtime?.workflowDevkit?.behavior ?? step.type;
 }
@@ -158,6 +158,9 @@ import { ${exportName} } from "${specImportPath}";
 export async function ${workflowFunctionName}(input = {}, bridge = {}) {
   "use workflow";
 
+  // Keep the workflow function deterministic.
+  // Any Node.js or side-effectful logic should live in "use step" helpers that
+  // your bridge calls, not in this orchestrator itself.
   return runWorkflowSpecWithWorkflowDevkit({
     spec: ${exportName},
     initialData: input,

package/dist/browser/helpers.js

@@ -1,5 +1,5 @@
 // src/helpers.ts
-import { evaluateExpression } from "@contractspec/lib.contracts-spec/workflow";
+import { evaluateExpression } from "@contractspec/lib.contracts-spec/workflow/expression";
 function inferWorkflowDevkitBehavior(step) {
   return step.runtime?.workflowDevkit?.behavior ?? step.type;
 }

package/dist/browser/index.js

@@ -167,7 +167,7 @@ function readStartIndex(url) {
 }
 
 // src/helpers.ts
-import { evaluateExpression } from "@contractspec/lib.contracts-spec/workflow";
+import { evaluateExpression } from "@contractspec/lib.contracts-spec/workflow/expression";
 function inferWorkflowDevkitBehavior(step) {
   return step.runtime?.workflowDevkit?.behavior ?? step.type;
 }
@@ -326,6 +326,9 @@ import { ${exportName} } from "${specImportPath}";
 export async function ${workflowFunctionName}(input = {}, bridge = {}) {
   "use workflow";
 
+  // Keep the workflow function deterministic.
+  // Any Node.js or side-effectful logic should live in "use step" helpers that
+  // your bridge calls, not in this orchestrator itself.
   return runWorkflowSpecWithWorkflowDevkit({
     spec: ${exportName},
     initialData: input,

package/dist/browser/runtime.js

@@ -1,5 +1,5 @@
 // src/helpers.ts
-import { evaluateExpression } from "@contractspec/lib.contracts-spec/workflow";
+import { evaluateExpression } from "@contractspec/lib.contracts-spec/workflow/expression";
 function inferWorkflowDevkitBehavior(step) {
   return step.runtime?.workflowDevkit?.behavior ?? step.type;
 }

package/dist/compiler.d.ts

@@ -1,4 +1,4 @@
-import type { WorkflowSpec } from '@contractspec/lib.contracts-spec/workflow';
+import type { WorkflowSpec } from '@contractspec/lib.contracts-spec/workflow/spec';
 import type { WorkflowDevkitCompilation, WorkflowDevkitGeneratedArtifacts } from './types';
 export interface CompileWorkflowSpecToWorkflowDevkitOptions {
     exportName: string;

package/dist/compiler.js

@@ -1,6 +1,6 @@
 // @bun
 // src/helpers.ts
-import { evaluateExpression } from "@contractspec/lib.contracts-spec/workflow";
+import { evaluateExpression } from "@contractspec/lib.contracts-spec/workflow/expression";
 function inferWorkflowDevkitBehavior(step) {
   return step.runtime?.workflowDevkit?.behavior ?? step.type;
 }
@@ -159,6 +159,9 @@ import { ${exportName} } from "${specImportPath}";
 export async function ${workflowFunctionName}(input = {}, bridge = {}) {
   "use workflow";
 
+  // Keep the workflow function deterministic.
+  // Any Node.js or side-effectful logic should live in "use step" helpers that
+  // your bridge calls, not in this orchestrator itself.
   return runWorkflowSpecWithWorkflowDevkit({
     spec: ${exportName},
     initialData: input,

package/dist/helpers.d.ts

@@ -1,5 +1,5 @@
-import type { Step, WorkflowSpec } from '@contractspec/lib.contracts-spec/workflow';
-export declare function inferWorkflowDevkitBehavior(step: Step): import("@contractspec/lib.contracts-spec/workflow").StepType | import("@contractspec/lib.contracts-spec/workflow").WorkflowDevkitStepBehavior;
+import type { Step, WorkflowSpec } from '@contractspec/lib.contracts-spec/workflow/spec';
+export declare function inferWorkflowDevkitBehavior(step: Step): import("@contractspec/lib.contracts-spec/workflow/spec").StepType | import("@contractspec/lib.contracts-spec/workflow/workflow-devkit").WorkflowDevkitStepBehavior;
 export declare function resolveWorkflowDevkitEntryStepId(spec: WorkflowSpec): string;
 export declare function resolveWorkflowDevkitRunIdentity(spec: WorkflowSpec, runIdentity?: string): string;
 export declare function resolveWorkflowDevkitWaitToken(spec: WorkflowSpec, step: Step, runIdentity?: string): string | undefined;

package/dist/helpers.js

@@ -1,6 +1,6 @@
 // @bun
 // src/helpers.ts
-import { evaluateExpression } from "@contractspec/lib.contracts-spec/workflow";
+import { evaluateExpression } from "@contractspec/lib.contracts-spec/workflow/expression";
 function inferWorkflowDevkitBehavior(step) {
   return step.runtime?.workflowDevkit?.behavior ?? step.type;
 }

package/dist/index.js

@@ -168,7 +168,7 @@ function readStartIndex(url) {
 }
 
 // src/helpers.ts
-import { evaluateExpression } from "@contractspec/lib.contracts-spec/workflow";
+import { evaluateExpression } from "@contractspec/lib.contracts-spec/workflow/expression";
 function inferWorkflowDevkitBehavior(step) {
   return step.runtime?.workflowDevkit?.behavior ?? step.type;
 }
@@ -327,6 +327,9 @@ import { ${exportName} } from "${specImportPath}";
 export async function ${workflowFunctionName}(input = {}, bridge = {}) {
   "use workflow";
 
+  // Keep the workflow function deterministic.
+  // Any Node.js or side-effectful logic should live in "use step" helpers that
+  // your bridge calls, not in this orchestrator itself.
   return runWorkflowSpecWithWorkflowDevkit({
     spec: ${exportName},
     initialData: input,

package/dist/node/compiler.js

@@ -1,5 +1,5 @@
 // src/helpers.ts
-import { evaluateExpression } from "@contractspec/lib.contracts-spec/workflow";
+import { evaluateExpression } from "@contractspec/lib.contracts-spec/workflow/expression";
 function inferWorkflowDevkitBehavior(step) {
   return step.runtime?.workflowDevkit?.behavior ?? step.type;
 }
@@ -158,6 +158,9 @@ import { ${exportName} } from "${specImportPath}";
 export async function ${workflowFunctionName}(input = {}, bridge = {}) {
   "use workflow";
 
+  // Keep the workflow function deterministic.
+  // Any Node.js or side-effectful logic should live in "use step" helpers that
+  // your bridge calls, not in this orchestrator itself.
   return runWorkflowSpecWithWorkflowDevkit({
     spec: ${exportName},
     initialData: input,

package/dist/node/helpers.js

@@ -1,5 +1,5 @@
 // src/helpers.ts
-import { evaluateExpression } from "@contractspec/lib.contracts-spec/workflow";
+import { evaluateExpression } from "@contractspec/lib.contracts-spec/workflow/expression";
 function inferWorkflowDevkitBehavior(step) {
   return step.runtime?.workflowDevkit?.behavior ?? step.type;
 }

package/dist/node/index.js

@@ -167,7 +167,7 @@ function readStartIndex(url) {
 }
 
 // src/helpers.ts
-import { evaluateExpression } from "@contractspec/lib.contracts-spec/workflow";
+import { evaluateExpression } from "@contractspec/lib.contracts-spec/workflow/expression";
 function inferWorkflowDevkitBehavior(step) {
   return step.runtime?.workflowDevkit?.behavior ?? step.type;
 }
@@ -326,6 +326,9 @@ import { ${exportName} } from "${specImportPath}";
 export async function ${workflowFunctionName}(input = {}, bridge = {}) {
   "use workflow";
 
+  // Keep the workflow function deterministic.
+  // Any Node.js or side-effectful logic should live in "use step" helpers that
+  // your bridge calls, not in this orchestrator itself.
   return runWorkflowSpecWithWorkflowDevkit({
     spec: ${exportName},
     initialData: input,

package/dist/node/runtime.js

@@ -1,5 +1,5 @@
 // src/helpers.ts
-import { evaluateExpression } from "@contractspec/lib.contracts-spec/workflow";
+import { evaluateExpression } from "@contractspec/lib.contracts-spec/workflow/expression";
 function inferWorkflowDevkitBehavior(step) {
   return step.runtime?.workflowDevkit?.behavior ?? step.type;
 }

package/dist/runtime.d.ts

@@ -1,4 +1,4 @@
-import type { WorkflowSpec } from '@contractspec/lib.contracts-spec/workflow';
+import type { WorkflowSpec } from '@contractspec/lib.contracts-spec/workflow/spec';
 import type { WorkflowDevkitPrimitives, WorkflowDevkitRunResult, WorkflowDevkitRuntimeBridge } from './types';
 export interface RunWorkflowSpecWithWorkflowDevkitOptions {
     bridge?: WorkflowDevkitRuntimeBridge;

package/dist/runtime.js

@@ -1,6 +1,6 @@
 // @bun
 // src/helpers.ts
-import { evaluateExpression } from "@contractspec/lib.contracts-spec/workflow";
+import { evaluateExpression } from "@contractspec/lib.contracts-spec/workflow/expression";
 function inferWorkflowDevkitBehavior(step) {
   return step.runtime?.workflowDevkit?.behavior ?? step.type;
 }

package/dist/types.d.ts

@@ -1,4 +1,5 @@
-import type { Step, WorkflowDevkitHostTarget, WorkflowDevkitIntegrationMode, WorkflowDevkitStepBehavior, WorkflowDevkitStepRuntimeConfig, WorkflowSpec } from '@contractspec/lib.contracts-spec/workflow';
+import type { Step, WorkflowSpec } from '@contractspec/lib.contracts-spec/workflow/spec';
+import type { WorkflowDevkitHostTarget, WorkflowDevkitIntegrationMode, WorkflowDevkitStepBehavior, WorkflowDevkitStepRuntimeConfig } from '@contractspec/lib.contracts-spec/workflow/workflow-devkit';
 import type { UIMessageChunk } from 'ai';
 export interface WorkflowDevkitCompiledTransition {
     condition?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractspec/integration.workflow-devkit",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Workflow DevKit compiler and runtime bridges for ContractSpec workflows",
   "keywords": [
     "contractspec",
@@ -77,7 +77,7 @@
   "scripts": {
     "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
     "publish:pkg:canary": "bun publish:pkg --tag canary",
-    "build": "bun run prebuild && bun run build:bundle && bun run build:types",
+    "build": "bun run build:bundle && bun run build:types",
     "build:bundle": "contractspec-bun-build transpile",
     "build:types": "contractspec-bun-build types",
     "dev": "contractspec-bun-build dev",
@@ -90,15 +90,15 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@contractspec/lib.ai-agent": "8.0.3",
-    "@contractspec/lib.contracts-spec": "5.0.3",
+    "@contractspec/lib.ai-agent": "8.0.5",
+    "@contractspec/lib.contracts-spec": "5.1.0",
     "@workflow/ai": "^4.1.0-beta.58",
     "ai": "6.0.138",
     "workflow": "^4.2.0-beta.72"
   },
   "devDependencies": {
-    "@contractspec/tool.bun": "3.7.11",
-    "@contractspec/tool.typescript": "3.7.11",
+    "@contractspec/tool.bun": "3.7.13",
+    "@contractspec/tool.typescript": "3.7.13",
     "typescript": "^5.9.3"
   },
   "publishConfig": {