ahmido
e7c9b4b853
## Summary - add shared governance artifact truth presentation and badge taxonomy - integrate artifact-truth messaging across baseline, evidence, tenant review, review pack, and operation run surfaces - add focused regression coverage and spec artifacts for artifact truth semantics ## Testing - not run in this step Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #188
409 lines
11 KiB
YAML
409 lines
11 KiB
YAML
openapi: 3.1.0
|
|
info:
|
|
title: Governance Artifact Truth Internal Contract
|
|
version: 0.1.0
|
|
summary: Internal planning contract for Spec 158 operator-surface read models.
|
|
description: |
|
|
This contract documents the normalized truth-envelope expected by the first
|
|
implementation slice for baseline snapshots, evidence snapshots, tenant
|
|
reviews, review packs, and artifact-targeted operation runs. These paths map
|
|
to existing Filament surfaces and internal action handlers; they are not a
|
|
commitment to a public JSON API.
|
|
servers:
|
|
- url: /admin
|
|
paths:
|
|
/baseline-snapshots:
|
|
get:
|
|
summary: List workspace baseline snapshots with normalized truth summaries
|
|
operationId: listBaselineSnapshotsWithTruth
|
|
responses:
|
|
'200':
|
|
description: Baseline snapshot list rows
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ArtifactCollectionResponse'
|
|
/baseline-snapshots/{snapshotId}:
|
|
get:
|
|
summary: Read one workspace baseline snapshot with truth envelope and diagnostics
|
|
operationId: viewBaselineSnapshotWithTruth
|
|
parameters:
|
|
- $ref: '#/components/parameters/SnapshotId'
|
|
responses:
|
|
'200':
|
|
description: Baseline snapshot detail
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ArtifactDetailResponse'
|
|
/evidence/overview:
|
|
get:
|
|
summary: List canonical workspace evidence rows limited to entitled tenants
|
|
operationId: listEvidenceOverviewWithTruth
|
|
parameters:
|
|
- in: query
|
|
name: tenant_id
|
|
schema:
|
|
type: integer
|
|
required: false
|
|
responses:
|
|
'200':
|
|
description: Canonical evidence overview rows
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ArtifactCollectionResponse'
|
|
/t/{tenantId}/evidence:
|
|
get:
|
|
summary: List tenant evidence snapshots with truth summaries
|
|
operationId: listEvidenceSnapshotsWithTruth
|
|
parameters:
|
|
- $ref: '#/components/parameters/TenantId'
|
|
responses:
|
|
'200':
|
|
description: Evidence snapshot list rows
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ArtifactCollectionResponse'
|
|
/t/{tenantId}/evidence/{snapshotId}:
|
|
get:
|
|
summary: Read one evidence snapshot with truth envelope, per-dimension state, and diagnostics
|
|
operationId: viewEvidenceSnapshotWithTruth
|
|
parameters:
|
|
- $ref: '#/components/parameters/TenantId'
|
|
- $ref: '#/components/parameters/SnapshotId'
|
|
responses:
|
|
'200':
|
|
description: Evidence snapshot detail
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ArtifactDetailResponse'
|
|
/reviews:
|
|
get:
|
|
summary: List canonical review register rows limited to entitled tenants
|
|
operationId: listReviewRegisterWithTruth
|
|
parameters:
|
|
- in: query
|
|
name: tenant_id
|
|
schema:
|
|
type: integer
|
|
required: false
|
|
responses:
|
|
'200':
|
|
description: Canonical review register rows
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ArtifactCollectionResponse'
|
|
/t/{tenantId}/reviews:
|
|
get:
|
|
summary: List tenant reviews with lifecycle, completeness, and publication truth
|
|
operationId: listTenantReviewsWithTruth
|
|
parameters:
|
|
- $ref: '#/components/parameters/TenantId'
|
|
responses:
|
|
'200':
|
|
description: Tenant review list rows
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ArtifactCollectionResponse'
|
|
/t/{tenantId}/reviews/{reviewId}:
|
|
get:
|
|
summary: Read one tenant review with truth envelope and blocker explanations
|
|
operationId: viewTenantReviewWithTruth
|
|
parameters:
|
|
- $ref: '#/components/parameters/TenantId'
|
|
- $ref: '#/components/parameters/ReviewId'
|
|
responses:
|
|
'200':
|
|
description: Tenant review detail
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ArtifactDetailResponse'
|
|
/t/{tenantId}/review-packs:
|
|
get:
|
|
summary: List review packs with lifecycle and provenance truth
|
|
operationId: listReviewPacksWithTruth
|
|
parameters:
|
|
- $ref: '#/components/parameters/TenantId'
|
|
responses:
|
|
'200':
|
|
description: Review-pack list rows
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ArtifactCollectionResponse'
|
|
/t/{tenantId}/review-packs/{packId}:
|
|
get:
|
|
summary: Read one review pack with truth envelope, provenance, and diagnostics
|
|
operationId: viewReviewPackWithTruth
|
|
parameters:
|
|
- $ref: '#/components/parameters/TenantId'
|
|
- $ref: '#/components/parameters/PackId'
|
|
responses:
|
|
'200':
|
|
description: Review-pack detail
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ArtifactDetailResponse'
|
|
/operations/{runId}:
|
|
get:
|
|
summary: Read canonical artifact-targeted run detail with normalized artifact result
|
|
operationId: viewArtifactRunWithTruth
|
|
parameters:
|
|
- $ref: '#/components/parameters/RunId'
|
|
responses:
|
|
'200':
|
|
description: Operation-run detail
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ArtifactRunDetailResponse'
|
|
components:
|
|
parameters:
|
|
TenantId:
|
|
in: path
|
|
name: tenantId
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
SnapshotId:
|
|
in: path
|
|
name: snapshotId
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
ReviewId:
|
|
in: path
|
|
name: reviewId
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
PackId:
|
|
in: path
|
|
name: packId
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
RunId:
|
|
in: path
|
|
name: runId
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
schemas:
|
|
ArtifactCollectionResponse:
|
|
type: object
|
|
required:
|
|
- rows
|
|
properties:
|
|
rows:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/ArtifactSummaryRow'
|
|
ArtifactDetailResponse:
|
|
type: object
|
|
required:
|
|
- artifact
|
|
- truth
|
|
properties:
|
|
artifact:
|
|
type: object
|
|
additionalProperties: true
|
|
truth:
|
|
$ref: '#/components/schemas/ArtifactTruthEnvelope'
|
|
diagnostics:
|
|
type: object
|
|
additionalProperties: true
|
|
ArtifactRunDetailResponse:
|
|
allOf:
|
|
- $ref: '#/components/schemas/ArtifactDetailResponse'
|
|
- type: object
|
|
properties:
|
|
run:
|
|
type: object
|
|
additionalProperties: true
|
|
ArtifactSummaryRow:
|
|
type: object
|
|
required:
|
|
- artifactKey
|
|
- artifactFamily
|
|
- truth
|
|
properties:
|
|
artifactKey:
|
|
type: string
|
|
artifactFamily:
|
|
type: string
|
|
enum:
|
|
- baseline_snapshot
|
|
- evidence_snapshot
|
|
- tenant_review
|
|
- review_pack
|
|
- artifact_run
|
|
displayTitle:
|
|
type: string
|
|
tenantName:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
truth:
|
|
$ref: '#/components/schemas/ArtifactTruthEnvelope'
|
|
ArtifactTruthEnvelope:
|
|
type: object
|
|
required:
|
|
- artifactFamily
|
|
- artifactExistence
|
|
- contentState
|
|
- freshnessState
|
|
- supportState
|
|
- actionability
|
|
- primaryLabel
|
|
properties:
|
|
artifactFamily:
|
|
type: string
|
|
executionOutcome:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
enum:
|
|
- pending
|
|
- succeeded
|
|
- partially_succeeded
|
|
- blocked
|
|
- failed
|
|
- null
|
|
artifactExistence:
|
|
type: string
|
|
enum:
|
|
- not_created
|
|
- historical_only
|
|
- created
|
|
- created_but_not_usable
|
|
contentState:
|
|
type: string
|
|
enum:
|
|
- trusted
|
|
- partial
|
|
- missing_input
|
|
- metadata_only
|
|
- reference_only
|
|
- empty
|
|
- unsupported
|
|
freshnessState:
|
|
type: string
|
|
enum:
|
|
- current
|
|
- stale
|
|
- unknown
|
|
publicationReadiness:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
enum:
|
|
- not_applicable
|
|
- internal_only
|
|
- publishable
|
|
- blocked
|
|
- null
|
|
supportState:
|
|
type: string
|
|
enum:
|
|
- normal
|
|
- limited_support
|
|
actionability:
|
|
type: string
|
|
enum:
|
|
- none
|
|
- optional
|
|
- required
|
|
primaryLabel:
|
|
type: string
|
|
primaryExplanation:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
reason:
|
|
$ref: '#/components/schemas/ArtifactTruthCause'
|
|
nextAction:
|
|
$ref: '#/components/schemas/ArtifactTruthNextAction'
|
|
dimensions:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/ArtifactTruthDimension'
|
|
ArtifactTruthDimension:
|
|
type: object
|
|
required:
|
|
- axis
|
|
- state
|
|
- label
|
|
- classification
|
|
properties:
|
|
axis:
|
|
type: string
|
|
enum:
|
|
- execution_outcome
|
|
- artifact_existence
|
|
- content_fidelity
|
|
- data_freshness
|
|
- publication_readiness
|
|
- support_maturity
|
|
- operator_actionability
|
|
state:
|
|
type: string
|
|
label:
|
|
type: string
|
|
classification:
|
|
type: string
|
|
enum:
|
|
- primary
|
|
- secondary
|
|
- diagnostic
|
|
badgeDomain:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
badgeState:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
ArtifactTruthCause:
|
|
type: object
|
|
properties:
|
|
reasonCode:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
operatorLabel:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
shortExplanation:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
diagnosticCode:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
nextSteps:
|
|
type: array
|
|
items:
|
|
type: string
|
|
ArtifactTruthNextAction:
|
|
type: object
|
|
properties:
|
|
label:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
url:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
required:
|
|
type: boolean |