@mitre/hdf-schema 3.7.2 → 3.8.0-next.42533588944.1

package/dist/ts/hdf.d.ts

@@ -19,12 +19,10 @@ export interface HDFResults {
      */
     derivation?: Derivation;
     /**
-     * Reserved for tool-specific data not defined in the HDF standard. Use this to preserve
-     * original tool output, auxiliary data, or custom metadata.
+     * Producer data outside the HDF model, and the pre-converted source artifact(s) these
+     * results were converted from.
      */
-    extensions?: {
-        [key: string]: any;
-    };
+    extensions?: Extensions;
     /**
      * 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
@@ -98,15 +96,10 @@ export interface EvaluatedBaseline {
      */
     depends?: Dependency[];
     /**
-     * The description - should be more detailed than the summary.
+     * Producer data outside the HDF model that belongs to this baseline rather than to the
+     * document, and the pre-converted source artifact(s) this baseline was built from.
      */
-    description?: string;
-    /**
-     * Reserved for tool-specific baseline metadata not defined in the HDF standard.
-     */
-    extensions?: {
-        [key: string]: any;
-    };
+    extensions?: Extensions;
     /**
      * A set of descriptions for the requirement groups.
      */
@@ -138,8 +131,10 @@ export interface EvaluatedBaseline {
     requirements: EvaluatedRequirement[];
     /**
      * SHA-256 checksum of the raw results before any amendments (statusOverrides or POAMs).
-     * Used to detect tampering with test results. Compare with currentChecksum to verify
-     * amendment integrity.
+     * Used to detect tampering with test results. Amendment integrity is checked against the
+     * document-level preAmendmentChecksum at the root, not this per-baseline value: hdf amend
+     * apply writes it as the hash of the raw document bytes immediately before the most recent
+     * amendment application, one step back only.
      */
     resultsChecksum?: Checksum;
     /**
@@ -159,6 +154,11 @@ export interface EvaluatedBaseline {
      * The email address or other contact information of the copyright holder(s).
      */
     copyrightEmail?: string;
+    /**
+     * Prose description of the baseline, more detailed than summary. Carried verbatim, like
+     * every HDF prose field.
+     */
+    description?: string;
     /**
      * Optional references to external artifacts relevant to this baseline (CTI/STIX,
      * advisories, source catalogs, or any URI-addressable artifact). Travels with the baseline
@@ -245,6 +245,53 @@ export interface Dependency {
     url?: string;
     [property: string]: any;
 }
+/**
+ * Carrier for data outside the HDF model: `passthrough` for producer data HDF does not model,
+ * `rawSourceArtifacts` for the pre-converted input(s). CLOSED: these two members are the whole of
+ * it. A key HDF does not define goes inside `passthrough` — that is what `passthrough` is for — so
+ * `extensions` never becomes a second, unnamed schema that consumers must reverse-engineer from the
+ * producers that happen to write it. Closed with `additionalProperties` rather than the house
+ * `unevaluatedProperties` because this definition composes nothing, and the shipped Go validator is
+ * a draft-07 engine that does not implement `unevaluatedProperties` — a closure only one of the two
+ * validators enforces is not a closure. Declared on every HDF document type that carries a producer
+ * envelope (`generator` / `integrity`), and on `Evaluated_Baseline`, so one rule governs both
+ * sites.
+ */
+export interface Extensions {
+    /**
+     * Catch-all for producer data that HDF does not model — the role heimdall2's
+     * `passthrough.auxiliary_data` played: fields a converter deliberately carried but had no
+     * home for.
+     *
+     * Deliberately permissive: unenumerated properties are accepted by design, with no shape
+     * imposed on them. HDF neither reads nor interprets what is here. It is the ONLY permissive
+     * surface in `extensions` — everything HDF does not define belongs here rather than beside
+     * it.
+     *
+     * This is NOT where the pre-converted source artifact goes. v2 put it here only because
+     * nothing else had room; `rawSourceArtifacts` is its home now, and it gives the bytes a
+     * checksum, a media type and a reference contract that an untyped object cannot.
+     *
+     * For data that belongs to one requirement rather than to the document, use that object's
+     * own fields — a document-level bag cannot say which requirement it describes.
+     */
+    passthrough?: {
+        [key: string]: any;
+    };
+    /**
+     * The input(s) this document was converted from, verbatim.
+     *
+     * An array because a conversion can consume more than one artifact — the OSCAL profile path
+     * takes a profile and a catalog. Every other converter takes one input, and an array of one
+     * costs nothing.
+     *
+     * Populating this is required of ingest converters by policy, enforced by the converter
+     * contract and test harness rather than by a schema `required`: a tool that emits HDF
+     * natively has no source artifact, and requiring the field would make valid native HDF
+     * invalid.
+     */
+    rawSourceArtifacts?: ExternalReference[];
+}
 /**
  * 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
@@ -252,8 +299,11 @@ export interface Dependency {
  * 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.
+ * interconvertible. An entry may also carry the artifact itself rather than point at it: `document`
+ * for a JSON object, `content` + `encoding` for anything else. Embedding satisfies the at-least-one
+ * rule on its own, so an artifact with no meaningful public location needs no synthetic `href`. A
+ * reference is inert context: it overrides nothing, so it carries only lightweight optional
+ * `addedBy`/`addedAt` attribution, never override machinery.
  */
 export interface ExternalReference {
     /**
@@ -266,18 +316,36 @@ export interface ExternalReference {
      */
     addedBy?: Identity;
     /**
-     * Integrity hash of the referenced artifact. Reuses the HDF `Checksum` primitive (not STIX
-     * `hashes`). Meaningful only with a retrievable `href`.
+     * Integrity hash of the artifact. Reuses the HDF `Checksum` primitive (not STIX `hashes`).
+     * Applies both to an artifact retrievable at `href` and to one embedded here in `content`
+     * or `document` — beside embedded bytes it is what makes the copy verifiable rather than
+     * merely present.
      */
     checksum?: Checksum;
+    /**
+     * Optional lossless embedded copy of the artifact's bytes as a string, for artifacts
+     * `document` cannot hold: XML, CSV, NDJSON, plain text, a JSON array, or bytes that are not
+     * valid UTF-8 text at all.
+     *
+     * `encoding` states how to read it back and is required alongside it. Set `mediaType` so a
+     * consumer knows what the bytes are, and `checksum` so the copy can be verified against the
+     * source.
+     *
+     * Carried verbatim — never reformatted, re-indented, or re-serialized.
+     */
+    content?: string;
     /**
      * 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;
     /**
-     * Optional lossless embedded copy of the referenced artifact — the raw STIX object, EPSS
-     * record, advisory, or annotation payload — preserved verbatim.
+     * Optional lossless embedded copy of the referenced artifact as a JSON object — the raw
+     * STIX object, EPSS record, advisory, or annotation payload — preserved verbatim.
+     *
+     * JSON objects only. An artifact that is not a JSON object (XML, CSV, NDJSON, plain text, a
+     * JSON array, or bytes that are not text at all) embeds through `content` + `encoding`
+     * instead.
      *
      * 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.
@@ -288,6 +356,15 @@ export interface ExternalReference {
     document?: {
         [key: string]: any;
     };
+    /**
+     * How to read `content` back into the artifact's bytes. 'utf-8' for text (XML, CSV, NDJSON,
+     * plain text, JavaScript-wrapped JSON); 'base64' for anything that is not valid UTF-8
+     * text.
+     *
+     * Required whenever `content` is present, and meaningless without it — an embedded copy
+     * whose encoding a consumer has to guess is not lossless.
+     */
+    encoding?: ExternalReferenceEncoding;
     /**
      * 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`
@@ -296,8 +373,8 @@ export interface ExternalReference {
     externalId?: string;
     /**
      * 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`.
+     * `#fragment`/`#uuid` reference is expressible alongside absolute URLs. Set it only when
+     * the location is meaningful to a reader — never a producer's local filesystem path.
      */
     href?: string;
     /**
@@ -314,8 +391,9 @@ export interface ExternalReference {
      */
     kind?: string;
     /**
-     * IANA media type of the referenced artifact when retrievable (RFC 6838), e.g.,
-     * 'application/json'. Meaningful only with `href`.
+     * IANA media type of the artifact (RFC 6838), e.g., 'application/json', 'application/xml',
+     * 'text/csv'. Applies both to an artifact retrievable at `href` and to one embedded here in
+     * `content` or `document`.
      */
     mediaType?: string;
     /**
@@ -394,8 +472,14 @@ export interface Checksum {
     [property: string]: any;
 }
 /**
- * Supported cryptographic hash algorithms for checksums and integrity verification. blake3 covers
- * container-image and other artifact digests that use it.
+ * Cryptographic hash algorithms a checksum or integrity record may name. blake3 covers
+ * container-image and other artifact digests that use it. HDF tooling verifies every algorithm in
+ * this enum, so any of them may be recorded where the checksum needs to be verifiable. md5 and sha1
+ * are excluded deliberately: a checksum or integrity record exists to detect tampering, and both
+ * are collision-broken, so a digest in either would look verifiable while proving nothing. A source
+ * tool digest in an excluded algorithm is not recorded as a checksum. Admitting weak hashes as an
+ * application-level accept/reject decision was considered and rejected; widening this enum is a
+ * schema decision, not an oversight.
  */
 export declare enum HashAlgorithm {
     Blake3 = "blake3",
@@ -403,6 +487,14 @@ export declare enum HashAlgorithm {
     Sha384 = "sha384",
     Sha512 = "sha512"
 }
+/**
+ * How an embedded copy's bytes are read back: 'utf-8' for text, 'base64' for anything that is not
+ * valid UTF-8 text.
+ */
+export declare enum ExternalReferenceEncoding {
+    Base64 = "base64",
+    UTF8 = "utf-8"
+}
 /**
  * Describes a group of requirements, such as those defined in a single file.
  */
@@ -469,7 +561,9 @@ export interface Input {
  */
 export interface InputConstraints {
     /**
-     * Enumeration of permitted values.
+     * Enumeration of permitted values. Each entry may be any JSON value, the same freedom
+     * Input.value has: an Array or Hash input enumerates container values, so no element type
+     * is imposed.
      */
     allowedValues?: any[];
     /**
@@ -645,7 +739,11 @@ export interface EvaluatedRequirement {
      */
     statusOverrides?: StatusOverride[];
     /**
-     * The requirement identifier. Example: 'SV-238196'.
+     * The requirement identifier, naming the requirement itself rather than one finding of it.
+     * Example: 'SV-238196'. Several entries in one baseline may legitimately carry the same id
+     * (one scanner reporting one CVE against several packages, or an overlay restating what it
+     * inherits), so an id is not an instance key: index requirements as id to list, never id to
+     * one, and an amendment addressing an id applies to every entry carrying it.
      */
     id: string;
     /**
@@ -954,10 +1052,11 @@ export interface Description {
  * to 'notApplicable'. The disposition field on the requirement distinguishes false positives from
  * genuinely not-applicable findings. - 'riskAdjustment': impact score adjusted based on
  * environmental context (FedRAMP Risk Adjustment); does not change pass/fail status, only impact
- * via the impact field. - 'operationalRequirement': deviation required by operational constraints
- * (FedRAMP Operational Requirement); the finding cannot be remediated because the system requires
- * the affected functionality. Remains an open risk. Migration note: 'exception' was removed in
- * v3.1.0 — use 'waiver' with status 'notApplicable' instead.
+ * via the impact field; a status on it is rejected by validation. - 'operationalRequirement':
+ * deviation required by operational constraints (FedRAMP Operational Requirement); the finding
+ * cannot be remediated because the system requires the affected functionality. Remains an open
+ * risk. Migration note: 'exception' was removed in v3.1.0 — use 'waiver' with status
+ * 'notApplicable' instead.
  */
 export declare enum OverrideType {
     Attestation = "attestation",
@@ -1303,6 +1402,13 @@ export interface RequirementResult {
      * explain why a test was not applicable or not reviewed.
      */
     message?: string;
+    /**
+     * The source tool's own record for this result, carrying every field the record had.
+     * Complete, not necessarily byte-exact: see Raw_Source_Record.content for the producer and
+     * consumer obligations, and extensions.rawSourceArtifacts[] when byte-exact carriage is
+     * required.
+     */
+    rawSourceRecord?: RawSourceRecord;
     /**
      * The resource used in the test. Example: 'file', 'command', 'service'.
      */
@@ -1325,6 +1431,66 @@ export interface RequirementResult {
     status: ResultStatus;
     [property: string]: any;
 }
+/**
+ * The source tool's own record for this result — the one entry in the converter's input that
+ * produced it, complete though not necessarily byte-for-byte (see `content`). SCOPED TO THE RESULT
+ * DELIBERATELY. For a vulnerability scanner the native record is one (vulnerability, package) pair,
+ * which is exactly one result: a CVE reported against two packages yields two entries whose records
+ * differ only in the package they matched. Held on the requirement instead, those two records would
+ * collide, and merging entries that share an id would have to discard one — so the result is not
+ * merely an available home but the correct one. Distinct from `extensions.rawSourceArtifacts[]`,
+ * which carries whole input artifacts: this carries the one record inside one of them, and
+ * `pointer` ties the two together. A consumer that wants the whole input reads the artifact; one
+ * that wants provenance for a single finding reads this. Distinct from `code`, which means the code
+ * that ran to evaluate the requirement — an InSpec control's source, or a check reference. A
+ * serialized finding is not code, and putting one there overloaded a field whose meaning came from
+ * InSpec. CLOSED, and deliberately not a passthrough bag: three required members and an optional
+ * pointer are the whole of it. Producer data that HDF does not model belongs in
+ * `extensions.passthrough`, which is document-scoped and permissive by design; this field is
+ * neither. Closed with `additionalProperties` rather than the house `unevaluatedProperties` because
+ * this definition composes nothing, and the shipped Go validator is a draft-07 engine that does not
+ * implement `unevaluatedProperties` — a closure only one of the two validators enforces is not a
+ * closure.
+ */
+export interface RawSourceRecord {
+    /**
+     * The source tool's own record for this result, carrying every field the record had.
+     *
+     * COMPLETE, NOT NECESSARILY BYTE-EXACT. A producer SHOULD write the record's bytes
+     * unchanged where it can. A producer that cannot — notably one implemented in two languages
+     * whose JSON serializers disagree on key order, HTML escaping and number rendering, and
+     * which therefore MUST canonicalize to stay byte-identical with its twin — MAY write a
+     * canonically serialized form instead. Such a form preserves every field and value but not
+     * the original key order, insignificant whitespace, or duplicate keys. A consumer MUST
+     * therefore compare records by parsing them, not by comparing bytes, and MUST NOT checksum
+     * this field and expect the result to match a checksum of the input.
+     *
+     * For carriage that IS byte-exact, use `extensions.rawSourceArtifacts[]`, which forbids a
+     * parsed `document` precisely so the bytes and their checksum survive; `pointer` ties this
+     * record to its position within that artifact.
+     */
+    content: string;
+    /**
+     * How to read `content`: 'utf-8' for text, 'base64' for bytes that are not valid UTF-8 text.
+     */
+    encoding: ExternalReferenceEncoding;
+    /**
+     * The record's IANA media type — the type of this record, which for a fragment of a larger
+     * artifact may be narrower than the artifact's own. Example: 'application/json' for one
+     * match object out of a JSON report.
+     */
+    mediaType: string;
+    /**
+     * Where this record sits inside the artifact it came from, as a JSON Pointer (RFC 6901) for
+     * JSON sources or an XPath for XML ones. Example: '/matches/3'.
+     *
+     * Optional, and the link that makes carriage verifiable rather than merely present: with it
+     * a consumer can confirm the record really is the subtree of
+     * `extensions.rawSourceArtifacts[]` it claims to be. Omit it when the source's shape gives
+     * a record no addressable location.
+     */
+    pointer?: string;
+}
 /**
  * Severity rating for a requirement. Typically derived from the numeric impact score.
  */
@@ -1350,9 +1516,14 @@ export interface SourceLocation {
     [property: string]: any;
 }
 /**
- * An intentional change to a requirement's compliance status and/or impact score. At least one of
- * 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.
+ * An intentional change to a requirement's compliance status and/or impact score, as it sits on the
+ * requirement once applied. The same type-conditional rule as Standalone_Override: when type is
+ * 'operationalRequirement', neither status nor impact may be set, because the override records an
+ * accepted deviation without adjudicating the finding; it still governs disposition, and
+ * effectiveStatus stays what the results decided. When type is 'riskAdjustment', status may not be
+ * set: it re-rates the risk through impact and never changes pass/fail. For every other type, at
+ * least one of status or impact must be set. All overrides must have an expiration date to enforce
+ * periodic review.
  */
 export interface StatusOverride {
     /**
@@ -1388,7 +1559,8 @@ export interface StatusOverride {
      */
     externalReferences?: ExternalReference[];
     /**
-     * Override to the requirement's impact score. At least one of status or impact must be set.
+     * Override to the requirement's impact score. For every type except operationalRequirement,
+     * at least one of status or impact must be set; an operationalRequirement carries neither.
      */
     impact?: ImpactOverride;
     /**
@@ -1420,7 +1592,8 @@ export interface StatusOverride {
     signature?: Signature;
     /**
      * The new status this override sets for the requirement. Optional when only impact is being
-     * overridden.
+     * overridden; forbidden on an operationalRequirement, which adjudicates nothing, and on a
+     * riskAdjustment, which re-rates impact only.
      */
     status?: ResultStatus;
     /**
@@ -2328,6 +2501,11 @@ export interface HDFBaseline {
      * The set of dependencies this baseline depends on.
      */
     depends?: Dependency[];
+    /**
+     * Producer data outside the HDF model, and the pre-converted source artifact(s) this
+     * baseline was converted from.
+     */
+    extensions?: Extensions;
     /**
      * The tool that generated this file.
      */
@@ -2366,6 +2544,11 @@ export interface HDFBaseline {
      * The email address or other contact information of the copyright holder(s).
      */
     copyrightEmail?: string;
+    /**
+     * Prose description of the baseline, more detailed than summary. Carried verbatim, like
+     * every HDF prose field.
+     */
+    description?: string;
     /**
      * Optional references to external artifacts relevant to this baseline (CTI/STIX,
      * advisories, source catalogs, or any URI-addressable artifact). Travels with the baseline
@@ -2425,7 +2608,11 @@ export interface BaselineRequirement {
      */
     severity?: Severity;
     /**
-     * The requirement identifier. Example: 'SV-238196'.
+     * The requirement identifier, naming the requirement itself rather than one finding of it.
+     * Example: 'SV-238196'. Several entries in one baseline may legitimately carry the same id
+     * (one scanner reporting one CVE against several packages, or an overlay restating what it
+     * inherits), so an id is not an instance key: index requirements as id to list, never id to
+     * one, and an amendment addressing an id applies to every entry carrying it.
      */
     id: string;
     /**
@@ -2536,11 +2723,10 @@ export interface HDFComparison {
      */
     drift?: RequirementDiff[];
     /**
-     * Reserved for tool-specific data not defined in the HDF standard.
+     * Producer data outside the HDF model, and the pre-converted source artifact(s) this
+     * comparison was derived from.
      */
-    extensions?: {
-        [key: string]: any;
-    };
+    extensions?: Extensions;
     /**
      * Optional references to external artifacts relevant to this comparison (CTI/STIX,
      * advisories, or any URI-addressable artifact). Inert context; see External_Reference.
@@ -2651,9 +2837,8 @@ export interface BaselineDiff {
     [property: string]: any;
 }
 /**
- * The state of this baseline in the comparison.
- *
- * The state of this component in the comparison.
+ * How a baseline or component fared across the compared documents: new (only in the newer), absent
+ * (only in the older), unchanged, or updated (present in both with a changed version).
  */
 export declare enum BaselineDiffState {
     Absent = "absent",
@@ -2751,6 +2936,12 @@ export interface RequirementDiff {
      * IDs of annotations attached to this requirement diff.
      */
     annotationIds?: string[];
+    /**
+     * Name of the baseline the requirement belongs to, so a consumer can group diffs the way
+     * hdf diff --group-by baseline does. '(multiple)' when the id appears in more than one
+     * baseline of the same document.
+     */
+    baseline?: string;
     /**
      * The requirement as it appeared in the old/reference source. Null when state is 'new'.
      */
@@ -3134,7 +3325,8 @@ export interface ComparisonSummary {
      */
     regressed?: number;
     /**
-     * Total number of unique requirements across all sources.
+     * Total number of distinct requirement ids across all sources; an id carried by several
+     * entries counts once.
      */
     total: number;
     /**
@@ -3303,6 +3495,11 @@ export interface HDFSystem {
      * Description of the system's purpose and mission.
      */
     description?: string;
+    /**
+     * Producer data outside the HDF model, and the pre-converted source artifact(s) this system
+     * document was converted from.
+     */
+    extensions?: Extensions;
     /**
      * 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
@@ -3486,6 +3683,11 @@ export interface HDFPlan {
      * Description of the plan's purpose and scope.
      */
     description?: string;
+    /**
+     * Producer data outside the HDF model, and the pre-converted source artifact(s) this plan
+     * was converted from.
+     */
+    extensions?: Extensions;
     /**
      * Optional references to external artifacts relevant to this assessment plan (CTI/STIX,
      * advisories, methodology docs, or any URI-addressable artifact). Inert context; see
@@ -3647,6 +3849,12 @@ export interface HDFAmendments {
      * Description of the amendments' purpose and scope.
      */
     description?: string;
+    /**
+     * Producer data outside the HDF model, and the pre-converted source artifact(s) these
+     * amendments were converted from — the VEX family and oscal-poam-to-hdf all emit this
+     * document type.
+     */
+    extensions?: Extensions;
     /**
      * Information about the tool that generated this document.
      */
@@ -3685,11 +3893,13 @@ export interface HDFAmendments {
     [property: string]: any;
 }
 /**
- * A standalone override to a requirement's compliance status or risk impact. Validation has two
- * branches gated on 'type': when type is 'operationalRequirement', neither 'status' nor 'impact'
- * may be set — the override records accepted risk without changing the finding
- * (documentation-only). For all other types, at least one of 'status' or 'impact' must be set. This
- * rule aligns with: - OSCAL Assessment Results — finding.target.status and
+ * A standalone override to a requirement's compliance status or risk impact. Validation is gated on
+ * 'type': when type is 'operationalRequirement', neither 'status' nor 'impact' may be set — the
+ * override records accepted risk without changing the finding (documentation-only). When type is
+ * 'riskAdjustment', 'status' may not be set — it re-rates the risk through 'impact' and never
+ * changes the finding's pass/fail; an override that must change status is a waiver or
+ * falsePositive. For all other types, at least one of 'status' or 'impact' must be set. This rule
+ * aligns with: - OSCAL Assessment Results — finding.target.status and
  * finding.associated-risk[].facet[] are separate axes
  * (https://pages.nist.gov/OSCAL/learn/concepts/layer/assessment/assessment-results/) - FedRAMP
  * deviation request types — Risk Adjustment changes impact only, Operational Requirement documents
@@ -3789,8 +3999,9 @@ export interface StandaloneOverride {
      */
     reason: string;
     /**
-     * The ID of the requirement being amended. Must match a requirement ID in the referenced
-     * baseline.
+     * The id of the requirement being amended. An id names the requirement, not one finding, so
+     * the override applies to every requirement entry carrying that id in the baseline(s) it
+     * targets.
      */
     requirementId: string;
     /**
@@ -3798,7 +4009,9 @@ export interface StandaloneOverride {
      */
     signature?: Signature;
     /**
-     * The new status this amendment sets. Optional when only impact is being overridden.
+     * The new status this override sets for the requirement. Optional when only impact is being
+     * overridden; forbidden on an operationalRequirement, which adjudicates nothing, and on a
+     * riskAdjustment, which re-rates impact only.
      */
     status?: ResultStatus;
     /**
@@ -3824,6 +4037,11 @@ export interface HDFEvidencePackage {
      * Description of the evidence package's purpose and scope.
      */
     description?: string;
+    /**
+     * Producer data outside the HDF model, and the pre-converted source artifact(s) this
+     * package was assembled from.
+     */
+    extensions?: Extensions;
     /**
      * References to external native-format evidence (log/telemetry corpora and other artifacts)
      * carried by URI + integrity hash + format discriminator, without recreating the data
@@ -3957,7 +4175,17 @@ export interface ContentReference {
      */
     type: ContentType;
     /**
-     * URI to the document. Can be a relative path or absolute URL.
+     * A uri-reference whose DECODED form is a path relative to the package document's own
+     * directory — that is what the reference MEANS, independently of any one consumer.
+     * Percent-escapes are part of the encoding, not the name: `my%20scans/q4.json` and `my
+     * scans/q4.json` name the same file, and the escaped spelling is the one this field's
+     * format admits. A consumer decodes before it resolves, never after, because decoding can
+     * produce a parent traversal that containment must then see. It is never fetched: there is
+     * no network retrieval anywhere in evidence handling. `uri-reference` admits shapes other
+     * than a relative path and they stay schema-valid; how a consumer resolves one, and what it
+     * does when it cannot, is that consumer's own contract. An artifact deliberately held
+     * elsewhere belongs in externalEvidence[], which references it by URI and checksum without
+     * retrieving it.
      */
     uri: string;
     [property: string]: any;

package/dist/ts/hdf.js

@@ -18,8 +18,14 @@ export var IdentityType;
     IdentityType["Username"] = "username";
 })(IdentityType || (IdentityType = {}));
 /**
- * Supported cryptographic hash algorithms for checksums and integrity verification. blake3 covers
- * container-image and other artifact digests that use it.
+ * Cryptographic hash algorithms a checksum or integrity record may name. blake3 covers
+ * container-image and other artifact digests that use it. HDF tooling verifies every algorithm in
+ * this enum, so any of them may be recorded where the checksum needs to be verifiable. md5 and sha1
+ * are excluded deliberately: a checksum or integrity record exists to detect tampering, and both
+ * are collision-broken, so a digest in either would look verifiable while proving nothing. A source
+ * tool digest in an excluded algorithm is not recorded as a checksum. Admitting weak hashes as an
+ * application-level accept/reject decision was considered and rejected; widening this enum is a
+ * schema decision, not an oversight.
  */
 export var HashAlgorithm;
 (function (HashAlgorithm) {
@@ -28,6 +34,15 @@ export var HashAlgorithm;
     HashAlgorithm["Sha384"] = "sha384";
     HashAlgorithm["Sha512"] = "sha512";
 })(HashAlgorithm || (HashAlgorithm = {}));
+/**
+ * How an embedded copy's bytes are read back: 'utf-8' for text, 'base64' for anything that is not
+ * valid UTF-8 text.
+ */
+export var ExternalReferenceEncoding;
+(function (ExternalReferenceEncoding) {
+    ExternalReferenceEncoding["Base64"] = "base64";
+    ExternalReferenceEncoding["UTF8"] = "utf-8";
+})(ExternalReferenceEncoding || (ExternalReferenceEncoding = {}));
 /**
  * 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.
@@ -146,10 +161,11 @@ export var Version;
  * to 'notApplicable'. The disposition field on the requirement distinguishes false positives from
  * genuinely not-applicable findings. - 'riskAdjustment': impact score adjusted based on
  * environmental context (FedRAMP Risk Adjustment); does not change pass/fail status, only impact
- * via the impact field. - 'operationalRequirement': deviation required by operational constraints
- * (FedRAMP Operational Requirement); the finding cannot be remediated because the system requires
- * the affected functionality. Remains an open risk. Migration note: 'exception' was removed in
- * v3.1.0 — use 'waiver' with status 'notApplicable' instead.
+ * via the impact field; a status on it is rejected by validation. - 'operationalRequirement':
+ * deviation required by operational constraints (FedRAMP Operational Requirement); the finding
+ * cannot be remediated because the system requires the affected functionality. Remains an open
+ * risk. Migration note: 'exception' was removed in v3.1.0 — use 'waiver' with status
+ * 'notApplicable' instead.
  */
 export var OverrideType;
 (function (OverrideType) {
@@ -327,9 +343,8 @@ export var AnnotationCategory;
     AnnotationCategory["Waiver"] = "waiver";
 })(AnnotationCategory || (AnnotationCategory = {}));
 /**
- * The state of this baseline in the comparison.
- *
- * The state of this component in the comparison.
+ * How a baseline or component fared across the compared documents: new (only in the newer), absent
+ * (only in the older), unchanged, or updated (present in both with a changed version).
  */
 export var BaselineDiffState;
 (function (BaselineDiffState) {