ahmido
44898a98ac
## Summary - harden governance artifact truth propagation so stale or partial evidence downgrades evidence snapshots, tenant reviews, review packs, the canonical evidence overview, and the canonical review register consistently - add the full Spec 174 artifact set under `specs/174-evidence-freshness-publication-trust/` including spec, plan, research, data model, contracts, quickstart, checklist, and completed tasks - add focused fixture helpers plus a new browser smoke test for the touched evidence, review, and review-pack trust surfaces ## Testing - `vendor/bin/sail artisan test --compact tests/Feature/Evidence/EvidenceSnapshotResourceTest.php tests/Feature/Evidence/EvidenceOverviewPageTest.php tests/Feature/TenantReview/TenantReviewLifecycleTest.php tests/Feature/TenantReview/TenantReviewRegisterTest.php tests/Feature/ReviewPack/ReviewPackResourceTest.php tests/Feature/Monitoring/ArtifactTruthRunDetailTest.php tests/Browser/Spec174EvidenceFreshnessPublicationTrustSmokeTest.php` - manual integrated-browser smoke pass across Evidence Overview, Review Register, tenant review detail, tenant evidence snapshot detail, and review-packs list ## Notes - Livewire v4 compliance is preserved and no Filament v3/v4 APIs were introduced - no panel or provider changes were made; Laravel 11+ provider registration remains in `bootstrap/providers.php` - no new global-search behavior was introduced; existing resource view pages remain the relevant detail endpoints - destructive actions were not broadened; existing confirmation and authorization behavior remains in place - no new assets were added, so the current Filament asset strategy and deploy-time `php artisan filament:assets` behavior stay unchanged - branch `174-evidence-freshness-publication-trust` is pushed at `7f2c82c26dc83bbc09fbf9e732d5644cdd143113` and targets `dev` Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #205
396 lines
10 KiB
YAML
396 lines
10 KiB
YAML
openapi: 3.1.0
|
|
info:
|
|
title: Evidence Review Trust Surfaces Contract
|
|
version: 1.0.0
|
|
description: >-
|
|
Internal reference contract for the rendered HTML surfaces affected by Spec 174.
|
|
These routes continue to return HTML through Filament and Livewire. The vendor
|
|
media types below document the structured truth payloads that must be derivable
|
|
before rendering. This is not a public API commitment.
|
|
paths:
|
|
/admin/evidence/overview:
|
|
get:
|
|
summary: Canonical evidence overview
|
|
description: >-
|
|
Returns the rendered evidence overview for entitled tenants in the current workspace.
|
|
The vendor media type documents the derived row contract used to communicate
|
|
artifact truth, freshness, and next steps.
|
|
responses:
|
|
'200':
|
|
description: Rendered evidence overview page
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
application/vnd.tenantpilot.evidence-overview+json:
|
|
schema:
|
|
$ref: '#/components/schemas/EvidenceOverviewPage'
|
|
'404':
|
|
description: Workspace context is missing or the viewer is not entitled to the relevant scope
|
|
/admin/reviews:
|
|
get:
|
|
summary: Canonical review register
|
|
description: >-
|
|
Returns the rendered review register for entitled tenants in the current workspace.
|
|
The vendor media type documents the row-level trust and publication contract.
|
|
responses:
|
|
'200':
|
|
description: Rendered review register page
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
application/vnd.tenantpilot.review-register+json:
|
|
schema:
|
|
$ref: '#/components/schemas/ReviewRegisterPage'
|
|
'404':
|
|
description: Workspace context is missing or the viewer is not entitled to the relevant scope
|
|
/admin/t/{tenant}/evidence/{snapshot}:
|
|
get:
|
|
summary: Tenant-scoped evidence snapshot detail
|
|
parameters:
|
|
- name: tenant
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: snapshot
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
responses:
|
|
'200':
|
|
description: Rendered evidence snapshot detail page
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
application/vnd.tenantpilot.evidence-snapshot-detail+json:
|
|
schema:
|
|
$ref: '#/components/schemas/EvidenceSnapshotDetailPage'
|
|
'403':
|
|
description: Viewer is in tenant scope but lacks the required manage capability for actions
|
|
'404':
|
|
description: Snapshot is not visible because it does not exist or tenant entitlement is missing
|
|
/admin/t/{tenant}/reviews/{review}:
|
|
get:
|
|
summary: Tenant-scoped review detail
|
|
parameters:
|
|
- name: tenant
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: review
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
responses:
|
|
'200':
|
|
description: Rendered tenant review detail page
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
application/vnd.tenantpilot.tenant-review-detail+json:
|
|
schema:
|
|
$ref: '#/components/schemas/TenantReviewDetailPage'
|
|
'403':
|
|
description: Viewer is in tenant scope but lacks the required manage capability for actions
|
|
'404':
|
|
description: Review is not visible because it does not exist or tenant entitlement is missing
|
|
/admin/t/{tenant}/review-packs/{pack}:
|
|
get:
|
|
summary: Tenant-scoped review pack detail
|
|
parameters:
|
|
- name: tenant
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: pack
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
responses:
|
|
'200':
|
|
description: Rendered review pack detail page
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
application/vnd.tenantpilot.review-pack-detail+json:
|
|
schema:
|
|
$ref: '#/components/schemas/ReviewPackDetailPage'
|
|
'403':
|
|
description: Viewer is in tenant scope but lacks the required manage capability for actions
|
|
'404':
|
|
description: Review pack is not visible because it does not exist or tenant entitlement is missing
|
|
components:
|
|
schemas:
|
|
ArtifactTruthSummary:
|
|
type: object
|
|
required:
|
|
- primaryLabel
|
|
- contentState
|
|
- freshnessState
|
|
- actionability
|
|
properties:
|
|
primaryLabel:
|
|
type: string
|
|
primaryExplanation:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
contentState:
|
|
type: string
|
|
freshnessState:
|
|
type: string
|
|
enum:
|
|
- current
|
|
- stale
|
|
- unknown
|
|
publicationReadiness:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
enum:
|
|
- publishable
|
|
- internal_only
|
|
- blocked
|
|
actionability:
|
|
type: string
|
|
enum:
|
|
- none
|
|
- optional
|
|
- required
|
|
nextActionLabel:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
nextActionUrl:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
diagnosticLabel:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
Badge:
|
|
type: object
|
|
required:
|
|
- label
|
|
properties:
|
|
label:
|
|
type: string
|
|
color:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
icon:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
EvidenceOverviewRow:
|
|
type: object
|
|
required:
|
|
- tenantName
|
|
- tenantId
|
|
- snapshotId
|
|
- completenessState
|
|
- artifactTruth
|
|
- freshness
|
|
- nextStep
|
|
properties:
|
|
tenantName:
|
|
type: string
|
|
tenantId:
|
|
type: integer
|
|
snapshotId:
|
|
type: integer
|
|
completenessState:
|
|
type: string
|
|
generatedAt:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
format: date-time
|
|
missingDimensions:
|
|
type: integer
|
|
staleDimensions:
|
|
type: integer
|
|
artifactTruth:
|
|
$ref: '#/components/schemas/ArtifactTruthSummary'
|
|
freshness:
|
|
$ref: '#/components/schemas/Badge'
|
|
nextStep:
|
|
type: string
|
|
viewUrl:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
ReviewRegisterRow:
|
|
type: object
|
|
required:
|
|
- tenantName
|
|
- tenantId
|
|
- reviewId
|
|
- status
|
|
- completenessState
|
|
- artifactTruth
|
|
- publication
|
|
- nextStep
|
|
properties:
|
|
tenantName:
|
|
type: string
|
|
tenantId:
|
|
type: integer
|
|
reviewId:
|
|
type: integer
|
|
status:
|
|
type: string
|
|
completenessState:
|
|
type: string
|
|
generatedAt:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
format: date-time
|
|
publishedAt:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
format: date-time
|
|
artifactTruth:
|
|
$ref: '#/components/schemas/ArtifactTruthSummary'
|
|
publication:
|
|
$ref: '#/components/schemas/Badge'
|
|
nextStep:
|
|
type: string
|
|
viewUrl:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
EvidenceOverviewPage:
|
|
type: object
|
|
required:
|
|
- rows
|
|
properties:
|
|
rows:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/EvidenceOverviewRow'
|
|
ReviewRegisterPage:
|
|
type: object
|
|
required:
|
|
- rows
|
|
properties:
|
|
rows:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/ReviewRegisterRow'
|
|
EvidenceSnapshotDetailPage:
|
|
type: object
|
|
required:
|
|
- recordId
|
|
- tenantId
|
|
- completenessState
|
|
- artifactTruth
|
|
properties:
|
|
recordId:
|
|
type: integer
|
|
tenantId:
|
|
type: integer
|
|
status:
|
|
type: string
|
|
completenessState:
|
|
type: string
|
|
generatedAt:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
format: date-time
|
|
artifactTruth:
|
|
$ref: '#/components/schemas/ArtifactTruthSummary'
|
|
linkedReviewUrl:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
linkedRunUrl:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
TenantReviewDetailPage:
|
|
type: object
|
|
required:
|
|
- recordId
|
|
- tenantId
|
|
- status
|
|
- completenessState
|
|
- artifactTruth
|
|
properties:
|
|
recordId:
|
|
type: integer
|
|
tenantId:
|
|
type: integer
|
|
status:
|
|
type: string
|
|
completenessState:
|
|
type: string
|
|
generatedAt:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
format: date-time
|
|
publishedAt:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
format: date-time
|
|
artifactTruth:
|
|
$ref: '#/components/schemas/ArtifactTruthSummary'
|
|
linkedEvidenceUrl:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
linkedPackUrl:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
ReviewPackDetailPage:
|
|
type: object
|
|
required:
|
|
- recordId
|
|
- tenantId
|
|
- status
|
|
- artifactTruth
|
|
properties:
|
|
recordId:
|
|
type: integer
|
|
tenantId:
|
|
type: integer
|
|
status:
|
|
type: string
|
|
generatedAt:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
format: date-time
|
|
expiresAt:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
format: date-time
|
|
artifactTruth:
|
|
$ref: '#/components/schemas/ArtifactTruthSummary'
|
|
linkedReviewUrl:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
linkedEvidenceUrl:
|
|
type:
|
|
- string
|
|
- 'null' |