feat(conductor): Spec 005 — Omadia Conductor (deterministic engine, designer, human-in-the-loop) — US1–US8 implemented + live-tested

[iret77]

Summary

Conception for Omadia Conductor — a deterministic workflow/process layer where the
runtime, not the LLM, owns step progression and hand-offs. It promotes the existing
per-tool atoms (postconditions + verifier, OB-31 tool-obligation / repeat-failure
guards, the deterministic_action fast-path) to process scope, so a multi-step,
multi-agent process cannot silently stall the way prompt-only frameworks do.

A workflow is a graph of steps (agentic, deterministic action, or human)
connected by guarded transitions. After each step the Conductor evaluates an exit
postcondition and, when unmet, acts deterministically (re-inject / force a tool
obligation / fire a declared fallback transition) instead of hoping the LLM
self-corrects. A hand-off is a transition the runtime fires, not a prompt line an Agent
can drop.

What's in this PR

Docs only — two spec artifacts under specs/005-omadia-conductor/. No code changes.
Status: Draft.

• spec.md — 9 user stories (P1: engine, durable run lifecycle/resume, triggers, event
  triggers + connector "Conductor Surface", human steps with durable awaits/reminders/
  deadline, principals & role resolver seam; P2: visual+conversational Designer, dry-run;
  P3: audit), 32 functional requirements, 10 success criteria, edge cases, assumptions.
• data-model.md — schema for workflow / version / draft, run / run-step, the net-new
  durable conductor_awaits (+ per-holder responses), roles / role-assignments (the
  "baton"), the manifest emits: extension, LISTEN/NOTIFY resume hook, and the
  run/await state machines.

Key decisions captured (clarified with the owner)

• In-repo, modular — @omadia/conductor-core (pure engine) + kernel wiring via the
  existing serviceRegistry + a Designer under web-ui/app/admin/conductor/. No
  separate repo; only an HR/ERP role resolver belongs in a swappable plugin.
• Deadline fallback = in-graph transition only (no sub-workflow as a deadline
  handler).
• Human-step quorum: any | all (default any) for multi-holder roles.
• Event trigger is first-class, day one — the contract (emits: block, event
  catalog, ctx.events.emit, subscription/filter) ships; connectors themselves are out
  of scope.
• Roles are late-bound — resolved at dispatch and re-resolved on every reminder via a
  pluggable RoleResolver; await access follows the current holder at access time (the
  baton can move mid-wait).

Scope boundary

Conductor defines and depends only on the contract a connector implements
(emits: / provides: / event catalog). Building connectors (GitHub/CI, ATS/HR,
calendar, ERP) and the role-movement policy are owned by separate plugin work and the
live instance.

🤖 Generated with Claude Code

[Weegy]

Status update — Spec 005 implemented end-to-end (Draft)

This PR started as the Spec 005 design docs and now also carries the full vertical implementation of the Omadia Conductor, grounded against the live codebase. Marking it Draft — it is feature-complete for the P1 scope and live-tested locally, but kept in draft until we pick it back up for review/merge (we're moving to other topics for now).

What's in the branch (005-omadia-conductor @ 62edeaf)

Design

• specs/005-omadia-conductor/spec.md + data-model.md — 9 user stories, 32 FRs, 10 SCs.
• specs/005-omadia-conductor/plan.md — grounded integration plan: phase-by-phase build sequence, reuse map, net-new substrate, 16 resolved integration landmines (A–P), test strategy mapped to SC-001..010, and the 4 owner design decisions (conductor_channel_bindings, conductor_schedules, FOR UPDATE SKIP LOCKED claim, serializable predicate AST).

Implementation — all P1 user stories (US1–US8), no stubs

Story	What landed
US1 Deterministic engine	@omadia/conductor-core — I/O-free predicate-AST engine (serializable guards/postconditions, no eval), validate(graph) shape+graph checks, deterministic nextStep(). 46 vitest green.
US2 Durable runs	migrations/0001_conductor.sql (full conductor_* schema + claim cols + pg_notify), per-subsystem migrator, ConductorWorkflowStore (versioned publish), ConductorRunStore (durable per-step record), ConductorRunExecutor with a StepEffects seam; async background drive + UI polling (real agent turns are slow).
US3 Manual triggers	Operator API /api/v1/operator/conductors (publish/list/status/run/trace) behind requireAuth.
US4 Event triggers	ConductorEventRouter.emit(eventId, payload) → matches active versions' event trigger (+ payload-filter predicate) → starts a run per match with payload as context. Operator POST /emit + UI form. (Connector half — plugin ctx.events.emit + manifest emits: autodiscovery — is the documented remaining piece.)
US5 Human-in-the-loop	Durable conductor_awaits; human step parks run waiting; resolveAwait records response + atomically closes + resumes; expireAwait fires in-graph fallback on deadline; minute-tick ConductorAwaitWorker; operator inbox (Approve/Reject).
US6 Roles & baton	ConductorRoleStore (create / add-remove holder = the baton / live resolve()); awaits inbox resolves role:<key> to current holders live; "Roles & the baton" UI.
US7 Visual designer	ConductorCanvas (@xyflow/react): add agent/action/human nodes, drag-wire transitions, per-kind inspector, trigger config, load existing workflow, Save→validate→publish, Run+poll. + NEW: per-row "Edit" button in the list loads a workflow into the canvas (commit 62edeaf).
US8 Dry-run / preview	executor.previewRun(...) simulates the path in-memory with zero side effects (no runs/awaits rows, no notifications; irreversible connector actions stubbed); "Dry-run" button renders the simulated step path.

Real execution = real orchestrator turns: an agent step targets an Agent (orchestrator instance) resolved by slug from the multi-orchestrator registry (RealStepEffects), answer.text is the step result; action steps invoke the real connector tool. No stubbed execution.

Verification

• conductor-core: 46/46 vitest green; middleware tsc --noEmit clean; web-ui tsc + i18n parity (1279 keys, en/de) clean.
• Deployed + live-tested in the local omadia-test docker stack (~/sources/omadia, same commit): migrations apply, 11 conductor_* tables, route auth-gated. End-to-end smokes via Interceptor (authenticated Chrome, :3333 → Conductor): publish + run (real gpt-5.5 output persisted), event emit → auto-run, human await → Approve → resume → complete, role baton re-resolution, dry-run (no DB writes), and the new Edit flow (loads visual-demo into the canvas).

Known limitations / remaining work (future phases, not in scope here)

• US4 connector half — plugin ctx.events.emit + manifest emits: autodiscovery + EventCatalogRegistry on both activation paths (landmines B/K).
• US9 audit viewer — Conductor-shaped branch of RunTraceViewer over conductor_run_steps.
• US7 conversational builder (chat co-design) — only the visual canvas exists.
• Reminders (proactive channel notify) — needs the conductor_channel_bindings sender wired.
• Run-resume worker for async/running runs after a restart (waiting-on-human already survives via durable awaits).
• Cron triggers actually firing (conductor_schedules + ScheduleWorker tick); quorum all.

Notes

• All implementation commits authored as Marcel Wege <mwege@byte5.de>.
• Leftover demo workflows in the omadia-test DB are harmless local test data.

[iret77]

Follow-up: roles should be consumed from the new Identity & Role Projection layer (#333) rather than owned by a local conductor_role_assignments table — that table is demoted to the stand-alone fallback. Principal = user|role becomes a platform-wide default (see #333).

[iret77]

@Weegy heads-up on the role model while you're building this out 👇

Spec 005 was just updated (commit 420694c) to align with #333 (Identity & Role Projection). Key point for your conductor_role_assignments / roleStore.ts:

• Principal = user | role should be the default addressee everywhere — human steps, escalation/fallback targets, and report/notification recipients alike. User-only is the justified exception (technically/legally necessary, documented). (Identity & Role Projection — omadia as a team-player in the existing IT landscape (Principal = user|role everywhere) #333)
• The local conductor_role_assignments store is the default / stand-alone fallback, not the long-term system of record. The primary path projects role holders from the org's external systems of record (Entra groups/app-roles, HR/ERP) and matches them to users on a primary key (email / provider sub), via a resolver registered in front of the local one — exactly the "external resolver in front; follow-up" your roleStore.ts comment already anticipates. 👍

Nothing urgent to change — your seam is already shaped right, and migration 0003 moving the holder to a session-identity TEXT already leans this way. Just flagging so the local table doesn't get cemented as the SoT. Full rationale in #333 — happy to sync whenever.