1// SPDX-License-Identifier: Apache-2.0
  2
  3// Schema lifecycle: experimental | stable | deprecated
  4@gemara(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	evidence?: [#_EvidenceStrict, ...#_EvidenceStrict]
 62
 63	// recommendations records corrective actions for this result
 64	recommendations?: [#Recommendation, ...#Recommendation] @go(Recommendations)
 65}
 66
 67// Recommendation provides a corrective action for an audit result
 68#Recommendation: {
 69	// id uniquely identifies this recommendation
 70	id?: string
 71
 72	// text describes the recommended corrective action
 73	text: string
 74
 75	// required indicates whether this recommendation is a mandatory corrective action
 76	required: *false | bool @gemara(default=false)
 77}
 78
 79// Evidence records what was cited to support an opinion for a specific activity:
 80// raw data for the evaluation layer, evaluation and enforcement artifacts for the audit layer.
 81// At least one of payload or source MUST be present; an entry with neither is semantically incomplete.
 82#Evidence: {
 83	// id uniquely identifies this evidence
 84	id: string
 85
 86	// type categorizes the kind of evidence
 87	type: #EvidenceType
 88
 89	// collected-at is the timestamp when the evidence was gathered
 90	"collected-at": #Datetime @go(CollectedAt)
 91
 92	// payload is the raw evidence data collected inline
 93	payload?: _ @go(Payload,type=any)
 94
 95	// source identifies the artifact or system from which this evidence was collected
 96	source?: #EvidenceMapping @go(Source)
 97
 98	// description explains what this evidence represents
 99	description?: string
100}
101
102// _EvidenceStrict layers the "at least one of payload or source" rule on top of #Evidence
103#_EvidenceStrict: {
104	@go(-)
105} & #Evidence & {
106	payload?: _
107	if payload == _|_ {
108		source: #EvidenceMapping
109	}
110}
111
112// EvidenceType categorizes the kind of evidence. It remains an open enum:
113// recommended values include artifact types already known to Gemara (e.g.
114// EvaluationLog, EnforcementLog) plus categories for common evidence forms.
115#EvidenceType: #ArtifactType | string @go(-)