REL-WF-001 — Make synchronization failure and retry actionable
| Field | Value |
|---|---|
| Status | Open; source-verified |
| Architecture state | Deployed behavior |
| Severity | High |
| Affected surface | Create, edit, status pill, failure details, retry, and recovery |
| Components | sparqd/oqullus, sparqd/bff-api, sparqd/workflow-backend, Airflow |
| Associated issue | Not opened |
Where the problem appears
Create or update a disposable workflow whose requested revision fails Airflow discovery or parsing.
Concrete observed case
Workflow-backend records detailed failure state and has an idempotent synchronization retry operation. The BFF does not expose that retry, while the UI reduces failure to Needs attention and suggests editing. Create and update toasts say success when persistence/publication succeeds even though the runtime revision is still pending and may later fail.
Expected condition
Acknowledge Save separately from Applied. Needs attention shows a safe failure category, correlation identity, last check, and available Edit, Retry, Delete, or support path. Retry republishes the intended revision without creating another workflow.
Cause and evidence
- Backend models syncing and failed revisions and marks timeout, import, availability, and mismatch failures.
- Backend retry is intentionally absent from the current BFF/UI.
- UI success copy precedes Airflow confirmation.
Why it matters
Users can believe a workflow is runnable when only its product record was saved and have no direct recovery when synchronization fails.
Existing controls and workarounds
Treat Creating and Applying changes as pending. For Needs attention, inspect operational evidence and use a corrective edit or delete; no user-facing retry currently exists.
Alternatives considered
- Recommended: expose safe retry plus distinct Saved and Applied feedback.
- Require an edit for every retry — rejected because transient discovery failures need no definition change.
- Make create wait synchronously for Airflow — rejected due to scheduler latency and availability coupling.
Component involvement
- sparqd/workflow-backend owns durable sync state and idempotent retry.
- sparqd/bff-api exposes only safe product recovery operations.
- sparqd/oqullus presents phase-specific feedback and recovery.
Reproduction and verification
Follow WF-S008.
Resolution conditions
Close when save/apply states are distinct, every failure category has a supported recovery, retry is gated by the active access contract and is idempotent, and reload preserves accurate state. Require an OpenFGA capability only after that authorization plane is activated.
Validation and blockers
Workflow-backend, BFF, Oqullus, Airflow, support, and operations owners must validate.