gdc-common-utils-ts 1.17.0 → 1.20.0

package/README.md

@@ -30,6 +30,24 @@ boundaries used in `gdc-common-utils-ts`.
 - `resource.meta.claims` is the canonical project-specific claims container and must be preserved across conversions/transports.
 - `resource.meta.claims` is not part of base FHIR; it is a claims-first extension carried by FHIR-like resources in GDC contracts.
 
+## 101 Test Convention
+
+Every `101` test in this repo is expected to be a didactic executable tutorial,
+not only a behavior check.
+
+Required shape for `101` tests:
+
+- start with a short `Teaching goal` comment block
+- explain the main app/business flow, not only internal plumbing
+- use explicit `Step 1.`, `Step 2.`, ... comments for the happy path
+- make clear what the user/app already has, what is shown, what is edited,
+  what is saved, and what is reloaded
+- if a low-level helper path is shown, mark it explicitly as an escape hatch
+  and not the primary `101` path
+
+The goal is that a developer can read the test top-to-bottom as tutorial
+material without needing chat history or private repo context.
+
 If you need the canonical explanation of how DIDComm envelope, batch body,
 entry types, FHIR-like resources, and `resource.meta.claims` fit together,
 read first:
@@ -213,13 +231,14 @@ import { HostNetworkTypes } from 'gdc-common-utils-ts/constants/network';
 
 const hostContext = {
   participantId: 'host',
+  hostCoverageScope: 'EU',
   jurisdiction: 'ES',
   version: 'v1',
   hostNetwork: HostNetworkTypes.Test,
 };
 
 const discoveryPath = buildGwDspaceVersionWellKnownPath(hostContext);
-const metadata = buildDspaceVersionMetadata('/host/cds-ES/v1/test/dsp');
+const metadata = buildDspaceVersionMetadata('/host/cds-EU/v1/test/dsp');
 const catalogPath = buildGwCatalogArtifactPath(hostContext);
 const catalogUrl = deriveGwCatalogArtifactUrlFromDspaceVersion(
   `https://host.example.org${discoveryPath}`,

package/dist/claims/claims-helpers-communication.d.ts

@@ -9,6 +9,8 @@ export declare function getCommunicationCategoryList(claims: CommunicationIntero
 export declare function setCommunicationCategory(claims: CommunicationInteroperableClaims, value: string | readonly string[]): CommunicationInteroperableClaims;
 export declare function addCommunicationCategoryList(claims: CommunicationInteroperableClaims, value: string | readonly string[]): CommunicationInteroperableClaims;
 export declare function removeCommunicationCategoryList(claims: CommunicationInteroperableClaims, value: string | readonly string[]): CommunicationInteroperableClaims;
+export declare function getCommunicationTopic(claims: CommunicationInteroperableClaims): string;
+export declare function setCommunicationTopic(claims: CommunicationInteroperableClaims, value: unknown): CommunicationInteroperableClaims;
 export declare function getCommunicationText(claims: CommunicationInteroperableClaims): string;
 export declare function setCommunicationText(claims: CommunicationInteroperableClaims, value: unknown): CommunicationInteroperableClaims;
 export declare function getCommunicationContentAttachmentData(claims: CommunicationInteroperableClaims): string;

package/dist/claims/claims-helpers-communication.js

@@ -37,6 +37,12 @@ export function addCommunicationCategoryList(claims, value) {
 export function removeCommunicationCategoryList(claims, value) {
     return removeClaimValues(claims, CommunicationClaim.Category, value);
 }
+export function getCommunicationTopic(claims) {
+    return getCommunicationScalar(claims, CommunicationClaim.Topic);
+}
+export function setCommunicationTopic(claims, value) {
+    return setCommunicationScalar(claims, CommunicationClaim.Topic, value);
+}
 export function getCommunicationText(claims) {
     return getCommunicationScalar(claims, CommunicationClaim.Text);
 }

package/dist/constants/identity-gender.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Common gender/sex identity enumerations shared by tests and mappers.
+ *
+ * This module is designed to remove string literals from tests and to
+ * unify the semantics between different layers:
+ * - BirthSex (F/M)
+ * - AdministrativeSex (F/M/O; Other unified as O)
+ * - GenderIdentity (FHIR PCORNet-style codes, with Other handled as OT)
+ */
+/** BirthSex can only be "F", "M" or "U". */
+export declare enum BirthSex {
+    /** Female */
+    Female = "F",
+    /** Male */
+    Male = "M",
+    /** Unknown / not available in source data. */
+    Unknown = "U"
+}
+/**
+ * PCORNet Gender Identity terminology.
+ * https://hl7.org/fhir/us/cdmh/ValueSet-pcornet-gender-identity.html
+ */
+export declare enum GenderIdentity {
+    /** Gender identity is a Man. */
+    Man = "M",
+    /** Gender identity is a Woman. */
+    Woman = "F",
+    /** Transgender male or Transman or Female-to-Male. */
+    TransgenderMale = "TM",
+    /** Transgender female or Transwoman or Male-to-female. */
+    TransgenderFemale = "TF",
+    /** Gender identity is Genderqueer/Non-binary. */
+    GenderqueerNonBinary = "GQ",
+    /** Gender identity is Something else. */
+    SomethingElse = "SE",
+    /** Gender identity is Multiple gender categories. */
+    MultipleGenderCategories = "MU",
+    /** Person has declined to answer about their gender identity. */
+    DeclineToAnswer = "DC",
+    /** There is no information about the Person's gender identity. */
+    NoInformation = "NI",
+    /** Person's gender identity is unknown. */
+    Unknown = "UN",
+    /** Gender identity is Other. */
+    Other = "OT"
+}

package/dist/constants/identity-gender.js

@@ -0,0 +1,48 @@
+/**
+ * Common gender/sex identity enumerations shared by tests and mappers.
+ *
+ * This module is designed to remove string literals from tests and to
+ * unify the semantics between different layers:
+ * - BirthSex (F/M)
+ * - AdministrativeSex (F/M/O; Other unified as O)
+ * - GenderIdentity (FHIR PCORNet-style codes, with Other handled as OT)
+ */
+/** BirthSex can only be "F", "M" or "U". */
+export var BirthSex;
+(function (BirthSex) {
+    /** Female */
+    BirthSex["Female"] = "F";
+    /** Male */
+    BirthSex["Male"] = "M";
+    /** Unknown / not available in source data. */
+    BirthSex["Unknown"] = "U";
+})(BirthSex || (BirthSex = {}));
+/**
+ * PCORNet Gender Identity terminology.
+ * https://hl7.org/fhir/us/cdmh/ValueSet-pcornet-gender-identity.html
+ */
+export var GenderIdentity;
+(function (GenderIdentity) {
+    /** Gender identity is a Man. */
+    GenderIdentity["Man"] = "M";
+    /** Gender identity is a Woman. */
+    GenderIdentity["Woman"] = "F";
+    /** Transgender male or Transman or Female-to-Male. */
+    GenderIdentity["TransgenderMale"] = "TM";
+    /** Transgender female or Transwoman or Male-to-female. */
+    GenderIdentity["TransgenderFemale"] = "TF";
+    /** Gender identity is Genderqueer/Non-binary. */
+    GenderIdentity["GenderqueerNonBinary"] = "GQ";
+    /** Gender identity is Something else. */
+    GenderIdentity["SomethingElse"] = "SE";
+    /** Gender identity is Multiple gender categories. */
+    GenderIdentity["MultipleGenderCategories"] = "MU";
+    /** Person has declined to answer about their gender identity. */
+    GenderIdentity["DeclineToAnswer"] = "DC";
+    /** There is no information about the Person's gender identity. */
+    GenderIdentity["NoInformation"] = "NI";
+    /** Person's gender identity is unknown. */
+    GenderIdentity["Unknown"] = "UN";
+    /** Gender identity is Other. */
+    GenderIdentity["Other"] = "OT";
+})(GenderIdentity || (GenderIdentity = {}));

package/dist/constants/identity-identifiers.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Canonical identifier kinds reused by onboarding forms, KYC mappers, and
+ * frontend/backend tests.
+ *
+ * Source semantics:
+ * - ISO identifiers keep their reverse-DNS namespace
+ * - HL7 v2-0203 identifier types are normalized to reverse-DNS strings
+ *
+ * Design rule:
+ * - tests must import these values instead of hardcoding identifier type
+ *   strings inline
+ * - onboarding form fields may still accept legacy provider strings, but new
+ *   code should author `IdKind` values
+ *
+ * Reference:
+ * http://terminology.hl7.org/CodeSystem/v2-0203
+ */
+export declare enum IdKind {
+    /** ISO 18013-5 mobile driving licence credential. */
+    MobileDriverLicense = "org.iso.18013.5.1.mDL",
+    /** HL7 driver license identifier. */
+    PersonalDriverLicense = "org.hl7.terminology.codesystem.v2-0203.DL",
+    /** HL7 citizenship card identifier. */
+    PersonalCitizenshipCard = "org.hl7.terminology.codesystem.v2-0203.CZ",
+    /** HL7 national identity number. */
+    PersonalNationalNumber = "org.hl7.terminology.codesystem.v2-0203.NN",
+    /** HL7 jurisdictional health number. */
+    RegionalHeathCardNumber = "org.hl7.terminology.codesystem.v2-0203.JHN",
+    /** HL7 local/private health card identifier. */
+    LocalHealthCard = "org.hl7.terminology.codesystem.v2-0203.HC",
+    /** HL7 donor record identifier. */
+    LocalDonorRecord = "org.hl7.terminology.codesystem.v2-0203.DR",
+    /** HL7 local patient identifier. */
+    LocalPatientIdentifier = "org.hl7.terminology.codesystem.v2-0203.PI"
+}
+/** Union helper for code that wants typed values without depending on the enum object. */
+export type IdKindValue = typeof IdKind[keyof typeof IdKind];

package/dist/constants/identity-identifiers.js

@@ -0,0 +1,36 @@
+/**
+ * Canonical identifier kinds reused by onboarding forms, KYC mappers, and
+ * frontend/backend tests.
+ *
+ * Source semantics:
+ * - ISO identifiers keep their reverse-DNS namespace
+ * - HL7 v2-0203 identifier types are normalized to reverse-DNS strings
+ *
+ * Design rule:
+ * - tests must import these values instead of hardcoding identifier type
+ *   strings inline
+ * - onboarding form fields may still accept legacy provider strings, but new
+ *   code should author `IdKind` values
+ *
+ * Reference:
+ * http://terminology.hl7.org/CodeSystem/v2-0203
+ */
+export var IdKind;
+(function (IdKind) {
+    /** ISO 18013-5 mobile driving licence credential. */
+    IdKind["MobileDriverLicense"] = "org.iso.18013.5.1.mDL";
+    /** HL7 driver license identifier. */
+    IdKind["PersonalDriverLicense"] = "org.hl7.terminology.codesystem.v2-0203.DL";
+    /** HL7 citizenship card identifier. */
+    IdKind["PersonalCitizenshipCard"] = "org.hl7.terminology.codesystem.v2-0203.CZ";
+    /** HL7 national identity number. */
+    IdKind["PersonalNationalNumber"] = "org.hl7.terminology.codesystem.v2-0203.NN";
+    /** HL7 jurisdictional health number. */
+    IdKind["RegionalHeathCardNumber"] = "org.hl7.terminology.codesystem.v2-0203.JHN";
+    /** HL7 local/private health card identifier. */
+    IdKind["LocalHealthCard"] = "org.hl7.terminology.codesystem.v2-0203.HC";
+    /** HL7 donor record identifier. */
+    IdKind["LocalDonorRecord"] = "org.hl7.terminology.codesystem.v2-0203.DR";
+    /** HL7 local patient identifier. */
+    IdKind["LocalPatientIdentifier"] = "org.hl7.terminology.codesystem.v2-0203.PI";
+})(IdKind || (IdKind = {}));

package/dist/constants/index.d.ts

@@ -21,3 +21,5 @@ export * from './permission-templates';
 export * from './service-capabilities';
 export * from './urn';
 export * from './verifiable-credentials';
+export * from './identity-gender';
+export * from './identity-identifiers';

package/dist/constants/index.js

@@ -21,3 +21,5 @@ export * from './permission-templates.js';
 export * from './service-capabilities.js';
 export * from './urn.js';
 export * from './verifiable-credentials.js';
+export * from './identity-gender.js';
+export * from './identity-identifiers.js';

package/dist/constants/kyc-gender.d.ts

@@ -0,0 +1,50 @@
+import { BirthSex, GenderIdentity } from './identity-gender';
+/**
+ * Centralized, typed fixtures and contract helpers for KYC gender.
+ *
+ * Goal:
+ * - tests must never hardcode gender strings
+ * - production mapping must reuse the same canonical tokens
+ * - normalize input values that come from KYC providers / UI forms
+ *
+ * Contract note:
+ * - output values match the compact values already used by
+ *   `org.schema.Person.gender` claim tests and onboarding flows.
+ */
+/**
+ * Canonical compact gender used by onboarding claims.
+ *
+ * This is intentionally aligned with the current `org.schema.Person.gender`
+ * contract in tests (values `'M'` / `'F'`).
+ */
+export type CompactKycGender = BirthSex.Female | BirthSex.Male;
+/** Canonical compact gender token: male. */
+export declare const KYC_COMPACT_GENDER_MALE = BirthSex.Male;
+/** Canonical compact gender token: female. */
+export declare const KYC_COMPACT_GENDER_FEMALE = BirthSex.Female;
+/**
+ * Provider/UI gender inputs supported by normalization.
+ *
+ * These variants are expected to be already in English (as per your rules).
+ * If new languages appear, they should go through a dedicated
+ * intermediate normalization layer.
+ */
+export type EnglishKycGenderInput = 'female' | 'female' | 'mujer' | 'woman' | 'male' | 'man' | 'hombre' | 'F' | 'M';
+/** Provider/UI inputs mapped to compact gender (female). */
+export declare const KYC_GENDER_INPUT_FEMALE: "female";
+export declare const KYC_GENDER_INPUT_WOMAN = GenderIdentity.Woman;
+export declare const KYC_GENDER_INPUT_MUJER: "mujer";
+/** Provider/UI inputs mapped to compact gender (male). */
+export declare const KYC_GENDER_INPUT_MALE: "male";
+export declare const KYC_GENDER_INPUT_MAN = GenderIdentity.Man;
+export declare const KYC_GENDER_INPUT_HOMBRE: "hombre";
+/** Direct compact inputs (already normalized by some providers). */
+export declare const KYC_GENDER_INPUT_COMPACT_FEMALE = BirthSex.Female;
+export declare const KYC_GENDER_INPUT_COMPACT_MALE = BirthSex.Male;
+/**
+ * Normalizes heterogeneous KYC gender values to the compact contract.
+ *
+ * Implementation mirrors the previous behavior from
+ * `src/utils/individual-organization-kyc.ts`, but centralized.
+ */
+export declare function normalizeKycGenderToCompact(value: unknown): CompactKycGender | undefined;

package/dist/constants/kyc-gender.js

@@ -0,0 +1,43 @@
+import { BirthSex, GenderIdentity } from './identity-gender.js';
+/** Canonical compact gender token: male. */
+export const KYC_COMPACT_GENDER_MALE = BirthSex.Male;
+/** Canonical compact gender token: female. */
+export const KYC_COMPACT_GENDER_FEMALE = BirthSex.Female;
+/** Provider/UI inputs mapped to compact gender (female). */
+export const KYC_GENDER_INPUT_FEMALE = 'female';
+export const KYC_GENDER_INPUT_WOMAN = GenderIdentity.Woman;
+export const KYC_GENDER_INPUT_MUJER = 'mujer';
+/** Provider/UI inputs mapped to compact gender (male). */
+export const KYC_GENDER_INPUT_MALE = 'male';
+export const KYC_GENDER_INPUT_MAN = GenderIdentity.Man;
+export const KYC_GENDER_INPUT_HOMBRE = 'hombre';
+/** Direct compact inputs (already normalized by some providers). */
+export const KYC_GENDER_INPUT_COMPACT_FEMALE = BirthSex.Female;
+export const KYC_GENDER_INPUT_COMPACT_MALE = BirthSex.Male;
+/**
+ * Normalizes heterogeneous KYC gender values to the compact contract.
+ *
+ * Implementation mirrors the previous behavior from
+ * `src/utils/individual-organization-kyc.ts`, but centralized.
+ */
+export function normalizeKycGenderToCompact(value) {
+    const raw = typeof value === 'string' ? value.trim() : '';
+    if (!raw)
+        return undefined;
+    const normalized = raw.toLowerCase();
+    if (normalized === 'f'
+        || normalized === 'female'
+        || normalized === 'woman'
+        || normalized === 'mujer') {
+        return KYC_COMPACT_GENDER_FEMALE;
+    }
+    if (normalized === 'm'
+        || normalized === 'male'
+        || normalized === 'man'
+        || normalized === 'hombre') {
+        return KYC_COMPACT_GENDER_MALE;
+    }
+    // Fallback preserves unknown provider tokens by uppercasing; this keeps
+    // the previous contract where unmapped values become uppercased tokens.
+    return raw.toUpperCase();
+}

package/dist/constants/schemaorg.d.ts

@@ -1,6 +1,7 @@
 import { ParameterData } from "../models/params";
 export declare enum ClaimsServiceSchemaorg {
     areaServed = "org.schema.Service.areaServed",
+    additionalType = "org.schema.Service.additionalType",
     category = "org.schema.Service.category",
     identifier = "org.schema.Service.identifier",
     serviceType = "org.schema.Service.serviceType",
@@ -74,11 +75,24 @@ export declare enum ClaimsOrganizationSchemaorg {
      */
     hasCredentialMaterial = "org.schema.Organization.hasCredential.material",
     /** Individual/family owner email used by subject-index registration flows. */
+    ownerAlternateName = "org.schema.Organization.owner.alternateName",
+    /** Individual/family owner email used by subject-index registration flows. */
     ownerEmail = "org.schema.Organization.owner.email",
     /** Individual/family owner telephone used by subject-index registration flows. */
     ownerTelephone = "org.schema.Organization.owner.telephone",
     /** Individual/family owner legal identifier used by subject-index registration flows. */
     ownerIdentifierValue = "org.schema.Organization.owner.identifier.value",
+    /** Individual/family indexed member friendly name used by onboarding draft helpers. */
+    memberAlternateName = "org.schema.Organization.member.alternateName",
+    memberGivenName = "org.schema.Organization.member.givenName",
+    memberFamilyName = "org.schema.Organization.member.familyName",
+    memberBirthDate = "org.schema.Organization.member.birthDate",
+    memberGender = "org.schema.Organization.member.gender",
+    memberEmail = "org.schema.Organization.member.email",
+    memberTelephone = "org.schema.Organization.member.telephone",
+    memberIdentifierType = "org.schema.Organization.member.identifier.additionalType",
+    memberIdentifierValue = "org.schema.Organization.member.identifier.value",
+    memberRole = "org.schema.Organization.member.role",
     numberOfEmployees = "org.schema.Organization.numberOfEmployees.value"
 }
 export declare enum ClaimsOfferSchemaorg {
@@ -95,6 +109,9 @@ export declare enum ClaimsOfferSchemaorg {
     priceCurrency = "org.schema.Offer.priceCurrency",
     serialNumber = "org.schema.Offer.serialNumber"
 }
+export declare enum ClaimsOrderSchemaorg {
+    orderedItemServiceType = "org.schema.Order.orderedItem.serviceType"
+}
 /** For Employees (and Employee Role, but no PII) and customers / related persons.
  * - `givenName`: The given name of the person.
  * - `familyName`: The primary family name or surname of the person.

package/dist/constants/schemaorg.js

@@ -3,6 +3,7 @@
 export var ClaimsServiceSchemaorg;
 (function (ClaimsServiceSchemaorg) {
     ClaimsServiceSchemaorg["areaServed"] = "org.schema.Service.areaServed";
+    ClaimsServiceSchemaorg["additionalType"] = "org.schema.Service.additionalType";
     ClaimsServiceSchemaorg["category"] = "org.schema.Service.category";
     ClaimsServiceSchemaorg["identifier"] = "org.schema.Service.identifier";
     ClaimsServiceSchemaorg["serviceType"] = "org.schema.Service.serviceType";
@@ -78,11 +79,24 @@ export var ClaimsOrganizationSchemaorg;
      */
     ClaimsOrganizationSchemaorg["hasCredentialMaterial"] = "org.schema.Organization.hasCredential.material";
     /** Individual/family owner email used by subject-index registration flows. */
+    ClaimsOrganizationSchemaorg["ownerAlternateName"] = "org.schema.Organization.owner.alternateName";
+    /** Individual/family owner email used by subject-index registration flows. */
     ClaimsOrganizationSchemaorg["ownerEmail"] = "org.schema.Organization.owner.email";
     /** Individual/family owner telephone used by subject-index registration flows. */
     ClaimsOrganizationSchemaorg["ownerTelephone"] = "org.schema.Organization.owner.telephone";
     /** Individual/family owner legal identifier used by subject-index registration flows. */
     ClaimsOrganizationSchemaorg["ownerIdentifierValue"] = "org.schema.Organization.owner.identifier.value";
+    /** Individual/family indexed member friendly name used by onboarding draft helpers. */
+    ClaimsOrganizationSchemaorg["memberAlternateName"] = "org.schema.Organization.member.alternateName";
+    ClaimsOrganizationSchemaorg["memberGivenName"] = "org.schema.Organization.member.givenName";
+    ClaimsOrganizationSchemaorg["memberFamilyName"] = "org.schema.Organization.member.familyName";
+    ClaimsOrganizationSchemaorg["memberBirthDate"] = "org.schema.Organization.member.birthDate";
+    ClaimsOrganizationSchemaorg["memberGender"] = "org.schema.Organization.member.gender";
+    ClaimsOrganizationSchemaorg["memberEmail"] = "org.schema.Organization.member.email";
+    ClaimsOrganizationSchemaorg["memberTelephone"] = "org.schema.Organization.member.telephone";
+    ClaimsOrganizationSchemaorg["memberIdentifierType"] = "org.schema.Organization.member.identifier.additionalType";
+    ClaimsOrganizationSchemaorg["memberIdentifierValue"] = "org.schema.Organization.member.identifier.value";
+    ClaimsOrganizationSchemaorg["memberRole"] = "org.schema.Organization.member.role";
     ClaimsOrganizationSchemaorg["numberOfEmployees"] = "org.schema.Organization.numberOfEmployees.value"; // to purchase licenses for device profile's activation
 })(ClaimsOrganizationSchemaorg || (ClaimsOrganizationSchemaorg = {}));
 export var ClaimsOfferSchemaorg;
@@ -100,6 +114,10 @@ export var ClaimsOfferSchemaorg;
     ClaimsOfferSchemaorg["priceCurrency"] = "org.schema.Offer.priceCurrency";
     ClaimsOfferSchemaorg["serialNumber"] = "org.schema.Offer.serialNumber";
 })(ClaimsOfferSchemaorg || (ClaimsOfferSchemaorg = {}));
+export var ClaimsOrderSchemaorg;
+(function (ClaimsOrderSchemaorg) {
+    ClaimsOrderSchemaorg["orderedItemServiceType"] = "org.schema.Order.orderedItem.serviceType";
+})(ClaimsOrderSchemaorg || (ClaimsOrderSchemaorg = {}));
 /** For Employees (and Employee Role, but no PII) and customers / related persons.
  * - `givenName`: The given name of the person.
  * - `familyName`: The primary family name or surname of the person.

package/dist/constants/service-capabilities.d.ts

@@ -1,80 +1,114 @@
 /**
- * Canonical capability families persisted through
+ * Canonical persisted capability values stored in
  * `org.schema.Service.serviceType`.
  */
-export declare const ServiceCapabilityFamily: {
-    readonly Indexing: "indexing";
-    readonly DigitalTwin: "digitaltwin";
+export declare const ServiceCapability: {
+    readonly IndexReader: "organization/Composition.rs";
+    readonly IndexProvider: "organization/Composition.cruds";
+    readonly DigitalTwinReader: "organization/ResearchSubject.rs";
+    readonly DigitalTwinProvider: "organization/ResearchSubject.cruds";
 };
-export type ServiceCapabilityFamilyValue = typeof ServiceCapabilityFamily[keyof typeof ServiceCapabilityFamily];
+export type ServiceCapabilityValue = typeof ServiceCapability[keyof typeof ServiceCapability];
 /**
- * Canonical capability tokens currently documented for tenant activation.
- *
- * The family prefix is the stable part of the contract. Suffixes such as
- * `.rs` and `.cruds` can evolve independently across runtimes.
+ * Canonical capability families derived from the persisted service capability
+ * values.
  */
-export declare const ServiceCapabilityToken: {
+export declare const ServiceCapabilityKind: {
+    readonly Indexing: "organization/composition";
+    readonly DigitalTwin: "organization/researchsubject";
+};
+export type ServiceCapabilityKindValue = typeof ServiceCapabilityKind[keyof typeof ServiceCapabilityKind];
+/**
+ * @deprecated Legacy serviceType values accepted for backward compatibility.
+ */
+export declare const DeprecatedServiceCapabilityToken: {
     readonly IndexReader: "indexing.rs";
     readonly IndexProvider: "indexing.cruds";
     readonly DigitalTwinReader: "digitaltwin.rs";
     readonly DigitalTwinProvider: "digitaltwin.cruds";
+};
+export type DeprecatedServiceCapabilityTokenValue = typeof DeprecatedServiceCapabilityToken[keyof typeof DeprecatedServiceCapabilityToken];
+/**
+ * @deprecated Prefer `ServiceCapability`.
+ *
+ * Kept as a compatibility alias for older callers that imported
+ * `ServiceCapabilityToken`.
+ */
+export declare const ServiceCapabilityToken: {
+    readonly IndexReader: "organization/Composition.rs";
+    readonly IndexProvider: "organization/Composition.cruds";
+    readonly DigitalTwinReader: "organization/ResearchSubject.rs";
+    readonly DigitalTwinProvider: "organization/ResearchSubject.cruds";
     /**
      * @deprecated Prefer `IndexReader`.
      */
-    readonly IndexingReadSearch: "indexing.rs";
+    readonly IndexingReadSearch: "organization/Composition.rs";
     /**
      * @deprecated Prefer `IndexProvider`.
      */
-    readonly IndexingCruds: "indexing.cruds";
+    readonly IndexingCruds: "organization/Composition.cruds";
     /**
      * @deprecated Prefer `DigitalTwinReader`.
      */
-    readonly DigitalTwinReadSearch: "digitaltwin.rs";
+    readonly DigitalTwinReadSearch: "organization/ResearchSubject.rs";
     /**
      * @deprecated Prefer `DigitalTwinProvider`.
      */
-    readonly DigitalTwinCruds: "digitaltwin.cruds";
-};
-export type ServiceCapabilityTokenValue = typeof ServiceCapabilityToken[keyof typeof ServiceCapabilityToken];
-/**
- * SDK-facing capability names.
- *
- * These names are intentionally more explicit than the persisted claim tokens:
- * - `Provider` maps to write/manage capability (`*.cruds`)
- * - `Reader` maps to read/search capability (`*.rs`)
- */
-export declare const ServiceCapability: {
-    readonly IndexProvider: "indexing.cruds";
-    readonly IndexReader: "indexing.rs";
-    readonly DigitalTwinProvider: "digitaltwin.cruds";
-    readonly DigitalTwinReader: "digitaltwin.rs";
+    readonly DigitalTwinCruds: "organization/ResearchSubject.cruds";
     /**
-     * @deprecated Prefer `IndexProvider`.
+     * @deprecated Prefer `ServiceCapability.IndexReader`.
+     * Legacy persisted value kept for compatibility while external payloads
+     * still emit `indexing.rs`.
      */
-    readonly IndexingProvider: "indexing.cruds";
+    readonly LegacyIndexReader: "indexing.rs";
     /**
-     * @deprecated Prefer `IndexReader`.
+     * @deprecated Prefer `ServiceCapability.IndexProvider`.
+     * Legacy persisted value kept for compatibility while external payloads
+     * still emit `indexing.cruds`.
+     */
+    readonly LegacyIndexProvider: "indexing.cruds";
+    /**
+     * @deprecated Prefer `ServiceCapability.DigitalTwinReader`.
+     * Legacy persisted value kept for compatibility while external payloads
+     * still emit `digitaltwin.rs`.
+     */
+    readonly LegacyDigitalTwinReader: "digitaltwin.rs";
+    /**
+     * @deprecated Prefer `ServiceCapability.DigitalTwinProvider`.
+     * Legacy persisted value kept for compatibility while external payloads
+     * still emit `digitaltwin.cruds`.
      */
-    readonly IndexingReader: "indexing.rs";
+    readonly LegacyDigitalTwinProvider: "digitaltwin.cruds";
 };
-export type ServiceCapabilityValue = typeof ServiceCapability[keyof typeof ServiceCapability];
+/**
+ * @deprecated Prefer `ServiceCapabilityValue`.
+ */
+export type ServiceCapabilityTokenValue = typeof ServiceCapabilityToken[keyof typeof ServiceCapabilityToken];
+/**
+ * Normalizes a service capability token into its canonical persisted form.
+ */
+export declare function normalizeServiceCapability(value: string | undefined | null): string | undefined;
 /**
  * Parses the CSV stored in `org.schema.Service.serviceType`.
  */
 export declare function parseServiceCapabilityTokens(value: unknown): string[];
+/**
+ * Merges capability claims published across compatibility locations.
+ */
+export declare function mergeServiceCapabilityClaims(...values: unknown[]): string | undefined;
 /**
  * Serializes capability tokens into the canonical CSV claim format.
  */
 export declare function serializeServiceCapabilityTokens(values: ReadonlyArray<string | undefined | null>): string | undefined;
 /**
- * Returns the capability family prefix from a token.
+ * Returns the capability family prefix from a persisted capability token.
  */
-export declare function getServiceCapabilityFamily(value: string | undefined): string | undefined;
+export declare function getServiceCapabilityKind(value: string | undefined): string | undefined;
 /**
  * Checks whether the claim contains at least one capability from the requested
  * family.
  */
-export declare function hasServiceCapabilityFamily(value: unknown, family: ServiceCapabilityFamilyValue | string): boolean;
+export declare function hasServiceCapabilityKind(value: unknown, family: ServiceCapabilityKindValue | string): boolean;
 /**
  * Returns whether a capability token denotes a discoverable provider/service
  * role rather than a reader-only role.