@imferno/wasm 3.0.2-beta.1b73397 → 3.0.2-beta.2427eb9

package/types.d.ts

@@ -0,0 +1,1337 @@
+/**
+ * TypeScript declarations for the values imferno passes across the JS boundary.
+ *
+ * Auto-generated by `cargo xtask generate-types-ts` from the Rust types'
+ * JSON Schema (schemars) — do not edit. @imferno/node and @imferno/wasm each
+ * ship their own copy: the WASM build serialises some CPL fields in camelCase.
+ */
+
+/**
+ * A SMPTE IMF UUID, serialised as a bare UUID string (e.g. "0eb3d1b9-b77b-4d3f-bbe5-7c69b15dca85")
+ */
+export type ImfUuid = string;
+/**
+ * Category of validation issue
+ */
+export type Category =
+  | "Structure"
+  | "Schema"
+  | "Reference"
+  | "Asset"
+  | "Timing"
+  | "Encoding"
+  | "Container"
+  | "Audio"
+  | "Video"
+  | "Subtitle"
+  | "Data"
+  | "Metadata"
+  | "Security"
+  | {
+      StudioSpecific: string;
+    };
+/**
+ * Severity level of validation issues
+ */
+export type Severity = "Info" | "Warning" | "Error" | "Critical";
+/**
+ * Which authority produced a validation finding.
+ *
+ * Encodes the "prose vs XSD" provenance distinction that SMPTE ST 2067-3 §5.1 calls out ("the prose document takes precedence on conflict"), so callers can filter, group, or apply per-source severity overrides without inspecting the code string.
+ *
+ * Currently *inferred* from the code prefix on a `ValidationIssue` (see `ValidationIssue::source`) — no engine code needs to set it explicitly. If inference ever becomes ambiguous (e.g. a non-XSD engine internal rule that wants the `XSD/` prefix for catalogue reasons), we can add a `with_source()` builder without changing the public shape.
+ */
+export type IssueSource = "XsdLayer" | "ProseRule" | "EngineInternal";
+/**
+ * Validation profile determining strictness
+ */
+export type ValidationProfile = "Minimal" | "SMPTE" | "Custom";
+export type LanguageString =
+  | string
+  | {
+      $text: string;
+      "@language"?: string | null;
+    };
+export type ContentKindElement =
+  | string
+  | {
+      $text: string;
+      "@scope"?: string | null;
+    };
+/**
+ * Coding equations SMPTE Universal Label, per ST 2067-21:2023 §7.2.3.
+ *
+ * Defines the Y'C'BC'R matrix coefficients. Required for CDCI descriptors; R'G'B' descriptors (COLOR.6) do not use CodingEquations. Byte 8 (registry version) is masked per ST 298M (Architecture Decision 1).
+ */
+export type CodingEquations =
+  | "Bt601"
+  | "Bt709"
+  | "Bt2020Ncl"
+  | {
+      Unknown: string;
+    };
+/**
+ * Color primaries SMPTE Universal Label, per ST 2067-21:2023 §7.2.4 and SMPTE Registers.
+ *
+ * Discriminating bytes are in positions 13-16 of the UL (last 4 bytes of the 16-byte label), with the common prefix `060e2b34.0401XXXX.04010101.03......`. Byte 8 (the registry version) is masked per ST 298M (Architecture Decision 1).
+ */
+export type ColorPrimaries =
+  | "Bt601_625"
+  | "Bt601_525"
+  | "Bt709"
+  | "Bt2020"
+  | "DciP3"
+  | "P3D65"
+  | {
+      Unknown: string;
+    };
+/**
+ * Video codec identified by SMPTE PictureEssenceCoding Universal Label.
+ *
+ * Per ST 2067-21:2023 §7.2.5 and Annex F. The full UL-to-codec mapping lives here. Called once at parse time; no runtime string decoding in downstream crates.
+ *
+ * Note: VideoCodec ULs have varying item-specific bytes, so we match on byte patterns rather than exact 16-byte comparisons. Byte 8 is still masked.
+ */
+export type VideoCodec =
+  | "Jpeg2000"
+  | "Jpeg2000Imf2k"
+  | "Jpeg2000Imf4k"
+  | "Jpeg2000Imf8k"
+  | "Jpeg2000Broadcast"
+  | "Jpeg2000Ht"
+  | "Vc5"
+  | "Mpeg2"
+  | "H264"
+  | "H265"
+  | "ProRes"
+  | "Av1"
+  | {
+      Unknown: string;
+    };
+/**
+ * Opto-electronic transfer function SMPTE Universal Label, per ST 2067-21:2023 §7.2.2.
+ *
+ * Used in `<TransferCharacteristic>` elements in CPL EssenceDescriptors. Byte 8 (registry version) is masked per ST 298M (Architecture Decision 1).
+ */
+export type TransferCharacteristic =
+  | "Linear"
+  | "Bt709"
+  | "Smpte240M"
+  | "XvYcc709"
+  | "Bt2020"
+  | "PqSt2084"
+  | "Hlg"
+  | {
+      Unknown: string;
+    };
+/**
+ * An RFC 5646 language tag, e.g. `"en"`, `"fr-CA"`, `"zh-Hant"`.
+ *
+ * Validation is minimal (non-empty, trimmed). Full BCP 47 validation is out of scope for the parser layer.
+ */
+export type LanguageTag = string;
+/**
+ * MCA (Multi-Channel Audio) tag symbol per SMPTE ST 377-4.
+ *
+ * Used in `<MCATagSymbol>` in `SoundfieldGroupLabelSubDescriptor` and `AudioChannelLabelSubDescriptor`.
+ */
+export type McaTagSymbol =
+  | (
+      | "Left"
+      | "Right"
+      | "Center"
+      | "Lfe"
+      | "LeftSurround"
+      | "RightSurround"
+      | "LeftSideSurround"
+      | "RightSideSurround"
+      | "LeftRearSurround"
+      | "RightRearSurround"
+    )
+  | "Sg51"
+  | "Sg71"
+  | "Sg71Ds"
+  | "SgSt"
+  | "SgMono"
+  | "Iab"
+  | {
+      Other: string;
+    };
+export type MarkerLabelElement =
+  | string
+  | {
+      $text: string;
+      "@scope"?: string | null;
+    };
+/**
+ * The hash algorithm used for a PKL asset digest.
+ *
+ * Per SMPTE ST 2067-2:2020 §9, SHA-1 is the default algorithm. SHA-256 is supported via the `<HashAlgorithm>` element using XML Digital Signature algorithm URIs.
+ */
+export type HashAlgorithm = "Sha1" | "Sha256";
+/**
+ * MIME type as used in `<Type>` elements in PKL assets (SMPTE ST 2067-2 §9).
+ */
+export type MimeType =
+  | "TextXml"
+  | "ApplicationXml"
+  | "ApplicationMxf"
+  | {
+      Other: string;
+    };
+/**
+ * Per-rule severity override.
+ *
+ * Mirrors ESLint's `"off"` / `"warn"` / `"error"` vocabulary, extended with the two IMF severity levels.
+ */
+export type RuleSeverity = "off" | "info" | "warn" | "error" | "critical";
+
+/**
+ * @deprecated
+ * Legacy report summary. Deprecated since v2.3.0.
+ *
+ * Use `ValidationResult` from `validate()` or `Imferno::parse_and_validate()` instead. `ImfReport` is a lossy summary that drops essence descriptors, locales, content versions, and other parsed data from the package.
+ */
+export interface ImfReport {
+  cpls: CplReport[];
+  package: PackageSummary;
+  validation: ValidationReport;
+}
+export interface CplReport {
+  /**
+   * Application profile, e.g. "App2E_2021", "App2E_2014", "App5"
+   */
+  applicationProfile?: string | null;
+  /**
+   * CPL-level edit rate, e.g. "24000/1001"
+   */
+  editRate?: string | null;
+  id: string;
+  /**
+   * True if this CPL references track files not present in the current package (supplemental IMP)
+   */
+  isSupplemental: boolean;
+  markers: CplMarker[];
+  /**
+   * Number of segments in this CPL
+   */
+  segmentCount: number;
+  /**
+   * Virtual tracks (sequences) merged across all segments
+   */
+  sequences: CplSequence[];
+  /**
+   * Timecode start address, e.g. "01:00:00:00"
+   */
+  timecodeStart?: string | null;
+  title: string;
+  /**
+   * Track file UUIDs referenced in this CPL that are not in the current package's AssetMap. These must be resolved from an ancestor package.
+   */
+  unresolvedAncestorAssetIds: string[];
+}
+export interface CplMarker {
+  annotation?: string | null;
+  label: string;
+  offset: number;
+}
+export interface CplSequence {
+  /**
+   * Audio channel count (e.g. 2, 6, 8) — only for audio sequences
+   */
+  channelCount?: number | null;
+  id: string;
+  /**
+   * RFC 5646 language tag extracted from the essence descriptor (e.g. "en", "fr")
+   */
+  language?: string | null;
+  resources: CplResource[];
+  /**
+   * MCA soundfield label (e.g. "5.1", "7.1", "Atmos") — only for audio sequences
+   */
+  soundfield?: string | null;
+  trackId: string;
+  /**
+   * Sequence type: "MainImage", "MainAudio", "Subtitles", etc.
+   */
+  type: string;
+}
+export interface CplResource {
+  /**
+   * Edit rate as "N/D" string, e.g. "24000/1001"
+   */
+  editRate?: string | null;
+  entryPoint?: number | null;
+  id: string;
+  intrinsicDuration: number;
+  sourceDuration?: number | null;
+  sourceEncoding?: string | null;
+  trackFileId?: string | null;
+}
+export interface PackageSummary {
+  assetCount: number;
+  assetMapId: string;
+  cplCount: number;
+  creator?: string | null;
+  issueDate: string;
+  issuer?: string | null;
+  pklCount: number;
+  scmCount: number;
+  sidecarCount: number;
+  unreferencedAssets: UnreferencedAsset[];
+  volumeIndex: number;
+}
+export interface UnreferencedAsset {
+  id: string;
+  path: string;
+}
+/**
+ * Comprehensive validation report
+ */
+export interface ValidationReport {
+  /**
+   * Critical issues that prevent usage
+   */
+  critical: ValidationIssue[];
+  /**
+   * Errors that must be fixed for compliance
+   */
+  errors: ValidationIssue[];
+  /**
+   * Informational issues
+   */
+  info: ValidationIssue[];
+  /**
+   * Whether the package is compliant with base SMPTE standards
+   */
+  is_compliant: boolean;
+  /**
+   * Whether the package is playable despite issues
+   */
+  is_playable: boolean;
+  profile: ValidationProfile;
+  /**
+   * Issues that were suppressed by a `RuleSeverity::Off` override. These are not counted toward `is_playable`/`is_compliant` or surfaced by `has_errors`/`summary` — they exist so operators can debug their `RulesConfig` (`--show-suppressed`) without re-running validation. Each carries a `context["suppressed_by"]` annotation naming the rule key that matched.
+   *
+   * Skipped during serialisation when empty so reports without suppressed rules keep the previous on-wire shape.
+   */
+  suppressed?: ValidationIssue[];
+  /**
+   * Timestamp of validation
+   */
+  timestamp: string;
+  /**
+   * Warnings that should be addressed
+   */
+  warnings: ValidationIssue[];
+}
+/**
+ * A single validation issue
+ */
+export interface ValidationIssue {
+  /**
+   * Other `Location`s when this issue represents an aggregation of multiple identical-code occurrences (see `ValidationReport::aggregate`). Empty for fresh, un-aggregated issues. Skipped during serialisation when empty so the on-wire shape stays back-compatible for callers that don't aggregate.
+   */
+  additional_instances?: Location[];
+  category: Category;
+  /**
+   * Error code (e.g., "ST2067-2:2020:8.3/FileNotFound")
+   */
+  code: string;
+  /**
+   * Additional context
+   */
+  context: {
+    [k: string]: string | undefined;
+  };
+  location: Location;
+  /**
+   * Human-readable message
+   */
+  message: string;
+  severity: Severity;
+  source?: IssueSource;
+  /**
+   * Suggestion for how to fix
+   */
+  suggestion?: string | null;
+}
+/**
+ * Location where the issue was found
+ */
+export interface Location {
+  /**
+   * CPL filename if applicable
+   */
+  cpl_filename?: string | null;
+  /**
+   * CPL UUID if applicable
+   */
+  cpl_id?: ImfUuid | null;
+  /**
+   * CPL content title if applicable
+   */
+  cpl_title?: string | null;
+  /**
+   * File path if applicable
+   */
+  file?: string | null;
+  /**
+   * Line number in XML file
+   */
+  line?: number | null;
+  /**
+   * XPath or field path
+   */
+  path?: string | null;
+  /**
+   * Resource UUID if applicable
+   */
+  resource_id?: string | null;
+  /**
+   * Segment index (0-based)
+   */
+  segment?: number | null;
+  /**
+   * Sequence UUID if applicable
+   */
+  sequence_id?: string | null;
+  /**
+   * Timecode if applicable
+   */
+  timecode?: string | null;
+}
+/**
+ * High-level IMF package representation.
+ *
+ * This is the full parsed package — all CPLs, PKLs, AssetMap, SCMs, and cross-references. Serializable to JSON for WASM/NAPI consumers.
+ */
+export interface Imferno {
+  assetMap: AssetMap;
+  /**
+   * Asset UUID to file path mapping
+   */
+  assetPaths: {
+    [k: string]: string | undefined;
+  };
+  /**
+   * Parsed CPL files mapped by UUID
+   */
+  compositionPlaylists: {
+    [k: string]: CompositionPlaylist | undefined;
+  };
+  /**
+   * Parsed Output Profile Lists mapped by UUID
+   */
+  outputProfileLists: {
+    [k: string]: OutputProfileList | undefined;
+  };
+  /**
+   * Parsed Packing Lists mapped by UUID
+   */
+  packingLists: {
+    [k: string]: PackingList | undefined;
+  };
+  /**
+   * Package root directory
+   */
+  rootPath: string;
+  /**
+   * Parsed Sidecar Composition Maps mapped by UUID (ST 2067-9:2018)
+   */
+  sidecarCompositionMaps: {
+    [k: string]: SidecarCompositionMap | undefined;
+  };
+  volumeIndex: VolumeIndex;
+}
+/**
+ * ASSETMAP.xml — maps UUIDs to physical file paths (ST 429-9 §6).
+ */
+export interface AssetMap {
+  annotationText?: string | null;
+  assetList: AssetList;
+  creator?: string | null;
+  id: ImfUuid;
+  /**
+   * ISO 8601 issue date (e.g. `"2016-10-06T08:35:02-00:00"`).
+   */
+  issueDate: string;
+  issuer?: string | null;
+  volumeCount: number;
+}
+/**
+ * The `<AssetList>` element in ASSETMAP.xml.
+ */
+export interface AssetList {
+  assets: Asset[];
+}
+/**
+ * A single asset entry in ASSETMAP.xml.
+ */
+export interface Asset {
+  chunkList: ChunkList;
+  id: ImfUuid;
+  /**
+   * Present and `true` when this entry refers to the Packing List file.
+   */
+  packingList?: boolean | null;
+}
+/**
+ * A list of file chunks for a single asset.
+ */
+export interface ChunkList {
+  chunks: Chunk[];
+}
+/**
+ * A single file path entry in a ChunkList.
+ */
+export interface Chunk {
+  /**
+   * File path relative to the IMP root directory.
+   */
+  path: string;
+  volumeIndex: number;
+}
+/**
+ * Root CPL structure — defines a complete IMF composition.
+ *
+ * # Spec-required vs `Option<T>` policy (FIX-7 audit)
+ *
+ * The parser is intentionally lenient: every spec-required element that isn't strictly necessary to **construct** a valid `CompositionPlaylist` is exposed as `Option<T>` (or via a `default = "…"` serde attribute). Missing-required-field violations are surfaced as catalogue diagnostics by the validator (`validate_cpl`) rather than as parse errors, so a caller can still inspect the parsed structure of a non-conformant CPL.
+ *
+ * Field-by-field map against ST 2067-3 §6 / §7 (2013 / 2016 — the 2020 edition reuses the 2016 schema verbatim):
+ *
+ * | Field                     | Type             | Spec status                               | |---------------------------|------------------|-------------------------------------------| | `id`                      | `ImfUuid`        | required §6.1 — parse error if missing    | | `annotation`              | `Option<…>`      | optional §6.2                             | | `issue_date`              | `String`         | required §6.3 — parse error if missing    | | `issuer`                  | `Option<…>`      | optional §6.4                             | | `creator`                 | `Option<…>`      | optional §6.5                             | | `content_originator`      | `Option<…>`      | optional §6.6                             | | `content_title`           | `LanguageString` | required §6.7 — parse error if missing    | | `content_kind`            | concrete (default) | required §6.8 — `default_content_kind`  | | `content_version_list`    | `Option<…>`      | optional §6.10                            | | `essence_descriptor_list` | `Option<…>`      | **required** per ST 2067-2 §6.1.5 —       | |                           |                  | parser-lenient; absence is reported by    | |                           |                  | `validate_cpl` as Error                   | | `edit_rate`               | `Option<…>`      | required §6.13 — parser-lenient; absence  | |                           |                  | reported by `validate_cpl`                | | `total_running_time`      | `Option<String>` | optional §6.14                            | | `locale_list`             | `Option<…>`      | optional §6.15                            | | `extension_properties`    | `Option<…>`      | optional §6.16                            | | `composition_timecode`    | `Option<…>`      | optional §6.9                             | | `segment_list`            | `SegmentList`    | required §6.17 — parse error if missing   | | `has_signer`/`has_signature` | `bool`        | reflect presence in raw XML (§8 signatures unparsed) | | `source_xml`              | `Option<String>` | retained when parsed from XML; absent for JSON-deserialised |
+ *
+ * Five fields are spec-required but stored as `Option<T>` (with `default` on the serde side) to support the parser-lenient model: `content_kind` (defaults via `default_content_kind`), `content_version_list`, `essence_descriptor_list`, `edit_rate`, `locale_list`. The validator surfaces missing-required findings against the ST 2067-3 prose.
+ */
+export interface CompositionPlaylist {
+  annotation?: LanguageString | null;
+  compositionTimecode?: CompositionTimecode | null;
+  contentKind?: ContentKindElement;
+  contentOriginator?: LanguageString | null;
+  contentTitle: LanguageString;
+  contentVersionList?: ContentVersionList | null;
+  creator?: LanguageString | null;
+  editRate?: EditRate | null;
+  essenceDescriptorList?: EssenceDescriptorList | null;
+  extensionProperties?: ExtensionProperties | null;
+  id: ImfUuid;
+  issueDate: string;
+  issuer?: LanguageString | null;
+  localeList?: LocaleList | null;
+  segmentList: SegmentList;
+  totalRunningTime?: string | null;
+}
+export interface CompositionTimecode {
+  timecodeDropFrame?: boolean | null;
+  timecodeRate?: number | null;
+  timecodeStartAddress?: string | null;
+}
+export interface ContentVersionList {
+  contentVersions: ContentVersion[];
+}
+export interface ContentVersion {
+  id: string;
+  labelText?: LanguageString | null;
+}
+/**
+ * A rational frame/sample rate as specified in SMPTE ST 2067-3 §6.
+ *
+ * In XML the value is a space-separated pair: `"60000 1001"`. Common values: `24000/1001` (≈23.976), `24/1`, `25/1`, `30/1`, `30000/1001` (≈29.97), `48000/1`, `96000/1`.
+ */
+export interface EditRate {
+  denominator: number;
+  numerator: number;
+}
+export interface EssenceDescriptorList {
+  essenceDescriptors: EssenceDescriptor[];
+}
+export interface EssenceDescriptor {
+  cdciDescriptor?: CDCIDescriptor | null;
+  dcTimedTextDescriptor?: DCTimedTextDescriptor | null;
+  iabEssenceDescriptor?: IABEssenceDescriptor | null;
+  id: ImfUuid;
+  isxdDataEssenceDescriptor?: ISXDDataEssenceDescriptor | null;
+  rgbaDescriptor?: RGBADescriptor | null;
+  wavePCMDescriptor?: WAVEPCMDescriptor | null;
+}
+/**
+ * CDCI video descriptor (YCbCr content)
+ */
+export interface CDCIDescriptor {
+  ActiveHeight?: number | null;
+  ActiveWidth?: number | null;
+  /**
+   * Table 12: AlphaSampleDepth — shall not be present
+   */
+  AlphaSampleDepth?: number | null;
+  /**
+   * Table 8: AlphaTransparency — shall not be present
+   */
+  AlphaTransparency?: string | null;
+  /**
+   * CDCI Descriptor: Black Ref Level (Table 13)
+   */
+  BlackRefLevel?: number | null;
+  CodingEquations?: CodingEquations | null;
+  ColorPrimaries?: ColorPrimaries | null;
+  /**
+   * CDCI Descriptor: Color Range (Table 13)
+   */
+  ColorRange?: number | null;
+  /**
+   * CDCI Descriptor: Color Siting (Table 12) Shall be 0 (CoSiting) but some encoders write a label string (e.g. "CoSiting").
+   */
+  ColorSiting?: number | null;
+  ComponentDepth?: number | null;
+  /**
+   * Generic Picture Essence Descriptor: DisplayF2Offset
+   */
+  DisplayF2Offset?: number | null;
+  DisplayHeight?: number | null;
+  DisplayWidth?: number | null;
+  /**
+   * Table 8: FieldDominance — shall be present if interlaced, shall not be present if progressive
+   */
+  FieldDominance?: number | null;
+  /**
+   * Generic Picture Essence Descriptor: Frame Layout "FullFrame" (00h, progressive) or "SeparateFields" (01h, interlaced)
+   */
+  FrameLayout?: string | null;
+  /**
+   * CDCI Descriptor: Horizontal Subsampling (Table 12) 1 = 4:4:4, 2 = 4:2:2
+   */
+  HorizontalSubsampling?: number | null;
+  /**
+   * Table 8: ImageAlignmentOffset — shall not be present
+   */
+  ImageAlignmentOffset?: number | null;
+  ImageAspectRatio?: string | null;
+  /**
+   * Table 8: ImageEndOffset — shall not be present
+   */
+  ImageEndOffset?: number | null;
+  /**
+   * Table 8: ImageStartOffset — shall not be present
+   */
+  ImageStartOffset?: number | null;
+  InstanceUID?: string | null;
+  LinkedTrackID?: number | null;
+  /**
+   * Table 12: PaddingBits — shall not be present
+   */
+  PaddingBits?: number | null;
+  PictureCompression?: VideoCodec | null;
+  /**
+   * Table 12: ReversedByteOrder — shall not be present
+   */
+  ReversedByteOrder?: string | null;
+  SampleRate?: EditRate | null;
+  /**
+   * Table 8: SampledHeight — shall not be present or shall be equal to StoredHeight
+   */
+  SampledHeight?: number | null;
+  /**
+   * Table 8: SampledWidth — shall not be present or shall be equal to StoredWidth
+   */
+  SampledWidth?: number | null;
+  /**
+   * Table 8: SampledXOffset — shall not be present or shall be 0
+   */
+  SampledXOffset?: number | null;
+  /**
+   * Table 8: SampledYOffset — shall not be present or shall be 0
+   */
+  SampledYOffset?: number | null;
+  /**
+   * Table 8: StoredF2Offset — shall not be present
+   */
+  StoredF2Offset?: number | null;
+  StoredHeight?: number | null;
+  StoredWidth?: number | null;
+  SubDescriptors?: VideoSubDescriptors | null;
+  TransferCharacteristic?: TransferCharacteristic | null;
+  /**
+   * CDCI Descriptor: Vertical Subsampling (Table 12) Shall be 1
+   */
+  VerticalSubsampling?: number | null;
+  /**
+   * CDCI Descriptor: White Ref Level (Table 13)
+   */
+  WhiteRefLevel?: number | null;
+}
+/**
+ * SubDescriptors for video (RGBA/CDCI) descriptors
+ */
+export interface VideoSubDescriptors {
+  /**
+   * JPEG 2000 Picture Sub Descriptor — Table 14 constraints
+   */
+  JPEG2000SubDescriptor?: JPEG2000SubDescriptor | null;
+  /**
+   * Presence indicates Dolby Vision HDR
+   */
+  PHDRMetadataTrackSubDescriptor?: PHDRMetadataTrackSubDescriptor | null;
+}
+/**
+ * JPEG 2000 Picture Sub Descriptor (ST 422 / ST 2067-21 Table 14)
+ */
+export interface JPEG2000SubDescriptor {
+  /**
+   * Table 14: Coding Style — shall be present
+   */
+  CodingStyleDefault?: string | null;
+  /**
+   * Number of components (Csiz)
+   */
+  Csiz?: number | null;
+  InstanceID?: string | null;
+  /**
+   * Table 14: J2CLayout — shall be present (§6.5.2)
+   */
+  J2CLayout?: J2CLayout | null;
+  /**
+   * Table 14: J2KExtendedCapabilities — shall be present if ISO/IEC 15444-15 coding
+   */
+  J2KExtendedCapabilities?: J2KExtendedCapabilities | null;
+  /**
+   * Picture component sizing information
+   */
+  PictureComponentSizing?: PictureComponentSizing | null;
+  /**
+   * Quantization Default
+   */
+  QuantizationDefault?: string | null;
+  /**
+   * Decoder capabilities (Rsiz)
+   */
+  Rsiz?: number | null;
+  /**
+   * Image X offset (XOsiz)
+   */
+  XOsiz?: number | null;
+  /**
+   * Tile X offset (XTOsiz)
+   */
+  XTOsiz?: number | null;
+  /**
+   * Tile width (XTsiz)
+   */
+  XTsiz?: number | null;
+  /**
+   * Image width (Xsiz)
+   */
+  Xsiz?: number | null;
+  /**
+   * Image Y offset (YOsiz)
+   */
+  YOsiz?: number | null;
+  /**
+   * Tile Y offset (YTOsiz)
+   */
+  YTOsiz?: number | null;
+  /**
+   * Tile height (YTsiz)
+   */
+  YTsiz?: number | null;
+  /**
+   * Image height (Ysiz)
+   */
+  Ysiz?: number | null;
+}
+/**
+ * J2CLayout — pixel component layout for JPEG 2000 (§6.5.2)
+ */
+export interface J2CLayout {
+  RGBAComponent?: RGBALayoutComponent[];
+}
+/**
+ * RGBA component entry within J2CLayout or PixelLayout
+ */
+export interface RGBALayoutComponent {
+  /**
+   * Absent in intentionally malformed corpus files (e.g. RGBAError1). Default to empty string so the parser succeeds; the validator flags missing codes.
+   */
+  Code?: string;
+  ComponentSize?: number;
+}
+/**
+ * J2K Extended Capabilities (ISO/IEC 15444-15)
+ */
+export interface J2KExtendedCapabilities {
+  /**
+   * Codestream capabilities (Ccap^i), one UInt16 per Pcap bit set, in increasing order of i (ISO/IEC 15444-1 CAP marker).
+   */
+  Ccapi?: J2KCcapi | null;
+  /**
+   * Profile capabilities (Pcap)
+   */
+  Pcap?: number | null;
+}
+/**
+ * `Ccapi` array of `J2KExtendedCapabilities`.
+ */
+export interface J2KCcapi {
+  UInt16?: number[];
+}
+/**
+ * Picture component sizing information
+ */
+export interface PictureComponentSizing {
+  J2KComponentSizing?: J2KComponentSizing[];
+}
+/**
+ * Individual J2K component sizing
+ */
+export interface J2KComponentSizing {
+  /**
+   * Component bit depth minus 1
+   */
+  Ssiz?: number | null;
+  /**
+   * Horizontal separation of sample
+   */
+  XRSiz?: number | null;
+  /**
+   * Vertical separation of sample
+   */
+  YRSiz?: number | null;
+}
+/**
+ * PHDR (Dolby Vision) metadata track sub-descriptor
+ */
+export interface PHDRMetadataTrackSubDescriptor {
+  InstanceID?: string | null;
+  PHDRMetadataTrackSubDescriptor_DataDefinition?: string | null;
+  PHDRMetadataTrackSubDescriptor_SimplePayloadSID?: number | null;
+  PHDRMetadataTrackSubDescriptor_SourceTrackID?: number | null;
+}
+/**
+ * DC Timed Text descriptor (subtitles/captions)
+ */
+export interface DCTimedTextDescriptor {
+  InstanceID?: string | null;
+  LinkedTrackID?: number | null;
+  NamespaceURI?: string | null;
+  /**
+   * Comma-separated RFC 5646 language tags for this timed text track
+   */
+  RFC5646LanguageTagList?: LanguageTag[];
+  SampleRate?: EditRate | null;
+}
+/**
+ * IAB (Immersive Audio Bitstream) essence descriptor — Dolby Atmos
+ */
+export interface IABEssenceDescriptor {
+  AudioSampleRate?: EditRate | null;
+  ChannelCount?: number | null;
+  /**
+   * ST 2067-201 §5.9: Codec item shall NOT be present.
+   */
+  Codec?: string | null;
+  /**
+   * ST 2067-201 §5.3: ContainerFormat shall be the IAB essence container UL.
+   */
+  ContainerFormat?: string | null;
+  /**
+   * ST 2067-201 §5.9: ElectrospatialFormulation shall NOT be present.
+   */
+  ElectrospatialFormulation?: number | null;
+  InstanceID?: string | null;
+  LinkedTrackID?: number | null;
+  /**
+   * ST 2067-201 §5.9: QuantizationBits shall be 24.
+   */
+  QuantizationBits?: number | null;
+  SampleRate?: EditRate | null;
+  SoundCompression?: string | null;
+  SubDescriptors?: IABSubDescriptors | null;
+}
+/**
+ * SubDescriptors for IAB essence
+ */
+export interface IABSubDescriptors {
+  /**
+   * ST 2067-201:2026 Annex E — IAB Channel SubDescriptor entries. Optional in 2021 (and earlier — silently dropped), recommended in 2026 ("should contain one instance for each channel of each BedDefinition"). Captured as a raw count via a bag struct so downstream code can probe presence without the parser needing to model every field defined in Annex E Table E.1.
+   */
+  IABChannelSubDescriptor?: IABChannelSubDescriptor[];
+  IABSoundfieldLabelSubDescriptor?: IABSoundfieldLabelSubDescriptor | null;
+}
+/**
+ * Presence-only stub for ST 2067-201:2026 Annex E `IABChannelSubDescriptor`.
+ *
+ * The 2026 spec defines the full item set in Table E.1 (`IABBedMetaID`, `IABChannelID`, `IABAudioDescription`, `IABAudioDescriptionText`); imferno's CPL parser only needs to count occurrences to fire the `IabChannelSubDescriptorRecommended` warning, so the inner shape is intentionally permissive — any nested content deserialises into the catch-all map without affecting presence.
+ */
+export interface IABChannelSubDescriptor {
+  /**
+   * Annex E §E.2 — IAB Bed MetaID of the associated BedDefinition.
+   */
+  IABBedMetaID?: number | null;
+  /**
+   * Annex E §E.2 — Channel ID within the bed.
+   */
+  IABChannelID?: number | null;
+}
+/**
+ * IAB soundfield label sub-descriptor — contains language for Atmos tracks
+ */
+export interface IABSoundfieldLabelSubDescriptor {
+  InstanceID?: string | null;
+  /**
+   * ST 2067-201 §5.9: MCALabelDictionaryID shall be `urn:smpte:ul:060e2b34.0401010d.03020221.00000000`.
+   */
+  MCALabelDictionaryID?: string | null;
+  MCATagName?: string | null;
+  MCATagSymbol?: McaTagSymbol | null;
+  RFC5646SpokenLanguage?: LanguageTag | null;
+}
+/**
+ * ISXD (Immersive Sound XML Data) essence descriptor — Dolby Atmos sidecar format
+ */
+export interface ISXDDataEssenceDescriptor {
+  DataEssenceCoding?: string | null;
+  InstanceID?: string | null;
+  LinkedTrackID?: number | null;
+  NamespaceURI?: string | null;
+  SampleRate?: EditRate | null;
+  SubDescriptors?: IsxdSubDescriptors | null;
+}
+/**
+ * SubDescriptors for ISXD essence descriptor
+ */
+export interface IsxdSubDescriptors {
+  /**
+   * ST 2067-202: ContainerConstraintsSubDescriptor shall be present.
+   */
+  ContainerConstraintsSubDescriptor?: ContainerConstraintsSubDescriptor | null;
+}
+/**
+ * ContainerConstraintsSubDescriptor — presence required by ST 2067-202 §5
+ */
+export interface ContainerConstraintsSubDescriptor {
+  InstanceID?: string | null;
+}
+/**
+ * RGBA video descriptor (JPEG 2000 RGB content)
+ */
+export interface RGBADescriptor {
+  /**
+   * Table 10: AlphaMaxRef — shall not be present
+   */
+  AlphaMaxRef?: number | null;
+  /**
+   * Table 10: AlphaMinRef — shall not be present
+   */
+  AlphaMinRef?: number | null;
+  /**
+   * Table 8: AlphaTransparency — shall not be present
+   */
+  AlphaTransparency?: string | null;
+  CodingEquations?: CodingEquations | null;
+  ColorPrimaries?: ColorPrimaries | null;
+  /**
+   * RGBA Descriptor: Component Max Ref (Table 10/11)
+   */
+  ComponentMaxRef?: number | null;
+  /**
+   * RGBA Descriptor: Component Min Ref (Table 10/11)
+   */
+  ComponentMinRef?: number | null;
+  /**
+   * Generic Picture Essence Descriptor: DisplayF2Offset
+   */
+  DisplayF2Offset?: number | null;
+  DisplayHeight?: number | null;
+  DisplayWidth?: number | null;
+  /**
+   * Table 8: FieldDominance — shall be present if interlaced, shall not be present if progressive
+   */
+  FieldDominance?: number | null;
+  /**
+   * Generic Picture Essence Descriptor: Frame Layout "FullFrame" (00h, progressive) or "SeparateFields" (01h, interlaced)
+   */
+  FrameLayout?: string | null;
+  /**
+   * Table 8: ImageAlignmentOffset — shall not be present
+   */
+  ImageAlignmentOffset?: number | null;
+  ImageAspectRatio?: string | null;
+  /**
+   * Table 8: ImageEndOffset — shall not be present
+   */
+  ImageEndOffset?: number | null;
+  /**
+   * Table 8: ImageStartOffset — shall not be present
+   */
+  ImageStartOffset?: number | null;
+  InstanceID?: string | null;
+  LinkedTrackID?: number | null;
+  /**
+   * Table 10: Palette — shall not be present
+   */
+  Palette?: string | null;
+  /**
+   * Table 10: PaletteLayout — shall not be present
+   */
+  PaletteLayout?: string | null;
+  PictureCompression?: VideoCodec | null;
+  SampleRate?: EditRate | null;
+  /**
+   * Table 8: SampledHeight — shall not be present or shall be equal to StoredHeight
+   */
+  SampledHeight?: number | null;
+  /**
+   * Table 8: SampledWidth — shall not be present or shall be equal to StoredWidth
+   */
+  SampledWidth?: number | null;
+  /**
+   * Table 8: SampledXOffset — shall not be present or shall be 0
+   */
+  SampledXOffset?: number | null;
+  /**
+   * Table 8: SampledYOffset — shall not be present or shall be 0
+   */
+  SampledYOffset?: number | null;
+  /**
+   * RGBA Descriptor: Scanning Direction (Table 10) Shall be "ScanningDirection_LeftToRightTopToBottom" (00h)
+   */
+  ScanningDirection?: string | null;
+  /**
+   * Table 8: StoredF2Offset — shall not be present
+   */
+  StoredF2Offset?: number | null;
+  StoredHeight?: number | null;
+  StoredWidth?: number | null;
+  SubDescriptors?: VideoSubDescriptors | null;
+  TransferCharacteristic?: TransferCharacteristic | null;
+}
+/**
+ * WAVE PCM audio descriptor
+ */
+export interface WAVEPCMDescriptor {
+  AudioSampleRate?: EditRate | null;
+  ChannelCount?: number | null;
+  InstanceID?: string | null;
+  LinkedTrackID?: number | null;
+  QuantizationBits?: number | null;
+  SampleRate?: EditRate | null;
+  SubDescriptors?: AudioSubDescriptors | null;
+}
+/**
+ * SubDescriptors for audio (WAVEPCMDescriptor)
+ */
+export interface AudioSubDescriptors {
+  SoundfieldGroupLabelSubDescriptor?: SoundfieldGroupLabelSubDescriptor | null;
+}
+/**
+ * Soundfield group label sub-descriptor — contains language and audio content kind
+ */
+export interface SoundfieldGroupLabelSubDescriptor {
+  MCAAudioContentKind?: string | null;
+  MCATagName?: string | null;
+  MCATagSymbol?: McaTagSymbol | null;
+  /**
+   * RFC 5646 language tag — field name varies between vendors
+   */
+  RFC5646SpokenLanguage?: LanguageTag | null;
+}
+export interface ExtensionProperties {
+  applicationIdentification?: string | null;
+  maxCLL?: number | null;
+  maxFALL?: number | null;
+}
+/**
+ * LocaleList - Content locale information
+ */
+export interface LocaleList {
+  locales?: Locale[];
+}
+export interface Locale {
+  contentMaturityRatingList?: ContentMaturityRatingList | null;
+  languageList?: LanguageList | null;
+  regionList?: RegionList | null;
+}
+export interface ContentMaturityRatingList {
+  contentMaturityRatings: ContentMaturityRating[];
+}
+/**
+ * A single content maturity rating entry per ST 2067-3 / ST 2067-21 §5.1.3.
+ */
+export interface ContentMaturityRating {
+  agency: string;
+  audience?: AudienceElement | null;
+  rating?: string | null;
+}
+/**
+ * The `<Audience>` element carries an optional `scope` attribute.
+ */
+export interface AudienceElement {
+  $text?: string | null;
+  "@scope"?: string | null;
+}
+export interface LanguageList {
+  languages: LanguageTag[];
+}
+export interface RegionList {
+  regions: string[];
+}
+export interface SegmentList {
+  segments?: Segment[];
+}
+export interface Segment {
+  id: ImfUuid;
+  sequenceList: SequenceList;
+}
+export interface SequenceList {
+  forcedNarrativeSequences?: ForcedNarrativeSequence[];
+  hearingImpairedCaptionsSequences?: HearingImpairedCaptionsSequence[];
+  iabSequences?: IABSequence[];
+  isxdSequences?: ISXDSequence[];
+  mainAudioSequences?: MainAudioSequence[];
+  mainImageSequences?: MainImageSequence[];
+  markerSequences?: MarkerSequence[];
+  subtitlesSequences?: SubtitlesSequence[];
+}
+export interface ForcedNarrativeSequence {
+  id: ImfUuid;
+  resourceList: ResourceList;
+  trackId: ImfUuid;
+}
+export interface ResourceList {
+  resources?: Resource[];
+}
+export interface Resource {
+  annotation?: LanguageString | null;
+  editRate?: EditRate | null;
+  entryPoint?: number | null;
+  hash?: string | null;
+  id: ImfUuid;
+  intrinsicDuration: number;
+  keyId?: ImfUuid | null;
+  markers?: MarkerInfo[];
+  repeatCount?: number | null;
+  sourceDuration?: number | null;
+  sourceEncoding?: ImfUuid | null;
+  trackFileId?: ImfUuid | null;
+}
+export interface MarkerInfo {
+  annotation?: string | null;
+  label: MarkerLabelElement;
+  offset: number;
+}
+export interface HearingImpairedCaptionsSequence {
+  id: ImfUuid;
+  resourceList: ResourceList;
+  trackId: ImfUuid;
+}
+export interface IABSequence {
+  id: ImfUuid;
+  resourceList: ResourceList;
+  trackId: ImfUuid;
+}
+export interface ISXDSequence {
+  id: ImfUuid;
+  resourceList: ResourceList;
+  trackId: ImfUuid;
+}
+export interface MainAudioSequence {
+  id: ImfUuid;
+  resourceList: ResourceList;
+  trackId: ImfUuid;
+}
+export interface MainImageSequence {
+  id: ImfUuid;
+  resourceList: ResourceList;
+  trackId: ImfUuid;
+}
+export interface MarkerSequence {
+  id: ImfUuid;
+  resourceList: ResourceList;
+  trackId: ImfUuid;
+}
+export interface SubtitlesSequence {
+  id: ImfUuid;
+  resourceList: ResourceList;
+  trackId: ImfUuid;
+}
+/**
+ * OPL XML — Output Profile List (SMPTE ST 2067-100).
+ *
+ * Defines output processing instructions for a composition: image scaling, cropping, pixel encoding, and audio routing/mixing macros.
+ *
+ * `macros` carries every `<Macro xsi:type="...">` entry from the `<MacroList>`. The list is structurally extracted via a small `quick_xml` walker rather than serde because the XSD uses `xsi:type` polymorphism with vendor-specific extension namespaces (`opl:PresetMacroType`, `arm:AudioRoutingMixingMacroType`, etc.). Type-specific payload fields land in `OplMacro::extra_fields` as `(local_name, text)` pairs so the parser doesn't have to know every macro subtype to round-trip the list.
+ */
+export interface OutputProfileList {
+  annotation?: string | null;
+  compositionPlaylistId: ImfUuid;
+  creator?: string | null;
+  id: ImfUuid;
+  /**
+   * ISO 8601 issue date.
+   */
+  issueDate: string;
+  issuer?: string | null;
+  /**
+   * Each `<Macro xsi:type="...">` entry from the `<MacroList>`. Empty when the OPL has no macros (or has `<MacroList/>`).
+   */
+  macros?: OplMacro[];
+}
+/**
+ * A single macro entry from an OPL `<MacroList>`.
+ *
+ * Captures the polymorphic `xsi:type` attribute plus the common `Name` / `Annotation` fields from the abstract `MacroType`. All other children of the macro are stored as `(local_name, text)` pairs in `Self::extra_fields` so that vendor-specific extensions remain accessible without the parser knowing each subtype.
+ */
+export interface OplMacro {
+  /**
+   * `MacroType.Annotation` (optional, §6.5.2).
+   */
+  annotation?: string | null;
+  /**
+   * Every other direct-child element of the `<Macro>` element, as `(local_name, text_body)`. Element nesting deeper than one level is flattened into the outermost name with the joined text body — callers that need structured access to nested macro extensions should re-parse the OPL with a richer model.
+   */
+  extraFields: [string, string][];
+  /**
+   * `MacroType.Name` per ST 2067-100 §6.5.1; required by the XSD.
+   */
+  name: string;
+  /**
+   * Value of the `xsi:type` attribute, e.g. `"opl:PresetMacroType"`. `None` when the writer omitted the attribute (non-conformant, but we don't reject — the validator can flag it).
+   */
+  xsiType?: string | null;
+}
+/**
+ * PKL XML — Packing List (SMPTE ST 2067-2 §9).
+ *
+ * Assets carry SHA-1 (default) or SHA-256 checksums. The algorithm is determined by the optional `<HashAlgorithm>` element on each asset.
+ */
+export interface PackingList {
+  annotationText?: string | null;
+  assetList: PklAssetList;
+  creator?: string | null;
+  /**
+   * Optional group identifier for partial deliveries (SMPTE ST 2067-2 §9).
+   */
+  groupId?: ImfUuid | null;
+  id: ImfUuid;
+  /**
+   * ISO 8601 issue date.
+   */
+  issueDate: string;
+  issuer?: string | null;
+}
+/**
+ * The `<AssetList>` element in a PKL.
+ */
+export interface PklAssetList {
+  assets: PklAsset[];
+}
+/**
+ * A single asset entry in a PKL.
+ */
+export interface PklAsset {
+  annotationText?: string | null;
+  hash: AssetHash;
+  id: ImfUuid;
+  mimeType: MimeType;
+  originalFileName?: string | null;
+  /**
+   * File size in bytes.
+   */
+  size: number;
+}
+/**
+ * A decoded asset hash from a Packing List, per SMPTE ST 2067-2 §9.
+ *
+ * PKL files carry base64-encoded SHA-1 or SHA-256 digests for each tracked asset.
+ */
+export interface AssetHash {
+  algorithm: HashAlgorithm;
+  bytes: number[];
+}
+/**
+ * A parsed Sidecar Composition Map document (ST 2067-9:2018).
+ *
+ * Field naming flattens the XSD's `<Properties>` wrapper into the top-level struct; on the wire the document still carries `<Properties>{Annotation,IssueDate,Issuer}</Properties>` per ST 2067-9:2018 §7.2 Table 2.
+ */
+export interface SidecarCompositionMap {
+  annotation?: string | null;
+  /**
+   * True if a `<Signature>` element was present (§7.2.5).
+   */
+  hasSignature: boolean;
+  /**
+   * True if a `<Signer>` element was present (§7.2.4).
+   */
+  hasSigner: boolean;
+  id: ImfUuid;
+  issueDate: string;
+  issuer?: string | null;
+  /**
+   * Sidecar asset associations.
+   */
+  sidecarAssets: SidecarAsset[];
+}
+/**
+ * A single sidecar asset association within an SCM document.
+ */
+export interface SidecarAsset {
+  /**
+   * CPLs this sidecar asset is associated with (§7.3.1.1: one or more).
+   */
+  cplIds: ImfUuid[];
+  id: ImfUuid;
+}
+/**
+ * VOLINDEX document (SMPTE ST 2067-9 §5 / ST 429-9:2014).
+ *
+ * In practice this is always `<Index>1</Index>` for single-volume IMF packages. The spec allows multi-volume packages but they are rarely used.
+ */
+export interface VolumeIndex {
+  /**
+   * The volume count. Almost always `1`.
+   */
+  index: number;
+}
+/**
+ * ESLint-style per-rule severity overrides.
+ *
+ * Keys are either: - A rule suffix — `"SegmentDuration"` — matched against the part of the issue code after the last `/`. - A full normalised code — `"ST2067-3:2020:7.2.2/SegmentDuration"`.
+ *
+ * Values are the desired `RuleSeverity`, or `RuleSeverity::Off` to suppress the rule entirely.
+ *
+ * An empty map (the default) is a no-op.
+ */
+export interface RulesConfig {
+  [k: string]: RuleSeverity | undefined;
+}
+/**
+ * Result of parsing and validating an IMF package.
+ *
+ * This is the primary return type — contains the full parsed package and all validation findings.
+ */
+export interface ValidationResult {
+  package: Imferno;
+  validation: ValidationReport;
+}
+
+/** Core constraints (ST 2067-2) edition to validate against. `"auto"` detects it from the CPL. */
+export type CoreSpec = "auto" | "v2013" | "v2016" | "v2020";
+
+/**
+ * App #2E (ST 2067-21) edition to validate against. `"auto"` uses the CPL's
+ * ApplicationIdentification; `"none"` skips application-profile validation.
+ */
+export type App2eSpec = "auto" | "none" | "v2014" | "v2016" | "v2020" | "v2023" | "v2026";
+
+/** Options accepted by every validating entry point. */
+export interface ValidateOptions {
+  /** Core constraints edition. Default: `"auto"`. */
+  coreSpec?: CoreSpec;
+  /** App #2E edition. Default: `"auto"`. */
+  app2eSpec?: App2eSpec;
+  /** ESLint-style per-rule severity overrides, keyed by code, rule suffix, glob or `source:<kind>`. */
+  rules?: RulesConfig;
+  /** Collapse repeated identical findings into one issue with `additional_instances`. Default: `false`. */
+  aggregateRepeats?: boolean;
+}