From 5d324659e3f9fbd953461b68ae43603d052eda86 Mon Sep 17 00:00:00 2001 From: Ahmed Darrazi Date: Sun, 11 Jan 2026 01:31:29 +0100 Subject: [PATCH] spec(049): clarify orchestration requirements --- .../spec.md | 31 +++++++++++++++++-- 1 file changed, 28 insertions(+), 3 deletions(-) diff --git a/specs/049-backup-restore-job-orchestration/spec.md b/specs/049-backup-restore-job-orchestration/spec.md index 8039727..c119263 100644 --- a/specs/049-backup-restore-job-orchestration/spec.md +++ b/specs/049-backup-restore-job-orchestration/spec.md @@ -15,6 +15,16 @@ ## Non-Goals (Phase 1) - No changes to external service contracts unless required for orchestration safety - No new promotion feature (e.g., DEV→PROD) (separate initiative) +## Clarifications + +### Session 2026-01-11 + +- Q: For FR-004 Idempotency, what should happen when the admin starts the same operation again for the same tenant + target while one is still queued/running? → A: Reuse existing run if identical is queued/running; allow a new run only after terminal. +- Q: For FR-002 status lifecycle, do we support canceling runs in Phase 1? → A: No cancel in Phase 1. +- Q: For FR-003 Progress visibility, which UI surfaces are required in Phase 1? → A: Phase 1 requires Run detail progress (counts/status) + DB notifications; Phase 2 adds a required global progress widget for all run types. +- Q: For FR-004, how should we define the “target object” used for de-duplication? → A: Dedupe key uses (tenant + operation type + target object id). +- Q: For FR-005 per-item outcome persistence, what is the item granularity for counts + item results in Phase 1? → A: Per internal DB record (e.g., restore/backup item rows). + ## User Scenarios & Testing *(mandatory)* ### User Story 1 - Capture snapshot runs in background (Priority: P1) @@ -99,17 +109,28 @@ ### Functional Requirements - Tenant identity - Initiator identity (user reference or audit reference) - Operation type and optional target object reference - - Status lifecycle: queued → running → (succeeded | failed | partial | canceled) + - Status lifecycle: queued → running → (succeeded | failed | partial) - Started/finished timestamps - Item counts: total / succeeded / failed - Safe error code and safe error context (no secrets) -- **FR-003 Progress visibility**: While a run is executing, the system MUST provide visible progress in the admin UI and MUST emit in-app notifications for key state transitions (queued/running/completed/failed). +- **FR-003 Progress visibility**: While a run is executing, the system MUST: + - Emit in-app notifications for key state transitions (queued/running/completed/failed) + - Provide a Run detail view that shows progress (status + item counts) + + Phase 1 does not require a global progress widget. + Phase 2 MUST add a global progress widget, required for all run types. - **FR-004 Idempotency & concurrency control**: The system MUST prevent uncontrolled duplicate execution due to double-clicks/retries by enforcing a deterministic de-duplication rule keyed by (tenant + operation type + target object) or (tenant + run id). When an identical run is already queued/running, the UI MUST show “already queued/running” and link to the existing run. + Clarification: For an identical start attempt while a run is `queued` or `running`, the system MUST re-use the existing Run Record and MUST NOT create a new run. A new run MAY be started only after the existing run reaches a terminal state. + + Clarification: For Phase 1, the default de-duplication key is (tenant + operation type + target object id). + - **FR-005 Deterministic outcome persistence**: The system MUST persist per-item outcomes for operations that act on multiple items, including status and a safe error summary, so results can be viewed later without relying on logs. + Clarification: In Phase 1, “item” refers to the internal DB record being acted on (e.g., a restore/backup item row). Counts (total/succeeded/failed) MUST be derived from these persisted item results. + - **FR-006 Tenant isolation & authorization**: Run visibility and execution MUST be tenant-scoped. Only authorized admins can start operations, and users MUST NOT be able to view or start runs across tenants. - **FR-007 Safety rules**: Preview/dry-run MUST be safe (no writes). Live restore MUST remain guarded with explicit confirmation and an auditable trail consistent with existing safety practices. @@ -122,9 +143,13 @@ ### Acceptance Checks - Starting any in-scope operation returns quickly with a queued Run Record link. - A Run Record always exists before background work begins and reaches a terminal state. -- Progress and state changes are visible in the UI via progress display and in-app notifications. +- Phase 1 does not support canceling runs. +- Progress and state changes are visible via Run detail view and in-app notifications. +- Phase 2 adds a global progress widget for all run types. - Duplicate start attempts for the same tenant + operation + target do not create uncontrolled duplicate execution. +- Duplicate start attempts for the same tenant + operation + target while a run is queued/running re-use the existing run and link to it. - Item-level outcomes and safe error summaries are viewable after completion. +- Run counts reflect persisted internal item results. - Preview/dry-run never performs writes. ### Key Entities *(include if feature involves data)*