ahmido
1f0cc5de56
## Summary - add the shared operator explanation layer with explanation families, trustworthiness semantics, count descriptors, and centralized badge mappings - adopt explanation-first rendering across baseline compare, governance operation run detail, baseline snapshot presentation, tenant review detail, and review register rows - extend reason translation, artifact-truth presentation, fallback ops UX messaging, and focused regression coverage for operator explanation semantics ## Testing - vendor/bin/sail bin pint --dirty --format agent - vendor/bin/sail artisan test --compact tests/Feature/Monitoring/OperationsTenantScopeTest.php tests/Feature/Operations/OperationRunBlockedExecutionPresentationTest.php - vendor/bin/sail artisan test --compact ## Notes - Livewire v4 compatible - panel provider registration remains in bootstrap/providers.php - no destructive Filament actions were added or changed in this PR - no new global-search behavior was introduced in this slice Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #191
235 lines
7.0 KiB
YAML
235 lines
7.0 KiB
YAML
openapi: 3.1.0
|
|
info:
|
|
title: Operator Explanation Layer Contract
|
|
version: 1.0.0
|
|
summary: Logical operator-facing read contract for explanation-first governance surfaces
|
|
description: |
|
|
This contract captures the intended read-model semantics for Spec 161.
|
|
These are logical contracts for existing Filament and Livewire-backed surfaces,
|
|
not a commitment to public REST endpoints.
|
|
servers:
|
|
- url: https://tenantpilot.local
|
|
tags:
|
|
- name: BaselineCompare
|
|
- name: GovernanceRuns
|
|
- name: GovernanceArtifacts
|
|
paths:
|
|
/tenants/{tenantId}/baseline-compare/explanation:
|
|
get:
|
|
tags: [BaselineCompare]
|
|
summary: Read baseline compare explanation model
|
|
description: Returns the operator explanation pattern for the current baseline compare state, including trustworthiness, count semantics, and diagnostics availability.
|
|
parameters:
|
|
- $ref: '#/components/parameters/TenantId'
|
|
responses:
|
|
'200':
|
|
description: Explanation model returned
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/GovernanceResultSurfaceModel'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
|
|
/operation-runs/{operationRunId}/explanation:
|
|
get:
|
|
tags: [GovernanceRuns]
|
|
summary: Read governance run explanation model
|
|
description: Returns the operator explanation pattern and secondary diagnostics for a governance-oriented operation run.
|
|
parameters:
|
|
- $ref: '#/components/parameters/OperationRunId'
|
|
responses:
|
|
'200':
|
|
description: Run explanation model returned
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/GovernanceResultSurfaceModel'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
|
|
/governance-artifacts/{artifactType}/{artifactId}/explanation:
|
|
get:
|
|
tags: [GovernanceArtifacts]
|
|
summary: Read governance artifact explanation model
|
|
description: Returns the primary explanation block, secondary truth dimensions, and diagnostics visibility for a governance artifact detail surface.
|
|
parameters:
|
|
- $ref: '#/components/parameters/ArtifactType'
|
|
- $ref: '#/components/parameters/ArtifactId'
|
|
responses:
|
|
'200':
|
|
description: Artifact explanation model returned
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/GovernanceResultSurfaceModel'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
|
|
components:
|
|
parameters:
|
|
TenantId:
|
|
name: tenantId
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
OperationRunId:
|
|
name: operationRunId
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
ArtifactType:
|
|
name: artifactType
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
enum: [baseline_snapshot, evidence_snapshot, tenant_review, review_pack]
|
|
ArtifactId:
|
|
name: artifactId
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
|
|
responses:
|
|
Forbidden:
|
|
description: Member lacks the required capability in the already established scope
|
|
NotFound:
|
|
description: Workspace or tenant scope is not entitled, or the requested record is not visible in that scope
|
|
|
|
schemas:
|
|
GovernanceResultSurfaceModel:
|
|
type: object
|
|
required:
|
|
- primaryPattern
|
|
- secondaryTruth
|
|
- diagnosticsAvailable
|
|
properties:
|
|
primaryPattern:
|
|
$ref: '#/components/schemas/OperatorExplanationPattern'
|
|
secondaryTruth:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/TruthDimension'
|
|
diagnosticsAvailable:
|
|
type: boolean
|
|
diagnosticsSummary:
|
|
type: string
|
|
nullable: true
|
|
actions:
|
|
type: array
|
|
items:
|
|
type: object
|
|
required: [label, mutationScope]
|
|
properties:
|
|
label:
|
|
type: string
|
|
mutationScope:
|
|
type: string
|
|
enum: [tenantpilot_only, microsoft_tenant, simulation_only, none]
|
|
enabled:
|
|
type: boolean
|
|
|
|
OperatorExplanationPattern:
|
|
type: object
|
|
required:
|
|
- headline
|
|
- executionOutcome
|
|
- evaluationResult
|
|
- reliabilityLevel
|
|
- nextAction
|
|
- countDescriptors
|
|
properties:
|
|
headline:
|
|
type: string
|
|
executionOutcome:
|
|
type: string
|
|
examples: [completed, completed_with_follow_up, failed, blocked]
|
|
evaluationResult:
|
|
type: string
|
|
examples: [full_result, incomplete_result, suppressed_result, no_result, unavailable]
|
|
reliabilityLevel:
|
|
type: string
|
|
enum: [trustworthy, limited_confidence, diagnostic_only, unusable]
|
|
reliabilityStatement:
|
|
type: string
|
|
coverageStatement:
|
|
type: string
|
|
nullable: true
|
|
dominantCause:
|
|
type: object
|
|
nullable: true
|
|
properties:
|
|
code:
|
|
type: string
|
|
nullable: true
|
|
label:
|
|
type: string
|
|
explanation:
|
|
type: string
|
|
nextAction:
|
|
type: object
|
|
required: [category, text]
|
|
properties:
|
|
category:
|
|
type: string
|
|
enum:
|
|
- none
|
|
- observe
|
|
- retry_later
|
|
- fix_prerequisite
|
|
- refresh_or_sync
|
|
- review_evidence_gaps
|
|
- manual_validate
|
|
- escalate
|
|
text:
|
|
type: string
|
|
countDescriptors:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/CountDescriptor'
|
|
diagnosticsAvailable:
|
|
type: boolean
|
|
|
|
CountDescriptor:
|
|
type: object
|
|
required: [label, value, role, visibilityTier]
|
|
properties:
|
|
label:
|
|
type: string
|
|
value:
|
|
type: integer
|
|
role:
|
|
type: string
|
|
enum: [execution, evaluation_output, coverage, reliability_signal]
|
|
qualifier:
|
|
type: string
|
|
nullable: true
|
|
visibilityTier:
|
|
type: string
|
|
enum: [primary, diagnostic]
|
|
|
|
TruthDimension:
|
|
type: object
|
|
required: [dimension, value, visibilityTier]
|
|
properties:
|
|
dimension:
|
|
type: string
|
|
examples: [artifact_existence, content, freshness, support_level, publication_readiness, actionability]
|
|
value:
|
|
type: string
|
|
visibilityTier:
|
|
type: string
|
|
enum: [primary, secondary, diagnostic]
|
|
explanation:
|
|
type: string
|
|
nullable: true |