ahmido
3c3daae405
## Summary - introduce a shared operator outcome taxonomy with semantic axes, severity bands, and next-action policy - apply the taxonomy to operations, evidence/review completeness, baseline semantics, and restore semantics - harden badge rendering, tenant-safe filtering/search behavior, and operator-facing summary/notification wording - add the spec kit artifacts, reference documentation, and regression coverage for diagnostic-vs-primary state handling ## Testing - focused Pest coverage for taxonomy registry and badge guardrails - operations presentation and notification tests - evidence, baseline, restore, and tenant-scope regression tests ## Notes - Livewire v4.0+ compliance is preserved in the existing Filament v5 stack - panel provider registration remains unchanged in bootstrap/providers.php - no new globally searchable resource was added; adopted resources remain tenant-safe and out of global search where required - no new destructive action family was introduced; existing actions keep their current authorization and confirmation behavior - no new frontend asset strategy was introduced; existing deploy flow with filament:assets remains unchanged Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #186
187 lines
5.4 KiB
YAML
187 lines
5.4 KiB
YAML
openapi: 3.1.0
|
|
info:
|
|
title: Operator State Presentation Logical Contract
|
|
version: 0.1.0
|
|
summary: Logical contract for resolving raw domain state into operator-facing state under the shared taxonomy.
|
|
description: |
|
|
This contract is logical rather than transport-prescriptive. It describes the
|
|
expected behavior of existing badge mappers, presenters, notifications, and
|
|
Filament surfaces that consume the shared operator outcome taxonomy.
|
|
Runtime badge implementations currently expose the resolved severity band
|
|
through Filament badge colors with the same enum values.
|
|
servers:
|
|
- url: https://tenantpilot.local
|
|
paths:
|
|
/contracts/operator-state/resolve:
|
|
post:
|
|
summary: Resolve one raw domain state into operator-facing presentation
|
|
operationId: resolveOperatorState
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/StateResolutionRequest'
|
|
responses:
|
|
'200':
|
|
description: Taxonomy-backed state presentation resolved
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/StateResolutionResponse'
|
|
examples:
|
|
blockedOperation:
|
|
value:
|
|
axis: execution_outcome
|
|
primaryLabel: Blocked by prerequisite
|
|
severity: warning
|
|
classificationLevel: primary
|
|
nextActionPolicy: required
|
|
explanationRequired: true
|
|
diagnosticLabel: null
|
|
legacyAliases:
|
|
- Blocked
|
|
notes: Execution could not start or continue until a prerequisite is fixed.
|
|
/contracts/operator-state/validate-adoption:
|
|
post:
|
|
summary: Validate that an adopted surface only uses allowed taxonomy mappings
|
|
operationId: validateAdoptionTarget
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/AdoptionValidationRequest'
|
|
responses:
|
|
'200':
|
|
description: Adoption validation result
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/AdoptionValidationResponse'
|
|
components:
|
|
schemas:
|
|
StateResolutionRequest:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- domain
|
|
- rawValue
|
|
- surfaceType
|
|
properties:
|
|
domain:
|
|
type: string
|
|
example: operation_run_outcome
|
|
rawValue:
|
|
type: string
|
|
example: blocked
|
|
surfaceType:
|
|
type: string
|
|
enum:
|
|
- badge
|
|
- summary_line
|
|
- notification
|
|
- infolist
|
|
- widget
|
|
tenantScoped:
|
|
type: boolean
|
|
default: true
|
|
includeDiagnostics:
|
|
type: boolean
|
|
default: false
|
|
StateResolutionResponse:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- axis
|
|
- primaryLabel
|
|
- severity
|
|
- classificationLevel
|
|
- nextActionPolicy
|
|
- explanationRequired
|
|
- notes
|
|
properties:
|
|
axis:
|
|
type: string
|
|
example: execution_outcome
|
|
primaryLabel:
|
|
type: string
|
|
example: Blocked by prerequisite
|
|
severity:
|
|
type: string
|
|
description: Operator-facing severity band. In runtime badge mappings this is the Filament badge color.
|
|
enum:
|
|
- gray
|
|
- info
|
|
- success
|
|
- warning
|
|
- danger
|
|
- primary
|
|
classificationLevel:
|
|
type: string
|
|
enum:
|
|
- primary
|
|
- diagnostic
|
|
nextActionPolicy:
|
|
type: string
|
|
enum:
|
|
- required
|
|
- optional
|
|
- none
|
|
explanationRequired:
|
|
type: boolean
|
|
diagnosticLabel:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
example: Fallback renderer
|
|
legacyAliases:
|
|
type: array
|
|
items:
|
|
type: string
|
|
notes:
|
|
type: string
|
|
example: Execution could not start or continue until a prerequisite is fixed.
|
|
AdoptionValidationRequest:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- target
|
|
- entries
|
|
properties:
|
|
target:
|
|
type: string
|
|
example: operations
|
|
entries:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/StateResolutionResponse'
|
|
AdoptionValidationResponse:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- valid
|
|
- violations
|
|
properties:
|
|
valid:
|
|
type: boolean
|
|
violations:
|
|
type: array
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- code
|
|
- message
|
|
properties:
|
|
code:
|
|
type: string
|
|
enum:
|
|
- diagnostic_severity_violation
|
|
- missing_next_action_policy
|
|
- unqualified_overloaded_term
|
|
- unauthorized_scope_leak_risk
|
|
message:
|
|
type: string
|
|
example: Diagnostic taxonomy entries cannot use warning or danger severity.
|