ahmido
a107e7e41b
## Summary - add the Spec 181 restore-safety layer with scope fingerprinting, preview/check integrity states, execution safety snapshots, result attention, and operator-facing copy across the wizard, restore detail, and canonical operation detail - add focused unit and feature coverage for restore-safety assessment, result attention, and restore-linked operation detail - switch the finding exceptions queue `Inspect exception` action to a native Filament slide-over while preserving query-param-backed inline summary behavior ## Testing - `vendor/bin/sail artisan test --compact tests/Feature/Monitoring/FindingExceptionsQueueTest.php tests/Feature/Filament/RestoreSafetyIntegrityWizardTest.php tests/Feature/Filament/RestoreResultAttentionSurfaceTest.php tests/Feature/Operations/RestoreLinkedOperationDetailTest.php tests/Unit/Support/RestoreSafety` ## Notes - Spec 181 checklist is complete (`specs/181-restore-safety-integrity/checklists/requirements.md`) - the branch still has unchecked follow-up tasks in `specs/181-restore-safety-integrity/tasks.md`: `T012`, `T018`, `T019`, `T023`, `T025`, `T029`, `T032`, `T033`, `T041`, `T042`, `T043`, `T044` - Filament v5 / Livewire v4 compliance is preserved, no panel provider registration changes were made, no global-search behavior was added, destructive actions remain confirmation-gated, and no new Filament assets were introduced Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #210
602 lines
16 KiB
YAML
602 lines
16 KiB
YAML
openapi: 3.1.0
|
|
info:
|
|
title: Restore Safety Integrity Contracts
|
|
version: 1.0.0
|
|
description: >-
|
|
Internal reference contract for the restore safety surfaces. The routes continue
|
|
to return rendered HTML through Filament and Livewire. The vendor media types below
|
|
document the structured page and mutation models that must be derivable before rendering
|
|
or execution. This is not a public API commitment.
|
|
paths:
|
|
/admin/t/{tenant}/restore-runs/create:
|
|
get:
|
|
summary: Restore run wizard page
|
|
description: >-
|
|
Returns the rendered restore wizard. The vendor media type documents the
|
|
safety-integrity page model that the wizard must expose.
|
|
parameters:
|
|
- name: tenant
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
responses:
|
|
'200':
|
|
description: Rendered restore wizard page
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
application/vnd.tenantpilot.restore-safety-wizard+json:
|
|
schema:
|
|
$ref: '#/components/schemas/RestoreSafetyWizardPage'
|
|
'403':
|
|
description: Viewer is in scope but lacks restore execution capability
|
|
'404':
|
|
description: Tenant or restore surface is not visible because tenant membership or workspace context is missing
|
|
/admin/t/{tenant}/restore-runs:
|
|
post:
|
|
summary: Create a restore run or queue a real restore execution
|
|
description: >-
|
|
Internal logical contract for the wizard submission. The real implementation is
|
|
Filament and Livewire driven, but the same validation truth must hold.
|
|
parameters:
|
|
- name: tenant
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/vnd.tenantpilot.restore-run-create+json:
|
|
schema:
|
|
$ref: '#/components/schemas/CreateRestoreRunRequest'
|
|
responses:
|
|
'201':
|
|
description: Restore run created or queued successfully
|
|
content:
|
|
application/vnd.tenantpilot.restore-run-created+json:
|
|
schema:
|
|
$ref: '#/components/schemas/CreateRestoreRunResponse'
|
|
'403':
|
|
description: Viewer is in scope but lacks restore execution capability
|
|
'404':
|
|
description: Tenant or backup scope is not visible because tenant membership or workspace context is missing
|
|
'422':
|
|
description: Preview, checks, scope fingerprint, or hard-confirm validation failed
|
|
/admin/t/{tenant}/restore-runs/{restoreRun}:
|
|
get:
|
|
summary: Restore run detail and result page
|
|
description: >-
|
|
Returns the rendered restore detail page. The vendor media type documents the
|
|
result-attention and basis-truth model that must be available for rendering.
|
|
parameters:
|
|
- name: tenant
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
- name: restoreRun
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
responses:
|
|
'200':
|
|
description: Rendered restore detail page
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
application/vnd.tenantpilot.restore-run-detail+json:
|
|
schema:
|
|
$ref: '#/components/schemas/RestoreRunDetailPage'
|
|
'403':
|
|
description: Viewer is in scope but lacks required capability for a linked follow-up action
|
|
'404':
|
|
description: Restore run is not visible because tenant membership or workspace context is missing
|
|
/admin/operations/{run}:
|
|
get:
|
|
summary: Canonical operation detail for a restore-linked run
|
|
description: >-
|
|
Returns the rendered canonical operation detail page. The vendor media type documents
|
|
the restore-specific continuation truth that must remain visible when the run represents
|
|
restore execution.
|
|
parameters:
|
|
- name: run
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
responses:
|
|
'200':
|
|
description: Rendered canonical operation detail page
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
application/vnd.tenantpilot.restore-linked-operation+json:
|
|
schema:
|
|
$ref: '#/components/schemas/RestoreLinkedOperationSurface'
|
|
'403':
|
|
description: Viewer is in scope but lacks a linked follow-up capability
|
|
'404':
|
|
description: Run is not visible because workspace or tenant entitlement is missing
|
|
components:
|
|
schemas:
|
|
RestoreSafetyWizardPage:
|
|
type: object
|
|
required:
|
|
- currentScope
|
|
- previewIntegrity
|
|
- checksIntegrity
|
|
- executionReadiness
|
|
- safetyAssessment
|
|
- primaryGuidance
|
|
properties:
|
|
currentScope:
|
|
$ref: '#/components/schemas/ScopeBasis'
|
|
previewIntegrity:
|
|
$ref: '#/components/schemas/IntegrityState'
|
|
checksIntegrity:
|
|
$ref: '#/components/schemas/IntegrityState'
|
|
executionReadiness:
|
|
$ref: '#/components/schemas/ExecutionReadiness'
|
|
safetyAssessment:
|
|
$ref: '#/components/schemas/SafetyAssessment'
|
|
primaryGuidance:
|
|
$ref: '#/components/schemas/PrimaryGuidance'
|
|
lastValidatedAt:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
format: date-time
|
|
CreateRestoreRunRequest:
|
|
type: object
|
|
required:
|
|
- backupSetId
|
|
- scopeMode
|
|
- groupMapping
|
|
- isDryRun
|
|
- scopeFingerprint
|
|
properties:
|
|
backupSetId:
|
|
type: integer
|
|
scopeMode:
|
|
type: string
|
|
enum:
|
|
- all
|
|
- selected
|
|
backupItemIds:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
groupMapping:
|
|
type: object
|
|
additionalProperties:
|
|
type: string
|
|
isDryRun:
|
|
type: boolean
|
|
acknowledgedImpact:
|
|
type: boolean
|
|
tenantConfirm:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
scopeFingerprint:
|
|
type: string
|
|
previewEvidence:
|
|
oneOf:
|
|
- $ref: '#/components/schemas/IntegrityEvidence'
|
|
- type: 'null'
|
|
checksEvidence:
|
|
oneOf:
|
|
- $ref: '#/components/schemas/IntegrityEvidence'
|
|
- type: 'null'
|
|
CreateRestoreRunResponse:
|
|
type: object
|
|
required:
|
|
- restoreRunId
|
|
- status
|
|
- executionMode
|
|
- executionSafetySnapshot
|
|
properties:
|
|
restoreRunId:
|
|
type: integer
|
|
status:
|
|
type: string
|
|
operationRunId:
|
|
type:
|
|
- integer
|
|
- 'null'
|
|
executionMode:
|
|
type: string
|
|
enum:
|
|
- preview_only
|
|
- execute
|
|
executionSafetySnapshot:
|
|
$ref: '#/components/schemas/SafetySnapshot'
|
|
RestoreRunDetailPage:
|
|
type: object
|
|
required:
|
|
- header
|
|
- basisTruth
|
|
- resultAttention
|
|
- primaryNextAction
|
|
properties:
|
|
header:
|
|
$ref: '#/components/schemas/RestoreRunHeader'
|
|
basisTruth:
|
|
$ref: '#/components/schemas/BasisTruth'
|
|
resultAttention:
|
|
$ref: '#/components/schemas/ResultAttention'
|
|
primaryNextAction:
|
|
$ref: '#/components/schemas/PrimaryGuidance'
|
|
itemBreakdown:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/ResultItem'
|
|
diagnostics:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/DiagnosticBlock'
|
|
relatedOperation:
|
|
oneOf:
|
|
- $ref: '#/components/schemas/RestoreOperationLink'
|
|
- type: 'null'
|
|
RestoreLinkedOperationSurface:
|
|
type: object
|
|
required:
|
|
- operationLifecycle
|
|
- operationOutcome
|
|
- restoreContinuation
|
|
properties:
|
|
operationLifecycle:
|
|
$ref: '#/components/schemas/Fact'
|
|
operationOutcome:
|
|
$ref: '#/components/schemas/Fact'
|
|
restoreContinuation:
|
|
$ref: '#/components/schemas/RestoreOperationLink'
|
|
ScopeBasis:
|
|
type: object
|
|
required:
|
|
- backupSetId
|
|
- scopeMode
|
|
- selectedItemIds
|
|
- groupMapping
|
|
- fingerprint
|
|
properties:
|
|
backupSetId:
|
|
type: integer
|
|
scopeMode:
|
|
type: string
|
|
enum:
|
|
- all
|
|
- selected
|
|
selectedItemIds:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
groupMapping:
|
|
type: object
|
|
additionalProperties:
|
|
type: string
|
|
fingerprint:
|
|
type: string
|
|
IntegrityState:
|
|
type: object
|
|
required:
|
|
- state
|
|
- rerunRequired
|
|
properties:
|
|
state:
|
|
type: string
|
|
enum:
|
|
- not_generated
|
|
- not_run
|
|
- current
|
|
- stale
|
|
- invalidated
|
|
fingerprint:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
capturedAt:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
format: date-time
|
|
blockingCount:
|
|
type:
|
|
- integer
|
|
- 'null'
|
|
warningCount:
|
|
type:
|
|
- integer
|
|
- 'null'
|
|
invalidationReasons:
|
|
type: array
|
|
items:
|
|
type: string
|
|
rerunRequired:
|
|
type: boolean
|
|
displaySummary:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
IntegrityEvidence:
|
|
type: object
|
|
required:
|
|
- fingerprint
|
|
- capturedAt
|
|
properties:
|
|
fingerprint:
|
|
type: string
|
|
capturedAt:
|
|
type: string
|
|
format: date-time
|
|
ExecutionReadiness:
|
|
type: object
|
|
required:
|
|
- allowed
|
|
- blockingReasons
|
|
- mutationScope
|
|
properties:
|
|
allowed:
|
|
type: boolean
|
|
blockingReasons:
|
|
type: array
|
|
items:
|
|
type: string
|
|
mutationScope:
|
|
type: string
|
|
enum:
|
|
- simulation_only
|
|
- microsoft_tenant
|
|
requiredCapability:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
SafetyAssessment:
|
|
type: object
|
|
required:
|
|
- state
|
|
- positiveClaimSuppressed
|
|
properties:
|
|
state:
|
|
type: string
|
|
enum:
|
|
- blocked
|
|
- risky
|
|
- ready_with_caution
|
|
- ready
|
|
positiveClaimSuppressed:
|
|
type: boolean
|
|
blockerCount:
|
|
type: integer
|
|
warningCount:
|
|
type: integer
|
|
primaryIssueCode:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
primaryNextAction:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
SafetySnapshot:
|
|
type: object
|
|
required:
|
|
- evaluatedAt
|
|
- scopeFingerprint
|
|
- previewState
|
|
- checksState
|
|
- safetyState
|
|
properties:
|
|
evaluatedAt:
|
|
type: string
|
|
format: date-time
|
|
scopeFingerprint:
|
|
type: string
|
|
previewState:
|
|
type: string
|
|
checksState:
|
|
type: string
|
|
safetyState:
|
|
type: string
|
|
blockingCount:
|
|
type: integer
|
|
warningCount:
|
|
type: integer
|
|
primaryIssueCode:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
followUpBoundary:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
RestoreRunHeader:
|
|
type: object
|
|
required:
|
|
- restoreRunId
|
|
- backupSetLabel
|
|
- status
|
|
- executionMode
|
|
properties:
|
|
restoreRunId:
|
|
type: integer
|
|
backupSetLabel:
|
|
type: string
|
|
status:
|
|
$ref: '#/components/schemas/Fact'
|
|
executionMode:
|
|
$ref: '#/components/schemas/Fact'
|
|
requestedBy:
|
|
oneOf:
|
|
- $ref: '#/components/schemas/Fact'
|
|
- type: 'null'
|
|
startedAt:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
format: date-time
|
|
completedAt:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
format: date-time
|
|
BasisTruth:
|
|
type: object
|
|
properties:
|
|
scopeBasis:
|
|
oneOf:
|
|
- $ref: '#/components/schemas/ScopeBasis'
|
|
- type: 'null'
|
|
previewIntegrity:
|
|
oneOf:
|
|
- $ref: '#/components/schemas/IntegrityState'
|
|
- type: 'null'
|
|
checksIntegrity:
|
|
oneOf:
|
|
- $ref: '#/components/schemas/IntegrityState'
|
|
- type: 'null'
|
|
executionSafetySnapshot:
|
|
oneOf:
|
|
- $ref: '#/components/schemas/SafetySnapshot'
|
|
- type: 'null'
|
|
ResultAttention:
|
|
type: object
|
|
required:
|
|
- state
|
|
- followUpRequired
|
|
- primaryCauseFamily
|
|
- summary
|
|
- recoveryClaimBoundary
|
|
properties:
|
|
state:
|
|
type: string
|
|
enum:
|
|
- not_executed
|
|
- completed
|
|
- partial
|
|
- failed
|
|
- completed_with_follow_up
|
|
followUpRequired:
|
|
type: boolean
|
|
primaryCauseFamily:
|
|
type: string
|
|
enum:
|
|
- execution_failure
|
|
- write_gate_or_rbac
|
|
- provider_operability
|
|
- missing_dependency_or_mapping
|
|
- payload_quality
|
|
- scope_mismatch
|
|
- item_level_failure
|
|
- none
|
|
summary:
|
|
type: string
|
|
recoveryClaimBoundary:
|
|
type: string
|
|
counts:
|
|
type: object
|
|
additionalProperties:
|
|
type: integer
|
|
PrimaryGuidance:
|
|
type: object
|
|
required:
|
|
- title
|
|
- body
|
|
- actionLabel
|
|
- actionKind
|
|
properties:
|
|
title:
|
|
type: string
|
|
body:
|
|
type: string
|
|
actionLabel:
|
|
type: string
|
|
actionKind:
|
|
type: string
|
|
enum:
|
|
- rerun_checks
|
|
- regenerate_preview
|
|
- adjust_scope
|
|
- review_warnings
|
|
- execute_preview
|
|
- execute_restore
|
|
- review_result
|
|
- open_operation
|
|
- inspect_blocker
|
|
ResultItem:
|
|
type: object
|
|
required:
|
|
- label
|
|
- status
|
|
properties:
|
|
label:
|
|
type: string
|
|
status:
|
|
type: string
|
|
causeFamily:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
nextAction:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
DiagnosticBlock:
|
|
type: object
|
|
required:
|
|
- title
|
|
properties:
|
|
title:
|
|
type: string
|
|
description:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
collapsible:
|
|
type: boolean
|
|
collapsed:
|
|
type: boolean
|
|
RestoreOperationLink:
|
|
type: object
|
|
required:
|
|
- accessState
|
|
properties:
|
|
restoreRunId:
|
|
type:
|
|
- integer
|
|
- 'null'
|
|
resultAttention:
|
|
oneOf:
|
|
- $ref: '#/components/schemas/ResultAttention'
|
|
- type: 'null'
|
|
restoreDetailUrl:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
accessState:
|
|
type: string
|
|
enum:
|
|
- linked
|
|
- unavailable
|
|
- forbidden_by_scope
|
|
unavailableReason:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
Fact:
|
|
type: object
|
|
required:
|
|
- label
|
|
- value
|
|
properties:
|
|
label:
|
|
type: string
|
|
value:
|
|
type: string |