API: migrate package-defect handling to CM patches (Phase 1, #128)

[ryukzak]

Phase 1 of the #128 migration (see docs/design/defect-handling-migration.md, PR #173): move the example preprocessPackage defect workarounds onto CanonicalManager's composable patches runtime (shipped in CM 0.0.25). Codegen-only; no CM changes.

Helpers + combinators — src/api/patches.ts

Unscoped transform helpers, scoped by nesting combinators:

• Combinators: inPackage(match, handlers) and inResource(url, handlers) — scope a list of handlers (nest freely).
• Transforms: injectDependency(deps), renameCanonical(renames), renameReferenceTarget(renames), swapBinding(swaps) (scoped via combinators); renamePackage(renames), patchCodeSystem(url, codes), and ensureDependency(deps) (self-matching — adds missing deps or adjusts versions, never injects a package into itself).

APIBuilder

• New patches?: PatchesInput constructor option — CM's Partial<Patches> (per-phase handler arrays: packageJson / indexEntry / fhirResource). Warns if combined with an injected manager/register (which owns its own patch wiring).
• New packageIndex?: PackageIndexMode constructor option ("use" / "recover" / "regenerate"), forwarded to CM; ignorePackageIndex is marked @deprecated (CM maps true → "regenerate" and throws if both are set).
• P1.7: generate() captures manager.report() into GenerationReport.inputReport (absent on the prebuilt-register path; empty for cache-served packages), and prettyReport renders it as an "Input fixes" section:

Input fixes (1):
  - recovered index for de.basisprofil.r4@1.6.0-ballot2: unparseable, 173 resources

Examples migrated off preprocessPackage

// kbv
patches: { packageJson: [inPackage("de.basisprofil.r4", [injectDependency({ "hl7.fhir.r4.core": "4.0.1" })])] },
packageIndex: "recover", // was ignorePackageIndex: true — heals the broken simplifier .index.json, warns on heal

// norge
patches: {
  packageJson: [
    ensureDependency({ "hl7.fhir.r4.core": "4.0.1" }), // every package except core itself
    renamePackage({ "simplifier.core.r4.rResources": "simplifier.core.r4.resources" }),
  ],
  fhirResource: [inResource(".../gd-RelatedPerson", [renameReferenceTarget({ /* Person→Patient ×3 */ })])],
}

// ccda (on its manual CM — nesting inPackage > inResource)
patches: { fhirResource: [
  inPackage("hl7.cda.uv.core", [renameCanonical({ ".../IVL_TS": ".../IVL-TS" })]),
  inPackage("hl7.cda.us.ccda", [inResource(".../CarePlanAct", [swapBinding({ "<nlm>": "<v3-xDocumentActMood>" })])]),
  patchCodeSystem("http://hl7.org/fhir/bundle-type", ["bundle", "subscription-notification"]),
] }

kbv, norge, and ccda have no preprocessPackage left.

Notes

• Pins CM to the released 0.0.25 (ships the patches runtime, ./patch subpath, packageIndex mode, and report()).
• The report covers CM's shipped ReportEntry kinds (index-recovery | exclusion | deprecation); transform helpers can't report what they patched until CM adds a patch kind — CM follow-up.

Verification

• Rebased onto current main: typecheck, lint, and the standard suite (337/0) green.
• Examples regenerate byte-identical through the patches runtime and typecheck: kbv (5/0 tests), norge, ccda (24/0), kbv-condition-diagnosis.
• kbv's packageIndex: "recover" verified from a cold cache — logs Recovered de.basisprofil.r4@1.6.0-ballot2: .index.json is unparseable; scanning directory instead and produces identical output.