# ISIS v2 WS10-002: Workflow Execution Endpoints with RBAC

## Scope

Implemented explicit workflow execution API endpoints in `@isis/generation-api`
for:

- `POST /api/v1/workflows/{workflowId}/run`
- `GET /api/v1/workflows/{workflowId}/executions`
- `GET /api/v1/workflows/{workflowId}/executions/{executionId}`

with route-level RBAC for both bearer and API-key authentication.

## Implemented Artifacts

- Generation API workflow execution routes:
  - `apps/isis/generation-api/src/routes/workflows.ts`
  - `apps/isis/generation-api/src/routes/workflows.spec.ts`
  - `apps/isis/generation-api/src/app.ts`
  - `apps/isis/generation-api/src/index.ts`
  - `apps/isis/generation-api/src/routes/index.ts`
- Auth + job filtering support:
  - `apps/isis/generation-api/src/middleware/auth.ts`
  - `apps/isis/generation-api/src/types.ts`
  - `apps/isis/generation-api/src/services/job.service.ts`
- OpenAPI generation/contract parity:
  - `scripts/isis/generate_generation_api_openapi.mjs`
  - `apps/isis/generation-api/src/openapi.contract.spec.ts`
  - `apps/isis/generation-api/openapi.yaml`
  - `openapi/isis/openapi.yaml`

## RBAC Model

- Run endpoint (`/run`):
  - Bearer: allowed via authorized roles (`admin`, `ops`, `sre`, `developer`) or
    permissions (`jobs:submit`, `jobs:manage`, `workflows:run`,
    `workflows:write`, `*`)
  - API key: requires equivalent run permissions (`jobs:submit`, `jobs:manage`,
    `workflows:run`, `workflows:write`, `*`)
- Execution history endpoints (`/executions*`):
  - Bearer: allowed via authorized roles (`admin`, `ops`, `sre`, `developer`,
    `viewer`) or read permissions (`workflows:read`, `jobs:read`, etc.)
  - API key: requires read permissions (`workflows:read`, `jobs:read`,
    `jobs:manage`, `workflows:run`, `workflows:write`, `*`)

## Behavior

- `POST /run` now creates a generation job with canonical workflow metadata:
  - `workflowId`
  - `workflowVersion`
  - tenant/project/auth trace context
- `GET /executions` returns workflow-scoped history from job storage.
- `GET /executions/{executionId}` returns the execution only when it belongs to
  the requested workflow.
- Job-list filtering now supports workflow ID resolution across canonical and
  legacy metadata keys for robust historical coverage.

## Verification

```bash
pnpm --filter @isis/generation-api exec vitest run src/routes/workflows.spec.ts src/openapi.contract.spec.ts --reporter=dot
pnpm --filter @isis/generation-api exec vitest run src/routes/jobs.spec.ts src/routes/workflows.spec.ts src/openapi.contract.spec.ts --reporter=dot
node scripts/isis/generate_generation_api_openapi.mjs --check
pnpm --filter @isis/generation-api run openapi:check
```

## Outcome

WS10-002 is now closed with explicit workflow execution/history endpoints,
enforced RBAC, and OpenAPI + contract test parity aligned to source routes.
