@mitre/hdf-schema 3.4.3 → 3.5.0

package/dist/go/hdf.go

@@ -21,6 +21,9 @@
 //
 //    hDFEvidencePackage, err := UnmarshalHDFEvidencePackage(bytes)
 //    bytes, err = hDFEvidencePackage.Marshal()
+//
+//    hDFRequirementChangeEvent, err := UnmarshalHDFRequirementChangeEvent(bytes)
+//    bytes, err = hDFRequirementChangeEvent.Marshal()
 
 package hdf
 
@@ -100,41 +103,59 @@ func (r *HDFEvidencePackage) Marshal() ([]byte, error) {
 	return json.Marshal(r)
 }
 
+func UnmarshalHDFRequirementChangeEvent(data []byte) (HDFRequirementChangeEvent, error) {
+	var r HDFRequirementChangeEvent
+	err := json.Unmarshal(data, &r)
+	return r, err
+}
+
+func (r *HDFRequirementChangeEvent) Marshal() ([]byte, error) {
+	return json.Marshal(r)
+}
+
 // The top level value containing all assessment results.
 type HDFResults struct {
-	// Information on the baselines that were evaluated, including findings.                                          
-	Baselines                                                                                  []EvaluatedBaseline    `json:"baselines"`
-	// The components that were assessed. Each component describes a system element (host,                            
-	// container, cloud resource, application, etc.) with optional identity, SBOM, and external                       
-	// references.                                                                                                    
-	Components                                                                                 []Component            `json:"components,omitempty"`
-	// Reserved for tool-specific data not defined in the HDF standard. Use this to preserve                          
-	// original tool output, auxiliary data, or custom metadata.                                                      
-	Extensions                                                                                 map[string]interface{} `json:"extensions,omitempty"`
-	// Information about the tool that generated this file.                                                           
-	Generator                                                                                  *Generator             `json:"generator,omitempty"`
-	// Unique identifier for this assessment run.                                                                     
-	ID                                                                                         *string                `json:"id,omitempty"`
-	// Cryptographic integrity information for verifying this file.                                                   
-	Integrity                                                                                  *Integrity             `json:"integrity,omitempty"`
-	// Reference to an hdf-plan document describing the assessment plan that produced these                           
-	// results. May be a relative path, absolute URI, or fragment identifier.                                         
-	PlanRef                                                                                    *string                `json:"planRef,omitempty"`
-	// Optional reference to automated remediation resources (Ansible playbooks, Terraform                            
-	// scripts, etc.) for fixing failing requirements found in this assessment.                                       
-	Remediation                                                                                *Remediation           `json:"remediation,omitempty"`
-	// Information about the test execution environment where the security tool was run.                              
-	// Distinct from targets (what is being tested).                                                                  
-	Runner                                                                                     *Runner                `json:"runner,omitempty"`
-	// Statistics for the assessment run, including duration and result counts.                                       
-	Statistics                                                                                 *Statistics            `json:"statistics,omitempty"`
-	// Reference to an hdf-system document describing the system under assessment. May be a                           
-	// relative path, absolute URI, or fragment identifier.                                                           
-	SystemRef                                                                                  *string                `json:"systemRef,omitempty"`
-	// When this assessment was executed.                                                                             
-	Timestamp                                                                                  *time.Time             `json:"timestamp,omitempty"`
-	// The security tool that produced the assessment data in this file.                                              
-	Tool                                                                                       *Tool                  `json:"tool,omitempty"`
+	// Information on the baselines that were evaluated, including findings.                                           
+	Baselines                                                                                   []EvaluatedBaseline    `json:"baselines"`
+	// The components that were assessed. Each component describes a system element (host,                             
+	// container, cloud resource, application, etc.) with optional identity, SBOM, and external                        
+	// references.                                                                                                     
+	Components                                                                                  []Component            `json:"components,omitempty"`
+	// Present ONLY on reconciled result sets: lineage recording the seed snapshot and event                           
+	// watermark this document was reassembled from (ADR-0005). Documents produced directly by a                       
+	// scan omit this field. When present, generator names the reconciling tool.                                       
+	Derivation                                                                                  *Derivation            `json:"derivation,omitempty"`
+	// Reserved for tool-specific data not defined in the HDF standard. Use this to preserve                           
+	// original tool output, auxiliary data, or custom metadata.                                                       
+	Extensions                                                                                  map[string]interface{} `json:"extensions,omitempty"`
+	// Optional references to external artifacts (CTI/STIX, BOMs, advisories, runbooks, or any                         
+	// URI-addressable artifact) relevant to this assessment as a whole. Inert context; see                            
+	// External_Reference.                                                                                             
+	ExternalReferences                                                                          []ExternalReference    `json:"externalReferences,omitempty"`
+	// Information about the tool that generated this file.                                                            
+	Generator                                                                                   *Generator             `json:"generator,omitempty"`
+	// Unique identifier for this assessment run.                                                                      
+	ID                                                                                          *string                `json:"id,omitempty"`
+	// Cryptographic integrity information for verifying this file.                                                    
+	Integrity                                                                                   *Integrity             `json:"integrity,omitempty"`
+	// Reference to an hdf-plan document describing the assessment plan that produced these                            
+	// results. May be a relative path, absolute URI, or fragment identifier.                                          
+	PlanRef                                                                                     *string                `json:"planRef,omitempty"`
+	// Optional reference to automated remediation resources (Ansible playbooks, Terraform                             
+	// scripts, etc.) for fixing failing requirements found in this assessment.                                        
+	Remediation                                                                                 *Remediation           `json:"remediation,omitempty"`
+	// Information about the test execution environment where the security tool was run.                               
+	// Distinct from targets (what is being tested).                                                                   
+	Runner                                                                                      *Runner                `json:"runner,omitempty"`
+	// Statistics for the assessment run, including duration and result counts.                                        
+	Statistics                                                                                  *Statistics            `json:"statistics,omitempty"`
+	// Reference to an hdf-system document describing the system under assessment. May be a                            
+	// relative path, absolute URI, or fragment identifier.                                                            
+	SystemRef                                                                                   *string                `json:"systemRef,omitempty"`
+	// When this assessment was executed.                                                                              
+	Timestamp                                                                                   *time.Time             `json:"timestamp,omitempty"`
+	// The security tool that produced the assessment data in this file.                                               
+	Tool                                                                                        *Tool                  `json:"tool,omitempty"`
 }
 
 // Information on a baseline that was evaluated, including any findings.
@@ -175,6 +196,10 @@ type EvaluatedBaseline struct {
 	Copyright                                                                                  *string                `json:"copyright,omitempty"`
 	// The email address or other contact information of the copyright holder(s).                                     
 	CopyrightEmail                                                                             *string                `json:"copyrightEmail,omitempty"`
+	// Optional references to external artifacts relevant to this baseline (CTI/STIX,                                 
+	// advisories, source catalogs, or any URI-addressable artifact). Travels with the baseline                       
+	// definition. Inert context; see External_Reference.                                                             
+	ExternalReferences                                                                         []ExternalReference    `json:"externalReferences,omitempty"`
 	// Optional key-value labels for flexible grouping. Well-known keys: system, component,                           
 	// environment, region, team. Values must be strings.                                                             
 	Labels                                                                                     map[string]string      `json:"labels,omitempty"`
@@ -217,6 +242,88 @@ type Dependency struct {
 	URL                                                           *string `json:"url,omitempty"`
 }
 
+// A generalized reference to any external artifact by identity and/or location, modeled on the STIX
+// 2.1 `external_references` common property. Purpose-agnostic: cite a CVE, an ATT&CK technique, a
+// STIX bundle/object, a BOM, a runbook, or any vendor artifact — including kinds with no dedicated
+// HDF reference category. `sourceName` names the system; `externalId` cites by id within that
+// system; `href` locates it. `sourceName` + `externalId` is equivalently a URN
+// (`urn:<sourceName>:<externalId>`, RFC 8141), so the by-identity and by-location forms stay
+// interconvertible. A reference is inert context: it overrides nothing, so it carries only
+// lightweight optional `addedBy`/`addedAt` attribution, never override machinery.
+type ExternalReference struct {
+	// When this reference was attached (RFC 3339 / trimmed-UTC per HDF timestamp convention).                         
+	AddedAt                                                                                     *time.Time             `json:"addedAt,omitempty"`
+	// Who attached this reference. Lightweight, flat attribution — a reference overrides                              
+	// nothing, so it has no chaining/superseding/disposition.                                                         
+	AddedBy                                                                                     *Identity              `json:"addedBy,omitempty"`
+	// Integrity hash of the referenced artifact. Reuses the HDF `Checksum` primitive (not STIX                        
+	// `hashes`). Meaningful only with a retrievable `href`.                                                           
+	Checksum                                                                                    *Checksum              `json:"checksum,omitempty"`
+	// Human-readable description of what is referenced. Satisfies the at-least-one rule on its                        
+	// own when neither id nor href is available.                                                                      
+	Description                                                                                 *string                `json:"description,omitempty"`
+	// Optional lossless embedded copy of the referenced artifact — the raw STIX object, EPSS                          
+	// record, advisory, or annotation payload — preserved verbatim. Composes with                                     
+	// `href`/`externalId` (which point at the artifact) and `checksum` (which ties the copy to                        
+	// the source): a single entry can both point and embed. HDF stays payload-agnostic — the                          
+	// content is carried untouched, never normalized into HDF fields — so this does not                               
+	// duplicate the source ontology (e.g. STIX rides here unchanged).                                                 
+	Document                                                                                    map[string]interface{} `json:"document,omitempty"`
+	// Identifier of the artifact within `sourceName` (e.g., 'CVE-2021-44228' for source 'cve',                        
+	// 'T1059' for 'mitre-att&ck'). Cite by id without needing a URL. Together with `sourceName`                       
+	// this is a URN.                                                                                                  
+	ExternalID                                                                                  *string                `json:"externalId,omitempty"`
+	// Location of the artifact. `uri-reference` (not `uri`) so a bare internal                                        
+	// `#fragment`/`#uuid` reference is expressible alongside absolute URLs.                                           
+	// `checksum`/`mediaType` apply only to a retrievable `href`.                                                      
+	Href                                                                                        *string                `json:"href,omitempty"`
+	// Open token classifying the referenced/embedded payload, turning a bare reference into an                        
+	// enrichment envelope. Deliberately open (like `sourceName`/`rel`), not a closed enum.                            
+	// Documented starter vocabulary: 'threat-intel' (STIX/CTI object), 'annotation' (human                            
+	// triage note), 'exploitation' (EPSS/KEV signal carried as context), 'advisory'                                   
+	// (vendor/security advisory). Use the `x-` prefix for custom kinds.                                               
+	Kind                                                                                        *string                `json:"kind,omitempty"`
+	// IANA media type of the referenced artifact when retrievable (RFC 6838), e.g.,                                   
+	// 'application/json'. Meaningful only with `href`.                                                                
+	MediaType                                                                                   *string                `json:"mediaType,omitempty"`
+	// Open relationship token describing how this reference relates to the referencing object.                        
+	// Deliberately open (cf. OSCAL `rel` allow-other, RFC 8288 extension relations). Documented                       
+	// starter vocabulary: 'reference' (generic), 'definition' (defines the concept), 'evidence'                       
+	// (supporting evidence), 'investigate' (a live pivot to investigate), 'canonical' (the                            
+	// authoritative source).                                                                                          
+	Rel                                                                                         *string                `json:"rel,omitempty"`
+	// Name of the external system/source being referenced (e.g., 'cve', 'mitre-att&ck', 'stix',                       
+	// 'taxii', or any vendor label). Open string — not a closed enum. Use the `x-` prefix                             
+	// convention for custom/experimental sources, mirroring `bomType`.                                                
+	SourceName                                                                                  string                 `json:"sourceName"`
+}
+
+// Represents an identity that performed an action, such as capturing evidence or applying an
+// override.
+type Identity struct {
+	// Optional description of the identity or identity system, particularly useful when type is             
+	// 'other'.                                                                                              
+	Description                                                                                 *string      `json:"description,omitempty"`
+	// The identifier value. Example: 'user@example.com', 'jdoe', 'automated-scanner-01'.                    
+	Identifier                                                                                  string       `json:"identifier"`
+	// The type of identifier. Use 'email' for email addresses, 'username' for user accounts,                
+	// 'system' for deterministic non-interactive automation (CI jobs, cron, scanners), 'agent'              
+	// for an AI/LLM agent acting with autonomy — kept distinct from 'system' so auditors can                
+	// apply AI-specific scrutiny (e.g. 'an LLM proposed this' vs a deterministic job) and                   
+	// satisfy AI-source disclosure under frameworks like the EU AI Act and NIST AI RMF,                     
+	// 'simple' for basic string identifiers without additional classification, or 'other' for               
+	// custom identity systems.                                                                              
+	Type                                                                                        IdentityType `json:"type"`
+}
+
+// Cryptographic checksum for baseline integrity verification.
+type Checksum struct {
+	// The hash algorithm used for the checksum.              
+	Algorithm                                   HashAlgorithm `json:"algorithm"`
+	// The checksum value.                                    
+	Value                                       string        `json:"value"`
+}
+
 // Describes a group of requirements, such as those defined in a single file.
 type RequirementGroup struct {
 	// The unique identifier for the group. Example: the relative path to the file specifying         
@@ -277,14 +384,6 @@ type Integrity struct {
 	SignedBy                                    *string        `json:"signedBy,omitempty"`
 }
 
-// Cryptographic checksum for baseline integrity verification.
-type Checksum struct {
-	// The hash algorithm used for the checksum.              
-	Algorithm                                   HashAlgorithm `json:"algorithm"`
-	// The checksum value.                                    
-	Value                                       string        `json:"value"`
-}
-
 // A requirement that has been evaluated, including any findings.
 type EvaluatedRequirement struct {
 	// Packages affected by this vulnerability finding. Vulnerability-finding-scoped — see                              
@@ -309,6 +408,14 @@ type EvaluatedRequirement struct {
 	// riskAdjustment) or what remediation is being tracked (poam). Absent when no overrides or                         
 	// POAMs apply.                                                                                                     
 	Disposition                                                                                 *OverrideType           `json:"disposition,omitempty"`
+	// Checksum of this requirement's resolved effective posture, for per-control change                                
+	// detection in continuous monitoring. sha256 over the canonical JSON object with keys                              
+	// status, impact, disposition (in that order), holding the resolved effective status,                              
+	// resolved effective impact, and governing override type (null when nothing governs), with                         
+	// override expiry anchored to the document timestamp. Flips exactly when the operative                             
+	// status, impact, or disposition changes; stable under all other churn (result details,                            
+	// timestamps, tags). Optional; stamped by tooling (hdf convert, hdf amend apply).                                  
+	EffectiveChecksum                                                                           *Checksum               `json:"effectiveChecksum,omitempty"`
 	// The current effective impact score (0.0–1.0) after applying the most recent non-expired                          
 	// override with an impact field. Absent when no impact overrides apply; consumers should                           
 	// use the requirement's impact field in that case.                                                                 
@@ -368,6 +475,11 @@ type EvaluatedRequirement struct {
 	// AT, IR, MA families). Optional: when omitted, consumers may infer heuristically from                             
 	// family/id but should not assume a default.                                                                       
 	ControlType                                                                                 *ControlType            `json:"controlType,omitempty"`
+	// Optional references to external artifacts relevant to this requirement (CTI/STIX                                 
+	// correlation, advisories, control/definition sources, or any URI-addressable artifact).                           
+	// Applies to both baseline requirement definitions and evaluated requirements. Inert                               
+	// context; see External_Reference.                                                                                 
+	ExternalReferences                                                                          []ExternalReference     `json:"externalReferences,omitempty"`
 	// The set of references to external documents.                                                                     
 	Refs                                                                                        []Reference             `json:"refs,omitempty"`
 	// The title - is nullable.                                                                                         
@@ -514,24 +626,6 @@ type Evidence struct {
 	Type                                                                                      EvidenceType `json:"type"`
 }
 
-// Represents an identity that performed an action, such as capturing evidence or applying an
-// override.
-type Identity struct {
-	// Optional description of the identity or identity system, particularly useful when type is             
-	// 'other'.                                                                                              
-	Description                                                                                 *string      `json:"description,omitempty"`
-	// The identifier value. Example: 'user@example.com', 'jdoe', 'automated-scanner-01'.                    
-	Identifier                                                                                  string       `json:"identifier"`
-	// The type of identifier. Use 'email' for email addresses, 'username' for user accounts,                
-	// 'system' for deterministic non-interactive automation (CI jobs, cron, scanners), 'agent'              
-	// for an AI/LLM agent acting with autonomy — kept distinct from 'system' so auditors can                
-	// apply AI-specific scrutiny (e.g. 'an LLM proposed this' vs a deterministic job) and                   
-	// satisfy AI-source disclosure under frameworks like the EU AI Act and NIST AI RMF,                     
-	// 'simple' for basic string identifiers without additional classification, or 'other' for               
-	// custom identity systems.                                                                              
-	Type                                                                                        IdentityType `json:"type"`
-}
-
 // CISA Known Exploited Vulnerabilities (KEV) catalog status. When inKev=true, dateAdded and
 // dueDate carry the federal patching deadline.
 type Kev struct {
@@ -561,8 +655,11 @@ type PoamElement struct {
 	// Supporting evidence for this POA&M, such as documentation of compensating controls or               
 	// mitigation implementation.                                                                          
 	Evidence                                                                                   []Evidence  `json:"evidence,omitempty"`
-	// Optional expiration date for this POA&M requiring review/renewal. ISO 8601 format.                  
-	ExpiresAt                                                                                  *time.Time  `json:"expiresAt,omitempty"`
+	// Required deadline for this POA&M. A POA&M is a time-boxed acceptance of an open finding;            
+	// without a deadline it lets a failing requirement duck remediation indefinitely. Source a            
+	// real date (e.g. a remediation target or vendor-fix date) — never a wall-clock default.              
+	// ISO 8601 format.                                                                                    
+	ExpiresAt                                                                                  time.Time   `json:"expiresAt"`
 	// Detailed explanation of the plan, including what actions will be taken.                             
 	Explanation                                                                                string      `json:"explanation"`
 	// Optional array of milestones tracking progress toward completion.                                   
@@ -679,44 +776,49 @@ type SourceLocation struct {
 // status or impact must be set. Overrides change the effectiveStatus or impact of the requirement.
 // All overrides must have an expiration date to enforce periodic review.
 type StatusOverride struct {
-	// Timestamp when this override was applied. ISO 8601 format.                                               
-	AppliedAt                                                                                   time.Time       `json:"appliedAt"`
-	// Identity of who applied this override. For simple cases, use type 'simple' with just an                  
-	// identifier.                                                                                              
-	AppliedBy                                                                                   Identity        `json:"appliedBy"`
-	// Structured CVSS scoring data backing this override. Captures the rubric (which                           
-	// Environmental/Threat metrics the consumer modified, the recomputed score) used to justify                
-	// a riskAdjustment. For other override types this is optional context.                                     
-	Cvss                                                                                        *Cvss           `json:"cvss,omitempty"`
-	// Supporting evidence for this override, such as screenshots demonstrating manual                          
-	// verification for attestations.                                                                           
-	Evidence                                                                                    []Evidence      `json:"evidence,omitempty"`
-	// Timestamp when this override expires and must be reviewed/renewed. REQUIRED - no                         
-	// permanent overrides allowed. ISO 8601 format.                                                            
-	ExpiresAt                                                                                   time.Time       `json:"expiresAt"`
-	// Override to the requirement's impact score. At least one of status or impact must be set.                
-	Impact                                                                                      *ImpactOverride `json:"impact,omitempty"`
-	// Structured controlled-vocabulary classification for why this override applies.                           
-	// Complements (does not replace) the free-text 'reason' field. Most useful on falsePositive                
-	// and attestation overrides where the structured category enables filtering and lossless                   
-	// round-trip with VEX / OSCAL / FedRAMP DR. See the Justification primitive for the                        
-	// precedent vocabulary and rationale.                                                                      
-	Justification                                                                               *Justification  `json:"justification,omitempty"`
-	// SHA-256 checksum of the previous amendment in chronological order. Creates a                             
-	// tamper-evident chain of amendments (similar to blockchain). Null for the first amendment                 
-	// on a requirement.                                                                                        
-	PreviousChecksum                                                                            *Checksum       `json:"previousChecksum,omitempty"`
-	// Explanation for why this override was applied.                                                           
-	Reason                                                                                      string          `json:"reason"`
-	// Optional digital signature for enhanced trust and non-repudiation. Supports hardware                     
-	// security tokens (PKCS#11/PKCS#12), Yubikeys, GPG keys, passkeys, and other signing                       
-	// methods.                                                                                                 
-	Signature                                                                                   *Signature      `json:"signature,omitempty"`
-	// The new status this override sets for the requirement. Optional when only impact is being                
-	// overridden.                                                                                              
-	Status                                                                                      *ResultStatus   `json:"status,omitempty"`
-	// The type of override applied to this requirement.                                                        
-	Type                                                                                        OverrideType    `json:"type"`
+	// Timestamp when this override was applied. ISO 8601 format.                                                   
+	AppliedAt                                                                                   time.Time           `json:"appliedAt"`
+	// Identity of who applied this override. For simple cases, use type 'simple' with just an                      
+	// identifier.                                                                                                  
+	AppliedBy                                                                                   Identity            `json:"appliedBy"`
+	// Structured CVSS scoring data backing this override. Captures the rubric (which                               
+	// Environmental/Threat metrics the consumer modified, the recomputed score) used to justify                    
+	// a riskAdjustment. For other override types this is optional context.                                         
+	Cvss                                                                                        *Cvss               `json:"cvss,omitempty"`
+	// Supporting evidence for this override, such as screenshots demonstrating manual                              
+	// verification for attestations.                                                                               
+	Evidence                                                                                    []Evidence          `json:"evidence,omitempty"`
+	// Timestamp when this override expires and must be reviewed/renewed. REQUIRED - no                             
+	// permanent overrides allowed. ISO 8601 format.                                                                
+	ExpiresAt                                                                                   time.Time           `json:"expiresAt"`
+	// Optional references to the external artifacts behind this override (e.g. the STIX                            
+	// bundle/object or CTI feed motivating an E:A riskAdjustment). Inert context distinct from                     
+	// `evidence`; see External_Reference. Symmetric with Standalone_Override.externalReferences                    
+	// for the inline (results-embedded) override carrier.                                                          
+	ExternalReferences                                                                          []ExternalReference `json:"externalReferences,omitempty"`
+	// Override to the requirement's impact score. At least one of status or impact must be set.                    
+	Impact                                                                                      *ImpactOverride     `json:"impact,omitempty"`
+	// Structured controlled-vocabulary classification for why this override applies.                               
+	// Complements (does not replace) the free-text 'reason' field. Most useful on falsePositive                    
+	// and attestation overrides where the structured category enables filtering and lossless                       
+	// round-trip with VEX / OSCAL / FedRAMP DR. See the Justification primitive for the                            
+	// precedent vocabulary and rationale.                                                                          
+	Justification                                                                               *Justification      `json:"justification,omitempty"`
+	// SHA-256 checksum of the previous amendment in chronological order. Creates a                                 
+	// tamper-evident chain of amendments (similar to blockchain). Null for the first amendment                     
+	// on a requirement.                                                                                            
+	PreviousChecksum                                                                            *Checksum           `json:"previousChecksum,omitempty"`
+	// Explanation for why this override was applied.                                                               
+	Reason                                                                                      string              `json:"reason"`
+	// Optional digital signature for enhanced trust and non-repudiation. Supports hardware                         
+	// security tokens (PKCS#11/PKCS#12), Yubikeys, GPG keys, passkeys, and other signing                           
+	// methods.                                                                                                     
+	Signature                                                                                   *Signature          `json:"signature,omitempty"`
+	// The new status this override sets for the requirement. Optional when only impact is being                    
+	// overridden.                                                                                                  
+	Status                                                                                      *ResultStatus       `json:"status,omitempty"`
+	// The type of override applied to this requirement.                                                            
+	Type                                                                                        OverrideType        `json:"type"`
 }
 
 // An override to the requirement's impact score. The prior impact is the original result value or
@@ -1072,6 +1174,37 @@ type InputOverride struct {
 	Value                                                                                      interface{} `json:"value"`
 }
 
+// Derived-document lineage for a reconciled result set (an hdf-results produced by
+// applyChangeEvents rather than a scanner). Records exactly which seed and event horizon the
+// document represents so it can never masquerade as primary scan evidence. Conceptually PROV
+// qualified derivation: derived entity, used entity (seed), activity (event application),
+// generation time (asOf).
+type Derivation struct {
+	// The posture-as-of time of this reconciled view (RFC 3339, trimmed UTC) — the analog of           
+	// PROV's generatedAtTime.                                                                          
+	AsOf                                                                                      time.Time `json:"asOf"`
+	// Number of change events applied to the seed to produce this document.                            
+	EventsApplied                                                                             int64     `json:"eventsApplied"`
+	// The authoritative snapshot this document was reassembled from, pinned by content.                
+	Seed                                                                                      Seed      `json:"seed"`
+	// URI of the event-stream producer context whose events were applied (matches the events'          
+	// envelope source).                                                                                
+	Source                                                                                    string    `json:"source"`
+	// The event watermark: the highest per-key sequence number applied. Downstream precedence          
+	// rule: a full-scan document supersedes the reconciled view as of its scan time; between           
+	// scans, the reconciled document with the highest throughSequence is the current posture.          
+	ThroughSequence                                                                           int64     `json:"throughSequence"`
+}
+
+// The authoritative snapshot this document was reassembled from, pinned by content.
+type Seed struct {
+	// Checksum of the seed snapshot, REQUIRED: the derivation pins an immutable snapshot by         
+	// content, not just location.                                                                   
+	Checksum                                                                                Checksum `json:"checksum"`
+	// URI to the seed snapshot document (relative path or absolute URL).                            
+	URI                                                                                     string   `json:"uri"`
+}
+
 // Information about the tool that generated this HDF file.
 type Generator struct {
 	// The name of the software that produced this HDF file. Example: 'gosec-to-hdf'.       
@@ -1157,59 +1290,67 @@ type StatisticBlock struct {
 // The security tool that produced the assessment data represented in this HDF file. Aligns with
 // SARIF, OSCAL, and CycloneDX terminology.
 type Tool struct {
-	// The file format, if it is a recognized named format shared by multiple tools. Examples:         
-	// 'SARIF', 'XCCDF'. Omit for tool-specific formats where the tool name already implies the        
-	// format (Nessus XML, gosec JSON).                                                                
-	Format                                                                                     *string `json:"format,omitempty"`
-	// The name of the security tool that produced the data. Examples: 'gosec', 'Semgrep',             
-	// 'OpenSCAP', 'AWS Config', 'Nessus'. Omit if the tool cannot be identified.                      
-	Name                                                                                       *string `json:"name,omitempty"`
-	// Version of the source tool, if available in the tool's output. Example: '5.22.3'.               
-	Version                                                                                    *string `json:"version,omitempty"`
+	// The named format of the source data, when it follows a recognized format specification        
+	// with its own identity: an interchange format emitted by many tools ('SARIF', 'XCCDF',         
+	// 'OSCAL') or one of several named output formats a single tool produces ('FVDL',               
+	// 'exec-json', 'FPF'). Never a serialization structure — 'JSON', 'XML', and 'CSV' are           
+	// encodings, not formats. Omit for a tool's native output: an absent format means the           
+	// tool's own shape, and data arriving as a named format is converted by that format's           
+	// converter, which sets this field alongside the producing tool's name.                         
+	Format                                                                                   *string `json:"format,omitempty"`
+	// The name of the security tool that produced the data. Examples: 'gosec', 'Semgrep',           
+	// 'OpenSCAP', 'AWS Config', 'Nessus'. Omit if the tool cannot be identified.                    
+	Name                                                                                     *string `json:"name,omitempty"`
+	// Version of the source tool, if available in the tool's output. Example: '5.22.3'.             
+	Version                                                                                  *string `json:"version,omitempty"`
 }
 
 // Information on the set of requirements that can be assessed, including baseline metadata and
 // requirement definitions.
 type HDFBaseline struct {
-	// The set of dependencies this baseline depends on.                                                           
-	Depends                                                                                  []Dependency          `json:"depends,omitempty"`
-	// The tool that generated this file.                                                                          
-	Generator                                                                                *Generator            `json:"generator,omitempty"`
-	// A set of descriptions for the requirement groups.                                                           
-	Groups                                                                                   []RequirementGroup    `json:"groups,omitempty"`
-	// The input(s) or attribute(s) to be used in the run.                                                         
-	Inputs                                                                                   []Input               `json:"inputs,omitempty"`
-	// Cryptographic integrity information for verifying this baseline has not been tampered                       
-	// with.                                                                                                       
-	Integrity                                                                                *Integrity            `json:"integrity,omitempty"`
-	// Optional reference to automated remediation resources (Ansible playbooks, Terraform                         
-	// scripts, etc.) for implementing the security controls defined in this baseline.                             
-	Remediation                                                                              *Remediation          `json:"remediation,omitempty"`
-	// The set of requirements - contains no findings as the assessment has not yet occurred.                      
-	Requirements                                                                             []BaselineRequirement `json:"requirements"`
-	// The name - must be unique.                                                                                  
-	Name                                                                                     string                `json:"name"`
-	// The copyright holder(s).                                                                                    
-	Copyright                                                                                *string               `json:"copyright,omitempty"`
-	// The email address or other contact information of the copyright holder(s).                                  
-	CopyrightEmail                                                                           *string               `json:"copyrightEmail,omitempty"`
-	// Optional key-value labels for flexible grouping. Well-known keys: system, component,                        
-	// environment, region, team. Values must be strings.                                                          
-	Labels                                                                                   map[string]string     `json:"labels,omitempty"`
-	// The copyright license. Example: 'Apache-2.0'.                                                               
-	License                                                                                  *string               `json:"license,omitempty"`
-	// The maintainer(s).                                                                                          
-	Maintainer                                                                               *string               `json:"maintainer,omitempty"`
-	// The status. Example: 'loaded'.                                                                              
-	Status                                                                                   *string               `json:"status,omitempty"`
-	// The summary. Example: the Security Technical Implementation Guide (STIG) header.                            
-	Summary                                                                                  *string               `json:"summary,omitempty"`
-	// The set of supported platform targets.                                                                      
-	Supports                                                                                 []SupportedPlatform   `json:"supports,omitempty"`
-	// The title - should be human readable.                                                                       
-	Title                                                                                    *string               `json:"title,omitempty"`
-	// The version of the baseline.                                                                                
-	Version                                                                                  *string               `json:"version,omitempty"`
+	// The set of dependencies this baseline depends on.                                                             
+	Depends                                                                                    []Dependency          `json:"depends,omitempty"`
+	// The tool that generated this file.                                                                            
+	Generator                                                                                  *Generator            `json:"generator,omitempty"`
+	// A set of descriptions for the requirement groups.                                                             
+	Groups                                                                                     []RequirementGroup    `json:"groups,omitempty"`
+	// The input(s) or attribute(s) to be used in the run.                                                           
+	Inputs                                                                                     []Input               `json:"inputs,omitempty"`
+	// Cryptographic integrity information for verifying this baseline has not been tampered                         
+	// with.                                                                                                         
+	Integrity                                                                                  *Integrity            `json:"integrity,omitempty"`
+	// Optional reference to automated remediation resources (Ansible playbooks, Terraform                           
+	// scripts, etc.) for implementing the security controls defined in this baseline.                               
+	Remediation                                                                                *Remediation          `json:"remediation,omitempty"`
+	// The set of requirements - contains no findings as the assessment has not yet occurred.                        
+	Requirements                                                                               []BaselineRequirement `json:"requirements"`
+	// The name - must be unique.                                                                                    
+	Name                                                                                       string                `json:"name"`
+	// The copyright holder(s).                                                                                      
+	Copyright                                                                                  *string               `json:"copyright,omitempty"`
+	// The email address or other contact information of the copyright holder(s).                                    
+	CopyrightEmail                                                                             *string               `json:"copyrightEmail,omitempty"`
+	// Optional references to external artifacts relevant to this baseline (CTI/STIX,                                
+	// advisories, source catalogs, or any URI-addressable artifact). Travels with the baseline                      
+	// definition. Inert context; see External_Reference.                                                            
+	ExternalReferences                                                                         []ExternalReference   `json:"externalReferences,omitempty"`
+	// Optional key-value labels for flexible grouping. Well-known keys: system, component,                          
+	// environment, region, team. Values must be strings.                                                            
+	Labels                                                                                     map[string]string     `json:"labels,omitempty"`
+	// The copyright license. Example: 'Apache-2.0'.                                                                 
+	License                                                                                    *string               `json:"license,omitempty"`
+	// The maintainer(s).                                                                                            
+	Maintainer                                                                                 *string               `json:"maintainer,omitempty"`
+	// The status. Example: 'loaded'.                                                                                
+	Status                                                                                     *string               `json:"status,omitempty"`
+	// The summary. Example: the Security Technical Implementation Guide (STIG) header.                              
+	Summary                                                                                    *string               `json:"summary,omitempty"`
+	// The set of supported platform targets.                                                                        
+	Supports                                                                                   []SupportedPlatform   `json:"supports,omitempty"`
+	// The title - should be human readable.                                                                         
+	Title                                                                                      *string               `json:"title,omitempty"`
+	// The version of the baseline.                                                                                  
+	Version                                                                                    *string               `json:"version,omitempty"`
 }
 
 // A requirement definition without assessment results.
@@ -1246,6 +1387,11 @@ type BaselineRequirement struct {
 	// AT, IR, MA families). Optional: when omitted, consumers may infer heuristically from                             
 	// family/id but should not assume a default.                                                                       
 	ControlType                                                                                 *ControlType            `json:"controlType,omitempty"`
+	// Optional references to external artifacts relevant to this requirement (CTI/STIX                                 
+	// correlation, advisories, control/definition sources, or any URI-addressable artifact).                           
+	// Applies to both baseline requirement definitions and evaluated requirements. Inert                               
+	// context; see External_Reference.                                                                                 
+	ExternalReferences                                                                          []ExternalReference     `json:"externalReferences,omitempty"`
 	// The set of references to external documents.                                                                     
 	Refs                                                                                        []Reference             `json:"refs,omitempty"`
 	// The explicit location of the requirement within the source code.                                                 
@@ -1278,6 +1424,9 @@ type HDFComparison struct {
 	Drift                                                                                       []RequirementDiff      `json:"drift,omitempty"`
 	// Reserved for tool-specific data not defined in the HDF standard.                                                
 	Extensions                                                                                  map[string]interface{} `json:"extensions,omitempty"`
+	// Optional references to external artifacts relevant to this comparison (CTI/STIX,                                
+	// advisories, or any URI-addressable artifact). Inert context; see External_Reference.                            
+	ExternalReferences                                                                          []ExternalReference    `json:"externalReferences,omitempty"`
 	// Schema version for this comparison format.                                                                      
 	FormatVersion                                                                               FormatVersion          `json:"formatVersion"`
 	// Information about the tool that generated this comparison.                                                      
@@ -1613,6 +1762,10 @@ type HDFSystem struct {
 	DataFlows                                                                                   []DataFlow           `json:"dataFlows,omitempty"`
 	// Description of the system's purpose and mission.                                                              
 	Description                                                                                 *string              `json:"description,omitempty"`
+	// Optional references to external artifacts describing this system's threat environment or                      
+	// context (CTI/STIX, BOMs, advisories, or any URI-addressable artifact). Inert context; see                     
+	// External_Reference.                                                                                           
+	ExternalReferences                                                                          []ExternalReference  `json:"externalReferences,omitempty"`
 	// Information about the tool that generated this system document.                                               
 	Generator                                                                                   *Generator           `json:"generator,omitempty"`
 	// System identifier from an authoritative source. Example: eMASS system ID, FedRAMP package                     
@@ -1692,31 +1845,35 @@ type DataFlow struct {
 // Defines an assessment plan — what baselines to run against which targets, with resolved inputs
 // and scheduling. Maps to OSCAL Assessment Plan.
 type HDFPlan struct {
-	// The assessments to perform. Each assessment pairs a baseline with targets and resolved                     
-	// inputs.                                                                                                    
-	Assessments                                                                                 []Assessment      `json:"assessments"`
-	// Description of the plan's purpose and scope.                                                               
-	Description                                                                                 *string           `json:"description,omitempty"`
-	// Information about the tool that generated this plan.                                                       
-	Generator                                                                                   *Generator        `json:"generator,omitempty"`
-	// Cryptographic integrity information for verifying this plan document has not been                          
-	// tampered with.                                                                                             
-	Integrity                                                                                   *Integrity        `json:"integrity,omitempty"`
-	// Optional key-value labels for grouping and querying plans.                                                 
-	Labels                                                                                      map[string]string `json:"labels,omitempty"`
-	// Human-readable plan name. Example: 'Portal Monthly Assessment'.                                            
-	Name                                                                                        string            `json:"name"`
-	// Unique identifier for this plan. Optional in casual use, expected in production                            
-	// documents. Auto-generated if omitted during creation.                                                      
-	PlanID                                                                                      *string           `json:"planId,omitempty"`
-	// Optional scheduling configuration for recurring assessments.                                               
-	Schedule                                                                                    *Schedule         `json:"schedule,omitempty"`
-	// URI to the hdf-system document this plan targets. Example: 'portal-prod.hdf-system.json'.                  
-	SystemRef                                                                                   *string           `json:"systemRef,omitempty"`
-	// The type of assessment plan.                                                                               
-	Type                                                                                        *PlanType         `json:"type,omitempty"`
-	// Version of this plan document.                                                                             
-	Version                                                                                     *string           `json:"version,omitempty"`
+	// The assessments to perform. Each assessment pairs a baseline with targets and resolved                       
+	// inputs.                                                                                                      
+	Assessments                                                                                 []Assessment        `json:"assessments"`
+	// Description of the plan's purpose and scope.                                                                 
+	Description                                                                                 *string             `json:"description,omitempty"`
+	// Optional references to external artifacts relevant to this assessment plan (CTI/STIX,                        
+	// advisories, methodology docs, or any URI-addressable artifact). Inert context; see                           
+	// External_Reference.                                                                                          
+	ExternalReferences                                                                          []ExternalReference `json:"externalReferences,omitempty"`
+	// Information about the tool that generated this plan.                                                         
+	Generator                                                                                   *Generator          `json:"generator,omitempty"`
+	// Cryptographic integrity information for verifying this plan document has not been                            
+	// tampered with.                                                                                               
+	Integrity                                                                                   *Integrity          `json:"integrity,omitempty"`
+	// Optional key-value labels for grouping and querying plans.                                                   
+	Labels                                                                                      map[string]string   `json:"labels,omitempty"`
+	// Human-readable plan name. Example: 'Portal Monthly Assessment'.                                              
+	Name                                                                                        string              `json:"name"`
+	// Unique identifier for this plan. Optional in casual use, expected in production                              
+	// documents. Auto-generated if omitted during creation.                                                        
+	PlanID                                                                                      *string             `json:"planId,omitempty"`
+	// Optional scheduling configuration for recurring assessments.                                                 
+	Schedule                                                                                    *Schedule           `json:"schedule,omitempty"`
+	// URI to the hdf-system document this plan targets. Example: 'portal-prod.hdf-system.json'.                    
+	SystemRef                                                                                   *string             `json:"systemRef,omitempty"`
+	// The type of assessment plan.                                                                                 
+	Type                                                                                        *PlanType           `json:"type,omitempty"`
+	// Version of this plan document.                                                                               
+	Version                                                                                     *string             `json:"version,omitempty"`
 }
 
 // A single assessment within a plan — defines which baseline to run against which targets with what
@@ -1809,61 +1966,65 @@ type HDFAmendments struct {
 // 800-37 RMF — risk response (accept/mitigate/transfer) is a separate step from control assessment
 // status (https://csrc.nist.gov/pubs/sp/800/37/r2/final).
 type StandaloneOverride struct {
-	// Software packages this amendment is scoped to, distinct from componentRef (which scopes                    
-	// to an HDF-internal Component by UUID). Use when the source amendment format references                     
-	// packages by purl/cpe/name+version — e.g., VEX `affects[]` / `products[]`, OSCAL POA&M                      
-	// `subjects[]`, FedRAMP component-aware amendments. Symmetric with                                           
-	// Evaluated_Requirement.affectedPackages, which scopes findings to the same package                          
-	// vocabulary. When omitted, the amendment applies system-wide (or only to componentRef when                  
-	// that is set).                                                                                              
-	AffectedPackages                                                                            []AffectedPackage `json:"affectedPackages,omitempty"`
-	// When this amendment was applied. ISO 8601 format.                                                          
-	AppliedAt                                                                                   time.Time         `json:"appliedAt"`
-	// Identity of who applied this amendment.                                                                    
-	AppliedBy                                                                                   Identity          `json:"appliedBy"`
-	// Name of the baseline containing the requirement. Required when the system has multiple                     
-	// baselines with potentially overlapping requirement IDs.                                                    
-	BaselineRef                                                                                 *string           `json:"baselineRef,omitempty"`
-	// componentId of the component this amendment is scoped to. When set, the amendment only                     
-	// applies to the specified component. When omitted, the amendment applies system-wide.                       
-	ComponentRef                                                                                *string           `json:"componentRef,omitempty"`
-	// Structured CVSS scoring data backing this override. Captures the rubric (which                             
-	// Environmental/Threat metrics the consumer modified, the recomputed score) used to justify                  
-	// a riskAdjustment. For other override types this is optional context.                                       
-	Cvss                                                                                        *Cvss             `json:"cvss,omitempty"`
-	// Supporting evidence (screenshots, logs, URLs, documents).                                                  
-	Evidence                                                                                    []Evidence        `json:"evidence,omitempty"`
-	// When this amendment expires and must be reviewed. No permanent amendments. ISO 8601                        
-	// format.                                                                                                    
-	ExpiresAt                                                                                   time.Time         `json:"expiresAt"`
-	// Override to the requirement's impact score. At least one of status or impact must be set.                  
-	Impact                                                                                      *ImpactOverride   `json:"impact,omitempty"`
-	// componentId of the local component that provides this control. Set when the provider is                    
-	// in the same system. Omit for external or cross-system providers; the reason field                          
-	// explains the source. Primarily used with type 'inherited'.                                                 
-	InheritedFrom                                                                               *string           `json:"inheritedFrom,omitempty"`
-	// Structured controlled-vocabulary classification for why this override applies.                             
-	// Complements (does not replace) the free-text 'reason' field. Most useful on falsePositive                  
-	// and attestation overrides where the structured category enables filtering and lossless                     
-	// round-trip with VEX / OSCAL / FedRAMP DR. See the Justification primitive for the                          
-	// precedent vocabulary and rationale.                                                                        
-	Justification                                                                               *Justification    `json:"justification,omitempty"`
-	// Remediation milestones (primarily for POA&M type amendments).                                              
-	Milestones                                                                                  []Milestone       `json:"milestones,omitempty"`
-	// Checksum of the prior amendment in the chain. Creates a tamper-evident linked list. Null                   
-	// for the first amendment.                                                                                   
-	PreviousChecksum                                                                            *Checksum         `json:"previousChecksum,omitempty"`
-	// Justification for this amendment.                                                                          
-	Reason                                                                                      string            `json:"reason"`
-	// The ID of the requirement being amended. Must match a requirement ID in the referenced                     
-	// baseline.                                                                                                  
-	RequirementID                                                                               string            `json:"requirementId"`
-	// Digital signature for non-repudiation.                                                                     
-	Signature                                                                                   *Signature        `json:"signature,omitempty"`
-	// The new status this amendment sets. Optional when only impact is being overridden.                         
-	Status                                                                                      *ResultStatus     `json:"status,omitempty"`
-	// The type of amendment.                                                                                     
-	Type                                                                                        OverrideType      `json:"type"`
+	// Software packages this amendment is scoped to, distinct from componentRef (which scopes                      
+	// to an HDF-internal Component by UUID). Use when the source amendment format references                       
+	// packages by purl/cpe/name+version — e.g., VEX `affects[]` / `products[]`, OSCAL POA&M                        
+	// `subjects[]`, FedRAMP component-aware amendments. Symmetric with                                             
+	// Evaluated_Requirement.affectedPackages, which scopes findings to the same package                            
+	// vocabulary. When omitted, the amendment applies system-wide (or only to componentRef when                    
+	// that is set).                                                                                                
+	AffectedPackages                                                                            []AffectedPackage   `json:"affectedPackages,omitempty"`
+	// When this amendment was applied. ISO 8601 format.                                                            
+	AppliedAt                                                                                   time.Time           `json:"appliedAt"`
+	// Identity of who applied this amendment.                                                                      
+	AppliedBy                                                                                   Identity            `json:"appliedBy"`
+	// Name of the baseline containing the requirement. Required when the system has multiple                       
+	// baselines with potentially overlapping requirement IDs.                                                      
+	BaselineRef                                                                                 *string             `json:"baselineRef,omitempty"`
+	// componentId of the component this amendment is scoped to. When set, the amendment only                       
+	// applies to the specified component. When omitted, the amendment applies system-wide.                         
+	ComponentRef                                                                                *string             `json:"componentRef,omitempty"`
+	// Structured CVSS scoring data backing this override. Captures the rubric (which                               
+	// Environmental/Threat metrics the consumer modified, the recomputed score) used to justify                    
+	// a riskAdjustment. For other override types this is optional context.                                         
+	Cvss                                                                                        *Cvss               `json:"cvss,omitempty"`
+	// Supporting evidence (screenshots, logs, URLs, documents).                                                    
+	Evidence                                                                                    []Evidence          `json:"evidence,omitempty"`
+	// When this amendment expires and must be reviewed. No permanent amendments. ISO 8601                          
+	// format.                                                                                                      
+	ExpiresAt                                                                                   time.Time           `json:"expiresAt"`
+	// Optional references to the external artifacts behind this override (e.g. the STIX                            
+	// bundle/object, advisory, or CTI feed that motivated it). Inert context distinct from                         
+	// `evidence`; see External_Reference.                                                                          
+	ExternalReferences                                                                          []ExternalReference `json:"externalReferences,omitempty"`
+	// Override to the requirement's impact score. At least one of status or impact must be set.                    
+	Impact                                                                                      *ImpactOverride     `json:"impact,omitempty"`
+	// componentId of the local component that provides this control. Set when the provider is                      
+	// in the same system. Omit for external or cross-system providers; the reason field                            
+	// explains the source. Primarily used with type 'inherited'.                                                   
+	InheritedFrom                                                                               *string             `json:"inheritedFrom,omitempty"`
+	// Structured controlled-vocabulary classification for why this override applies.                               
+	// Complements (does not replace) the free-text 'reason' field. Most useful on falsePositive                    
+	// and attestation overrides where the structured category enables filtering and lossless                       
+	// round-trip with VEX / OSCAL / FedRAMP DR. See the Justification primitive for the                            
+	// precedent vocabulary and rationale.                                                                          
+	Justification                                                                               *Justification      `json:"justification,omitempty"`
+	// Remediation milestones (primarily for POA&M type amendments).                                                
+	Milestones                                                                                  []Milestone         `json:"milestones,omitempty"`
+	// Checksum of the prior amendment in the chain. Creates a tamper-evident linked list. Null                     
+	// for the first amendment.                                                                                     
+	PreviousChecksum                                                                            *Checksum           `json:"previousChecksum,omitempty"`
+	// Justification for this amendment.                                                                            
+	Reason                                                                                      string              `json:"reason"`
+	// The ID of the requirement being amended. Must match a requirement ID in the referenced                       
+	// baseline.                                                                                                    
+	RequirementID                                                                               string              `json:"requirementId"`
+	// Digital signature for non-repudiation.                                                                       
+	Signature                                                                                   *Signature          `json:"signature,omitempty"`
+	// The new status this amendment sets. Optional when only impact is being overridden.                           
+	Status                                                                                      *ResultStatus       `json:"status,omitempty"`
+	// The type of amendment.                                                                                       
+	Type                                                                                        OverrideType        `json:"type"`
 }
 
 // Bundles references to all HDF documents for audit, authorization, and compliance review. Each
@@ -1880,6 +2041,10 @@ type HDFEvidencePackage struct {
 	// inside HDF. Logs in ECS/OCSF/etc. are legitimate accreditation evidence; HDF indexes them                            
 	// here rather than transcoding them.                                                                                   
 	ExternalEvidence                                                                            []ExternalEvidenceReference `json:"externalEvidence,omitempty"`
+	// Optional references to external artifacts relevant to this evidence package (CTI/STIX,                               
+	// BOMs, advisories, or any URI-addressable artifact) beyond the document references it                                 
+	// already carries. Inert context; see External_Reference.                                                              
+	ExternalReferences                                                                          []ExternalReference         `json:"externalReferences,omitempty"`
 	// Information about the tool that generated this document.                                                             
 	Generator                                                                                   *Generator                  `json:"generator,omitempty"`
 	// Cryptographic integrity information for verifying this evidence package has not been                                 
@@ -1994,6 +2159,99 @@ type ExternalEvidenceTimeRange struct {
 	Start                                                    *time.Time `json:"start,omitempty"`
 }
 
+// A single continuous-monitoring wire event: one requirement's effective posture changed on one
+// system component. The streaming increment of a systemDrift hdf-comparison — events fold into
+// comparisons and reassemble into hdf-results, they never mutate documents in place. One event per
+// wire document (NDJSON-friendly). The envelope (identity, ordering, hash chain) is the shared
+// Change_Event_Envelope primitive; the payload carries the producer-computable change state, a thin
+// before projection, and the full after requirement (the evidence a responder opens the event for).
+// Design: ADR-0005.
+type HDFRequirementChangeEvent struct {
+	// The full requirement as evaluated after the change — required and non-null for every                           
+	// state except absent (null there: the requirement left the assessment scope). Full content                      
+	// is load-bearing twice over: reassembly parity (applyChangeEvents cannot reproduce changed                      
+	// result content from a projection) and triage (the failing results[] ARE the 'why' a                            
+	// responder opens the event for).                                                                                
+	After                                                                                       interface{}           `json:"after"`
+	// Thin projection of the prior effective posture, for at-a-glance alerting without a                             
+	// state-store lookup. Null exactly when state is new (no prior posture exists). The full                         
+	// prior state is recoverable from the consumer's materialized state; the envelope's                              
+	// priorChecksum covers the integrity of that recovery.                                                           
+	Before                                                                                      interface{}           `json:"before"`
+	// Why the state changed. An overrideExpired flip is a different triage than resultChanged:                       
+	// the control did not get worse, a waiver lapsed.                                                                
+	ChangeReasons                                                                               []EventChangeReason   `json:"changeReasons,omitempty"`
+	// Canonical requirement identifier — the same identity as Requirement_Diff.id and the                            
+	// requirement's id in hdf-results. Together with the envelope's (systemRef, componentId)                         
+	// this forms the durable entity key. A requirement renumbering is emitted as absent + new                        
+	// under the two keys, never an in-place key change; batch comparison reconciles renames via                      
+	// its oldId/newId matching.                                                                                      
+	RequirementID                                                                               string                `json:"requirementId"`
+	// The producer-computable subset of Requirement_State: new | absent | updated | fixed |                          
+	// regressed. fixed and regressed carry the direction SARIF's baselineState lacks; project                        
+	// down to SARIF's closed 4 values for external interop.                                                          
+	State                                                                                       EventRequirementState `json:"state"`
+	// componentId of the system component this event concerns.                                                       
+	ComponentID                                                                                 string                `json:"componentId"`
+	// Identity of this event occurrence, unique per source. (source, eventId) is the                                 
+	// deduplication key: consumers may treat events with identical source and eventId as                             
+	// duplicates. UUIDv7 (time-ordered) is recommended but not required.                                             
+	EventID                                                                                     string                `json:"eventId"`
+	// The effectiveChecksum of the entity state this event supersedes, forming a per-key hash                        
+	// chain: a mismatch or gap against stored state is detectable, letting a consumer mark the                       
+	// key unverified instead of serving stale posture. Null at chain start (no prior state,                          
+	// e.g. a new entity or the first event after a seed). The chain provides tamper/gap                              
+	// evidence given a trusted head; completeness is anchored out-of-band by periodic                                
+	// re-centering rescans.                                                                                          
+	PriorChecksum                                                                               interface{}           `json:"priorChecksum"`
+	// The versioned schema $id this event validates against, so events self-describe on                              
+	// heterogeneous streams. Recommended on every wire event.                                                        
+	SchemaRef                                                                                   *string               `json:"schemaRef,omitempty"`
+	// Monotonically increasing sequence number per entity key. The ONLY ordering authority for                       
+	// folding: consumers keep the greatest sequence per key regardless of arrival order or                           
+	// timestamp. Deliberately per-entity-key (event-sourcing aggregate-version practice) rather                      
+	// than per-source.                                                                                               
+	Sequence                                                                                    int64                 `json:"sequence"`
+	// URI identifying the producer context that emitted this event (for example, a scanner                           
+	// instance and profile). eventId uniqueness and sequence numbering are scoped per source.                        
+	Source                                                                                      string                `json:"source"`
+	// URI to the hdf-system document (authorization boundary) this event applies to. Resolves                        
+	// to the latest version of the evolving system document.                                                         
+	SystemRef                                                                                   string                `json:"systemRef"`
+	// Occurrence time of the observed change (RFC 3339, trimmed UTC). Display and audit                              
+	// metadata only — NEVER an ordering key; ordering is sequence's job.                                             
+	Timestamp                                                                                   time.Time             `json:"timestamp"`
+}
+
+// The type of identifier. Use 'email' for email addresses, 'username' for user accounts,
+// 'system' for deterministic non-interactive automation (CI jobs, cron, scanners), 'agent'
+// for an AI/LLM agent acting with autonomy — kept distinct from 'system' so auditors can
+// apply AI-specific scrutiny (e.g. 'an LLM proposed this' vs a deterministic job) and
+// satisfy AI-source disclosure under frameworks like the EU AI Act and NIST AI RMF,
+// 'simple' for basic string identifiers without additional classification, or 'other' for
+// custom identity systems.
+type IdentityType string
+
+const (
+	Agent              IdentityType = "agent"
+	Email              IdentityType = "email"
+	IdentityTypeOther  IdentityType = "other"
+	IdentityTypeSystem IdentityType = "system"
+	Simple             IdentityType = "simple"
+	Username           IdentityType = "username"
+)
+
+// Supported cryptographic hash algorithms for checksums and integrity verification. blake3 covers
+// container-image and other artifact digests that use it.
+type HashAlgorithm string
+
+const (
+	Blake3 HashAlgorithm = "blake3"
+	Sha256 HashAlgorithm = "sha256"
+	Sha384 HashAlgorithm = "sha384"
+	Sha512 HashAlgorithm = "sha512"
+)
+
 // Comparison operator for evaluating the input value against observed values. Numeric:
 // eq/ne/lt/le/gt/ge. String: eq/ne/contains/matches. Collection: in/notIn.
 type ComparisonOperator string
@@ -2023,17 +2281,6 @@ const (
 	String  InputType = "String"
 )
 
-// Supported cryptographic hash algorithms for checksums and integrity verification. blake3 covers
-// container-image and other artifact digests that use it.
-type HashAlgorithm string
-
-const (
-	Blake3 HashAlgorithm = "blake3"
-	Sha256 HashAlgorithm = "sha256"
-	Sha384 HashAlgorithm = "sha384"
-	Sha512 HashAlgorithm = "sha512"
-)
-
 // The packaging ecosystem the package belongs to. Use 'generic' for hardware, firmware, or
 // anything outside the listed language/OS package managers.
 type Ecosystem string
@@ -2143,24 +2390,6 @@ const (
 	Passed        ResultStatus = "passed"
 )
 
-// The type of identifier. Use 'email' for email addresses, 'username' for user accounts,
-// 'system' for deterministic non-interactive automation (CI jobs, cron, scanners), 'agent'
-// for an AI/LLM agent acting with autonomy — kept distinct from 'system' so auditors can
-// apply AI-specific scrutiny (e.g. 'an LLM proposed this' vs a deterministic job) and
-// satisfy AI-source disclosure under frameworks like the EU AI Act and NIST AI RMF,
-// 'simple' for basic string identifiers without additional classification, or 'other' for
-// custom identity systems.
-type IdentityType string
-
-const (
-	Agent              IdentityType = "agent"
-	Email              IdentityType = "email"
-	IdentityTypeOther  IdentityType = "other"
-	IdentityTypeSystem IdentityType = "system"
-	Simple             IdentityType = "simple"
-	Username           IdentityType = "username"
-)
-
 // The type of evidence being provided.
 type EvidenceType string
 
@@ -2352,22 +2581,27 @@ const (
 	Replace Op = "replace"
 )
 
-// The reason a requirement's state changed between sources.
+// The reason a requirement's state changed between sources. 'dispositionChanged' = the governing
+// override type differs between the sources (e.g. a waiver replaced a riskAdjustment);
+// 'effectiveImpactChanged' = the post-override impact score differs while the base impact may be
+// unchanged.
 type ChangeReason string
 
 const (
-	BaselineUpgraded ChangeReason = "baselineUpgraded"
-	ConfigChanged    ChangeReason = "configChanged"
-	ControlMapped    ChangeReason = "controlMapped"
-	ImpactChanged    ChangeReason = "impactChanged"
-	MetadataChanged  ChangeReason = "metadataChanged"
-	OverrideAdded    ChangeReason = "overrideAdded"
-	OverrideExpired  ChangeReason = "overrideExpired"
-	OverrideModified ChangeReason = "overrideModified"
-	OverrideRemoved  ChangeReason = "overrideRemoved"
-	ResultChanged    ChangeReason = "resultChanged"
-	ScannerChanged   ChangeReason = "scannerChanged"
-	TargetChanged    ChangeReason = "targetChanged"
+	BaselineUpgraded             ChangeReason = "baselineUpgraded"
+	ChangeReasonConfigChanged    ChangeReason = "configChanged"
+	ChangeReasonImpactChanged    ChangeReason = "impactChanged"
+	ChangeReasonOverrideAdded    ChangeReason = "overrideAdded"
+	ChangeReasonOverrideExpired  ChangeReason = "overrideExpired"
+	ChangeReasonOverrideModified ChangeReason = "overrideModified"
+	ChangeReasonOverrideRemoved  ChangeReason = "overrideRemoved"
+	ChangeReasonResultChanged    ChangeReason = "resultChanged"
+	ControlMapped                ChangeReason = "controlMapped"
+	DispositionChanged           ChangeReason = "dispositionChanged"
+	EffectiveImpactChanged       ChangeReason = "effectiveImpactChanged"
+	MetadataChanged              ChangeReason = "metadataChanged"
+	ScannerChanged               ChangeReason = "scannerChanged"
+	TargetChanged                ChangeReason = "targetChanged"
 )
 
 // How a conflict between multiple scanner results was resolved.
@@ -2401,12 +2635,12 @@ const (
 type RequirementState string
 
 const (
-	Fixed                     RequirementState = "fixed"
 	Moved                     RequirementState = "moved"
-	Regressed                 RequirementState = "regressed"
 	RequirementStateAbsent    RequirementState = "absent"
+	RequirementStateFixed     RequirementState = "fixed"
 	RequirementStateMerged    RequirementState = "merged"
 	RequirementStateNew       RequirementState = "new"
+	RequirementStateRegressed RequirementState = "regressed"
 	RequirementStateUnchanged RequirementState = "unchanged"
 	RequirementStateUpdated   RequirementState = "updated"
 	Split                     RequirementState = "split"
@@ -2518,6 +2752,36 @@ const (
 	HdfSystem     ContentType = "hdf-system"
 )
 
+// The producer-computable subset of the comparison vocabulary's Change_Reason, value-identical with
+// the parent enum (test-enforced). Batch-only reasons (baselineUpgraded, controlMapped,
+// scannerChanged, targetChanged, metadataChanged) require cross-corpus context and are excluded.
+type EventChangeReason string
+
+const (
+	EventChangeReasonConfigChanged    EventChangeReason = "configChanged"
+	EventChangeReasonImpactChanged    EventChangeReason = "impactChanged"
+	EventChangeReasonOverrideAdded    EventChangeReason = "overrideAdded"
+	EventChangeReasonOverrideExpired  EventChangeReason = "overrideExpired"
+	EventChangeReasonOverrideModified EventChangeReason = "overrideModified"
+	EventChangeReasonOverrideRemoved  EventChangeReason = "overrideRemoved"
+	EventChangeReasonResultChanged    EventChangeReason = "resultChanged"
+)
+
+// The producer-computable subset of the comparison vocabulary's Requirement_State. Kept
+// value-identical with the parent enum (test-enforced): the batch-only states (moved, split,
+// merged) are outputs of cross-document identity resolution a per-key producer cannot compute.
+// Declared as a distinct named type (rather than a $ref intersection) so generated Go/TS types keep
+// stable, distinct enum names.
+type EventRequirementState string
+
+const (
+	EventRequirementStateAbsent    EventRequirementState = "absent"
+	EventRequirementStateFixed     EventRequirementState = "fixed"
+	EventRequirementStateNew       EventRequirementState = "new"
+	EventRequirementStateRegressed EventRequirementState = "regressed"
+	EventRequirementStateUpdated   EventRequirementState = "updated"
+)
+
 type Ref struct {
 	AnythingMapArray []map[string]interface{}
 	String           *string