Add Optional `#Evidence` type to `#AssessmentLog`

[jpower432]

Is your feature request related to a problem?

The evidence chain (EvaluationLog → EnforcementLog → AuditLog) traces across logs, but there is no way to record what specifically the evaluator examined within the target during an assessment.

AssessmentLog records pass/fail with a message, but not I consulted THIS specific resource at THIS time. This means consumers like SARIF converters cannot populate file locations effectively, and auditors cannot verify what data sources the evaluator actually consulted without requesting supplementary evidence.

Describe the solution you'd like

Add a #Provenance type and optional field to #AssessmentLog in evaluationlog.cue:

Example

  #Provenance: {
      // address identifies what was consulted (file path, API endpoint, ARN, image ref, etc.)
      address:   string
      // collected is the timestamp when the data was acquired
      collected: #Datetime @go(Collected)
      // observed is the relevant content extracted
      observed?: string
  }

Three fields (two required, one optional), modality-neutral -- works for file scans, API checks, container scans, cloud config, physical audits, and interviews.

On #AssessmentLog:
The field is optional and backward-compatible.
provenance?: [#Provenance, ...#Provenance] @go(Provenance,type=[]Provenance)

Describe alternatives you've considered

Extensive naming exploration rejected 11 alternatives:

• #Observation — collides with #ResultType: "Observation" enum value in auditlog.cue
• #Subject — in OSCAL, subject means the component (inventory item instance) being assessed (equivalent to Gemara's target)
• #Evidence — already exists on #AuditResult for macro-level log references
• #Resource — already exists as a type (#Entity extension)
• #Source — source field already exists on #Mapping in mappingdocument.cue
• #Sample — implies statistical sampling methodology
• #Examination — synonym/subset of Assessment and Evaluation

Success Criteria

• Criterion 1: #Provenance type and provenance? field on #AssessmentLog are added to evaluationlog.cue and pass CUE validation
• Criterion 2: Existing EvaluationLog YAML documents validate without changes (backward-compatible)
• Criterion 3: The backward compatibility check (test/compat_test.go) passes with the new field
• Criterion 4: go-gemara can generate types from the updated schema and round-trip provenance data through YAML serialization

Additional context

assessment-logs:
    - requirement:
        reference-id: osps-baseline
        entry-id: OSPS-AC-01.01
      description: "MFA enforcement check"
      result: Passed
      message: "MFA is enabled for all organization members"
      provenance:
        - address: "https://api.github.com/orgs/myorg/settings"
          collected: "2025-08-22T16:02:00Z"
          observed: '{"two_factor_requirement_enabled": true}'
        - address: "https://api.github.com/orgs/myorg/members?filter=2fa_disabled"
          collected: "2025-08-22T16:02:01Z"
          observed: "[]"

Rel #23

[jpower432]

@eddie-knight Exploring an idea I would like your take on.

I worked a bit on a prototype for SARIF conversation I can share. A byproduct is allowing better support for the SARIF Region structure, but at the same time not tying the schema to static analysis use cases.

[eddie-knight]

I like the direction here. No issues I can see at first glance. I'd like to talk through it more on Thursday's call to make sure we think through any potential gaps or edge cases.

[jpower432]

cc @trevor-vaughan Tagging you for thoughts on the Evidence alternative

We already have an Evidence object (part of an experimental schemas so can be changed):

// Evidence records a specific data source consulted during an audit
#Evidence: {
	// id uniquely identifies this evidence
	id?: string

	// type categorizes the kind of evidence
	type: #EvidenceType

	// collected is the timestamp when the evidence was gathered
	collected: #Datetime @go(Collected)

	// location references the artifact containing this evidence
	location: #ArtifactMapping

	// description explains what this evidence represents
	description?: string
}

I had considered reusing this object and I thought about this alternative more and this is the conclusion I came to:

If we think of EvaluationLog and EnforcementLog as assertions with varying degrees of verifiability (machine-generated assertions that say "I checked these things and here's what I found") then fields like Provenance increase that verifiability. So when does an assertion become evidence? When an auditor cites it to support a conclusion in a specific engagement expressed in AuditLog. That's exactly what #Evidence is meant to AuditResult capture.

[jpower432]

We have decided on #Evidence with Provenance as a type.

Steps:

1. ADR PR
2. Schema PR if approved

[eddie-knight]

+1

We'll allow 0+ evidence entries on the assessment log, and the evidence itself will contain the option to provide a location/address for the body of the evidence or a payload containing the body of the evidence. The #Evidence object will be reused between here and the Audit layer.