Feat v0.9.7 workflow starlark write ops

Add workflow.start(), workflow.advance(), workflow.cancel(), and
workflow.submit_signoff() to the Starlark workflow module. Extract
WorkflowEngine interface in sandbox package to break the circular
import between workflow and sandbox packages.

- WorkflowEngine interface (Start/Advance/Cancel/SubmitSignoff)
- instanceToDict/signoffToDict/dictToJSON shared helpers
- Runner.SetWorkflowEngine setter + main.go wiring
- 6 new unit tests with mock engine

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

server/sandbox/workflow_module.go

@@ -6,12 +6,13 @@ package sandbox
 // manage instances, and programmatically advance workflow stages.
 //
 // Starlark API:
-//   wf = workflow.get_definition(workflow_id)         # returns dict
-//   inst = workflow.get_instance(instance_id)         # returns dict
-//   inst = workflow.start(workflow_id, data={})        # start new instance
-//   inst = workflow.advance(instance_id, data={})      # advance to next stage
-//   workflow.cancel(instance_id)                       # cancel instance
-//   instances = workflow.list_instances(workflow_id)    # list instances
+//   wf = workflow.get_definition(workflow_id)                            # returns dict
+//   inst = workflow.get_instance(instance_id)                           # returns dict
+//   instances = workflow.list_instances(workflow_id)                     # list instances
+//   inst = workflow.start(workflow_id, data={})                          # start new instance
+//   inst = workflow.advance(instance_id, data={})                        # advance to next stage
+//   workflow.cancel(instance_id)                                         # cancel instance
+//   signoff = workflow.submit_signoff(instance_id, decision, comment="") # submit signoff
 
 import (
 	"context"
@@ -21,21 +22,37 @@ import (
 	"go.starlark.net/starlark"
 	"go.starlark.net/starlarkstruct"
 
+	"armature/models"
 	"armature/store"
 )
 
+// WorkflowEngine is the subset of the workflow engine needed by Starlark
+// write operations. Defined here (not in the workflow package) to avoid
+// circular imports — workflow imports sandbox for the Runner.
+type WorkflowEngine interface {
+	Start(ctx context.Context, workflowID string, initialData json.RawMessage, userID string) (*models.WorkflowInstance, error)
+	Advance(ctx context.Context, instanceID string, stageData json.RawMessage, userID string) (*models.WorkflowInstance, error)
+	Cancel(ctx context.Context, instanceID string, userID string) error
+	SubmitSignoff(ctx context.Context, instanceID, userID, decision, comment string) (*models.WorkflowSignoff, error)
+}
+
 // BuildWorkflowModule creates the "workflow" Starlark module for a package.
 // Requires the workflow.access permission.
 //
-// Mutating operations (start/advance/cancel) are available via HTTP API;
-// Starlark builtins for them will be added when the engine interface is
-// extracted to a shared package to avoid circular imports.
-func BuildWorkflowModule(ctx context.Context, stores store.Stores) *starlarkstruct.Module {
-	return MakeModule("workflow", starlark.StringDict{
+// Read operations use stores directly. Write operations delegate to the
+// WorkflowEngine interface (engine may be nil if not wired — write builtins
+// return an error in that case).
+func BuildWorkflowModule(ctx context.Context, stores store.Stores, engine WorkflowEngine, rc *RunContext) *starlarkstruct.Module {
+	members := starlark.StringDict{
 		"get_definition": starlark.NewBuiltin("workflow.get_definition", workflowGetDef(ctx, stores)),
 		"get_instance":   starlark.NewBuiltin("workflow.get_instance", workflowGetInstance(ctx, stores)),
 		"list_instances": starlark.NewBuiltin("workflow.list_instances", workflowListInstances(ctx, stores)),
-	})
+		"start":          starlark.NewBuiltin("workflow.start", workflowStart(ctx, engine, rc)),
+		"advance":        starlark.NewBuiltin("workflow.advance", workflowAdvance(ctx, engine, rc)),
+		"cancel":         starlark.NewBuiltin("workflow.cancel", workflowCancel(ctx, engine, rc)),
+		"submit_signoff": starlark.NewBuiltin("workflow.submit_signoff", workflowSubmitSignoff(ctx, engine, rc)),
+	}
+	return MakeModule("workflow", members)
 }
 
 func workflowGetDef(ctx context.Context, stores store.Stores) func(*starlark.Thread, *starlark.Builtin, starlark.Tuple, []starlark.Tuple) (starlark.Value, error) {
@@ -98,35 +115,51 @@ func workflowGetInstance(ctx context.Context, stores store.Stores) func(*starlar
 		if err != nil {
 			return starlark.None, fmt.Errorf("workflow.get_instance: %w", err)
 		}
-
-		d := starlark.NewDict(8)
-		d.SetKey(starlark.String("id"), starlark.String(inst.ID))
-		d.SetKey(starlark.String("workflow_id"), starlark.String(inst.WorkflowID))
-		d.SetKey(starlark.String("workflow_version"), starlark.MakeInt(inst.WorkflowVersion))
-		d.SetKey(starlark.String("current_stage"), starlark.String(inst.CurrentStage))
-		d.SetKey(starlark.String("status"), starlark.String(inst.Status))
-		d.SetKey(starlark.String("started_by"), starlark.String(inst.StartedBy))
-
-		// Parse stage_data into Starlark dict
-		var dataMap map[string]interface{}
-		if json.Unmarshal(inst.StageData, &dataMap) == nil {
-			starlarkData := starlark.NewDict(len(dataMap))
-			for k, v := range dataMap {
-				starlarkData.SetKey(starlark.String(k), GoToStarlark(v))
-			}
-			d.SetKey(starlark.String("stage_data"), starlarkData)
-		} else {
-			d.SetKey(starlark.String("stage_data"), starlark.NewDict(0))
-		}
-
-		if inst.EntryToken != nil {
-			d.SetKey(starlark.String("entry_token"), starlark.String(*inst.EntryToken))
-		}
-
-		return d, nil
+		return instanceToDict(inst), nil
 	}
 }
 
+// instanceToDict converts a WorkflowInstance to a Starlark dict.
+func instanceToDict(inst *models.WorkflowInstance) *starlark.Dict {
+	d := starlark.NewDict(8)
+	d.SetKey(starlark.String("id"), starlark.String(inst.ID))
+	d.SetKey(starlark.String("workflow_id"), starlark.String(inst.WorkflowID))
+	d.SetKey(starlark.String("workflow_version"), starlark.MakeInt(inst.WorkflowVersion))
+	d.SetKey(starlark.String("current_stage"), starlark.String(inst.CurrentStage))
+	d.SetKey(starlark.String("status"), starlark.String(inst.Status))
+	d.SetKey(starlark.String("started_by"), starlark.String(inst.StartedBy))
+
+	// Parse stage_data into Starlark dict
+	var dataMap map[string]interface{}
+	if json.Unmarshal(inst.StageData, &dataMap) == nil {
+		starlarkData := starlark.NewDict(len(dataMap))
+		for k, v := range dataMap {
+			starlarkData.SetKey(starlark.String(k), GoToStarlark(v))
+		}
+		d.SetKey(starlark.String("stage_data"), starlarkData)
+	} else {
+		d.SetKey(starlark.String("stage_data"), starlark.NewDict(0))
+	}
+
+	if inst.EntryToken != nil {
+		d.SetKey(starlark.String("entry_token"), starlark.String(*inst.EntryToken))
+	}
+	return d
+}
+
+// signoffToDict converts a WorkflowSignoff to a Starlark dict.
+func signoffToDict(s *models.WorkflowSignoff) *starlark.Dict {
+	d := starlark.NewDict(7)
+	d.SetKey(starlark.String("id"), starlark.String(s.ID))
+	d.SetKey(starlark.String("instance_id"), starlark.String(s.InstanceID))
+	d.SetKey(starlark.String("stage"), starlark.String(s.Stage))
+	d.SetKey(starlark.String("user_id"), starlark.String(s.UserID))
+	d.SetKey(starlark.String("decision"), starlark.String(s.Decision))
+	d.SetKey(starlark.String("comment"), starlark.String(s.Comment))
+	d.SetKey(starlark.String("created_at"), starlark.String(s.CreatedAt.Format("2006-01-02T15:04:05Z07:00")))
+	return d
+}
+
 func workflowListInstances(ctx context.Context, stores store.Stores) func(*starlark.Thread, *starlark.Builtin, starlark.Tuple, []starlark.Tuple) (starlark.Value, error) {
 	return func(_ *starlark.Thread, _ *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
 		var workflowID string
@@ -155,5 +188,113 @@ func workflowListInstances(ctx context.Context, stores store.Stores) func(*starl
 	}
 }
 
-// workflowRoute routes the workflow to a named stage.
-// Starlark: workflow.route(instance_id, target_stage, reason)
+// ── Instance Write API ──────────────
+
+// workflowWriteGuard checks that the engine and user context are available.
+func workflowWriteGuard(engine WorkflowEngine, rc *RunContext) error {
+	if engine == nil {
+		return fmt.Errorf("workflow engine not available")
+	}
+	if rc == nil || rc.UserID == "" {
+		return fmt.Errorf("workflow write operations require an authenticated user context")
+	}
+	return nil
+}
+
+// dictToJSON converts a Starlark dict to json.RawMessage.
+func dictToJSON(d *starlark.Dict) (json.RawMessage, error) {
+	m := DictToMap(d)
+	b, err := json.Marshal(m)
+	if err != nil {
+		return nil, err
+	}
+	return json.RawMessage(b), nil
+}
+
+func workflowStart(ctx context.Context, engine WorkflowEngine, rc *RunContext) func(*starlark.Thread, *starlark.Builtin, starlark.Tuple, []starlark.Tuple) (starlark.Value, error) {
+	return func(_ *starlark.Thread, _ *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
+		var workflowID string
+		data := starlark.NewDict(0)
+		if err := starlark.UnpackArgs("workflow.start", args, kwargs,
+			"workflow_id", &workflowID,
+			"data?", &data,
+		); err != nil {
+			return nil, err
+		}
+		if err := workflowWriteGuard(engine, rc); err != nil {
+			return nil, fmt.Errorf("workflow.start: %w", err)
+		}
+		dataJSON, err := dictToJSON(data)
+		if err != nil {
+			return nil, fmt.Errorf("workflow.start: marshal data: %w", err)
+		}
+		inst, err := engine.Start(ctx, workflowID, dataJSON, rc.UserID)
+		if err != nil {
+			return nil, fmt.Errorf("workflow.start: %w", err)
+		}
+		return instanceToDict(inst), nil
+	}
+}
+
+func workflowAdvance(ctx context.Context, engine WorkflowEngine, rc *RunContext) func(*starlark.Thread, *starlark.Builtin, starlark.Tuple, []starlark.Tuple) (starlark.Value, error) {
+	return func(_ *starlark.Thread, _ *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
+		var instanceID string
+		data := starlark.NewDict(0)
+		if err := starlark.UnpackArgs("workflow.advance", args, kwargs,
+			"instance_id", &instanceID,
+			"data?", &data,
+		); err != nil {
+			return nil, err
+		}
+		if err := workflowWriteGuard(engine, rc); err != nil {
+			return nil, fmt.Errorf("workflow.advance: %w", err)
+		}
+		dataJSON, err := dictToJSON(data)
+		if err != nil {
+			return nil, fmt.Errorf("workflow.advance: marshal data: %w", err)
+		}
+		inst, err := engine.Advance(ctx, instanceID, dataJSON, rc.UserID)
+		if err != nil {
+			return nil, fmt.Errorf("workflow.advance: %w", err)
+		}
+		return instanceToDict(inst), nil
+	}
+}
+
+func workflowCancel(ctx context.Context, engine WorkflowEngine, rc *RunContext) func(*starlark.Thread, *starlark.Builtin, starlark.Tuple, []starlark.Tuple) (starlark.Value, error) {
+	return func(_ *starlark.Thread, _ *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
+		var instanceID string
+		if err := starlark.UnpackPositionalArgs("workflow.cancel", args, kwargs, 1, &instanceID); err != nil {
+			return nil, err
+		}
+		if err := workflowWriteGuard(engine, rc); err != nil {
+			return nil, fmt.Errorf("workflow.cancel: %w", err)
+		}
+		if err := engine.Cancel(ctx, instanceID, rc.UserID); err != nil {
+			return nil, fmt.Errorf("workflow.cancel: %w", err)
+		}
+		return starlark.None, nil
+	}
+}
+
+func workflowSubmitSignoff(ctx context.Context, engine WorkflowEngine, rc *RunContext) func(*starlark.Thread, *starlark.Builtin, starlark.Tuple, []starlark.Tuple) (starlark.Value, error) {
+	return func(_ *starlark.Thread, _ *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
+		var instanceID, decision string
+		comment := ""
+		if err := starlark.UnpackArgs("workflow.submit_signoff", args, kwargs,
+			"instance_id", &instanceID,
+			"decision", &decision,
+			"comment?", &comment,
+		); err != nil {
+			return nil, err
+		}
+		if err := workflowWriteGuard(engine, rc); err != nil {
+			return nil, fmt.Errorf("workflow.submit_signoff: %w", err)
+		}
+		signoff, err := engine.SubmitSignoff(ctx, instanceID, rc.UserID, decision, comment)
+		if err != nil {
+			return nil, fmt.Errorf("workflow.submit_signoff: %w", err)
+		}
+		return signoffToDict(signoff), nil
+	}
+}