ahmido
acc8947384
## Summary - add the Spec 194 governance action catalog, friction classes, reason policies, and regression guards - align exception, review, evidence, finding, tenant, provider connection, and system run actions to the shared semantics model - add focused feature, RBAC, audit, unit, and browser coverage, including the tenant detail triage header consistency update ## Verification - ran the focused Spec 194 verification pack from the quickstart and task plan - ran targeted tenant triage coverage after the detail-header update - ran `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent` ## Filament Notes - Filament v5 / Livewire v4 compliance preserved - provider registration remains in `apps/platform/bootstrap/providers.php` - globally searchable resources were not changed - destructive actions remain confirmation-gated and server-authorized - no new Filament assets were introduced; the existing `cd apps/platform && php artisan filament:assets` deploy step stays unchanged Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #229
319 lines
9.5 KiB
YAML
319 lines
9.5 KiB
YAML
openapi: 3.1.0
|
|
info:
|
|
title: Governance Action Semantics Internal Contract
|
|
version: 0.1.0
|
|
summary: Internal logical contract for Spec 194 governance action friction, reason, and vocabulary alignment
|
|
description: |
|
|
This contract is an internal planning artifact for Spec 194. The affected
|
|
surfaces continue to render through Filament and Livewire. The schemas
|
|
below define the bounded semantic contract for governance action families,
|
|
friction classes, reason policies, danger expectations, approved surface
|
|
bindings, and documented deviations.
|
|
servers:
|
|
- url: /internal
|
|
x-governance-action-consumers:
|
|
- family: exception_decision
|
|
sourceFiles:
|
|
- apps/platform/app/Filament/Pages/Monitoring/FindingExceptionsQueue.php
|
|
- apps/platform/app/Filament/Resources/FindingExceptionResource/Pages/ViewFindingException.php
|
|
- apps/platform/app/Services/Findings/FindingExceptionService.php
|
|
mustRender:
|
|
- shared_family_binding
|
|
- required_reason_for_f2_or_f3_actions
|
|
- canonical_exception_vocabulary
|
|
mustNotRender:
|
|
- local_synonym_drift
|
|
- undocumented_reason_override
|
|
- family: review_lifecycle
|
|
sourceFiles:
|
|
- apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php
|
|
- apps/platform/app/Services/TenantReviews/TenantReviewLifecycleService.php
|
|
mustRender:
|
|
- publish_vs_archive_semantic_separation
|
|
- export_remains_f0
|
|
mustNotRender:
|
|
- export_as_governance_peer
|
|
- family: evidence_lifecycle
|
|
sourceFiles:
|
|
- apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php
|
|
- apps/platform/app/Filament/Resources/EvidenceSnapshotResource/Pages/ViewEvidenceSnapshot.php
|
|
- apps/platform/app/Services/Evidence/EvidenceSnapshotService.php
|
|
mustRender:
|
|
- refresh_vs_expire_separation
|
|
- required_reason_for_expire_when_declared
|
|
mustNotRender:
|
|
- refresh_and_expire_equivalent_semantics
|
|
- family: run_triage
|
|
sourceFiles:
|
|
- apps/platform/app/Filament/System/Pages/Ops/ViewRun.php
|
|
- apps/platform/app/Services/SystemConsole/OperationRunTriageService.php
|
|
mustRender:
|
|
- retry_cancel_investigated_severity_split
|
|
- required_reason_for_high_impact_actions
|
|
mustNotRender:
|
|
- cancel_as_lightweight_follow_up
|
|
- family: lifecycle_support
|
|
sourceFiles:
|
|
- apps/platform/app/Filament/Resources/FindingResource.php
|
|
- apps/platform/app/Filament/Resources/TenantResource.php
|
|
- apps/platform/app/Services/Findings/FindingWorkflowService.php
|
|
mustRender:
|
|
- consistent_close_reopen_family
|
|
- consistent_archive_restore_family
|
|
mustNotRender:
|
|
- undocumented_surface_specific_override
|
|
- family: regression_guards
|
|
sourceFiles:
|
|
- apps/platform/app/Support/Ui/GovernanceActions/GovernanceActionCatalog.php
|
|
- apps/platform/tests/Feature/Guards/Spec194GovernanceActionSemanticsGuardTest.php
|
|
- apps/platform/tests/Unit/Ui/GovernanceActions/GovernanceActionCatalogTest.php
|
|
paths:
|
|
/internal/governance-actions/families/{family}:
|
|
get:
|
|
summary: Return the logical semantics contract for one governance action family
|
|
operationId: getGovernanceActionFamilyContract
|
|
parameters:
|
|
- name: family
|
|
in: path
|
|
required: true
|
|
schema:
|
|
$ref: '#/components/schemas/FamilyKey'
|
|
responses:
|
|
'200':
|
|
description: Logical semantics contract for the requested family
|
|
content:
|
|
application/vnd.tenantpilot.governance-action-semantics+json:
|
|
schema:
|
|
$ref: '#/components/schemas/GovernanceActionFamilyContract'
|
|
'404':
|
|
description: Requested family is not declared in the Spec 194 catalog
|
|
/internal/governance-actions/surfaces/{surface}:
|
|
get:
|
|
summary: Return all governance action bindings for one surface
|
|
operationId: getGovernanceSurfaceBindings
|
|
parameters:
|
|
- name: surface
|
|
in: path
|
|
required: true
|
|
schema:
|
|
$ref: '#/components/schemas/SurfaceKey'
|
|
responses:
|
|
'200':
|
|
description: Declared governance action bindings for the requested surface
|
|
content:
|
|
application/vnd.tenantpilot.governance-action-bindings+json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/GovernanceActionSurfaceBinding'
|
|
'404':
|
|
description: Requested surface has no Spec 194 governance bindings
|
|
components:
|
|
schemas:
|
|
FamilyKey:
|
|
type: string
|
|
enum:
|
|
- exception_decision
|
|
- review_lifecycle
|
|
- evidence_lifecycle
|
|
- run_triage
|
|
- finding_lifecycle
|
|
- tenant_lifecycle
|
|
- non_governance_navigation
|
|
SurfaceKey:
|
|
type: string
|
|
enum:
|
|
- finding_exceptions_queue
|
|
- view_finding_exception
|
|
- list_evidence_snapshots
|
|
- view_evidence_snapshot
|
|
- view_tenant_review
|
|
- view_finding
|
|
- tenantless_operation_run_viewer
|
|
- system_view_run
|
|
- view_tenant
|
|
- edit_tenant
|
|
FrictionClass:
|
|
type: string
|
|
enum:
|
|
- F0
|
|
- F1
|
|
- F2
|
|
- F3
|
|
ReasonPolicy:
|
|
type: string
|
|
enum:
|
|
- none
|
|
- optional
|
|
- required
|
|
DangerPolicy:
|
|
type: string
|
|
enum:
|
|
- none
|
|
- contextual
|
|
- required
|
|
AuditChannel:
|
|
type: string
|
|
enum:
|
|
- tenant_audit
|
|
- workspace_audit
|
|
- system_audit
|
|
- operation_context
|
|
GovernanceActionRule:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- actionKey
|
|
- canonicalLabel
|
|
- frictionClass
|
|
- reasonPolicy
|
|
- dangerPolicy
|
|
- auditVerb
|
|
- serviceOwner
|
|
properties:
|
|
actionKey:
|
|
type: string
|
|
canonicalLabel:
|
|
type: string
|
|
frictionClass:
|
|
$ref: '#/components/schemas/FrictionClass'
|
|
reasonPolicy:
|
|
$ref: '#/components/schemas/ReasonPolicy'
|
|
dangerPolicy:
|
|
$ref: '#/components/schemas/DangerPolicy'
|
|
modalHeadingPattern:
|
|
type: string
|
|
successNotificationPattern:
|
|
type: string
|
|
auditVerb:
|
|
type: string
|
|
serviceOwner:
|
|
type: string
|
|
GovernanceActionSurfaceBinding:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- surfaceKey
|
|
- pageClass
|
|
- actionName
|
|
- familyKey
|
|
- statePredicate
|
|
- auditChannel
|
|
properties:
|
|
surfaceKey:
|
|
$ref: '#/components/schemas/SurfaceKey'
|
|
pageClass:
|
|
type: string
|
|
actionName:
|
|
type: string
|
|
familyKey:
|
|
$ref: '#/components/schemas/FamilyKey'
|
|
statePredicate:
|
|
type: string
|
|
primaryOrSecondary:
|
|
type: string
|
|
enum:
|
|
- primary
|
|
- secondary
|
|
capabilityKey:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
uiFieldKey:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
auditChannel:
|
|
$ref: '#/components/schemas/AuditChannel'
|
|
DocumentedDeviation:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- actionKey
|
|
- surfaceKey
|
|
- deviationType
|
|
- rationale
|
|
- reviewGate
|
|
properties:
|
|
actionKey:
|
|
type: string
|
|
surfaceKey:
|
|
$ref: '#/components/schemas/SurfaceKey'
|
|
deviationType:
|
|
type: string
|
|
enum:
|
|
- friction_override
|
|
- reason_override
|
|
- danger_override
|
|
- vocabulary_override
|
|
rationale:
|
|
type: string
|
|
reviewGate:
|
|
type: string
|
|
allowedUntil:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
GovernanceActionFamilyContract:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- familyKey
|
|
- canonicalObject
|
|
- rules
|
|
- bindings
|
|
- regressionRequirements
|
|
properties:
|
|
familyKey:
|
|
$ref: '#/components/schemas/FamilyKey'
|
|
canonicalObject:
|
|
type: string
|
|
panels:
|
|
type: array
|
|
items:
|
|
type: string
|
|
enum:
|
|
- tenant
|
|
- admin
|
|
- system
|
|
defaultActionOrder:
|
|
type: array
|
|
items:
|
|
type: string
|
|
defaultMutationScopeSource:
|
|
type: string
|
|
rules:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/GovernanceActionRule'
|
|
bindings:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/GovernanceActionSurfaceBinding'
|
|
deviations:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/DocumentedDeviation'
|
|
regressionRequirements:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- requiresGuardCoverage
|
|
- requiresFeatureCoverage
|
|
- requiresBrowserSmoke
|
|
- requiresPositiveAuthCase
|
|
- requiresNegativeAuthCase
|
|
properties:
|
|
requiresGuardCoverage:
|
|
type: boolean
|
|
requiresFeatureCoverage:
|
|
type: boolean
|
|
requiresBrowserSmoke:
|
|
type: boolean
|
|
requiresPositiveAuthCase:
|
|
type: boolean
|
|
requiresNegativeAuthCase:
|
|
type: boolean
|
|
mustVerifyAuditPropagation:
|
|
type: boolean
|