uima.ts

// ═══════════════════════════════════════════════════════════════════════════
// @amlhubs/uima — OASIS UIMA 1.0 (2009) Component Descriptor Metamodel
// Unstructured Information Management Architecture
// (OASIS standard ratified 2009; Apache UIMA 3.6.x reference implementation;
//  also published as ISO/IEC 24618 Information Technology — UIMA framework)
//
// Scope: the OASIS UIMA 1.0 Component Descriptor metamodel + the Apache UIMA
// reference-implementation surface needed for downstream NLP-pipeline
// metamodel consumers (LMF, MAF, LAF, SemAF, OntoLex). Surfaces every
// metaclass declared by the OASIS UIMA 1.0 specification across its seven
// chapters of formal model:
//
//   - Type System Description (§3.2 + §4.2 + §6 + Apache references)
//       TypeSystemDescription, TypeDescription, FeatureDescription,
//       AllowedValue, Import, TypePriorities, TypePriorityList, TypeOrFeature
//
//   - Common Analysis Structure (§3.1 + §4.1)
//       CAS, View, Sofa, FeatureStructure, AnnotationFS, ArrayFS, ListFS,
//       FSIndex, FSIndexDescription, FSIndexCollection, FSIterator
//
//   - Base Type System (§3.3 + §4.3)
//       BaseType, SourceDocumentInformation, AnnotationBase, TextAnnotation,
//       TemporalAnnotation, Referent, AnnotationMetadata, Provenance,
//       AnchoredView, SofaReference, LocalSofaReference, RemoteSofaReference
//
//   - Abstract Interfaces (§3.4 + §4.4)
//       ProcessingElement, Analytic, Analyzer, CasMultiplier, FlowController,
//       Step
//
//   - Behavioral Metadata / Capabilities (§3.5 + §4.5)
//       BehavioralMetadata, Capability, Condition, TypeOrFeatureRef
//
//   - Processing Element Metadata (§3.6 + §4.6)
//       ProcessingElementMetadata, IdentificationInfo, ConfigurationParameter,
//       ConfigurationParameterDeclarations, ConfigurationParameterSettings,
//       ConfigurationGroup, NameValuePair, Extension
//
//   - Analysis Engine Descriptors (Apache UIMA 3.x — derived from §4.6)
//       AnalysisEngineDescription, PrimitiveAnalysisEngineDescription,
//       AggregateAnalysisEngineDescription, AnalysisEngineMetaData,
//       FlowControllerDescription, FlowConstraints, FixedFlow,
//       CapabilityLanguageFlow
//
//   - Auxiliary Components (Apache UIMA 3.x — derived from §3.4 + §4.4)
//       CollectionReaderDescription, CASConsumerDescription,
//       CASMultiplierDescription, CASInitializerDescription,
//       CollectionProcessingEngine
//
//   - Resource Manager + External Resources (Apache UIMA 3.x — §4.6 substrate)
//       ResourceManagerConfiguration, ResourceSpecifier,
//       ExternalResourceDescription, ExternalResourceBinding,
//       FileResourceSpecifier, RelativePathResourceSpecifier
//
//   - Operational Properties (Apache UIMA 3.x — §4.5 derivation)
//       OperationalProperties (with modifiesCas, multipleDeploymentAllowed,
//       outputsNewCASes attributes)
//
//   - Service WSDL (§3.7 + §4.7)
//       ServiceWSDLDescription, DeltaResponse
//
// Architectural ordering:
//   UML 2.5.1 (@amlhubs/uml) ──┐
//                              ├──► UIMA Component Descriptor Metamodel
//   MOF 2.5.1 (@amlhubs/mof) ──┤    (this file, @amlhubs/uima)
//   XMI 2.5.1 (@amlhubs/xmi) ──┘
//
// Out of scope for 0.0.1:
//   - UIMA-AS (Asynchronous Scaleout) — separate @amlhubs/uima-as candidate
//   - Apache Ruta (Rule-based Text Annotation) — separate @amlhubs/uima-ruta
//   - Apache UIMA DUCC (Distributed UIMA Cluster Computing) — out of metamodel
//   - JCas Java code generation — downstream tooling
//
// Citation discipline: every metaclass carries JSDoc with @standard, @chapter,
// @section, @metaclass, @generalization, @definition, @ownedAttributes,
// @associationEnds, @operations, @constraints reproduced from
// OASIS UIMA 1.0 (2009) and the Apache UIMA 3.6.x reference implementation
// (uima.apache.org/d/uimaj-current/references.html).
// ═══════════════════════════════════════════════════════════════════════════

import type {
  IElement,
  IPackage,
  IClass,
  IDataType,
  IPrimitiveType,
  IProperty,
  IAssociation,
  INamedElement,
  IClassifier,
  IConstraint,
  ITypedElement,
  IMultiplicityElement,
  IEnumeration,
  IEnumerationLiteral,
} from '@amlhubs/uml';

// suppress “unused import” diagnostics during the empty-skeleton phase;
// implementer subagents will consume each of these symbols.
type _UmlAnchor =
  | IElement
  | IPackage
  | IClass
  | IDataType
  | IPrimitiveType
  | IProperty
  | IAssociation
  | INamedElement
  | IClassifier
  | IConstraint
  | ITypedElement
  | IMultiplicityElement
  | IEnumeration
  | IEnumerationLiteral;
export type { _UmlAnchor as UmlAnchor };

// ═══════════════════════════════════════════════════════════════════════════
// UIMA METACLASSES — INTERFACES (Layer 1)
// ═══════════════════════════════════════════════════════════════════════════

// ─────────────────────────────────────────────────────────────────────────────
// SUBSTRATE — UIMABase Root
// ─────────────────────────────────────────────────────────────────────────────

// --- 1. IUIMABase --- ABSOLUTE ROOT
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @section §3 — Elements of the UIMA Specification
 * @metaclass abstract
 * @generalization (root -- no parent)
 * @definition UIMABase is the absolute root of every metaclass surfaced by
 *   @amlhubs/uima. Every UIMA metaclass extends UIMABase directly or
 *   transitively. UIMABase carries the universal identity attribute
 *   (`elementId`) that lets every consumer of a UIMA-compliant instance
 *   address any metaclass instance unambiguously across XMI serializations,
 *   CAS dumps, and descriptor XML files.
 * @ownedAttributes
 *   elementId : String [1] -- machine-readable identifier, unique within the
 *     enclosing UIMA artifact (descriptor, CAS, type-system file)
 * @constraints
 *   [unique_id]: every UIMABase instance has an elementId unique within its
 *     enclosing artifact.
 */
export interface IUIMABase {
  readonly elementId: string;
}

// ─────────────────────────────────────────────────────────────────────────────
// TYPE SYSTEM DESCRIPTION (§3.2 + §4.2 + §6)
// ─────────────────────────────────────────────────────────────────────────────

// --- 2. ITypeSystemDescription (§4.2 + §6) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.2 The Type System Model
 * @section §6 Type System Description
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition TypeSystemDescription is the declarative XML representation of
 *   a UIMA Type System. It enumerates every TypeDescription declared by the
 *   enclosing component (Analysis Engine, Collection Reader, CAS Consumer,
 *   CAS Multiplier, Flow Controller) and references imported Type System
 *   Descriptions through Import elements. The Type System defines the
 *   permissible structure of FeatureStructure instances stored in any CAS
 *   processed by the component.
 * @ownedAttributes
 *   name        : String [0..1] -- human-readable type-system name
 *   description : String [0..1] -- human-readable summary
 *   version     : String [0..1] -- type-system version identifier
 *   vendor      : String [0..1] -- type-system author/vendor
 * @associationEnds
 *   types   : TypeDescription [0..*] {composite} -- the declared types
 *   imports : Import          [0..*] {composite} -- imported type systems
 * @constraints
 *   [unique_type_names]: every TypeDescription in `types` has a unique
 *     fully-qualified `typeName`.
 *   [acyclic_inheritance]: the supertypeName edges over `types` form a DAG.
 *   [import_resolvable]: every Import element resolves to a syntactically
 *     valid TypeSystemDescription.
 */
export interface ITypeSystemDescription extends IUIMABase {
  readonly name: string | undefined;
  readonly description: string | undefined;
  readonly version: string | undefined;
  readonly vendor: string | undefined;
  readonly typeIds: ReadonlyArray<string>;
  readonly importIds: ReadonlyArray<string>;
}

// --- 3. ITypeDescription (§4.2 + §6.2) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.2 The Type System Model
 * @section §6.2 Type Description
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition TypeDescription declares a single Type in a UIMA Type System.
 *   A Type is the schema for a class of FeatureStructure instances; it has a
 *   fully-qualified name, a single supertype (the inheritance edge),
 *   zero-or-more Features (the structural slots), and zero-or-more
 *   AllowedValues (only when supertype = uima.cas.String, i.e., a typed
 *   string enumeration).
 * @ownedAttributes
 *   typeName        : String [1] -- fully-qualified UIMA type name
 *     (e.g., "uima.tcas.Annotation", "org.example.Phrase")
 *   supertypeName   : String [1] -- fully-qualified parent type name
 *   description     : String [0..1] -- human-readable type summary
 * @associationEnds
 *   features       : FeatureDescription [0..*] {composite}
 *   allowedValues  : AllowedValue      [0..*] {composite, only when
 *                                              supertypeName = uima.cas.String}
 * @constraints
 *   [valid_type_name]: typeName matches the UIMA fully-qualified name regex
 *     `[A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)*`.
 *   [supertype_exists]: supertypeName resolves to a Type either built-in or
 *     declared in the same TypeSystemDescription (transitively through Imports).
 *   [allowed_values_iff_string]: allowedValues is non-empty if and only if
 *     supertypeName is "uima.cas.String".
 */
export interface ITypeDescription extends IUIMABase {
  readonly typeName: string;
  readonly supertypeName: string;
  readonly description: string | undefined;
  readonly featureIds: ReadonlyArray<string>;
  readonly allowedValueIds: ReadonlyArray<string>;
}

// --- 4. IFeatureDescription (§4.2 + §6.3) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.2 The Type System Model
 * @section §6.3 Feature Description
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition FeatureDescription declares a single Feature on a parent
 *   TypeDescription. A Feature is a typed slot on a FeatureStructure: it has
 *   a name (unique within the declaring Type), a rangeTypeName (the Type of
 *   values stored in the slot), an optional elementType (when rangeType is a
 *   collection — Array, List), and a multipleReferencesAllowed flag (controls
 *   XMI shared-reference serialization for collection-typed features).
 * @ownedAttributes
 *   name                       : String  [1] -- feature name, unique within
 *                                               the parent Type
 *   description                : String  [0..1] -- human-readable summary
 *   rangeTypeName              : String  [1] -- fully-qualified range Type
 *   elementType                : String  [0..1] -- element Type when range is
 *                                                  ArrayFS / ListFS / FSArray
 *   multipleReferencesAllowed  : Boolean [0..1] -- XMI shared-reference flag
 *                                                  (defaults to false)
 * @associationEnds
 *   parentType : TypeDescription [1] {opposite features}
 * @constraints
 *   [unique_within_type]: name is unique among the FeatureDescriptions of
 *     parentType.
 *   [range_resolvable]: rangeTypeName resolves to a declared or built-in Type.
 *   [element_iff_collection]: elementType is non-empty if and only if
 *     rangeTypeName denotes a UIMA collection type (FSArray, FSList,
 *     IntegerArray, FloatArray, StringArray, BooleanArray, ByteArray,
 *     ShortArray, LongArray, DoubleArray, IntegerList, FloatList, StringList,
 *     EmptyFSList, NonEmptyFSList, EmptyIntegerList, NonEmptyIntegerList,
 *     EmptyFloatList, NonEmptyFloatList, EmptyStringList, NonEmptyStringList).
 */
export interface IFeatureDescription extends IUIMABase {
  readonly name: string;
  readonly description: string | undefined;
  readonly rangeTypeName: string;
  readonly elementType: string | undefined;
  readonly multipleReferencesAllowed: boolean | undefined;
  readonly parentTypeId: string;
}

// --- 5. IAllowedValue (§4.2 + §6.4) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.2 The Type System Model
 * @section §6.4 Allowed Value
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition AllowedValue declares a single permissible string value for a
 *   typed-string enumeration TypeDescription. AllowedValues are admissible
 *   only when the parent TypeDescription's supertypeName is "uima.cas.String"
 *   — they convert an open string Type into a closed enumeration.
 * @ownedAttributes
 *   string      : String [1] -- the permissible literal value
 *   description : String [0..1] -- human-readable summary of the value
 * @associationEnds
 *   parentType : TypeDescription [1] {opposite allowedValues}
 * @constraints
 *   [string_required]: string->notEmpty()
 *   [parent_is_string_enum]: parentType.supertypeName = "uima.cas.String".
 *   [unique_within_type]: string is unique among the AllowedValues of
 *     parentType.
 */
export interface IAllowedValue extends IUIMABase {
  readonly string: string;
  readonly description: string | undefined;
  readonly parentTypeId: string;
}

// --- 6. IImport (§4.2 + §6.5) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.2 The Type System Model
 * @section §6.5 Import
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition Import references an external TypeSystemDescription (or
 *   FsIndexCollection, TypePriorities, ResourceManagerConfiguration) that
 *   contributes its declarations to the importing component. The Import
 *   element supports two mutually-exclusive resolution modes: by-location
 *   (relative URL) or by-name (Java-style dotted name resolved against the
 *   data path).
 * @ownedAttributes
 *   location : String [0..1] -- relative URL of the imported XML descriptor
 *   name     : String [0..1] -- Java-style dotted name resolved against the
 *                               UIMA data path
 * @constraints
 *   [exactly_one_resolution]: exactly one of location or name is non-empty.
 *   [location_is_relative]: when location is set, it MUST be a relative URL
 *     (per §6.5).
 */
export interface IImport extends IUIMABase {
  readonly location: string | undefined;
  readonly name: string | undefined;
}

// --- 7. ITypePriorities (§4.2 + §6.6) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.2 The Type System Model
 * @section §6.6 Type Priorities
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition TypePriorities is the descriptor element that orders Types for
 *   FSIndex iteration. When two FeatureStructures of related-but-not-equal
 *   Types compare equal under an FSIndex sort key, the TypePriorities
 *   determine which Type sorts first. A TypePriorities groups one-or-more
 *   TypePriorityList instances; each list defines a strict total order over
 *   the Types it enumerates.
 * @ownedAttributes
 *   name        : String [0..1] -- human-readable priorities name
 *   description : String [0..1] -- human-readable summary
 *   version     : String [0..1] -- priorities-block version identifier
 *   vendor      : String [0..1] -- author/vendor
 * @associationEnds
 *   priorityLists : TypePriorityList [0..*] {composite}
 *   imports       : Import           [0..*] {composite}
 */
export interface ITypePriorities extends IUIMABase {
  readonly name: string | undefined;
  readonly description: string | undefined;
  readonly version: string | undefined;
  readonly vendor: string | undefined;
  readonly priorityListIds: ReadonlyArray<string>;
  readonly importIds: ReadonlyArray<string>;
}

// --- 8. ITypePriorityList (§4.2 + §6.6) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.2 The Type System Model
 * @section §6.6 Type Priorities
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition TypePriorityList is an ordered enumeration of fully-qualified
 *   Type names. The list defines a strict total order: an earlier entry has
 *   higher priority than a later entry. UIMA FSIndex iteration uses this
 *   order to break ties between FeatureStructures of related Types that
 *   would otherwise compare equal under the index sort key.
 * @ownedAttributes
 *   typeNames : String [1..*] {ordered} -- ordered list of fully-qualified
 *                                          Type names
 * @associationEnds
 *   parentPriorities : TypePriorities [1] {opposite priorityLists}
 * @constraints
 *   [non_empty]: typeNames->size() >= 1.
 *   [no_duplicates]: typeNames->isUnique(self).
 */
export interface ITypePriorityList extends IUIMABase {
  readonly typeNames: ReadonlyArray<string>;
  readonly parentPrioritiesId: string;
}

// --- 9. ITypeOrFeature (§4.5 + §4.6) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.5 Behavioral Metadata
 * @section §4.6 Processing Element Metadata
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition TypeOrFeature is a discriminated reference used in Capabilities
 *   declarations to enumerate the Types and Features a component reads,
 *   modifies, creates, or deletes. The discriminator (`isType`) selects
 *   between a whole-Type reference (when true) and a single-Feature reference
 *   (when false).
 * @ownedAttributes
 *   isType : Boolean [1] -- true if `name` references a Type, false if it
 *                           references a Feature
 *   name   : String  [1] -- fully-qualified Type name (when isType = true)
 *                           or fully-qualified Type::Feature name (false)
 * @constraints
 *   [valid_name]: when isType = true, name matches the Type fully-qualified
 *     regex; when isType = false, name matches `Type:Feature` syntax.
 */
export interface ITypeOrFeature extends IUIMABase {
  readonly isType: boolean;
  readonly name: string;
}

// ═══════════════════════════════════════════════════════════════════════════
// UIMA METACLASSES — CLASSES (implementation)
// ═══════════════════════════════════════════════════════════════════════════

/** @standard OASIS UIMA 1.0 (2009) §3 — abstract root class implementation. */
export abstract class UIMABase implements IUIMABase {
  readonly elementId: string;
  protected constructor(data: { elementId: string }) {
    this.elementId = data.elementId;
  }
}

/** @standard OASIS UIMA 1.0 (2009) §4.2 + §6 — concrete class implementation. */
export class TypeSystemDescription extends UIMABase implements ITypeSystemDescription {
  readonly name: string | undefined;
  readonly description: string | undefined;
  readonly version: string | undefined;
  readonly vendor: string | undefined;
  readonly typeIds: ReadonlyArray<string>;
  readonly importIds: ReadonlyArray<string>;
  constructor(data: {
    elementId: string;
    name: string | undefined;
    description: string | undefined;
    version: string | undefined;
    vendor: string | undefined;
    typeIds: ReadonlyArray<string>;
    importIds: ReadonlyArray<string>;
  }) {
    super({ elementId: data.elementId });
    this.name = data.name;
    this.description = data.description;
    this.version = data.version;
    this.vendor = data.vendor;
    this.typeIds = data.typeIds;
    this.importIds = data.importIds;
  }
}

/** @standard OASIS UIMA 1.0 (2009) §4.2 + §6.2 — concrete class implementation. */
export class TypeDescription extends UIMABase implements ITypeDescription {
  readonly typeName: string;
  readonly supertypeName: string;
  readonly description: string | undefined;
  readonly featureIds: ReadonlyArray<string>;
  readonly allowedValueIds: ReadonlyArray<string>;
  constructor(data: {
    elementId: string;
    typeName: string;
    supertypeName: string;
    description: string | undefined;
    featureIds: ReadonlyArray<string>;
    allowedValueIds: ReadonlyArray<string>;
  }) {
    super({ elementId: data.elementId });
    this.typeName = data.typeName;
    this.supertypeName = data.supertypeName;
    this.description = data.description;
    this.featureIds = data.featureIds;
    this.allowedValueIds = data.allowedValueIds;
  }
}

/** @standard OASIS UIMA 1.0 (2009) §4.2 + §6.3 — concrete class implementation. */
export class FeatureDescription extends UIMABase implements IFeatureDescription {
  readonly name: string;
  readonly description: string | undefined;
  readonly rangeTypeName: string;
  readonly elementType: string | undefined;
  readonly multipleReferencesAllowed: boolean | undefined;
  readonly parentTypeId: string;
  constructor(data: {
    elementId: string;
    name: string;
    description: string | undefined;
    rangeTypeName: string;
    elementType: string | undefined;
    multipleReferencesAllowed: boolean | undefined;
    parentTypeId: string;
  }) {
    super({ elementId: data.elementId });
    this.name = data.name;
    this.description = data.description;
    this.rangeTypeName = data.rangeTypeName;
    this.elementType = data.elementType;
    this.multipleReferencesAllowed = data.multipleReferencesAllowed;
    this.parentTypeId = data.parentTypeId;
  }
}

/** @standard OASIS UIMA 1.0 (2009) §4.2 + §6.4 — concrete class implementation. */
export class AllowedValue extends UIMABase implements IAllowedValue {
  readonly string: string;
  readonly description: string | undefined;
  readonly parentTypeId: string;
  constructor(data: {
    elementId: string;
    string: string;
    description: string | undefined;
    parentTypeId: string;
  }) {
    super({ elementId: data.elementId });
    this.string = data.string;
    this.description = data.description;
    this.parentTypeId = data.parentTypeId;
  }
}

/** @standard OASIS UIMA 1.0 (2009) §4.2 + §6.5 — concrete class implementation. */
export class Import extends UIMABase implements IImport {
  readonly location: string | undefined;
  readonly name: string | undefined;
  constructor(data: {
    elementId: string;
    location: string | undefined;
    name: string | undefined;
  }) {
    super({ elementId: data.elementId });
    this.location = data.location;
    this.name = data.name;
  }
}

/** @standard OASIS UIMA 1.0 (2009) §4.2 + §6.6 — concrete class implementation. */
export class TypePriorities extends UIMABase implements ITypePriorities {
  readonly name: string | undefined;
  readonly description: string | undefined;
  readonly version: string | undefined;
  readonly vendor: string | undefined;
  readonly priorityListIds: ReadonlyArray<string>;
  readonly importIds: ReadonlyArray<string>;
  constructor(data: {
    elementId: string;
    name: string | undefined;
    description: string | undefined;
    version: string | undefined;
    vendor: string | undefined;
    priorityListIds: ReadonlyArray<string>;
    importIds: ReadonlyArray<string>;
  }) {
    super({ elementId: data.elementId });
    this.name = data.name;
    this.description = data.description;
    this.version = data.version;
    this.vendor = data.vendor;
    this.priorityListIds = data.priorityListIds;
    this.importIds = data.importIds;
  }
}

/** @standard OASIS UIMA 1.0 (2009) §4.2 + §6.6 — concrete class implementation. */
export class TypePriorityList extends UIMABase implements ITypePriorityList {
  readonly typeNames: ReadonlyArray<string>;
  readonly parentPrioritiesId: string;
  constructor(data: {
    elementId: string;
    typeNames: ReadonlyArray<string>;
    parentPrioritiesId: string;
  }) {
    super({ elementId: data.elementId });
    this.typeNames = data.typeNames;
    this.parentPrioritiesId = data.parentPrioritiesId;
  }
}

/** @standard OASIS UIMA 1.0 (2009) §4.5 + §4.6 — concrete class implementation. */
export class TypeOrFeature extends UIMABase implements ITypeOrFeature {
  readonly isType: boolean;
  readonly name: string;
  constructor(data: { elementId: string; isType: boolean; name: string }) {
    super({ elementId: data.elementId });
    this.isType = data.isType;
    this.name = data.name;
  }
}

// ─────────────────────────────────────────────────────────────────────────────
// COMMON ANALYSIS STRUCTURE — CAS (§3.1 + §4.1)
// ─────────────────────────────────────────────────────────────────────────────

// --- 10. ICAS (§4.1) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.1 The Common Analysis Structure (CAS)
 * @section §4.1.1 Basic Structure: Objects and Slots
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition CAS (Common Analysis Structure) is the in-memory data
 *   structure UIMA components share to communicate analysis results. A CAS
 *   is the carrier for an artifact (one or more Sofas) and for the
 *   FeatureStructures that record annotations and analysis results over
 *   that artifact. Per §4.1: "The CAS is a graph of objects and slots,
 *   where every object is an instance of a Type and every slot is a Feature
 *   of that Type." Every CAS owns a TypeSystem describing the permissible
 *   shape of its FeatureStructures, and one or more Views indexing subsets
 *   of those FeatureStructures.
 * @ownedAttributes
 *   documentLanguage : String [0..1] -- ISO 639 language code of the CAS
 *                                       artifact, defaults to "x-unspecified"
 * @associationEnds
 *   typeSystem        : TypeSystemDescription [1] -- declares permissible Types
 *   sofas             : Sofa                  [1..*] {composite} -- artifacts
 *                                                                  carried by
 *                                                                  this CAS
 *   views             : View                  [1..*] {composite} -- named
 *                                                                  collections
 *                                                                  of FSes
 *   featureStructures : FeatureStructure      [0..*] {composite} -- the FS pool
 *   indexes           : FSIndex               [0..*] {composite} -- declared
 *                                                                  indexes
 * @operations
 *   getView(name : String) : View [0..1] -- look up a View by name
 *   getInitialView() : View [1] -- the always-present default View per §4.1.4
 *   getDocumentText() : String [0..1] -- shorthand for the initial View's Sofa
 *   createFS(typeName : String) : FeatureStructure -- construct a new FS
 * @constraints
 *   [initial_view_present]: views->one(v | v.viewName = "_InitialView").
 *   [sofa_per_view]: every View references exactly one Sofa via its sofa
 *     attribute (§4.1.4).
 *   [fs_type_in_typesystem]: every FeatureStructure's type is declared in
 *     this CAS's typeSystem (transitively through Imports).
 */
export interface ICAS extends IUIMABase {
  readonly documentLanguage: string | undefined;
  readonly typeSystemId: string;
  readonly sofaIds: ReadonlyArray<string>;
  readonly viewIds: ReadonlyArray<string>;
  readonly featureStructureIds: ReadonlyArray<string>;
  readonly indexIds: ReadonlyArray<string>;
}

// --- 11. IView (§4.1 + §4.3.3) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.1 The Common Analysis Structure (CAS)
 * @section §4.3.3 View Base Type System
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition View is a named, indexed collection of FeatureStructures
 *   anchored to a specific Sofa. The CAS may carry multiple Views to support
 *   multi-modal artifacts (text + audio + alignment) or alternate analyses
 *   (translated text + source text + alignment). Per §4.3.3: "A View is a
 *   subset of the FeatureStructures in a CAS, identified by a name, and
 *   anchored to a single Sofa via the sofa attribute". The default View is
 *   always named "_InitialView".
 * @ownedAttributes
 *   viewName : String [1] -- View name, unique within the parent CAS
 * @associationEnds
 *   parentCas         : CAS              [1] {opposite views}
 *   sofa              : Sofa             [1] -- the artifact this View anchors
 *   memberFsIds       : FeatureStructure [0..*] -- FSes indexed in this View
 * @constraints
 *   [unique_name]: viewName is unique among the Views of parentCas.
 *   [sofa_in_parent]: sofa is one of parentCas.sofas.
 *   [annotations_share_sofa]: every AnnotationFS in this View's index
 *     references the same sofa.
 */
export interface IView extends IUIMABase {
  readonly viewName: string;
  readonly parentCasId: string;
  readonly sofaId: string;
  readonly memberFsIds: ReadonlyArray<string>;
}

// --- 12. ISofa (§4.3.2) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.3 Base Type System
 * @section §4.3.2 Annotation and Sofa Base Type System
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition Sofa (Subject of Analysis) is a UIMA artifact carried by a CAS.
 *   Per §4.3.2: "A Sofa represents a single subject of analysis" — typically
 *   a text document, audio clip, video clip, or other unstructured-data
 *   element. The Sofa's content may be embedded directly (sofaString) or
 *   referenced externally (sofaURI). The sofaMime attribute records the
 *   IANA media type of the artifact for downstream processing decisions.
 * @ownedAttributes
 *   sofaID     : String [1] -- Sofa name, unique within the parent CAS
 *   sofaString : String [0..1] -- inline UTF-16 string artifact data
 *   sofaURI    : String [0..1] -- external artifact URI
 *   sofaMime   : String [0..1] -- IANA media type (e.g., "text/plain",
 *                                 "audio/wav")
 *   sofaArray  : ArrayFS [0..1] -- inline binary array artifact data
 * @associationEnds
 *   parentCas : CAS [1] {opposite sofas}
 * @constraints
 *   [unique_id]: sofaID is unique among the Sofas of parentCas.
 *   [exactly_one_artifact]: exactly one of sofaString, sofaURI, sofaArray is
 *     non-empty.
 */
export interface ISofa extends IUIMABase {
  readonly sofaID: string;
  readonly sofaString: string | undefined;
  readonly sofaURI: string | undefined;
  readonly sofaMime: string | undefined;
  readonly sofaArrayId: string | undefined;
  readonly parentCasId: string;
}

// --- 13. IFeatureStructure (§4.1) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.1 The Common Analysis Structure (CAS)
 * @section §4.1.1 Basic Structure: Objects and Slots
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition FeatureStructure is the elementary object stored in a CAS:
 *   "An object in the CAS is an instance of a Type, with a Slot for each
 *   Feature of that Type" (§4.1.1). FeatureStructures are typed (every FS
 *   has exactly one Type drawn from the CAS's TypeSystem), heap-allocated,
 *   and addressable by an integer FS reference. AnnotationFS, ArrayFS,
 *   ListFS are FeatureStructure subtypes carrying additional structure.
 * @ownedAttributes
 *   typeName : String [1] -- fully-qualified Type name in CAS.typeSystem
 *   slots    : Map<String, Object> [0..*] -- (featureName -> value) pairs;
 *                                            value is an FS reference,
 *                                            primitive value, or array.
 * @associationEnds
 *   parentCas : CAS [1] {opposite featureStructures}
 * @constraints
 *   [type_resolvable]: typeName resolves to a TypeDescription in
 *     parentCas.typeSystem.
 *   [slots_match_type]: every slot key matches a FeatureDescription declared
 *     by the FS's Type or any inherited Type.
 */
export interface IFeatureStructure extends IUIMABase {
  readonly typeName: string;
  readonly slots: ReadonlyMap<string, unknown>;
  readonly parentCasId: string;
}

// --- 14. IAnnotationFS (§4.3.2) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.3 Base Type System
 * @section §4.3.2 Annotation and Sofa Base Type System
 * @metaclass concrete
 * @generalization IFeatureStructure
 * @definition AnnotationFS (built-in Type "uima.tcas.Annotation") is a
 *   FeatureStructure that anchors an analysis result to a span of the
 *   underlying Sofa. Per §4.3.2: "AnnotationFS extends Annotation with
 *   begin and end character offsets into the sofaString of its Sofa." Every
 *   AnnotationFS references the Sofa to which its offsets apply through the
 *   inherited `sofa` feature.
 * @ownedAttributes
 *   beginChar : Integer [1] -- inclusive start character offset in sofaString
 *   endChar   : Integer [1] -- exclusive end character offset in sofaString
 * @associationEnds
 *   sofa : Sofa [1] -- the Sofa whose sofaString these offsets apply to
 * @constraints
 *   [valid_range]: 0 <= beginChar <= endChar <= sofa.sofaString.length.
 *   [supertype_is_annotation]: the FS's Type extends "uima.tcas.Annotation".
 */
export interface IAnnotationFS extends IFeatureStructure {
  readonly beginChar: number;
  readonly endChar: number;
  readonly sofaId: string;
}

// --- 15. IArrayFS (§4.3) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.3 Base Type System
 * @section §4.3.1 Primitive Types
 * @metaclass concrete
 * @generalization IFeatureStructure
 * @definition ArrayFS is the FeatureStructure subtype representing a
 *   fixed-size, ordered, homogeneously-typed array. UIMA defines built-in
 *   array Types per primitive: "uima.cas.IntegerArray", "uima.cas.FloatArray",
 *   "uima.cas.StringArray", "uima.cas.BooleanArray", "uima.cas.ByteArray",
 *   "uima.cas.ShortArray", "uima.cas.LongArray", "uima.cas.DoubleArray", and
 *   "uima.cas.FSArray" (an array of FS references).
 * @ownedAttributes
 *   elementType : String [1] -- the homogeneous element Type
 *   size        : Integer [1] -- fixed array size (≥ 0)
 *   elements    : Object [0..*] {ordered} -- the array contents
 */
export interface IArrayFS extends IFeatureStructure {
  readonly elementType: string;
  readonly size: number;
  readonly elements: ReadonlyArray<unknown>;
}

// --- 16. IListFS (§4.3) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.3 Base Type System
 * @section §4.3.1 Primitive Types
 * @metaclass concrete
 * @generalization IFeatureStructure
 * @definition ListFS is the FeatureStructure subtype representing a
 *   singly-linked list of values. UIMA defines built-in list Types per
 *   primitive: "uima.cas.IntegerList" (head :Integer + tail :IntegerList),
 *   "uima.cas.FloatList", "uima.cas.StringList", and "uima.cas.FSList"
 *   (head :TOP + tail :FSList). Each list type partitions into Empty/NonEmpty
 *   subtypes ("uima.cas.EmptyFSList", "uima.cas.NonEmptyFSList") for terminator
 *   identification.
 * @ownedAttributes
 *   isEmpty     : Boolean [1] -- discriminator between Empty and NonEmpty
 *   elementType : String [1] -- the homogeneous element Type
 *   head        : Object [0..1] -- the first element (only when not isEmpty)
 *   tail        : ListFS [0..1] -- the rest of the list (only when not isEmpty)
 */
export interface IListFS extends IFeatureStructure {
  readonly isEmpty: boolean;
  readonly elementType: string;
  readonly head: unknown;
  readonly tailId: string | undefined;
}

// --- 17. IFSIndex (Apache UIMA references §3) ---
/**
 * @standard Apache UIMA 3.6.x — references.html §3 (FSIndexes)
 * @chapter §4.1 The Common Analysis Structure (CAS) — index machinery
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition FSIndex is the in-memory access structure UIMA components use
 *   to retrieve FeatureStructures by Type and (optionally) by sort order.
 *   An FSIndex carries an indexKind ("sorted", "set", "bag"), a Type filter
 *   (FSes are indexed if and only if their Type or any subtype matches), and
 *   for sorted indexes an ordered list of sort keys.
 * @ownedAttributes
 *   label    : String [1] -- the index name, unique within the CAS
 *   typeName : String [1] -- the indexed Type filter (covers subtypes)
 *   indexKind : String [1] -- one of "sorted", "set", "bag"
 *   keys     : FSIndexKey [0..*] {ordered} -- the sort keys (sorted-only)
 * @associationEnds
 *   parentCas : CAS [1] {opposite indexes}
 * @constraints
 *   [valid_kind]: indexKind in {"sorted", "set", "bag"}.
 *   [keys_only_when_sorted]: keys->size() > 0 implies indexKind = "sorted".
 *   [unique_label]: label is unique among the indexes of parentCas.
 */
export interface IFSIndex extends IUIMABase {
  readonly label: string;
  readonly typeName: string;
  readonly indexKind: string;
  readonly keys: ReadonlyArray<{
    readonly featureName: string;
    readonly comparator: 'standard' | 'reverse';
  }>;
  readonly parentCasId: string;
}

// --- 18. IFSIndexDescription (Apache UIMA references §3) ---
/**
 * @standard Apache UIMA 3.6.x — references.html §3.4 (FSIndex Description)
 * @chapter §6 — descriptor element
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition FSIndexDescription is the declarative, XML-serialized form of
 *   an FSIndex. It appears inside an AnalysisEngineDescription's
 *   FSIndexCollection and tells the UIMA framework to instantiate an FSIndex
 *   with the declared label, type, kind, and keys when a CAS is created
 *   against the descriptor.
 * @ownedAttributes
 *   label     : String [1]
 *   typeName  : String [1]
 *   kind      : String [1] -- "sorted" | "set" | "bag"
 * @associationEnds
 *   keys              : FSIndexKey [0..*] {composite, ordered}
 *   parentCollection  : FSIndexCollection [1] {opposite fsIndexes}
 */
export interface IFSIndexDescription extends IUIMABase {
  readonly label: string;
  readonly typeName: string;
  readonly kind: string;
  readonly keys: ReadonlyArray<{
    readonly featureName: string;
    readonly comparator: 'standard' | 'reverse';
  }>;
  readonly parentCollectionId: string;
}

// --- 19. IFSIndexCollection (Apache UIMA references §3) ---
/**
 * @standard Apache UIMA 3.6.x — references.html §3.4 (FSIndexCollection)
 * @chapter §6 — descriptor element
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition FSIndexCollection is the descriptor element that groups one or
 *   more FSIndexDescription instances declared by a UIMA component. Like
 *   TypeSystemDescription, an FSIndexCollection may import other
 *   FSIndexCollections through Import elements.
 * @ownedAttributes
 *   name        : String [0..1]
 *   description : String [0..1]
 *   version     : String [0..1]
 *   vendor      : String [0..1]
 * @associationEnds
 *   fsIndexes : FSIndexDescription [0..*] {composite}
 *   imports   : Import             [0..*] {composite}
 */
export interface IFSIndexCollection extends IUIMABase {
  readonly name: string | undefined;
  readonly description: string | undefined;
  readonly version: string | undefined;
  readonly vendor: string | undefined;
  readonly fsIndexIds: ReadonlyArray<string>;
  readonly importIds: ReadonlyArray<string>;
}

// --- 20. IFSIterator (Apache UIMA references §3) ---
/**
 * @standard Apache UIMA 3.6.x — references.html §3.4 (FSIterator API)
 * @chapter §4.1 The Common Analysis Structure (CAS) — iteration protocol
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition FSIterator is the runtime object UIMA components use to walk an
 *   FSIndex. The iterator carries a current position into the index and
 *   supports the standard `moveToFirst()`, `moveToLast()`, `moveToNext()`,
 *   `moveToPrevious()`, `get()`, `isValid()`, and `moveTo(FS)` operations.
 *   Per Apache UIMA references §3.4: "FSIterators are positional — moving
 *   the iterator does not modify the underlying index".
 * @ownedAttributes
 *   currentPosition : Integer [0..1] -- 0-based offset into the iterated index
 *   isValid         : Boolean [1] -- true iff currentPosition addresses an FS
 * @associationEnds
 *   sourceIndex : FSIndex [1] -- the index this iterator walks
 * @operations
 *   moveToFirst()    : void
 *   moveToLast()     : void
 *   moveToNext()     : void
 *   moveToPrevious() : void
 *   get()            : FeatureStructure
 *   moveTo(fs : FeatureStructure) : void
 */
export interface IFSIterator extends IUIMABase {
  readonly currentPosition: number | undefined;
  readonly isValid: boolean;
  readonly sourceIndexId: string;
}

// ═══════════════════════════════════════════════════════════════════════════
// CAS — class implementations
// ═══════════════════════════════════════════════════════════════════════════

/** @standard OASIS UIMA 1.0 (2009) §4.1 — concrete class implementation. */
export class CAS extends UIMABase implements ICAS {
  readonly documentLanguage: string | undefined;
  readonly typeSystemId: string;
  readonly sofaIds: ReadonlyArray<string>;
  readonly viewIds: ReadonlyArray<string>;
  readonly featureStructureIds: ReadonlyArray<string>;
  readonly indexIds: ReadonlyArray<string>;
  constructor(data: {
    elementId: string;
    documentLanguage: string | undefined;
    typeSystemId: string;
    sofaIds: ReadonlyArray<string>;
    viewIds: ReadonlyArray<string>;
    featureStructureIds: ReadonlyArray<string>;
    indexIds: ReadonlyArray<string>;
  }) {
    super({ elementId: data.elementId });
    this.documentLanguage = data.documentLanguage;
    this.typeSystemId = data.typeSystemId;
    this.sofaIds = data.sofaIds;
    this.viewIds = data.viewIds;
    this.featureStructureIds = data.featureStructureIds;
    this.indexIds = data.indexIds;
  }
}

/** @standard OASIS UIMA 1.0 (2009) §4.1 + §4.3.3 — concrete class implementation. */
export class View extends UIMABase implements IView {
  readonly viewName: string;
  readonly parentCasId: string;
  readonly sofaId: string;
  readonly memberFsIds: ReadonlyArray<string>;
  constructor(data: {
    elementId: string;
    viewName: string;
    parentCasId: string;
    sofaId: string;
    memberFsIds: ReadonlyArray<string>;
  }) {
    super({ elementId: data.elementId });
    this.viewName = data.viewName;
    this.parentCasId = data.parentCasId;
    this.sofaId = data.sofaId;
    this.memberFsIds = data.memberFsIds;
  }
}

/** @standard OASIS UIMA 1.0 (2009) §4.3.2 — concrete class implementation. */
export class Sofa extends UIMABase implements ISofa {
  readonly sofaID: string;
  readonly sofaString: string | undefined;
  readonly sofaURI: string | undefined;
  readonly sofaMime: string | undefined;
  readonly sofaArrayId: string | undefined;
  readonly parentCasId: string;
  constructor(data: {
    elementId: string;
    sofaID: string;
    sofaString: string | undefined;
    sofaURI: string | undefined;
    sofaMime: string | undefined;
    sofaArrayId: string | undefined;
    parentCasId: string;
  }) {
    super({ elementId: data.elementId });
    this.sofaID = data.sofaID;
    this.sofaString = data.sofaString;
    this.sofaURI = data.sofaURI;
    this.sofaMime = data.sofaMime;
    this.sofaArrayId = data.sofaArrayId;
    this.parentCasId = data.parentCasId;
  }
}

/** @standard OASIS UIMA 1.0 (2009) §4.1 — concrete class implementation. */
export class FeatureStructure extends UIMABase implements IFeatureStructure {
  readonly typeName: string;
  readonly slots: ReadonlyMap<string, unknown>;
  readonly parentCasId: string;
  constructor(data: {
    elementId: string;
    typeName: string;
    slots: ReadonlyMap<string, unknown>;
    parentCasId: string;
  }) {
    super({ elementId: data.elementId });
    this.typeName = data.typeName;
    this.slots = data.slots;
    this.parentCasId = data.parentCasId;
  }
}

/** @standard OASIS UIMA 1.0 (2009) §4.3.2 — concrete class implementation. */
export class AnnotationFS extends FeatureStructure implements IAnnotationFS {
  readonly beginChar: number;
  readonly endChar: number;
  readonly sofaId: string;
  constructor(data: {
    elementId: string;
    typeName: string;
    slots: ReadonlyMap<string, unknown>;
    parentCasId: string;
    beginChar: number;
    endChar: number;
    sofaId: string;
  }) {
    super({
      elementId: data.elementId,
      typeName: data.typeName,
      slots: data.slots,
      parentCasId: data.parentCasId,
    });
    this.beginChar = data.beginChar;
    this.endChar = data.endChar;
    this.sofaId = data.sofaId;
  }
}

/** @standard OASIS UIMA 1.0 (2009) §4.3.1 — concrete class implementation. */
export class ArrayFS extends FeatureStructure implements IArrayFS {
  readonly elementType: string;
  readonly size: number;
  readonly elements: ReadonlyArray<unknown>;
  constructor(data: {
    elementId: string;
    typeName: string;
    slots: ReadonlyMap<string, unknown>;
    parentCasId: string;
    elementType: string;
    size: number;
    elements: ReadonlyArray<unknown>;
  }) {
    super({
      elementId: data.elementId,
      typeName: data.typeName,
      slots: data.slots,
      parentCasId: data.parentCasId,
    });
    this.elementType = data.elementType;
    this.size = data.size;
    this.elements = data.elements;
  }
}

/** @standard OASIS UIMA 1.0 (2009) §4.3.1 — concrete class implementation. */
export class ListFS extends FeatureStructure implements IListFS {
  readonly isEmpty: boolean;
  readonly elementType: string;
  readonly head: unknown;
  readonly tailId: string | undefined;
  constructor(data: {
    elementId: string;
    typeName: string;
    slots: ReadonlyMap<string, unknown>;
    parentCasId: string;
    isEmpty: boolean;
    elementType: string;
    head: unknown;
    tailId: string | undefined;
  }) {
    super({
      elementId: data.elementId,
      typeName: data.typeName,
      slots: data.slots,
      parentCasId: data.parentCasId,
    });
    this.isEmpty = data.isEmpty;
    this.elementType = data.elementType;
    this.head = data.head;
    this.tailId = data.tailId;
  }
}

/** @standard Apache UIMA 3.6.x references.html §3 — concrete class implementation. */
export class FSIndex extends UIMABase implements IFSIndex {
  readonly label: string;
  readonly typeName: string;
  readonly indexKind: string;
  readonly keys: ReadonlyArray<{
    readonly featureName: string;
    readonly comparator: 'standard' | 'reverse';
  }>;
  readonly parentCasId: string;
  constructor(data: {
    elementId: string;
    label: string;
    typeName: string;
    indexKind: string;
    keys: ReadonlyArray<{
      readonly featureName: string;
      readonly comparator: 'standard' | 'reverse';
    }>;
    parentCasId: string;
  }) {
    super({ elementId: data.elementId });
    this.label = data.label;
    this.typeName = data.typeName;
    this.indexKind = data.indexKind;
    this.keys = data.keys;
    this.parentCasId = data.parentCasId;
  }
}

/** @standard Apache UIMA 3.6.x references.html §3.4 — concrete class implementation. */
export class FSIndexDescription extends UIMABase implements IFSIndexDescription {
  readonly label: string;
  readonly typeName: string;
  readonly kind: string;
  readonly keys: ReadonlyArray<{
    readonly featureName: string;
    readonly comparator: 'standard' | 'reverse';
  }>;
  readonly parentCollectionId: string;
  constructor(data: {
    elementId: string;
    label: string;
    typeName: string;
    kind: string;
    keys: ReadonlyArray<{
      readonly featureName: string;
      readonly comparator: 'standard' | 'reverse';
    }>;
    parentCollectionId: string;
  }) {
    super({ elementId: data.elementId });
    this.label = data.label;
    this.typeName = data.typeName;
    this.kind = data.kind;
    this.keys = data.keys;
    this.parentCollectionId = data.parentCollectionId;
  }
}

/** @standard Apache UIMA 3.6.x references.html §3.4 — concrete class implementation. */
export class FSIndexCollection extends UIMABase implements IFSIndexCollection {
  readonly name: string | undefined;
  readonly description: string | undefined;
  readonly version: string | undefined;
  readonly vendor: string | undefined;
  readonly fsIndexIds: ReadonlyArray<string>;
  readonly importIds: ReadonlyArray<string>;
  constructor(data: {
    elementId: string;
    name: string | undefined;
    description: string | undefined;
    version: string | undefined;
    vendor: string | undefined;
    fsIndexIds: ReadonlyArray<string>;
    importIds: ReadonlyArray<string>;
  }) {
    super({ elementId: data.elementId });
    this.name = data.name;
    this.description = data.description;
    this.version = data.version;
    this.vendor = data.vendor;
    this.fsIndexIds = data.fsIndexIds;
    this.importIds = data.importIds;
  }
}

/** @standard Apache UIMA 3.6.x references.html §3.4 — concrete class implementation. */
export class FSIterator extends UIMABase implements IFSIterator {
  readonly currentPosition: number | undefined;
  readonly isValid: boolean;
  readonly sourceIndexId: string;
  constructor(data: {
    elementId: string;
    currentPosition: number | undefined;
    isValid: boolean;
    sourceIndexId: string;
  }) {
    super({ elementId: data.elementId });
    this.currentPosition = data.currentPosition;
    this.isValid = data.isValid;
    this.sourceIndexId = data.sourceIndexId;
  }
}

// ─────────────────────────────────────────────────────────────────────────────
// BASE TYPE SYSTEM (§3.3 + §4.3)
// ─────────────────────────────────────────────────────────────────────────────

// --- 21. ISofaReference (§4.3.2) --- abstract
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.3 Base Type System
 * @section §4.3.2 Annotation and Sofa Base Type System
 * @metaclass abstract
 * @generalization IFeatureStructure
 * @definition SofaReference is the abstract base FeatureStructure type used by
 *   AnnotationBase to identify the Sofa to which the annotation's offsets
 *   apply. Per §4.3.2: "SofaReference is the abstract base for sofa references;
 *   subtypes are LocalSofaReference (refers to a Sofa in the same CAS) and
 *   RemoteSofaReference (refers to a Sofa outside the CAS)."
 */
export interface ISofaReference extends IFeatureStructure {}

// --- 22. ILocalSofaReference (§4.3.2) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.3 Base Type System
 * @section §4.3.2 Annotation and Sofa Base Type System
 * @metaclass concrete
 * @generalization ISofaReference
 * @definition LocalSofaReference is a SofaReference whose target Sofa lives
 *   in the same CAS as the referencing FeatureStructure. The reference is
 *   resolved by Sofa name within the parent CAS.
 * @ownedAttributes
 *   sofaName : String [1] -- the local Sofa's sofaID
 */
export interface ILocalSofaReference extends ISofaReference {
  readonly sofaName: string;
}

// --- 23. IRemoteSofaReference (§4.3.2) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.3 Base Type System
 * @section §4.3.2 Annotation and Sofa Base Type System
 * @metaclass concrete
 * @generalization ISofaReference
 * @definition RemoteSofaReference is a SofaReference whose target Sofa lives
 *   in a different CAS, addressed by URI. UIMA-AS uses RemoteSofaReference
 *   to allow a FeatureStructure to reference an artifact carried by a remote
 *   CAS in a distributed pipeline.
 * @ownedAttributes
 *   sofaURI : String [1] -- the remote Sofa's URI
 */
export interface IRemoteSofaReference extends ISofaReference {
  readonly sofaURI: string;
}

// --- 24. IAnnotationBase (§4.3.2) --- abstract
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.3 Base Type System
 * @section §4.3.2 Annotation and Sofa Base Type System
 * @metaclass abstract
 * @generalization IFeatureStructure
 * @definition AnnotationBase is the abstract base for every annotation in the
 *   UIMA Base Type System (built-in Type "uima.cas.AnnotationBase"). Per
 *   §4.3.2: "AnnotationBase carries the universal annotation features:
 *   `sofa` (the SofaReference identifying the annotation's target),
 *   `occurrenceOf` (an optional Referent identifying what is annotated),
 *   `metadata` (optional AnnotationMetadata)". Concrete subtypes —
 *   TextAnnotation, TemporalAnnotation — extend this Type with span coords.
 * @ownedAttributes
 *   (none directly; carries inherited slots only)
 * @associationEnds
 *   sofa         : SofaReference      [1]
 *   occurrenceOf : Referent           [0..1]
 *   metadata     : AnnotationMetadata [0..1]
 */
export interface IAnnotationBase extends IFeatureStructure {
  readonly sofaReferenceId: string;
  readonly occurrenceOfId: string | undefined;
  readonly metadataId: string | undefined;
}

// --- 25. ITextAnnotation (§4.3.2) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.3 Base Type System
 * @section §4.3.2 Annotation and Sofa Base Type System
 * @metaclass concrete
 * @generalization IAnnotationBase
 * @definition TextAnnotation extends AnnotationBase with Unicode-character
 *   span offsets into the target Sofa's sofaString. Per §4.3.2: "beginChar
 *   is the inclusive start character offset; endChar is the exclusive end
 *   character offset." TextAnnotation is the canonical annotation Type for
 *   any text-mode UIMA pipeline; AnnotationFS (uima.tcas.Annotation) is its
 *   downstream specialization.
 * @ownedAttributes
 *   beginChar : Integer [1] -- inclusive start offset (Unicode characters)
 *   endChar   : Integer [1] -- exclusive end offset
 * @constraints
 *   [valid_range]: 0 <= beginChar <= endChar.
 */
export interface ITextAnnotation extends IAnnotationBase {
  readonly beginChar: number;
  readonly endChar: number;
}

// --- 26. ITemporalAnnotation (§4.3.2) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.3 Base Type System
 * @section §4.3.2 Annotation and Sofa Base Type System
 * @metaclass concrete
 * @generalization IAnnotationBase
 * @definition TemporalAnnotation extends AnnotationBase with time-aligned
 *   span offsets into a temporal Sofa (audio, video, time-series). Per
 *   §4.3.2: "beginTime is the inclusive start in seconds from the start of
 *   the artifact; endTime is the exclusive end." TemporalAnnotation is the
 *   canonical annotation Type for any audio- or video-mode UIMA pipeline.
 * @ownedAttributes
 *   beginTime : Double [1] -- inclusive start (seconds)
 *   endTime   : Double [1] -- exclusive end (seconds)
 * @constraints
 *   [valid_range]: 0.0 <= beginTime <= endTime.
 */
export interface ITemporalAnnotation extends IAnnotationBase {
  readonly beginTime: number;
  readonly endTime: number;
}

// --- 27. IReferent (§4.3.2) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.3 Base Type System
 * @section §4.3.2 Annotation and Sofa Base Type System
 * @metaclass concrete
 * @generalization IFeatureStructure
 * @definition Referent identifies a real-world entity, concept, or external
 *   ontology element that an Annotation is "an occurrence of". Per §4.3.2:
 *   "Referent has multi-valued occurrences (the Annotations citing it),
 *   ontologySource (an external ontology identifier), and ontologyElement
 *   (the element within that ontology)." Referent enables coreference and
 *   external-ontology grounding (e.g., linking an annotation to a Wikidata
 *   QID, an SNOMED-CT concept, a UMLS CUI).
 * @ownedAttributes
 *   ontologySource  : String [0..1]
 *   ontologyElement : String [0..1]
 * @associationEnds
 *   occurrences : AnnotationBase [0..*]
 */
export interface IReferent extends IFeatureStructure {
  readonly ontologySource: string | undefined;
  readonly ontologyElement: string | undefined;
  readonly occurrenceIds: ReadonlyArray<string>;
}

// --- 28. IAnnotationMetadata (§4.3.2) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.3 Base Type System
 * @section §4.3.2 Annotation and Sofa Base Type System
 * @metaclass concrete
 * @generalization IFeatureStructure
 * @definition AnnotationMetadata carries provenance and confidence data for
 *   an Annotation. Per §4.3.2: "confidence is a Float between 0.0 and 1.0;
 *   provenance is an optional Provenance reference recording which component
 *   produced the annotation, with what configuration, at what time."
 * @ownedAttributes
 *   confidence : Float [0..1]
 * @associationEnds
 *   provenance : Provenance [0..1]
 * @constraints
 *   [valid_confidence]: 0.0 <= confidence <= 1.0 when set.
 */
export interface IAnnotationMetadata extends IFeatureStructure {
  readonly confidence: number | undefined;
  readonly provenanceId: string | undefined;
}

// --- 29. IProvenance (§4.3.2) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.3 Base Type System
 * @section §4.3.2 Annotation and Sofa Base Type System
 * @metaclass concrete
 * @generalization IFeatureStructure
 * @definition Provenance is the open-ended provenance record cited by
 *   AnnotationMetadata. Per §4.3.2: "the structure of Provenance is defined
 *   by users via subclassing." The Base Type System ships only the empty
 *   Provenance Type; concrete pipelines extend it with component identity,
 *   configuration parameters, run timestamp, and any other audit fields.
 */
export interface IProvenance extends IFeatureStructure {}

// --- 30. IAnchoredView (§4.3.3) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.3 Base Type System
 * @section §4.3.3 View Base Type System
 * @metaclass concrete
 * @generalization IView
 * @definition AnchoredView extends View with the constraint that every
 *   member Annotation in the View must reference the same Sofa as the View
 *   itself. Per §4.3.3: "AnchoredView is a View whose member AnnotationBase
 *   instances all share the same sofa reference." UIMA's text-mode
 *   processing uses AnchoredView almost exclusively.
 * @constraints
 *   [members_share_sofa]: every member AnnotationBase has
 *     sofaReference.sofaName = parent View's sofa.sofaID.
 */
export interface IAnchoredView extends IView {}

// --- 31. ISourceDocumentInformation (§4.3.4) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.3 Base Type System
 * @section §4.3.4 Source Document Information
 * @metaclass concrete
 * @generalization IFeatureStructure
 * @definition SourceDocumentInformation is the built-in Type
 *   ("uima.examples.SourceDocumentInformation") attached to a CAS by a
 *   CollectionReader to record the URI/location of the underlying document
 *   and the offset/size if the CAS represents a fragment. Per §4.3.4: the
 *   feature `uri` carries the source URL/location, `offsetInSource` the byte
 *   offset, `documentSize` the total byte size of the source.
 * @ownedAttributes
 *   uri            : String  [1]
 *   offsetInSource : Integer [0..1]
 *   documentSize   : Integer [0..1]
 *   documentIndex  : Integer [0..1]
 *   lastSegment    : Boolean [0..1]
 */
export interface ISourceDocumentInformation extends IFeatureStructure {
  readonly uri: string;
  readonly offsetInSource: number | undefined;
  readonly documentSize: number | undefined;
  readonly documentIndex: number | undefined;
  readonly lastSegment: boolean | undefined;
}

// ─────────────────────────────────────────────────────────────────────────────
// ABSTRACT INTERFACES (§3.4 + §4.4)
// ─────────────────────────────────────────────────────────────────────────────

// --- 32. IProcessingElement (§4.4) --- abstract
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.4 Abstract Interfaces
 * @section §4.4.2 Abstract Interfaces Formal Specification
 * @metaclass abstract
 * @generalization IUIMABase
 * @definition ProcessingElement is the root abstract interface every UIMA
 *   processing component implements. Per §4.4.2: "ProcessingElement carries
 *   the universal lifecycle and metadata operations: getMetadata() returning
 *   the component's PE Metadata, and setConfigurationParameters(...) for
 *   binding configuration values at deployment time." Concrete ProcessingElement
 *   subtypes are Analyzer, CasMultiplier, FlowController, plus their Apache
 *   reference-impl specializations (CollectionReader, CasConsumer).
 * @operations
 *   getMetadata()                                       : ProcessingElementMetadata
 *   setConfigurationParameters(s : ConfigurationParameterSettings) : void
 *   destroy()                                           : void
 */
export interface IProcessingElement extends IUIMABase {}

// --- 33. IAnalytic (§4.4) --- abstract
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.4 Abstract Interfaces
 * @section §4.4.2 Abstract Interfaces Formal Specification
 * @metaclass abstract
 * @generalization IProcessingElement
 * @definition Analytic is the abstract subtype of ProcessingElement that
 *   produces analysis results — that is, modifies the CAS rather than only
 *   consuming it. Both Analyzer and CasMultiplier extend Analytic. Per
 *   §4.4.2: an Analytic always has a Capability declaring which Types and
 *   Features it analyzes, requires-as-input, modifies, creates, or deletes.
 */
export interface IAnalytic extends IProcessingElement {}

// --- 34. IAnalyzer (§4.4) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.4 Abstract Interfaces
 * @section §4.4.2 Abstract Interfaces Formal Specification
 * @metaclass concrete
 * @generalization IAnalytic
 * @definition Analyzer is the canonical analysis component: given a CAS as
 *   input, it produces zero-or-more new FeatureStructures (typically
 *   Annotations) over the existing Sofas of the CAS, and returns the same
 *   CAS instance to the caller. Per §4.4.2: the operation
 *   `processCas(CAS, SofaList) → CAS|Delta` either returns the modified CAS
 *   in full or returns a Delta description of the modifications.
 *   Apache UIMA's `AnalysisEngine` Java interface implements Analyzer.
 * @operations
 *   processCas(cas : CAS, sofas : Sofa [0..*]) : CAS or Delta
 *   processCasBatch(cases : CAS [*], sofas : Sofa [*][*])
 *     : (CAS or Delta or Exception) [*]
 */
export interface IAnalyzer extends IAnalytic {}

// --- 35. ICasMultiplier (§4.4) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.4 Abstract Interfaces
 * @section §4.4.2 Abstract Interfaces Formal Specification
 * @metaclass concrete
 * @generalization IAnalytic
 * @definition CasMultiplier is the abstract subtype of Analytic that
 *   produces N output CASes from one input CAS — fanning a single document
 *   into multiple downstream documents. Per §4.4.2: CasMultiplier defines
 *   `inputCas(CAS, SofaList)` to feed it an input, then iteratively
 *   `getNextCas() → CAS` to retrieve outputs, and finally `retrieveInputCas()`
 *   to return the (possibly modified) input CAS to the framework. The
 *   `outputsNewCASes` OperationalProperty is set true for any CasMultiplier.
 * @operations
 *   inputCas(cas : CAS, sofas : Sofa [0..*]) : void
 *   getNextCas() : CAS [0..1]
 *   retrieveInputCas() : CAS or Delta
 *   getNextCasBatch(maxCount : Integer, maxTime : Integer)
 *     : { cases : CAS [*], hasMore : Boolean, remaining : Integer }
 */
export interface ICasMultiplier extends IAnalytic {}

// --- 36. IFlowController (§4.4) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.4 Abstract Interfaces
 * @section §4.4.2 Abstract Interfaces Formal Specification
 * @metaclass concrete
 * @generalization IProcessingElement
 * @definition FlowController is the ProcessingElement that decides, for a
 *   given CAS at a given point in an Aggregate Analysis Engine, which
 *   downstream component receives the CAS next. Per §4.4.2: the operations
 *   `addAvailableAnalytics(Map<String, PE Metadata>)`,
 *   `removeAvailableAnalytics(String[])`,
 *   `setAggregateMetadata(PE Metadata)`,
 *   `getNextDestinations(CAS) → Step`,
 *   `continueOnFailure(CAS, String, UimaException) → Boolean` together let a
 *   FlowController route every CAS through any user-defined topology over
 *   the parent Aggregate's component set.
 * @operations
 *   addAvailableAnalytics(map : Map<String, ProcessingElementMetadata>) : void
 *   removeAvailableAnalytics(keys : String [*]) : void
 *   setAggregateMetadata(meta : ProcessingElementMetadata) : void
 *   getNextDestinations(cas : CAS) : Step
 *   continueOnFailure(cas : CAS, failedKey : String, ex : UimaException)
 *     : Boolean
 */
export interface IFlowController extends IProcessingElement {}

// --- 37. IStep (§4.4) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.4 Abstract Interfaces
 * @section §4.4.2 Abstract Interfaces Formal Specification
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition Step is the value returned by FlowController.getNextDestinations
 *   to specify what should happen next with a given CAS. Per §4.4.2 + Apache
 *   UIMA references: Step has three concrete forms — SimpleStep (deliver to
 *   one named component), ParallelStep (deliver to a set of components in
 *   parallel), FinalStep (terminate this CAS's flow). The discriminator
 *   `kind` selects between them.
 * @ownedAttributes
 *   kind                : String   [1] -- "simple" | "parallel" | "final"
 *   destinationKey      : String   [0..1] -- when kind = "simple"
 *   destinationKeys     : String   [0..*] -- when kind = "parallel"
 *   forceCasToBeDropped : Boolean  [0..1] -- when kind = "final"
 * @constraints
 *   [valid_kind]: kind in {"simple", "parallel", "final"}.
 *   [simple_has_one]: kind = "simple" implies destinationKey->notEmpty().
 *   [parallel_has_set]: kind = "parallel" implies destinationKeys->size() > 0.
 */
export interface IStep extends IUIMABase {
  readonly kind: string;
  readonly destinationKey: string | undefined;
  readonly destinationKeys: ReadonlyArray<string> | undefined;
  readonly forceCasToBeDropped: boolean | undefined;
}

// ═══════════════════════════════════════════════════════════════════════════
// BASE TYPE SYSTEM + ABSTRACT INTERFACES — class implementations
// ═══════════════════════════════════════════════════════════════════════════

/** @standard OASIS UIMA 1.0 (2009) §4.3.2 — abstract class implementation. */
export abstract class SofaReference extends FeatureStructure implements ISofaReference {}

/** @standard OASIS UIMA 1.0 (2009) §4.3.2 — concrete class implementation. */
export class LocalSofaReference extends SofaReference implements ILocalSofaReference {
  readonly sofaName: string;
  constructor(data: {
    elementId: string;
    typeName: string;
    slots: ReadonlyMap<string, unknown>;
    parentCasId: string;
    sofaName: string;
  }) {
    super({
      elementId: data.elementId,
      typeName: data.typeName,
      slots: data.slots,
      parentCasId: data.parentCasId,
    });
    this.sofaName = data.sofaName;
  }
}

/** @standard OASIS UIMA 1.0 (2009) §4.3.2 — concrete class implementation. */
export class RemoteSofaReference extends SofaReference implements IRemoteSofaReference {
  readonly sofaURI: string;
  constructor(data: {
    elementId: string;
    typeName: string;
    slots: ReadonlyMap<string, unknown>;
    parentCasId: string;
    sofaURI: string;
  }) {
    super({
      elementId: data.elementId,
      typeName: data.typeName,
      slots: data.slots,
      parentCasId: data.parentCasId,
    });
    this.sofaURI = data.sofaURI;
  }
}

/** @standard OASIS UIMA 1.0 (2009) §4.3.2 — abstract class implementation. */
export abstract class AnnotationBase extends FeatureStructure implements IAnnotationBase {
  readonly sofaReferenceId: string;
  readonly occurrenceOfId: string | undefined;
  readonly metadataId: string | undefined;
  protected constructor(data: {
    elementId: string;
    typeName: string;
    slots: ReadonlyMap<string, unknown>;
    parentCasId: string;
    sofaReferenceId: string;
    occurrenceOfId: string | undefined;
    metadataId: string | undefined;
  }) {
    super({
      elementId: data.elementId,
      typeName: data.typeName,
      slots: data.slots,
      parentCasId: data.parentCasId,
    });
    this.sofaReferenceId = data.sofaReferenceId;
    this.occurrenceOfId = data.occurrenceOfId;
    this.metadataId = data.metadataId;
  }
}

/** @standard OASIS UIMA 1.0 (2009) §4.3.2 — concrete class implementation. */
export class TextAnnotation extends AnnotationBase implements ITextAnnotation {
  readonly beginChar: number;
  readonly endChar: number;
  constructor(data: {
    elementId: string;
    typeName: string;
    slots: ReadonlyMap<string, unknown>;
    parentCasId: string;
    sofaReferenceId: string;
    occurrenceOfId: string | undefined;
    metadataId: string | undefined;
    beginChar: number;
    endChar: number;
  }) {
    super({
      elementId: data.elementId,
      typeName: data.typeName,
      slots: data.slots,
      parentCasId: data.parentCasId,
      sofaReferenceId: data.sofaReferenceId,
      occurrenceOfId: data.occurrenceOfId,
      metadataId: data.metadataId,
    });
    this.beginChar = data.beginChar;
    this.endChar = data.endChar;
  }
}

/** @standard OASIS UIMA 1.0 (2009) §4.3.2 — concrete class implementation. */
export class TemporalAnnotation extends AnnotationBase implements ITemporalAnnotation {
  readonly beginTime: number;
  readonly endTime: number;
  constructor(data: {
    elementId: string;
    typeName: string;
    slots: ReadonlyMap<string, unknown>;
    parentCasId: string;
    sofaReferenceId: string;
    occurrenceOfId: string | undefined;
    metadataId: string | undefined;
    beginTime: number;
    endTime: number;
  }) {
    super({
      elementId: data.elementId,
      typeName: data.typeName,
      slots: data.slots,
      parentCasId: data.parentCasId,
      sofaReferenceId: data.sofaReferenceId,
      occurrenceOfId: data.occurrenceOfId,
      metadataId: data.metadataId,
    });
    this.beginTime = data.beginTime;
    this.endTime = data.endTime;
  }
}

/** @standard OASIS UIMA 1.0 (2009) §4.3.2 — concrete class implementation. */
export class Referent extends FeatureStructure implements IReferent {
  readonly ontologySource: string | undefined;
  readonly ontologyElement: string | undefined;
  readonly occurrenceIds: ReadonlyArray<string>;
  constructor(data: {
    elementId: string;
    typeName: string;
    slots: ReadonlyMap<string, unknown>;
    parentCasId: string;
    ontologySource: string | undefined;
    ontologyElement: string | undefined;
    occurrenceIds: ReadonlyArray<string>;
  }) {
    super({
      elementId: data.elementId,
      typeName: data.typeName,
      slots: data.slots,
      parentCasId: data.parentCasId,
    });
    this.ontologySource = data.ontologySource;
    this.ontologyElement = data.ontologyElement;
    this.occurrenceIds = data.occurrenceIds;
  }
}

/** @standard OASIS UIMA 1.0 (2009) §4.3.2 — concrete class implementation. */
export class AnnotationMetadata extends FeatureStructure implements IAnnotationMetadata {
  readonly confidence: number | undefined;
  readonly provenanceId: string | undefined;
  constructor(data: {
    elementId: string;
    typeName: string;
    slots: ReadonlyMap<string, unknown>;
    parentCasId: string;
    confidence: number | undefined;
    provenanceId: string | undefined;
  }) {
    super({
      elementId: data.elementId,
      typeName: data.typeName,
      slots: data.slots,
      parentCasId: data.parentCasId,
    });
    this.confidence = data.confidence;
    this.provenanceId = data.provenanceId;
  }
}

/** @standard OASIS UIMA 1.0 (2009) §4.3.2 — concrete class implementation. */
export class Provenance extends FeatureStructure implements IProvenance {}

/** @standard OASIS UIMA 1.0 (2009) §4.3.3 — concrete class implementation. */
export class AnchoredView extends View implements IAnchoredView {}

/** @standard OASIS UIMA 1.0 (2009) §4.3.4 — concrete class implementation. */
export class SourceDocumentInformation extends FeatureStructure implements ISourceDocumentInformation {
  readonly uri: string;
  readonly offsetInSource: number | undefined;
  readonly documentSize: number | undefined;
  readonly documentIndex: number | undefined;
  readonly lastSegment: boolean | undefined;
  constructor(data: {
    elementId: string;
    typeName: string;
    slots: ReadonlyMap<string, unknown>;
    parentCasId: string;
    uri: string;
    offsetInSource: number | undefined;
    documentSize: number | undefined;
    documentIndex: number | undefined;
    lastSegment: boolean | undefined;
  }) {
    super({
      elementId: data.elementId,
      typeName: data.typeName,
      slots: data.slots,
      parentCasId: data.parentCasId,
    });
    this.uri = data.uri;
    this.offsetInSource = data.offsetInSource;
    this.documentSize = data.documentSize;
    this.documentIndex = data.documentIndex;
    this.lastSegment = data.lastSegment;
  }
}

/** @standard OASIS UIMA 1.0 (2009) §4.4 — abstract class implementation. */
export abstract class ProcessingElement extends UIMABase implements IProcessingElement {}

/** @standard OASIS UIMA 1.0 (2009) §4.4 — abstract class implementation. */
export abstract class Analytic extends ProcessingElement implements IAnalytic {}

/** @standard OASIS UIMA 1.0 (2009) §4.4 — concrete class implementation. */
export class Analyzer extends Analytic implements IAnalyzer {
  constructor(data: { elementId: string }) {
    super({ elementId: data.elementId });
  }
}

/** @standard OASIS UIMA 1.0 (2009) §4.4 — concrete class implementation. */
export class CasMultiplier extends Analytic implements ICasMultiplier {
  constructor(data: { elementId: string }) {
    super({ elementId: data.elementId });
  }
}

/** @standard OASIS UIMA 1.0 (2009) §4.4 — concrete class implementation. */
export class FlowController extends ProcessingElement implements IFlowController {
  constructor(data: { elementId: string }) {
    super({ elementId: data.elementId });
  }
}

/** @standard OASIS UIMA 1.0 (2009) §4.4 — concrete class implementation. */
export class Step extends UIMABase implements IStep {
  readonly kind: string;
  readonly destinationKey: string | undefined;
  readonly destinationKeys: ReadonlyArray<string> | undefined;
  readonly forceCasToBeDropped: boolean | undefined;
  constructor(data: {
    elementId: string;
    kind: string;
    destinationKey: string | undefined;
    destinationKeys: ReadonlyArray<string> | undefined;
    forceCasToBeDropped: boolean | undefined;
  }) {
    super({ elementId: data.elementId });
    this.kind = data.kind;
    this.destinationKey = data.destinationKey;
    this.destinationKeys = data.destinationKeys;
    this.forceCasToBeDropped = data.forceCasToBeDropped;
  }
}

// ─────────────────────────────────────────────────────────────────────────────
// BEHAVIORAL METADATA + CAPABILITIES (§3.5 + §4.5)
// ─────────────────────────────────────────────────────────────────────────────

// --- 38. IBehavioralMetadata (§4.5) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.5 Behavioral Metadata
 * @section §4.5.1 Behavioral Metadata UML
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition BehavioralMetadata declares what a ProcessingElement can do
 *   with a CAS — which Types it analyzes, which it requires as input, which
 *   it modifies, which it creates, which it deletes — and under which
 *   preconditions / postconditions / projection conditions. Per §4.5: the
 *   metadata set comprises {analyzes, requiredInputs, optionalInputs,
 *   creates, modifies, deletes} as Capability collections plus optional
 *   Conditions.
 * @associationEnds
 *   capabilities : Capability [0..*] {composite}
 * @constraints
 *   [non_empty]: an Analytic ProcessingElement MUST declare at least one
 *     Capability; FlowController and CasInitializer may have zero.
 */
export interface IBehavioralMetadata extends IUIMABase {
  readonly capabilityIds: ReadonlyArray<string>;
}

// --- 39. ICapability (§4.5) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.5 Behavioral Metadata
 * @section §4.5.1 Behavioral Metadata UML
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition Capability is the declarative grouping of TypeOrFeature
 *   references and Conditions describing one capability slice of a
 *   ProcessingElement. Per §4.5: each Capability has six relationship
 *   collections — analyzedTypes, requiredInputs, optionalInputs,
 *   createdTypes, modifiedTypes, deletedTypes — plus optional preconditions
 *   (Condition expressions over the input CAS), postconditions (over the
 *   output CAS), and projectionConditions (over the Sofa selection set).
 *   Capabilities also enumerate the set of input Sofa names and output Sofa
 *   names the component reads or produces, and the set of supported
 *   ISO 639 language codes.
 * @ownedAttributes
 *   inputSofas       : String [0..*]
 *   outputSofas      : String [0..*]
 *   languagesSupported : String [0..*] -- ISO 639 codes, "x-unspecified" wildcards
 *   description      : String [0..1]
 * @associationEnds
 *   analyzedTypes        : TypeOrFeature [0..*] {composite}
 *   requiredInputs       : TypeOrFeature [0..*] {composite}
 *   optionalInputs       : TypeOrFeature [0..*] {composite}
 *   createdTypes         : TypeOrFeature [0..*] {composite}
 *   modifiedTypes        : TypeOrFeature [0..*] {composite}
 *   deletedTypes         : TypeOrFeature [0..*] {composite}
 *   preconditions        : Condition     [0..*] {composite}
 *   postconditions       : Condition     [0..*] {composite}
 *   projectionConditions : Condition     [0..*] {composite}
 *   parentMetadata       : BehavioralMetadata [1] {opposite capabilities}
 */
export interface ICapability extends IUIMABase {
  readonly inputSofas: ReadonlyArray<string>;
  readonly outputSofas: ReadonlyArray<string>;
  readonly languagesSupported: ReadonlyArray<string>;
  readonly description: string | undefined;
  readonly analyzedTypeIds: ReadonlyArray<string>;
  readonly requiredInputIds: ReadonlyArray<string>;
  readonly optionalInputIds: ReadonlyArray<string>;
  readonly createdTypeIds: ReadonlyArray<string>;
  readonly modifiedTypeIds: ReadonlyArray<string>;
  readonly deletedTypeIds: ReadonlyArray<string>;
  readonly preconditionIds: ReadonlyArray<string>;
  readonly postconditionIds: ReadonlyArray<string>;
  readonly projectionConditionIds: ReadonlyArray<string>;
  readonly parentMetadataId: string;
}

// --- 40. ICondition (§4.5) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.5 Behavioral Metadata
 * @section §4.5.3 Formal Semantics for Behavioral Metadata
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition Condition is a typed predicate expression evaluated over the
 *   CAS as a precondition, postcondition, or projection condition of a
 *   Capability. Per §4.5.3: the Condition carries a `language` field naming
 *   the expression language (typically "OCL") and an `expression` field
 *   carrying the raw predicate text. The UIMA framework evaluates the
 *   Condition against the CAS at the corresponding Capability checkpoint
 *   and either admits or rejects the operation.
 * @ownedAttributes
 *   language   : String [1] -- e.g., "OCL", "JavaScript", "MVEL"
 *   expression : String [1] -- the raw predicate text
 *   description : String [0..1]
 * @constraints
 *   [valid_language]: language is a recognized expression-language identifier.
 */
export interface ICondition extends IUIMABase {
  readonly language: string;
  readonly expression: string;
  readonly description: string | undefined;
}

// ─────────────────────────────────────────────────────────────────────────────
// PROCESSING ELEMENT METADATA (§3.6 + §4.6)
// ─────────────────────────────────────────────────────────────────────────────

// --- 41. IProcessingElementMetadata (§4.6) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.6 Processing Element Metadata
 * @section §4.6.1 Elements of PE Metadata
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition ProcessingElementMetadata is the top-level metadata container
 *   for a UIMA ProcessingElement. Per §4.6: PE Metadata aggregates
 *   IdentificationInfo (symbolicName, name, vendor, version, description,
 *   url), the BehavioralMetadata (capabilities), the TypeSystem reference
 *   (or embedded TypeSystemDescription), the ConfigurationParameters
 *   (declarations + settings), and zero-or-more Extensions for
 *   vendor-specific augmentation. PE Metadata is the bridge between the
 *   declarative XML descriptor file and the runtime ProcessingElement
 *   instance.
 * @associationEnds
 *   identification             : IdentificationInfo                  [1] {composite}
 *   configurationParameterDecls: ConfigurationParameterDeclarations  [0..1] {composite}
 *   configurationParameterSettings: ConfigurationParameterSettings   [0..1] {composite}
 *   behavioralMetadata         : BehavioralMetadata                  [0..1] {composite}
 *   typeSystem                 : TypeSystemDescription               [0..1]
 *                                                                        (or imported)
 *   typePriorities             : TypePriorities                      [0..1] {composite}
 *   fsIndexCollection          : FSIndexCollection                   [0..1] {composite}
 *   resourceManagerConfig      : ResourceManagerConfiguration        [0..1] {composite}
 *   operationalProperties      : OperationalProperties               [0..1] {composite}
 *   extensions                 : Extension                           [0..*] {composite}
 */
export interface IProcessingElementMetadata extends IUIMABase {
  readonly identificationId: string;
  readonly configurationParameterDeclsId: string | undefined;
  readonly configurationParameterSettingsId: string | undefined;
  readonly behavioralMetadataId: string | undefined;
  readonly typeSystemId: string | undefined;
  readonly typePrioritiesId: string | undefined;
  readonly fsIndexCollectionId: string | undefined;
  readonly resourceManagerConfigId: string | undefined;
  readonly operationalPropertiesId: string | undefined;
  readonly extensionIds: ReadonlyArray<string>;
}

// --- 42. IIdentificationInfo (§4.6) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.6 Processing Element Metadata
 * @section §4.6.1 Elements of PE Metadata
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition IdentificationInfo carries the human- and machine-readable
 *   identity of a ProcessingElement. Per §4.6.1: symbolicName is a Java-style
 *   reverse-DNS-prefixed identifier ("org.apache.uima.examples.PersonTitleAnnotator");
 *   name is a human-readable label; vendor, version, description, copyright,
 *   url enumerate the standard descriptive fields.
 * @ownedAttributes
 *   symbolicName : String [1]
 *   name         : String [0..1]
 *   description  : String [0..1]
 *   version      : String [0..1]
 *   vendor       : String [0..1]
 *   copyright    : String [0..1]
 *   url          : String [0..1]
 */
export interface IIdentificationInfo extends IUIMABase {
  readonly symbolicName: string;
  readonly name: string | undefined;
  readonly description: string | undefined;
  readonly version: string | undefined;
  readonly vendor: string | undefined;
  readonly copyright: string | undefined;
  readonly url: string | undefined;
}

// --- 43. IConfigurationParameter (§4.6) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.6 Processing Element Metadata
 * @section §4.6.1 Elements of PE Metadata — Configuration Parameter
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition ConfigurationParameter declares a single configurable input to
 *   a ProcessingElement. Per §4.6.1: the parameter has a name (unique within
 *   its enclosing Declaration), an optional description, a type
 *   ("String" | "Integer" | "Float" | "Boolean"), a multiValued flag, a
 *   mandatory flag, and the list of overrides that re-bind the parameter
 *   for sub-components in an Aggregate.
 * @ownedAttributes
 *   name        : String  [1]
 *   description : String  [0..1]
 *   type        : String  [1] -- one of {"String","Integer","Float","Boolean"}
 *   multiValued : Boolean [0..1]
 *   mandatory   : Boolean [0..1]
 *   overrides   : String  [0..*] -- delegate-key/parameter-name overrides
 * @constraints
 *   [valid_type]: type in {"String","Integer","Float","Boolean"}.
 */
export interface IConfigurationParameter extends IUIMABase {
  readonly name: string;
  readonly description: string | undefined;
  readonly type: string;
  readonly multiValued: boolean | undefined;
  readonly mandatory: boolean | undefined;
  readonly overrides: ReadonlyArray<string>;
}

// --- 44. IConfigurationParameterDeclaration (§4.6) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.6 Processing Element Metadata
 * @section §4.6.1 Elements of PE Metadata
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition ConfigurationParameterDeclarations is the descriptor element
 *   that groups all ConfigurationParameter declarations of a
 *   ProcessingElement. It also enumerates the optional ConfigurationGroups
 *   for grouped parameters (a UIMA pattern in which multiple parameters share
 *   a common search-strategy: "default_fallback", "language_fallback",
 *   "none").
 * @ownedAttributes
 *   searchStrategy            : String [0..1] -- "language_fallback" | "default_fallback" | "none"
 *   defaultGroup              : String [0..1] -- when grouped
 * @associationEnds
 *   commonParameters : ConfigurationParameter  [0..*] {composite}
 *   groups           : ConfigurationGroup      [0..*] {composite}
 */
export interface IConfigurationParameterDeclaration extends IUIMABase {
  readonly searchStrategy: string | undefined;
  readonly defaultGroup: string | undefined;
  readonly commonParameterIds: ReadonlyArray<string>;
  readonly groupIds: ReadonlyArray<string>;
}

// --- 45. IConfigurationGroup (§4.6) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.6 Processing Element Metadata
 * @section §4.6.1 Elements of PE Metadata — Configuration Group
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition ConfigurationGroup binds a set of ConfigurationParameters
 *   together under one or more group names. The UIMA framework consults the
 *   group at runtime to look up parameter values according to the parent
 *   declaration's searchStrategy.
 * @ownedAttributes
 *   names : String [1..*] {ordered} -- the group name(s)
 * @associationEnds
 *   parameters : ConfigurationParameter [0..*] {composite}
 */
export interface IConfigurationGroup extends IUIMABase {
  readonly names: ReadonlyArray<string>;
  readonly parameterIds: ReadonlyArray<string>;
}

// --- 46. IConfigurationParameterSetting (§4.6) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.6 Processing Element Metadata
 * @section §4.6.1 Elements of PE Metadata — Configuration Parameter Settings
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition ConfigurationParameterSettings binds NameValuePair instances
 *   to the declared ConfigurationParameters of a ProcessingElement at
 *   deployment time. Per §4.6.1: the settings element may carry settings for
 *   the common parameter set and per-group settings for each declared
 *   ConfigurationGroup.
 * @associationEnds
 *   commonSettings    : NameValuePair [0..*] {composite}
 *   settingsPerGroup  : (groupName : String, NameValuePair [0..*]) [0..*]
 *                                                                  {composite}
 */
export interface IConfigurationParameterSetting extends IUIMABase {
  readonly commonSettingIds: ReadonlyArray<string>;
  readonly settingsPerGroup: ReadonlyMap<string, ReadonlyArray<string>>;
}

// --- 47. INameValuePair (§4.6) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.6 Processing Element Metadata
 * @section §4.6.1 Elements of PE Metadata — Name Value Pair
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition NameValuePair is the single (parameterName, parameterValue)
 *   binding inside a ConfigurationParameterSettings. Per §4.6.1: the value
 *   carries one of the four UIMA configuration-parameter primitive types or
 *   an array of them.
 * @ownedAttributes
 *   name  : String [1]
 *   value : Object [0..1] -- String | Integer | Float | Boolean | Array
 */
export interface INameValuePair extends IUIMABase {
  readonly name: string;
  readonly value: unknown;
}

// --- 48. IExtension (§4.6) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.6 Processing Element Metadata
 * @section §4.6.1 Elements of PE Metadata — Extension
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition Extension is the open-ended slot in PE Metadata for vendor- or
 *   profile-specific augmentation. Per §4.6.1: an Extension carries an
 *   `extenderId` (a vendor-namespaced identifier) and `contents` (the open
 *   serialized XML fragment the extender owns). The UIMA framework
 *   round-trips Extensions verbatim across descriptor parse and serialize.
 * @ownedAttributes
 *   extenderId : String [1]
 *   contents   : Object [0..1] -- vendor-defined XML/object structure
 */
export interface IExtension extends IUIMABase {
  readonly extenderId: string;
  readonly contents: unknown;
}

// ═══════════════════════════════════════════════════════════════════════════
// BEHAVIORAL METADATA + PE METADATA — class implementations
// ═══════════════════════════════════════════════════════════════════════════

/** @standard OASIS UIMA 1.0 (2009) §4.5 — concrete class implementation. */
export class BehavioralMetadata extends UIMABase implements IBehavioralMetadata {
  readonly capabilityIds: ReadonlyArray<string>;
  constructor(data: { elementId: string; capabilityIds: ReadonlyArray<string> }) {
    super({ elementId: data.elementId });
    this.capabilityIds = data.capabilityIds;
  }
}

/** @standard OASIS UIMA 1.0 (2009) §4.5 — concrete class implementation. */
export class Capability extends UIMABase implements ICapability {
  readonly inputSofas: ReadonlyArray<string>;
  readonly outputSofas: ReadonlyArray<string>;
  readonly languagesSupported: ReadonlyArray<string>;
  readonly description: string | undefined;
  readonly analyzedTypeIds: ReadonlyArray<string>;
  readonly requiredInputIds: ReadonlyArray<string>;
  readonly optionalInputIds: ReadonlyArray<string>;
  readonly createdTypeIds: ReadonlyArray<string>;
  readonly modifiedTypeIds: ReadonlyArray<string>;
  readonly deletedTypeIds: ReadonlyArray<string>;
  readonly preconditionIds: ReadonlyArray<string>;
  readonly postconditionIds: ReadonlyArray<string>;
  readonly projectionConditionIds: ReadonlyArray<string>;
  readonly parentMetadataId: string;
  constructor(data: {
    elementId: string;
    inputSofas: ReadonlyArray<string>;
    outputSofas: ReadonlyArray<string>;
    languagesSupported: ReadonlyArray<string>;
    description: string | undefined;
    analyzedTypeIds: ReadonlyArray<string>;
    requiredInputIds: ReadonlyArray<string>;
    optionalInputIds: ReadonlyArray<string>;
    createdTypeIds: ReadonlyArray<string>;
    modifiedTypeIds: ReadonlyArray<string>;
    deletedTypeIds: ReadonlyArray<string>;
    preconditionIds: ReadonlyArray<string>;
    postconditionIds: ReadonlyArray<string>;
    projectionConditionIds: ReadonlyArray<string>;
    parentMetadataId: string;
  }) {
    super({ elementId: data.elementId });
    this.inputSofas = data.inputSofas;
    this.outputSofas = data.outputSofas;
    this.languagesSupported = data.languagesSupported;
    this.description = data.description;
    this.analyzedTypeIds = data.analyzedTypeIds;
    this.requiredInputIds = data.requiredInputIds;
    this.optionalInputIds = data.optionalInputIds;
    this.createdTypeIds = data.createdTypeIds;
    this.modifiedTypeIds = data.modifiedTypeIds;
    this.deletedTypeIds = data.deletedTypeIds;
    this.preconditionIds = data.preconditionIds;
    this.postconditionIds = data.postconditionIds;
    this.projectionConditionIds = data.projectionConditionIds;
    this.parentMetadataId = data.parentMetadataId;
  }
}

/** @standard OASIS UIMA 1.0 (2009) §4.5.3 — concrete class implementation. */
export class Condition extends UIMABase implements ICondition {
  readonly language: string;
  readonly expression: string;
  readonly description: string | undefined;
  constructor(data: {
    elementId: string;
    language: string;
    expression: string;
    description: string | undefined;
  }) {
    super({ elementId: data.elementId });
    this.language = data.language;
    this.expression = data.expression;
    this.description = data.description;
  }
}

/** @standard OASIS UIMA 1.0 (2009) §4.6 — concrete class implementation. */
export class ProcessingElementMetadata extends UIMABase implements IProcessingElementMetadata {
  readonly identificationId: string;
  readonly configurationParameterDeclsId: string | undefined;
  readonly configurationParameterSettingsId: string | undefined;
  readonly behavioralMetadataId: string | undefined;
  readonly typeSystemId: string | undefined;
  readonly typePrioritiesId: string | undefined;
  readonly fsIndexCollectionId: string | undefined;
  readonly resourceManagerConfigId: string | undefined;
  readonly operationalPropertiesId: string | undefined;
  readonly extensionIds: ReadonlyArray<string>;
  constructor(data: {
    elementId: string;
    identificationId: string;
    configurationParameterDeclsId: string | undefined;
    configurationParameterSettingsId: string | undefined;
    behavioralMetadataId: string | undefined;
    typeSystemId: string | undefined;
    typePrioritiesId: string | undefined;
    fsIndexCollectionId: string | undefined;
    resourceManagerConfigId: string | undefined;
    operationalPropertiesId: string | undefined;
    extensionIds: ReadonlyArray<string>;
  }) {
    super({ elementId: data.elementId });
    this.identificationId = data.identificationId;
    this.configurationParameterDeclsId = data.configurationParameterDeclsId;
    this.configurationParameterSettingsId = data.configurationParameterSettingsId;
    this.behavioralMetadataId = data.behavioralMetadataId;
    this.typeSystemId = data.typeSystemId;
    this.typePrioritiesId = data.typePrioritiesId;
    this.fsIndexCollectionId = data.fsIndexCollectionId;
    this.resourceManagerConfigId = data.resourceManagerConfigId;
    this.operationalPropertiesId = data.operationalPropertiesId;
    this.extensionIds = data.extensionIds;
  }
}

/** @standard OASIS UIMA 1.0 (2009) §4.6.1 — concrete class implementation. */
export class IdentificationInfo extends UIMABase implements IIdentificationInfo {
  readonly symbolicName: string;
  readonly name: string | undefined;
  readonly description: string | undefined;
  readonly version: string | undefined;
  readonly vendor: string | undefined;
  readonly copyright: string | undefined;
  readonly url: string | undefined;
  constructor(data: {
    elementId: string;
    symbolicName: string;
    name: string | undefined;
    description: string | undefined;
    version: string | undefined;
    vendor: string | undefined;
    copyright: string | undefined;
    url: string | undefined;
  }) {
    super({ elementId: data.elementId });
    this.symbolicName = data.symbolicName;
    this.name = data.name;
    this.description = data.description;
    this.version = data.version;
    this.vendor = data.vendor;
    this.copyright = data.copyright;
    this.url = data.url;
  }
}

/** @standard OASIS UIMA 1.0 (2009) §4.6.1 — concrete class implementation. */
export class ConfigurationParameter extends UIMABase implements IConfigurationParameter {
  readonly name: string;
  readonly description: string | undefined;
  readonly type: string;
  readonly multiValued: boolean | undefined;
  readonly mandatory: boolean | undefined;
  readonly overrides: ReadonlyArray<string>;
  constructor(data: {
    elementId: string;
    name: string;
    description: string | undefined;
    type: string;
    multiValued: boolean | undefined;
    mandatory: boolean | undefined;
    overrides: ReadonlyArray<string>;
  }) {
    super({ elementId: data.elementId });
    this.name = data.name;
    this.description = data.description;
    this.type = data.type;
    this.multiValued = data.multiValued;
    this.mandatory = data.mandatory;
    this.overrides = data.overrides;
  }
}

/** @standard OASIS UIMA 1.0 (2009) §4.6.1 — concrete class implementation. */
export class ConfigurationParameterDeclaration extends UIMABase implements IConfigurationParameterDeclaration {
  readonly searchStrategy: string | undefined;
  readonly defaultGroup: string | undefined;
  readonly commonParameterIds: ReadonlyArray<string>;
  readonly groupIds: ReadonlyArray<string>;
  constructor(data: {
    elementId: string;
    searchStrategy: string | undefined;
    defaultGroup: string | undefined;
    commonParameterIds: ReadonlyArray<string>;
    groupIds: ReadonlyArray<string>;
  }) {
    super({ elementId: data.elementId });
    this.searchStrategy = data.searchStrategy;
    this.defaultGroup = data.defaultGroup;
    this.commonParameterIds = data.commonParameterIds;
    this.groupIds = data.groupIds;
  }
}

/** @standard OASIS UIMA 1.0 (2009) §4.6.1 — concrete class implementation. */
export class ConfigurationGroup extends UIMABase implements IConfigurationGroup {
  readonly names: ReadonlyArray<string>;
  readonly parameterIds: ReadonlyArray<string>;
  constructor(data: {
    elementId: string;
    names: ReadonlyArray<string>;
    parameterIds: ReadonlyArray<string>;
  }) {
    super({ elementId: data.elementId });
    this.names = data.names;
    this.parameterIds = data.parameterIds;
  }
}

/** @standard OASIS UIMA 1.0 (2009) §4.6.1 — concrete class implementation. */
export class ConfigurationParameterSetting extends UIMABase implements IConfigurationParameterSetting {
  readonly commonSettingIds: ReadonlyArray<string>;
  readonly settingsPerGroup: ReadonlyMap<string, ReadonlyArray<string>>;
  constructor(data: {
    elementId: string;
    commonSettingIds: ReadonlyArray<string>;
    settingsPerGroup: ReadonlyMap<string, ReadonlyArray<string>>;
  }) {
    super({ elementId: data.elementId });
    this.commonSettingIds = data.commonSettingIds;
    this.settingsPerGroup = data.settingsPerGroup;
  }
}

/** @standard OASIS UIMA 1.0 (2009) §4.6.1 — concrete class implementation. */
export class NameValuePair extends UIMABase implements INameValuePair {
  readonly name: string;
  readonly value: unknown;
  constructor(data: { elementId: string; name: string; value: unknown }) {
    super({ elementId: data.elementId });
    this.name = data.name;
    this.value = data.value;
  }
}

/** @standard OASIS UIMA 1.0 (2009) §4.6.1 — concrete class implementation. */
export class Extension extends UIMABase implements IExtension {
  readonly extenderId: string;
  readonly contents: unknown;
  constructor(data: { elementId: string; extenderId: string; contents: unknown }) {
    super({ elementId: data.elementId });
    this.extenderId = data.extenderId;
    this.contents = data.contents;
  }
}

// ─────────────────────────────────────────────────────────────────────────────
// ANALYSIS ENGINE DESCRIPTORS (Apache UIMA 3.x — derived from §4.6)
// ─────────────────────────────────────────────────────────────────────────────

// --- 49. IAnalysisEngineDescription (Apache UIMA references §2) --- abstract
/**
 * @standard Apache UIMA 3.6.x — references.html §2 (Analysis Engine Descriptors)
 * @chapter §4.6 Processing Element Metadata (OASIS UIMA 1.0 base)
 * @metaclass abstract
 * @generalization IUIMABase
 * @definition AnalysisEngineDescription is the descriptor element that
 *   declares an Analysis Engine — the Apache UIMA reference implementation's
 *   Java realization of the OASIS UIMA Analyzer interface (§4.4). The
 *   descriptor is XML-serialized; concrete subtypes are
 *   PrimitiveAnalysisEngineDescription (wraps a single Annotator
 *   implementation class) and AggregateAnalysisEngineDescription (composes
 *   one or more delegate AnalysisEngines under a FlowController).
 * @ownedAttributes
 *   frameworkImplementation : String [1] -- e.g., "org.apache.uima.java"
 *   primitive               : Boolean [1] -- discriminator over the subtypes
 *   annotatorImplementationName : String [0..1] -- when primitive = true
 * @associationEnds
 *   metadata : AnalysisEngineMetaData [1] {composite}
 *   externalResourceDependencies : ExternalResourceDescription [0..*] {composite}
 */
export interface IAnalysisEngineDescription extends IUIMABase {
  readonly frameworkImplementation: string;
  readonly primitive: boolean;
  readonly annotatorImplementationName: string | undefined;
  readonly metadataId: string;
  readonly externalResourceDependencyIds: ReadonlyArray<string>;
}

// --- 50. IPrimitiveAnalysisEngineDescription (Apache UIMA §2) ---
/**
 * @standard Apache UIMA 3.6.x — references.html §2.1 (Primitive Analysis Engine)
 * @metaclass concrete
 * @generalization IAnalysisEngineDescription
 * @definition PrimitiveAnalysisEngineDescription wraps a single Annotator
 *   implementation class (Java class extending JCasAnnotator_ImplBase or
 *   CasAnnotator_ImplBase). Per Apache UIMA references §2.1: "A primitive
 *   Analysis Engine has primitive = true, an annotatorImplementationName
 *   resolving to a Java class, and exactly one metadata block."
 */
export interface IPrimitiveAnalysisEngineDescription extends IAnalysisEngineDescription {}

// --- 51. IAggregateAnalysisEngineDescription (Apache UIMA §2) ---
/**
 * @standard Apache UIMA 3.6.x — references.html §2.2 (Aggregate Analysis Engine)
 * @metaclass concrete
 * @generalization IAnalysisEngineDescription
 * @definition AggregateAnalysisEngineDescription composes one or more
 *   delegate AnalysisEngines under a FlowController. Per Apache UIMA
 *   references §2.2: "An aggregate has primitive = false, a delegate map
 *   keyed by component-key (the within-aggregate name), and a
 *   FlowControllerDescription specifying the routing topology." The
 *   delegate map values can be either inline AnalysisEngineDescription or
 *   Import elements that reference external descriptor files.
 * @ownedAttributes
 *   delegates       : Map<String, AnalysisEngineDescription> [0..*]
 *   delegateImports : Map<String, Import>                    [0..*]
 *   sofaMappings    : SofaMapping [0..*] -- maps delegate sofa names to
 *                                           aggregate sofa names
 * @associationEnds
 *   flowController : FlowControllerDescription [0..1] {composite}
 *   flowConstraints : FlowConstraints           [0..1] {composite}
 */
export interface IAggregateAnalysisEngineDescription extends IAnalysisEngineDescription {
  readonly delegateIds: ReadonlyMap<string, string>;
  readonly delegateImportIds: ReadonlyMap<string, string>;
  readonly sofaMappingIds: ReadonlyArray<string>;
  readonly flowControllerId: string | undefined;
  readonly flowConstraintsId: string | undefined;
}

// --- 52. IAnalysisEngineMetaData (Apache UIMA §2) ---
/**
 * @standard Apache UIMA 3.6.x — references.html §2.3 (Analysis Engine Metadata)
 * @chapter §4.6 Processing Element Metadata (OASIS UIMA 1.0 base)
 * @metaclass concrete
 * @generalization IProcessingElementMetadata
 * @definition AnalysisEngineMetaData specializes ProcessingElementMetadata
 *   for AnalysisEngines. It carries the same identification, configuration,
 *   behavioral, type-system, type-priorities, fs-index, resource-manager,
 *   operational-properties, and extension fields as its parent, and adds
 *   no new fields — the specialization is structural only (it asserts that
 *   the metadata belongs to an AnalysisEngine vs. a CollectionReader,
 *   CASConsumer, etc.).
 */
export interface IAnalysisEngineMetaData extends IProcessingElementMetadata {}

// --- 53. IFlowControllerDescription (Apache UIMA §2) ---
/**
 * @standard Apache UIMA 3.6.x — references.html §2.5 (Flow Controllers)
 * @chapter §4.6 (PE Metadata) + §4.4.2 (Abstract Interfaces)
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition FlowControllerDescription is the descriptor element wrapping a
 *   FlowController implementation. Per Apache UIMA references §2.5: the
 *   description carries an `implementationName` (Java class extending
 *   JCasFlowController_ImplBase or CasFlowController_ImplBase), an inline
 *   ProcessingElementMetadata, and any external resource bindings needed by
 *   the FlowController at runtime.
 * @ownedAttributes
 *   implementationName : String [1]
 *   frameworkImplementation : String [1] -- e.g., "org.apache.uima.java"
 * @associationEnds
 *   metadata : ProcessingElementMetadata [1] {composite}
 */
export interface IFlowControllerDescription extends IUIMABase {
  readonly implementationName: string;
  readonly frameworkImplementation: string;
  readonly metadataId: string;
}

// --- 54. IFlowConstraints (Apache UIMA §2) --- abstract
/**
 * @standard Apache UIMA 3.6.x — references.html §2.4 (Flow Constraints)
 * @metaclass abstract
 * @generalization IUIMABase
 * @definition FlowConstraints is the abstract descriptor declaring the
 *   simple-flow constraints of an AggregateAnalysisEngine when no custom
 *   FlowController is provided. Per Apache UIMA references §2.4: concrete
 *   subtypes are FixedFlow (delegates run in a fixed sequence) and
 *   CapabilityLanguageFlow (delegates run in capability-and-language order).
 *   At descriptor-resolution time, FlowConstraints is converted to a
 *   built-in FlowController (FixedFlowController or CapabilityLanguageFlowController).
 */
export interface IFlowConstraints extends IUIMABase {}

// --- 55. IFixedFlow (Apache UIMA §2) ---
/**
 * @standard Apache UIMA 3.6.x — references.html §2.4.1 (FixedFlow)
 * @metaclass concrete
 * @generalization IFlowConstraints
 * @definition FixedFlow declares an ordered sequence of delegate keys. The
 *   AggregateAnalysisEngine routes every CAS through the keys in order. Per
 *   Apache UIMA references §2.4.1: "FixedFlow is the simplest flow shape
 *   and is the default if no FlowConstraints are declared on the aggregate."
 * @ownedAttributes
 *   nodes : String [1..*] {ordered} -- ordered delegate keys
 */
export interface IFixedFlow extends IFlowConstraints {
  readonly nodes: ReadonlyArray<string>;
}

// --- 56. ICapabilityLanguageFlow (Apache UIMA §2) ---
/**
 * @standard Apache UIMA 3.6.x — references.html §2.4.2 (CapabilityLanguageFlow)
 * @metaclass concrete
 * @generalization IFlowConstraints
 * @definition CapabilityLanguageFlow declares a delegate-key sequence with
 *   a guard: each delegate is invoked only if its declared Capability covers
 *   the required Types and the CAS's documentLanguage matches the delegate's
 *   languagesSupported. Per Apache UIMA references §2.4.2: "The capability
 *   filter lets aggregates declare a fan-out of language- and capability-
 *   specialized delegates without bespoke FlowController code."
 * @ownedAttributes
 *   nodes : String [1..*] {ordered}
 */
export interface ICapabilityLanguageFlow extends IFlowConstraints {
  readonly nodes: ReadonlyArray<string>;
}

// ─────────────────────────────────────────────────────────────────────────────
// AUXILIARY COMPONENTS — Collection Processing (Apache UIMA §7)
// ─────────────────────────────────────────────────────────────────────────────

// --- 57. ICollectionReaderDescription (Apache UIMA §7) ---
/**
 * @standard Apache UIMA 3.6.x — references.html §7 (Collection Processing)
 * @chapter §4.4.2 (Abstract Interfaces — ProcessingElement)
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition CollectionReaderDescription declares a CollectionReader — the
 *   ProcessingElement at the head of a Collection Processing Engine that
 *   produces a stream of CASes from an external corpus. Per Apache UIMA
 *   references §7.2: "A CollectionReader implements
 *   `getNext(CAS) → void`, `hasNext() → boolean`, `getProgress() → Progress`."
 *   The descriptor wraps the reader's implementation class, its PE Metadata,
 *   and any external resource dependencies.
 * @ownedAttributes
 *   implementationName : String [1]
 *   frameworkImplementation : String [1]
 * @associationEnds
 *   metadata : ProcessingElementMetadata [1] {composite}
 *   externalResourceDependencies : ExternalResourceDescription [0..*] {composite}
 */
export interface ICollectionReaderDescription extends IUIMABase {
  readonly implementationName: string;
  readonly frameworkImplementation: string;
  readonly metadataId: string;
  readonly externalResourceDependencyIds: ReadonlyArray<string>;
}

// --- 58. ICASConsumerDescription (Apache UIMA §7) ---
/**
 * @standard Apache UIMA 3.6.x — references.html §7.3 (CAS Consumers)
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition CASConsumerDescription declares a CASConsumer — the
 *   ProcessingElement at the tail of a Collection Processing Engine that
 *   serializes, indexes, or otherwise persists analysis results. Per Apache
 *   UIMA references §7.3: "A CASConsumer is an Analysis Engine that does not
 *   modify the CAS — it implements `processCas` but reads only." In Apache
 *   UIMA 3.x, CASConsumer is a special-case AnalysisEngine with
 *   modifiesCas = false.
 * @ownedAttributes
 *   implementationName : String [1]
 *   frameworkImplementation : String [1]
 * @associationEnds
 *   metadata : ProcessingElementMetadata [1] {composite}
 *   externalResourceDependencies : ExternalResourceDescription [0..*] {composite}
 */
export interface ICASConsumerDescription extends IUIMABase {
  readonly implementationName: string;
  readonly frameworkImplementation: string;
  readonly metadataId: string;
  readonly externalResourceDependencyIds: ReadonlyArray<string>;
}

// --- 59. ICASMultiplierDescription (Apache UIMA §7) ---
/**
 * @standard Apache UIMA 3.6.x — references.html §2.6 (CAS Multipliers)
 * @chapter §4.4.2 (Abstract Interfaces — CasMultiplier)
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition CASMultiplierDescription declares a CASMultiplier — the
 *   Analytic that fans one input CAS into N output CASes. Per Apache UIMA
 *   references §2.6: "A CAS Multiplier is an Analysis Engine whose
 *   operationalProperties.outputsNewCASes = true." The descriptor uses the
 *   same shape as AnalysisEngineDescription, distinguished only by the
 *   outputsNewCASes flag.
 * @ownedAttributes
 *   implementationName : String [1]
 *   frameworkImplementation : String [1]
 * @associationEnds
 *   metadata : ProcessingElementMetadata [1] {composite}
 */
export interface ICASMultiplierDescription extends IUIMABase {
  readonly implementationName: string;
  readonly frameworkImplementation: string;
  readonly metadataId: string;
}

// --- 60. ICASInitializerDescription (Apache UIMA §7) ---
/**
 * @standard Apache UIMA 3.6.x — references.html §7.2 (CAS Initializers)
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition CASInitializerDescription declares a CASInitializer — the
 *   ProcessingElement that prepares an empty CAS for population by a
 *   CollectionReader. Per Apache UIMA references §7.2: "CAS Initializers are
 *   deprecated as of Apache UIMA 2.4.0; use CollectionReader directly. The
 *   descriptor is preserved for round-trip compatibility with legacy CPE
 *   files."
 * @ownedAttributes
 *   implementationName : String [1]
 *   frameworkImplementation : String [1]
 * @associationEnds
 *   metadata : ProcessingElementMetadata [1] {composite}
 */
export interface ICASInitializerDescription extends IUIMABase {
  readonly implementationName: string;
  readonly frameworkImplementation: string;
  readonly metadataId: string;
}

// --- 61. ICollectionProcessingEngine (Apache UIMA §7) ---
/**
 * @standard Apache UIMA 3.6.x — references.html §7.5 (CPE Descriptor)
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition CollectionProcessingEngine is the descriptor that ties a
 *   CollectionReader, an optional CASInitializer, an ordered list of
 *   AnalysisEngines, and a list of CASConsumers into one runnable unit.
 *   Per Apache UIMA references §7.5: "A CPE is configured by a
 *   CpeDescription XML file declaring its CollectionReader, its
 *   AnalysisEngine sequence, its CASConsumer sequence, the CPE-level
 *   resource manager, and the CPE-level checkpointing/error-handling policy."
 * @ownedAttributes
 *   description : String [0..1]
 *   maxConcurrentTasks : Integer [0..1]
 *   processCount : Integer [0..1] -- target CAS-process count
 * @associationEnds
 *   collectionReader : CollectionReaderDescription [1]
 *   casInitializer   : CASInitializerDescription   [0..1] -- deprecated
 *   analysisEngines  : AnalysisEngineDescription   [0..*] {ordered}
 *   casConsumers     : CASConsumerDescription      [0..*] {ordered}
 */
export interface ICollectionProcessingEngine extends IUIMABase {
  readonly description: string | undefined;
  readonly maxConcurrentTasks: number | undefined;
  readonly processCount: number | undefined;
  readonly collectionReaderId: string;
  readonly casInitializerId: string | undefined;
  readonly analysisEngineIds: ReadonlyArray<string>;
  readonly casConsumerIds: ReadonlyArray<string>;
}

// ─────────────────────────────────────────────────────────────────────────────
// RESOURCE MANAGER + EXTERNAL RESOURCES (Apache UIMA references §3.5)
// ─────────────────────────────────────────────────────────────────────────────

// --- 62. IResourceManagerConfiguration (Apache UIMA §3.5) ---
/**
 * @standard Apache UIMA 3.6.x — references.html §3.5 (Resource Manager Configuration)
 * @chapter §4.6.1 (PE Metadata — Extension surface)
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition ResourceManagerConfiguration is the descriptor block that
 *   binds the External Resources used by a ProcessingElement at runtime.
 *   Per Apache UIMA references §3.5: "ResourceManagerConfiguration enumerates
 *   ExternalResourceDescription entries (the available resources) and
 *   ExternalResourceBinding entries (the parameter-key-to-resource bindings
 *   the implementation reads at runtime)."
 * @ownedAttributes
 *   name        : String [0..1]
 *   description : String [0..1]
 *   version     : String [0..1]
 *   vendor      : String [0..1]
 * @associationEnds
 *   externalResources       : ExternalResourceDescription [0..*] {composite}
 *   externalResourceBindings: ExternalResourceBinding     [0..*] {composite}
 *   imports                 : Import                      [0..*] {composite}
 */
export interface IResourceManagerConfiguration extends IUIMABase {
  readonly name: string | undefined;
  readonly description: string | undefined;
  readonly version: string | undefined;
  readonly vendor: string | undefined;
  readonly externalResourceIds: ReadonlyArray<string>;
  readonly externalResourceBindingIds: ReadonlyArray<string>;
  readonly importIds: ReadonlyArray<string>;
}

// --- 63. IResourceSpecifier (Apache UIMA §3.5) --- abstract
/**
 * @standard Apache UIMA 3.6.x — references.html §3.5 (Resource Specifiers)
 * @metaclass abstract
 * @generalization IUIMABase
 * @definition ResourceSpecifier is the abstract base for the descriptor
 *   element identifying *how* an ExternalResource is loaded. Per Apache UIMA
 *   references §3.5: "Concrete subtypes are FileResourceSpecifier (loads from
 *   a file URL), RelativePathResourceSpecifier (loads from a path resolved
 *   against the UIMA data path), CustomResourceSpecifier (loads through an
 *   arbitrary user-defined ResourceSpecifierFactory), and the various
 *   AnalysisEngineDescription / CollectionReaderDescription /
 *   CASConsumerDescription / CustomResourceSpecifier subtypes when the
 *   ExternalResource itself is a UIMA ProcessingElement."
 */
export interface IResourceSpecifier extends IUIMABase {}

// --- 64. IFileResourceSpecifier (Apache UIMA §3.5) ---
/**
 * @standard Apache UIMA 3.6.x — references.html §3.5.1 (FileResourceSpecifier)
 * @metaclass concrete
 * @generalization IResourceSpecifier
 * @definition FileResourceSpecifier loads an ExternalResource from a file
 *   URL. Per Apache UIMA references §3.5.1: "fileUrl is an absolute or
 *   relative URL; localCache is an optional secondary URL for a local cached
 *   copy."
 * @ownedAttributes
 *   fileUrl    : String [1]
 *   localCache : String [0..1]
 */
export interface IFileResourceSpecifier extends IResourceSpecifier {
  readonly fileUrl: string;
  readonly localCache: string | undefined;
}

// --- 65. IRelativePathResourceSpecifier (Apache UIMA §3.5) ---
/**
 * @standard Apache UIMA 3.6.x — references.html §3.5.2 (RelativePathResourceSpecifier)
 * @metaclass concrete
 * @generalization IResourceSpecifier
 * @definition RelativePathResourceSpecifier loads an ExternalResource from a
 *   path resolved against the UIMA data path. Per Apache UIMA references
 *   §3.5.2: "relativePath is interpreted against the colon-separated
 *   datapath property of the ResourceManager."
 * @ownedAttributes
 *   relativePath : String [1]
 *   localCache   : String [0..1]
 */
export interface IRelativePathResourceSpecifier extends IResourceSpecifier {
  readonly relativePath: string;
  readonly localCache: string | undefined;
}

// --- 66. IExternalResourceDescription (Apache UIMA §3.5) ---
/**
 * @standard Apache UIMA 3.6.x — references.html §3.5 (External Resource Description)
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition ExternalResourceDescription declares one available external
 *   resource (a file, a path, a remote service, a sub-pipeline). Per Apache
 *   UIMA references §3.5: "Each description carries a `name` (the local
 *   resource key), a ResourceSpecifier that says *how* to load it, and an
 *   optional `implementationName` (a SharedResourceObject Java class that
 *   wraps the loaded data)."
 * @ownedAttributes
 *   name               : String [1]
 *   description        : String [0..1]
 *   implementationName : String [0..1]
 * @associationEnds
 *   resourceSpecifier : ResourceSpecifier [1] {composite}
 */
export interface IExternalResourceDescription extends IUIMABase {
  readonly name: string;
  readonly description: string | undefined;
  readonly implementationName: string | undefined;
  readonly resourceSpecifierId: string;
}

// --- 67. IExternalResourceBinding (Apache UIMA §3.5) ---
/**
 * @standard Apache UIMA 3.6.x — references.html §3.5 (External Resource Binding)
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition ExternalResourceBinding binds an external-resource-dependency
 *   key (declared by the ProcessingElement) to an ExternalResourceDescription
 *   by name. Per Apache UIMA references §3.5: "key is the name of the
 *   dependency declaration in the PE's external-resource-dependencies block;
 *   resourceName resolves to an ExternalResourceDescription declared in
 *   the same ResourceManagerConfiguration (or imported)."
 * @ownedAttributes
 *   key          : String [1]
 *   resourceName : String [1]
 */
export interface IExternalResourceBinding extends IUIMABase {
  readonly key: string;
  readonly resourceName: string;
}

// ─────────────────────────────────────────────────────────────────────────────
// OPERATIONAL PROPERTIES (Apache UIMA references §2.5)
// ─────────────────────────────────────────────────────────────────────────────

// --- 68. IOperationalProperties (Apache UIMA §2.5) ---
/**
 * @standard Apache UIMA 3.6.x — references.html §2.5 (Operational Properties)
 * @chapter §4.5 (Behavioral Metadata) + §4.6 (PE Metadata)
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition OperationalProperties declares runtime behavioral flags of a
 *   ProcessingElement that the framework must know to deploy and orchestrate
 *   the element correctly. Per Apache UIMA references §2.5: the three flags
 *   are:
 *
 *     - `modifiesCas` (default true): false for CASConsumer-style read-only
 *       elements; the framework can skip post-processing CAS reset.
 *     - `multipleDeploymentAllowed` (default true): false for elements that
 *       must run as a singleton (e.g., a stateful collector); UIMA-AS uses
 *       this flag to bound horizontal scale-out.
 *     - `outputsNewCASes` (default false): true for CASMultiplier; the
 *       framework treats the element's process loop as a generator.
 * @ownedAttributes
 *   modifiesCas               : Boolean [1] -- defaults to true
 *   multipleDeploymentAllowed : Boolean [1] -- defaults to true
 *   outputsNewCASes           : Boolean [1] -- defaults to false
 * @constraints
 *   [multiplier_outputs_new]: outputsNewCASes = true is required when the
 *     parent ProcessingElement is a CASMultiplier; the framework treats this
 *     as a hard gate.
 */
export interface IOperationalProperties extends IUIMABase {
  readonly modifiesCas: boolean;
  readonly multipleDeploymentAllowed: boolean;
  readonly outputsNewCASes: boolean;
}

// ─────────────────────────────────────────────────────────────────────────────
// SERVICE WSDL (§3.7 + §4.7)
// ─────────────────────────────────────────────────────────────────────────────

// --- 69. IServiceWSDLDescription (§4.7) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.7 Service WSDL Descriptions
 * @section §4.7.1 Overview of the WSDL Definition
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition ServiceWSDLDescription wraps the WSDL 1.1 definition of a UIMA
 *   service exposing a ProcessingElement over SOAP. Per §4.7: "A UIMA service
 *   is a SOAP endpoint exposing the four standard service operations
 *   (`getMetaData`, `process`, `processBatch`, `processDelta`); the WSDL
 *   binds the service's input/output messages to the UIMA SOAP message
 *   schema." The descriptor carries the WSDL location (URL) and the
 *   serviceQName (the WSDL service binding name).
 * @ownedAttributes
 *   wsdlLocation : String [1] -- URL of the WSDL document
 *   serviceQName : String [1] -- WSDL service binding qualified name
 *   description  : String [0..1]
 */
export interface IServiceWSDLDescription extends IUIMABase {
  readonly wsdlLocation: string;
  readonly serviceQName: string;
  readonly description: string | undefined;
}

// --- 70. IDeltaResponse (§4.7) ---
/**
 * @standard OASIS UIMA 1.0 (2009)
 * @chapter §4.7 Service WSDL Descriptions
 * @section §4.7.2 Delta Responses
 * @metaclass concrete
 * @generalization IUIMABase
 * @definition DeltaResponse is the response payload returned by the
 *   `processDelta` SOAP operation. Per §4.7.2: "Instead of returning the
 *   full modified CAS, the service returns only the differences (added,
 *   modified, deleted FeatureStructures), letting the caller reconstruct the
 *   modified CAS without retransmitting unchanged content. Delta responses
 *   are critical for bandwidth-bounded UIMA-AS distributed pipelines." The
 *   delta is structured as three FS-id sets: added, modified, deleted.
 * @ownedAttributes
 *   addedFsIds    : String [0..*]
 *   modifiedFsIds : String [0..*]
 *   deletedFsIds  : String [0..*]
 */
export interface IDeltaResponse extends IUIMABase {
  readonly addedFsIds: ReadonlyArray<string>;
  readonly modifiedFsIds: ReadonlyArray<string>;
  readonly deletedFsIds: ReadonlyArray<string>;
}

// ═══════════════════════════════════════════════════════════════════════════
// AE DESCRIPTORS + AUXILIARY + RESOURCE + OPERATIONAL + WSDL — class implementations
// ═══════════════════════════════════════════════════════════════════════════

/** @standard Apache UIMA 3.6.x references.html §2 — abstract class implementation. */
export abstract class AnalysisEngineDescription extends UIMABase implements IAnalysisEngineDescription {
  readonly frameworkImplementation: string;
  readonly primitive: boolean;
  readonly annotatorImplementationName: string | undefined;
  readonly metadataId: string;
  readonly externalResourceDependencyIds: ReadonlyArray<string>;
  protected constructor(data: {
    elementId: string;
    frameworkImplementation: string;
    primitive: boolean;
    annotatorImplementationName: string | undefined;
    metadataId: string;
    externalResourceDependencyIds: ReadonlyArray<string>;
  }) {
    super({ elementId: data.elementId });
    this.frameworkImplementation = data.frameworkImplementation;
    this.primitive = data.primitive;
    this.annotatorImplementationName = data.annotatorImplementationName;
    this.metadataId = data.metadataId;
    this.externalResourceDependencyIds = data.externalResourceDependencyIds;
  }
}

/** @standard Apache UIMA 3.6.x references.html §2.1 — concrete class implementation. */
export class PrimitiveAnalysisEngineDescription extends AnalysisEngineDescription implements IPrimitiveAnalysisEngineDescription {
  constructor(data: {
    elementId: string;
    frameworkImplementation: string;
    annotatorImplementationName: string;
    metadataId: string;
    externalResourceDependencyIds: ReadonlyArray<string>;
  }) {
    super({
      elementId: data.elementId,
      frameworkImplementation: data.frameworkImplementation,
      primitive: true,
      annotatorImplementationName: data.annotatorImplementationName,
      metadataId: data.metadataId,
      externalResourceDependencyIds: data.externalResourceDependencyIds,
    });
  }
}

/** @standard Apache UIMA 3.6.x references.html §2.2 — concrete class implementation. */
export class AggregateAnalysisEngineDescription extends AnalysisEngineDescription implements IAggregateAnalysisEngineDescription {
  readonly delegateIds: ReadonlyMap<string, string>;
  readonly delegateImportIds: ReadonlyMap<string, string>;
  readonly sofaMappingIds: ReadonlyArray<string>;
  readonly flowControllerId: string | undefined;
  readonly flowConstraintsId: string | undefined;
  constructor(data: {
    elementId: string;
    frameworkImplementation: string;
    metadataId: string;
    externalResourceDependencyIds: ReadonlyArray<string>;
    delegateIds: ReadonlyMap<string, string>;
    delegateImportIds: ReadonlyMap<string, string>;
    sofaMappingIds: ReadonlyArray<string>;
    flowControllerId: string | undefined;
    flowConstraintsId: string | undefined;
  }) {
    super({
      elementId: data.elementId,
      frameworkImplementation: data.frameworkImplementation,
      primitive: false,
      annotatorImplementationName: undefined,
      metadataId: data.metadataId,
      externalResourceDependencyIds: data.externalResourceDependencyIds,
    });
    this.delegateIds = data.delegateIds;
    this.delegateImportIds = data.delegateImportIds;
    this.sofaMappingIds = data.sofaMappingIds;
    this.flowControllerId = data.flowControllerId;
    this.flowConstraintsId = data.flowConstraintsId;
  }
}

/** @standard Apache UIMA 3.6.x references.html §2.3 — concrete class implementation. */
export class AnalysisEngineMetaData extends ProcessingElementMetadata implements IAnalysisEngineMetaData {}

/** @standard Apache UIMA 3.6.x references.html §2.5 — concrete class implementation. */
export class FlowControllerDescription extends UIMABase implements IFlowControllerDescription {
  readonly implementationName: string;
  readonly frameworkImplementation: string;
  readonly metadataId: string;
  constructor(data: {
    elementId: string;
    implementationName: string;
    frameworkImplementation: string;
    metadataId: string;
  }) {
    super({ elementId: data.elementId });
    this.implementationName = data.implementationName;
    this.frameworkImplementation = data.frameworkImplementation;
    this.metadataId = data.metadataId;
  }
}

/** @standard Apache UIMA 3.6.x references.html §2.4 — abstract class implementation. */
export abstract class FlowConstraints extends UIMABase implements IFlowConstraints {}

/** @standard Apache UIMA 3.6.x references.html §2.4.1 — concrete class implementation. */
export class FixedFlow extends FlowConstraints implements IFixedFlow {
  readonly nodes: ReadonlyArray<string>;
  constructor(data: { elementId: string; nodes: ReadonlyArray<string> }) {
    super({ elementId: data.elementId });
    this.nodes = data.nodes;
  }
}

/** @standard Apache UIMA 3.6.x references.html §2.4.2 — concrete class implementation. */
export class CapabilityLanguageFlow extends FlowConstraints implements ICapabilityLanguageFlow {
  readonly nodes: ReadonlyArray<string>;
  constructor(data: { elementId: string; nodes: ReadonlyArray<string> }) {
    super({ elementId: data.elementId });
    this.nodes = data.nodes;
  }
}

/** @standard Apache UIMA 3.6.x references.html §7 — concrete class implementation. */
export class CollectionReaderDescription extends UIMABase implements ICollectionReaderDescription {
  readonly implementationName: string;
  readonly frameworkImplementation: string;
  readonly metadataId: string;
  readonly externalResourceDependencyIds: ReadonlyArray<string>;
  constructor(data: {
    elementId: string;
    implementationName: string;
    frameworkImplementation: string;
    metadataId: string;
    externalResourceDependencyIds: ReadonlyArray<string>;
  }) {
    super({ elementId: data.elementId });
    this.implementationName = data.implementationName;
    this.frameworkImplementation = data.frameworkImplementation;
    this.metadataId = data.metadataId;
    this.externalResourceDependencyIds = data.externalResourceDependencyIds;
  }
}

/** @standard Apache UIMA 3.6.x references.html §7.3 — concrete class implementation. */
export class CASConsumerDescription extends UIMABase implements ICASConsumerDescription {
  readonly implementationName: string;
  readonly frameworkImplementation: string;
  readonly metadataId: string;
  readonly externalResourceDependencyIds: ReadonlyArray<string>;
  constructor(data: {
    elementId: string;
    implementationName: string;
    frameworkImplementation: string;
    metadataId: string;
    externalResourceDependencyIds: ReadonlyArray<string>;
  }) {
    super({ elementId: data.elementId });
    this.implementationName = data.implementationName;
    this.frameworkImplementation = data.frameworkImplementation;
    this.metadataId = data.metadataId;
    this.externalResourceDependencyIds = data.externalResourceDependencyIds;
  }
}

/** @standard Apache UIMA 3.6.x references.html §2.6 — concrete class implementation. */
export class CASMultiplierDescription extends UIMABase implements ICASMultiplierDescription {
  readonly implementationName: string;
  readonly frameworkImplementation: string;
  readonly metadataId: string;
  constructor(data: {
    elementId: string;
    implementationName: string;
    frameworkImplementation: string;
    metadataId: string;
  }) {
    super({ elementId: data.elementId });
    this.implementationName = data.implementationName;
    this.frameworkImplementation = data.frameworkImplementation;
    this.metadataId = data.metadataId;
  }
}

/** @standard Apache UIMA 3.6.x references.html §7.2 — concrete class implementation. */
export class CASInitializerDescription extends UIMABase implements ICASInitializerDescription {
  readonly implementationName: string;
  readonly frameworkImplementation: string;
  readonly metadataId: string;
  constructor(data: {
    elementId: string;
    implementationName: string;
    frameworkImplementation: string;
    metadataId: string;
  }) {
    super({ elementId: data.elementId });
    this.implementationName = data.implementationName;
    this.frameworkImplementation = data.frameworkImplementation;
    this.metadataId = data.metadataId;
  }
}

/** @standard Apache UIMA 3.6.x references.html §7.5 — concrete class implementation. */
export class CollectionProcessingEngine extends UIMABase implements ICollectionProcessingEngine {
  readonly description: string | undefined;
  readonly maxConcurrentTasks: number | undefined;
  readonly processCount: number | undefined;
  readonly collectionReaderId: string;
  readonly casInitializerId: string | undefined;
  readonly analysisEngineIds: ReadonlyArray<string>;
  readonly casConsumerIds: ReadonlyArray<string>;
  constructor(data: {
    elementId: string;
    description: string | undefined;
    maxConcurrentTasks: number | undefined;
    processCount: number | undefined;
    collectionReaderId: string;
    casInitializerId: string | undefined;
    analysisEngineIds: ReadonlyArray<string>;
    casConsumerIds: ReadonlyArray<string>;
  }) {
    super({ elementId: data.elementId });
    this.description = data.description;
    this.maxConcurrentTasks = data.maxConcurrentTasks;
    this.processCount = data.processCount;
    this.collectionReaderId = data.collectionReaderId;
    this.casInitializerId = data.casInitializerId;
    this.analysisEngineIds = data.analysisEngineIds;
    this.casConsumerIds = data.casConsumerIds;
  }
}

/** @standard Apache UIMA 3.6.x references.html §3.5 — concrete class implementation. */
export class ResourceManagerConfiguration extends UIMABase implements IResourceManagerConfiguration {
  readonly name: string | undefined;
  readonly description: string | undefined;
  readonly version: string | undefined;
  readonly vendor: string | undefined;
  readonly externalResourceIds: ReadonlyArray<string>;
  readonly externalResourceBindingIds: ReadonlyArray<string>;
  readonly importIds: ReadonlyArray<string>;
  constructor(data: {
    elementId: string;
    name: string | undefined;
    description: string | undefined;
    version: string | undefined;
    vendor: string | undefined;
    externalResourceIds: ReadonlyArray<string>;
    externalResourceBindingIds: ReadonlyArray<string>;
    importIds: ReadonlyArray<string>;
  }) {
    super({ elementId: data.elementId });
    this.name = data.name;
    this.description = data.description;
    this.version = data.version;
    this.vendor = data.vendor;
    this.externalResourceIds = data.externalResourceIds;
    this.externalResourceBindingIds = data.externalResourceBindingIds;
    this.importIds = data.importIds;
  }
}

/** @standard Apache UIMA 3.6.x references.html §3.5 — abstract class implementation. */
export abstract class ResourceSpecifier extends UIMABase implements IResourceSpecifier {}

/** @standard Apache UIMA 3.6.x references.html §3.5.1 — concrete class implementation. */
export class FileResourceSpecifier extends ResourceSpecifier implements IFileResourceSpecifier {
  readonly fileUrl: string;
  readonly localCache: string | undefined;
  constructor(data: {
    elementId: string;
    fileUrl: string;
    localCache: string | undefined;
  }) {
    super({ elementId: data.elementId });
    this.fileUrl = data.fileUrl;
    this.localCache = data.localCache;
  }
}

/** @standard Apache UIMA 3.6.x references.html §3.5.2 — concrete class implementation. */
export class RelativePathResourceSpecifier extends ResourceSpecifier implements IRelativePathResourceSpecifier {
  readonly relativePath: string;
  readonly localCache: string | undefined;
  constructor(data: {
    elementId: string;
    relativePath: string;
    localCache: string | undefined;
  }) {
    super({ elementId: data.elementId });
    this.relativePath = data.relativePath;
    this.localCache = data.localCache;
  }
}

/** @standard Apache UIMA 3.6.x references.html §3.5 — concrete class implementation. */
export class ExternalResourceDescription extends UIMABase implements IExternalResourceDescription {
  readonly name: string;
  readonly description: string | undefined;
  readonly implementationName: string | undefined;
  readonly resourceSpecifierId: string;
  constructor(data: {
    elementId: string;
    name: string;
    description: string | undefined;
    implementationName: string | undefined;
    resourceSpecifierId: string;
  }) {
    super({ elementId: data.elementId });
    this.name = data.name;
    this.description = data.description;
    this.implementationName = data.implementationName;
    this.resourceSpecifierId = data.resourceSpecifierId;
  }
}

/** @standard Apache UIMA 3.6.x references.html §3.5 — concrete class implementation. */
export class ExternalResourceBinding extends UIMABase implements IExternalResourceBinding {
  readonly key: string;
  readonly resourceName: string;
  constructor(data: { elementId: string; key: string; resourceName: string }) {
    super({ elementId: data.elementId });
    this.key = data.key;
    this.resourceName = data.resourceName;
  }
}

/** @standard Apache UIMA 3.6.x references.html §2.5 — concrete class implementation. */
export class OperationalProperties extends UIMABase implements IOperationalProperties {
  readonly modifiesCas: boolean;
  readonly multipleDeploymentAllowed: boolean;
  readonly outputsNewCASes: boolean;
  constructor(data: {
    elementId: string;
    modifiesCas: boolean;
    multipleDeploymentAllowed: boolean;
    outputsNewCASes: boolean;
  }) {
    super({ elementId: data.elementId });
    this.modifiesCas = data.modifiesCas;
    this.multipleDeploymentAllowed = data.multipleDeploymentAllowed;
    this.outputsNewCASes = data.outputsNewCASes;
  }
}

/** @standard OASIS UIMA 1.0 (2009) §4.7 — concrete class implementation. */
export class ServiceWSDLDescription extends UIMABase implements IServiceWSDLDescription {
  readonly wsdlLocation: string;
  readonly serviceQName: string;
  readonly description: string | undefined;
  constructor(data: {
    elementId: string;
    wsdlLocation: string;
    serviceQName: string;
    description: string | undefined;
  }) {
    super({ elementId: data.elementId });
    this.wsdlLocation = data.wsdlLocation;
    this.serviceQName = data.serviceQName;
    this.description = data.description;
  }
}

/** @standard OASIS UIMA 1.0 (2009) §4.7.2 — concrete class implementation. */
export class DeltaResponse extends UIMABase implements IDeltaResponse {
  readonly addedFsIds: ReadonlyArray<string>;
  readonly modifiedFsIds: ReadonlyArray<string>;
  readonly deletedFsIds: ReadonlyArray<string>;
  constructor(data: {
    elementId: string;
    addedFsIds: ReadonlyArray<string>;
    modifiedFsIds: ReadonlyArray<string>;
    deletedFsIds: ReadonlyArray<string>;
  }) {
    super({ elementId: data.elementId });
    this.addedFsIds = data.addedFsIds;
    this.modifiedFsIds = data.modifiedFsIds;
    this.deletedFsIds = data.deletedFsIds;
  }
}