TypeSchema/TS/PY: keep a profile's reference targets within its base

[Palid]

Stacked on #256 — review that first; this PR's diff against it is the last 8 commits. A profile that listed reference targets its base element does not allow got that list verbatim, so its input type was wider than the base field createResource assigns it to, and nothing reported it. Reference targets are now narrowed base-to-leaf the way #200 narrows choice variants, and the dropped targets are reported as generation warnings.

Closes #255

TypeSchema

• resolvePermittedRefers in field-builder.ts folds each constraint level's reference targets base-to-leaf over the nearest specialization's targets
  • a target is admitted when its base resource lies within a permitted one, so Resource and DomainResource admit their descendants
  • an abstract target over a concrete set keeps the concrete permitted targets (Resource on Condition.subject keeps Patient, Group)
  • a level that admits none of its targets keeps the previous ones
• resource and profiles are both built from the surviving targets, so a profile of a dropped resource leaves profiles too
• new #nonMonotonicReference tag in src/utils/log.ts; the warning names the profile, the element and the dropped targets, and points at canonicalManager.patches
• no writer changed: TypeScript's Raw type, setter, getter and validateReference list, and Python's annotations, validate_reference list and accessor comment all follow from the IR

A dropped target, and a level whose targets are all outside its ancestor's:

Profile 'WidenedRelatedPerson' (http://example.test/StructureDefinition/widened-related-person) declares reference target(s) http://hl7.org/fhir/StructureDefinition/Person on 'patient' that an ancestor prohibits; they stay prohibited (allowed: Patient). Fix the package with canonicalManager.patches
Profile 'PersonOnlyRelatedPerson' (http://example.org/StructureDefinition/PersonOnlyRelatedPerson) declares reference target(s) http://hl7.org/fhir/StructureDefinition/Person on 'patient', none of which an ancestor allows; the ancestor's targets are kept (allowed: Patient). Fix the package with canonicalManager.patches

gd-RelatedPerson without the norge-r4 patch failed tsc with TS2322; its input type now matches the base Reference<"Patient">, and the runtime check agrees with it:

 export type GdRelatedPersonProfileRaw = {
-    patient: Reference<"Person" /* http://ehelse.no/fhir/StructureDefinition/gd-Person, http://hl7.no/fhir/StructureDefinition/no-basis-Person */ | "Patient" /* http://hl7.no/fhir/StructureDefinition/no-basis-Patient */>;
+    patient: Reference<"Patient" /* http://hl7.no/fhir/StructureDefinition/no-basis-Patient */>;
 }

-                ...validateReference(res, profileName, "patient", ["Patient","Person"]),
+                ...validateReference(res, profileName, "patient", ["Patient"]),

Generation report

• after the IR stage, APIBuilder.generate() copies the deduplicated #nonMonotonicReference and #nonMonotonicChoice messages of the ts logger into report.warnings, so prettyReport prints a Warnings: line
• entries for tags in the logger's suppressTags are left out
• success and .throwException() are unchanged: the narrowed output compiles, so the run succeeds
• the CLI is unchanged

The norge-r4 example used to report a plain success; its Warnings: line now includes:

Profile 'SfmMedicationDispense' (http://ehelse.no/fhir/StructureDefinition/sfm-MedicationDispense) declares reference target(s) http://ehelse.no/fhir/StructureDefinition/sfm-MedicationStatement on 'authorizingPrescription' that an ancestor prohibits; they stay prohibited (allowed: MedicationRequest). Fix the package with canonicalManager.patches

Examples and tests

• test/unit/typeschema/transformer/reference.test.ts: the first commit pins the widened targets, a later one asserts the narrowed ones and the warnings
  • widened top-level, choice-variant and nested-element targets
  • a narrowing of a family base, targets restated on an unconstrained base, an abstract target over a concrete set
  • a grandchild that allows none of its parent's targets
  • profile targets of an allowed and a dropped resource
• test/unit/api/generation-report-warnings.test.ts: report.warnings, the prettyReport line, and a suppressed tag
• the CDA describe in test/api/write-generator/typescript.test.ts asserts the ProtectiveFactor choice warning in result.warnings
• examples/typescript-custom-packages:
  • widened-related-person.structuredefinition.json (R5, Patient and Person on RelatedPerson.patient), added as one tree-shake root
  • profile-reference-widening.test.ts: a demo building a valid related person, @ts-expect-error on a Person reference passed to createResource and setPatient, validate() rejecting one read from the wire, and a snapshot of the generated module

Reach

• the only regenerated committed file is examples/python-r4-us-core/fhir_types/README.md: one line in its skipped-canonicals list, because that example loads the custom-packages structure-definitions/ folder
• no other committed generated output changes
• across the example corpora three profiles widen a reference target, all in norge-r4 (the three from TS: profile reference targets wider than the base emit a createResource that fails tsc (TS2322), with no diagnostic #255)
  • the gd-RelatedPerson patch stays; loader-level fixes remain the documented way
  • sfm-MedicationDispense and sfm-MedicationStatement are left unpatched: they now warn, and their validateReference lists lose MedicationStatement

Open question: should report.warnings honour suppressTags (it does here), or stay independent of the console filter?