1// SPDX-License-Identifier: Apache-2.0
  2
  3// Schema lifecycle: experimental | stable | deprecated
  4@status("experimental")
  5package gemara
  6
  7import "list"
  8
  9@go(gemara)
 10
 11// AuditLog records results from an audit performed against a target resource
 12#AuditLog: {
 13	#Log
 14	metadata: type: "AuditLog"
 15
 16	// owner defines the RACI roles responsible for managing the audit
 17	owner?: #RACI @go(Owner)
 18
 19	// summary provides the high-level conclusion
 20	summary: string
 21
 22	// criteria defines the acceptable state for the audited resource
 23	criteria: [#ArtifactMapping, ...#ArtifactMapping]
 24
 25	// results records audit results against the criteria
 26	results: [#AuditResult, ...#AuditResult] @go(Results,type=[]*AuditResult)
 27
 28	if results != _|_ {
 29		_uniqueResultIds: {for i, r in results {(r.id): i}}
 30		let _validCriteriaIds = [for c in criteria {c."reference-id"}]
 31
 32		// Unify the valid ID list with a list.Contains constraint to require each result scores against declared criteria
 33		for i, r in results {
 34			_criteriaValidation: "\(i)": _validCriteriaIds & list.Contains(r."criteria-reference"."reference-id")
 35		}
 36	}
 37}
 38
 39// ResultType classifies the nature of an audit result
 40#ResultType: "Gap" | "Finding" | "Observation" | "Strength" @go(-)
 41
 42// AuditResult records a single result with supporting evidence and recommendations.
 43#AuditResult: {
 44	// id uniquely identifies this result
 45	id: string
 46
 47	// title describes this result at a glance
 48	title: string
 49
 50	// type classifies the nature of this result
 51	type: #ResultType
 52
 53	// description explains the result in detail
 54	description: string
 55
 56	// criteria-reference maps this result to specific criteria entries
 57	"criteria-reference": #MultiEntryMapping @go(CriteriaReference)
 58
 59	// evidence records the data sources that support this result
 60	evidence?: [#Evidence, ...#Evidence] @go(Evidence)
 61
 62	// recommendations records corrective actions for this result
 63	recommendations?: [#Recommendation, ...#Recommendation] @go(Recommendations)
 64}
 65
 66// Recommendation provides a corrective action for an audit result
 67#Recommendation: {
 68	// id uniquely identifies this recommendation
 69	id?: string
 70
 71	// text describes the recommended corrective action
 72	text: string
 73
 74	// required indicates whether this recommendation is a mandatory corrective action
 75	required: *false | bool
 76}
 77
 78// Evidence records what was cited to support an opinion for a specific activity:
 79// raw data for the evaluation layer, evaluation and enforcement artifacts for the audit layer.
 80// At least one of payload or source MUST be present; an entry with neither is semantically incomplete.
 81#Evidence: {
 82	// id uniquely identifies this evidence
 83	id: string
 84
 85	// type categorizes the kind of evidence
 86	type: #EvidenceType
 87
 88	// collected-at is the timestamp when the evidence was gathered
 89	"collected-at": #Datetime @go(CollectedAt)
 90
 91	// payload is the raw evidence data collected inline
 92	payload?: _ @go(Payload,type=any)
 93
 94	// source identifies the artifact or system from which this evidence was collected
 95	source?: #EvidenceMapping @go(Source)
 96
 97	// description explains what this evidence represents
 98	description?: string
 99}
100
101// EvidenceType categorizes the kind of evidence. It remains an open enum:
102// recommended values include artifact types already known to Gemara (e.g.
103// EvaluationLog, EnforcementLog) plus categories for common evidence forms.
104#EvidenceType: #ArtifactType | string @go(-)