• ADR: 0022
  • Proposal Author(s): @jpower432, @eddie-knight
  • Status: Accepted

Context

Gemara’s measurement layers produce opinions, structured conclusions about the state of a target. An EvaluationLog is a tool’s opinion: “based on what I observed, this control passes or fails.” An AuditLog is an auditor’s opinion: “based on the evidence I reviewed, this control is effective or not.” Both opinions are rooted in evidence, the data that was actually observed that helped inform the actual conclusion. The tool sees it firsthand (an API response, a file, a config dump). The auditor sees it through the tool’s record. Different proximity to the raw data, same root.

Currently, the evidence root is invisible. An AssessmentLog records a pass/fail result with a message, but not “I consulted this specific resource at this time.” The tool’s opinion exists without a record of what it was rooted in, limiting downstream consumers of the log.

Action

Reshape the existing #Evidence type in the experimental auditlog.cue to serve both the evaluation layer (AssessmentLog) and the audit layer (AuditLog). The #Evidence type captures what was cited to support an opinion for a specific activity, raw data for the tool, evaluation and enforcement artifacts for the auditor.

#Evidence: {
    // id uniquely identifies this evidence
    id?: string

    // type categorizes the kind of evidence (open enum)
    type: #EvidenceType

    // collected is the timestamp when the evidence was gathered
    "collected-at": #Datetime

    // address identifies where the evidence can be found
    address?: string

    // payload is the raw evidence data collected
    payload?: _

    // digest is a hash of the evidence content at collection time for integrity verification
    // Enables verification that mutable-address evidence (S3 objects, HTTP URLs, API responses) has not changed since the tool observed it.
    // Not needed for content-addressable systems (OCI, git) or inline payloads.
    digest?: string

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

#EvidenceType remains an open enum. Recommended values include artifact types already known to Gemara (e.g., EvaluationLog, EnforcementLog) plus categories for common evidence forms like provenance.

Changes to the Assessment Log:

#AssessmentLog: {
    // ... existing fields ...

    // evidence records the raw data cited to support this assessment's opinion
    evidence?: [#Evidence, ...#Evidence]
}

The field is optional (one or more when present) to maintain backward compatibility with existing EvaluationLog documents.

Consequences

Positive

  • Assessment logs can record exactly what the tool consulted, when, and what was observed, making the root of the tool’s opinion inspectable.
  • The address field enables SARIF converters to populate PhysicalLocation and Region with file paths and line numbers from evidence data.
  • address as a plain string works for file paths, API endpoints, ARNs, container image references, physical locations, and any other evidence source.

Negative

Embedding raw evidence via the payload field can make assessment logs large. It is the evaluator’s responsibility to manage payload size, trim sensitive data, and ensure evidence does not cross trust boundaries inappropriately.

Alternatives Considered

Separate #Provenance type

A standalone #Provenance type on #AssessmentLog with fields for address, collected, and observed. This was the original proposal in issue #417.

Rejected because: Both layers produce opinions rooted in evidence. The tool cites raw data to support its opinion. The auditor cites evaluation artifacts to support theirs. Introducing a separate type creates an artificial distinction when the relationship (opinion rooted in evidence) is the same at both layers.