workflows/v1: adopt WorkflowService in objectives

[haasonsaas]

Summary

The workflows/v1 proto package landed in #1ef7dbe. The objectives service already owns objective lifecycle, wake scheduling, provenance, and mutation tracking. Workflows are compositions of objectives — the orchestration logic belongs next to the thing it's coordinating.

What needs to happen

Phase 1: Workflow definitions and versioning

• Implement CreateDefinition, GetDefinition, ListDefinitions, PublishVersion, ListVersions RPCs in objectives
• Add workflow_definitions table: id, workspace_id, name, description, latest_version, tags (text[]), created_at, updated_at
• Add workflow_versions table: id, definition_id, version (serial per definition), steps (jsonb), edges (jsonb), trigger (jsonb), default_retry_policy (jsonb), timeout_seconds, author, created_at
• Validate DAG acyclicity on PublishVersion
• Publish workflows.changes.definition.create / version.publish CloudEvents

Phase 2: Workflow execution engine

• Implement StartRun, GetRun, ListRuns, TransitionStep RPCs
• Add workflow_runs table matching WorkflowRun message
• Add step_runs table matching StepRun message
• DAG executor: on run start, identify root steps (no incoming edges), create objectives for AGENT_ACTION steps, and transition to RUNNING
• Step completion listener: subscribe to NATS for objective state changes, approval resolutions, governance decisions, CloudEvent arrivals
• On step completion: evaluate outgoing edges, start next steps, accumulate cost_usd

Phase 3: Step type implementations

Step Type	Implementation
AGENT_ACTION	Create objective via ObjectiveService.Create, optionally delegate via AgentService.Delegate
APPROVAL_GATE	Create approval via ApprovalService.RequestApproval, block until resolved
GOVERNANCE_CHECK	Call GovernanceService.EvaluateAction, fail on DENY, insert implicit approval on REQUIRE_APPROVAL
WAIT_FOR_EVENT	Subscribe to NATS with event_type_pattern + event_subject_pattern filter, block until match or timeout
BRANCH	Evaluate condition_expr against prior step outputs, follow matching edge
PARALLEL	Fan out to all child steps concurrently, complete when all children complete
NOTIFICATION	Send via NotificationService.Send, non-blocking
HUMAN_TASK	Create pending step, expose via API/product surface for manual completion

Phase 4: Lifecycle controls and compensation

• Implement PauseRun, ResumeRun, CancelRun, CompensateRun RPCs
• Pause: stop starting new steps, let in-progress steps complete
• Cancel: cancel all in-progress objectives, no compensation
• Compensate: walk DAG in reverse topological order, execute compensation_step_id for each completed step
• Publish workflows.changes.run.pause / .resume / .cancel / .compensate CloudEvents

Phase 5: Triggers

• Event trigger: NATS subscription matching WorkflowTrigger.event_type + event_subject, apply filter_expr, start run
• Webhook trigger: listen for tap events matching tap_provider + tap_entity_type + tap_action
• Schedule trigger: cron-based run creation
• Workflow trigger: sub-workflow invocation from parent step

Cross-service integration points

Service	Integration
agents (registry)	Resolve agent_id or required_capability for agent steps, create delegations
objectives	Create objective per agent step, listen for state transitions
approvals	Create approval requests for gate steps, listen for decisions
governance	Evaluate actions for governance check steps
notifications	Send notifications for notification steps
events (NATS)	Trigger on CloudEvents, wait for events in steps, publish workflow lifecycle events
tap (ensemble-tap)	Trigger on webhook events from external providers
entities	Resolve entity_id / entity_type for the workflow's primary entity
meter	Attribute step costs, accumulate total_cost_usd on run
prompts	Resolve prompt_name for agent action steps at execution time
skills	Validate skill_id availability for agent action steps
identity	Validate initiator_user_id for manual triggers

Contract fixtures

Canonical fixtures are already in proto/workflows/v1/testdata/:

• publish_version_response.json — full outbound SDR pipeline: research → qualify → governance check → branch by deal value → approval gate → send outreach → notify → wait for reply
• get_run_response.json — in-progress workflow with completed research/qualify/governance/branch steps, waiting on manager approval for an $85K deal, with cost tracking and entity linkage

Related

• Bootstrap evalops/proto with buf toolchain and CI #1 — bootstrap tracking
• Proto commit: 1ef7dbe

[haasonsaas]

Progress update:

• evalops/objectives#5 landed the definition/version half of workflows.v1.WorkflowService with persisted workflow_definitions / workflow_versions, DAG validation, and canonical Connect handlers.
• evalops/objectives#6 landed persisted workflow_runs / step_runs plus StartRun, GetRun, ListRuns, and TransitionStep scaffolding.

What remains here is the actual execution engine and cross-service orchestration work: root-step scheduling, downstream edge evaluation, approval/governance/event integrations, lifecycle controls, compensation, and trigger subscriptions.

[haasonsaas]

Progress update after objectives#7:

Landed now:

• objectives#5: CreateDefinition, GetDefinition, ListDefinitions, PublishVersion, ListVersions, plus persisted workflow_definitions / workflow_versions
• objectives#6: persisted workflow_runs / step_runs, plus StartRun, GetRun, ListRuns, TransitionStep scaffolding
• objectives#7: root-step activation on run start, downstream edge reconciliation, branch-path selection/skip behavior, step input propagation, and PauseRun / ResumeRun / CancelRun

Remaining scope on this tracker is now the real cross-service executor work rather than basic proto adoption:

• AGENT_ACTION creating objectives/delegations
• approval/governance/event-wait/notification/human-task integrations
• event and schedule triggers
• workflow lifecycle CloudEvents
• compensation semantics
• NATS-driven completion listeners

So the service surface is materially adopted now; the gap is execution integrations.

[haasonsaas]

Progress update after objectives#8:

The workflows/v1 service adoption in objectives now includes:

• definition/version RPCs and storage (objectives#5)
• run/step-run RPCs and storage (objectives#6)
• DAG progression plus pause/resume/cancel controls (objectives#7)
• real AGENT_ACTION objective creation and linked objective-state syncing (objectives#8)

So proto adoption is well past scaffolding now. Remaining work on this tracker is the rest of the execution integrations around approvals, governance, events, notifications, triggers, lifecycle events, delegation, and compensation.

[haasonsaas]

objectives#9 is now merged on top of the earlier workflow executor scaffolding. In addition to definitions/versions, persisted runs/steps, DAG progression, pause/resume/cancel, and AGENT_ACTION objective creation, the executor now auto-runs STEP_TYPE_NOTIFICATION via notifications/v1 and persists notification_id plus notification output metadata.

The remaining scope on this umbrella is still the cross-service executor/proto work for approvals/governance/events/notifications triggers, delegation routing, lifecycle events, and compensation.

[haasonsaas]

Approval-gate execution is now consuming the existing shared approvals contract.

Merged on April 13, 2026:

• objectives#10: APPROVAL_GATE steps now call approvals/v1.RequestApproval, persist approval_request_id, and validate configured risk_level values before publish.
• deploy#32: production wiring for the approvals service URL and network access is in place.

This narrows the remaining proto-facing workflow scope to the still-unimplemented executor seams rather than the approval gate boundary itself: governance / event waits, triggers / listeners, lifecycle events, and compensation.

[haasonsaas]

Progress update on April 13, 2026:

workflows.v1 contract gaps closed since this issue was filed now include:

• typed executor support already landed for approval, governance, notification, branch, and agent-action semantics in downstream services
• #41 just landed explicit StartRunRequest.trigger_type and StartRunRequest.trigger_event_id, so workflow runs can preserve non-manual provenance at creation time instead of relying on repo-local inference

The remaining proto surface is narrower now and should focus on the async/workflow-runtime edges that still lack shared contracts or ingress paths:

• event-trigger / webhook / schedule run-start ingress
• WAIT_FOR_EVENT satisfaction path / listener contract
• lifecycle event emission for workflow runs and step runs
• compensation-specific orchestration surface if we want something richer than generic TransitionStep + CompensateRun

So the next protobuf work should be around trigger/listener/event-runtime contracts, not basic run metadata.

[haasonsaas]

Progress update: proto#42 is merged.

What landed:

• additive workflows.v1.WorkflowService.HandleTrigger RPC
• new HandleTriggerRequest / HandleTriggerResponse messages for event, webhook, and schedule ingress
• generated Go / TS / Python surfaces and canonical handle_trigger_{request,response}.json fixtures

Remaining scope here is follow-on workflow runtime contract work, not the ingress shape itself.

[haasonsaas]

Workflow lifecycle proto scaffolding landed in proto#43.

Shipped in this slice:

• workflows.v1 WorkflowRunLifecycleEvent and WorkflowStepLifecycleEvent payload messages
• canonical workflow lifecycle and CloudEvent fixtures under workflows/v1 and events/v1
• fixture catalog coverage plus contract tests for the new payloads

The remaining proto work here is no longer basic lifecycle scaffolding. It is any additional cross-service event surface that future executor integrations still require.

[haasonsaas]

Lifecycle payload enrichment landed in proto#44 and is now merged.

What shipped:

• WorkflowRunLifecycleEvent now carries explicit operation and recorded_at
• WorkflowStepLifecycleEvent now carries explicit operation and recorded_at
• canonical workflows/v1 lifecycle fixtures and matching CloudEvent fixtures were updated in place
• generated Go / TS / Python workflow surfaces were regenerated on the merged schema

Validation:

• buf generate
• buf lint
• buf breaking --against ".git#branch=main"
• go test ./...
• npm run check:package
• git diff --check

This narrows the remaining proto scope on this tracker to any future executor/runtime event surface that consumers actually prove they need, rather than basic lifecycle metadata.