**Single-base mode** (legacy): supply ``baseline_xer_path`` or
        ``baseline_xer_content``. All fragnets are inserted into the
        same shared baseline XER and impact is measured against that
        shared baseline. The result carries a
        ``single_base_disclosure`` warning: one shared baseline is
        AACE 29R-03 MIP 3.6 (Modeled / Additive / Single Base), not
        MIP 3.7 Multiple Base; acceptable when all events share a
        single baseline window.

        **Multi-base mode** (AACE 29R-03 MIP 3.7 Multiple Base):
        supply ``per_event_bases`` — a dict keyed by each fragnet's
        ``id``, with each value a dict containing EITHER
        ``xer_path`` OR ``xer_content`` for that event's
        pre-event contemporaneous baseline. Each fragnet is inserted
        into its OWN base, impact is measured against THAT base's
        pre-event finish, and the result carries
        ``per_event_methodology``, ``per_event_base_count``, and
        ``per_event_bases_used`` (sha256-truncated content hashes for
        audit reproducibility). The cumulative-impact figure carries
        ``cumulative_caveat`` because the sum of events measured
        against different bases is NOT a valid joint impact.

        Exactly ONE of {baseline_xer_path, baseline_xer_content,
        per_event_bases} must be supplied. Multi-base mode errors out
        (returning ``{"error": ...}``) if any fragnet id is missing
        from ``per_event_bases``.

        Use this tool when modeling delay impact prospectively (e.g.
        quantifying RFI / change-order delay before settlement). For
        retrospective windows analysis after the fact, use
        ``forensic_windows_analysis`` (MIP 3.3 windows). For an
        impacted as-planned screen or rebuttal on the unprogressed
        as-planned baseline (MIP 3.6), use ``impacted_as_planned``.

        Args:
            baseline_xer_path:    server-side pre-impact baseline XER
                                  (single-base mode).
            baseline_xer_content: full text of pre-impact baseline XER
                                  (single-base mode, hosted/remote use).
            per_event_bases:      dict {fragnet_id: {"xer_path": "..."}
                                  OR {"xer_content": "<full XER text>"}}
                                  for AACE MIP 3.7 Multiple Base mode.
                                  Example::

                                    {
                                      "F1": {"xer_path": "/tmp/bl_pre_F1.xer"},
                                      "F2": {"xer_content": "<XER text>"},
                                    }

            fragnets: list of fragnet dicts. Each must have:
                - 'id', 'name', 'liability' (responsible party)
                - 'activities': list of {code, name, duration_days,
                                          clndr_id?}
                  (clndr_id is the P6 calendar id, CALENDAR.clndr_id.
                  This tool schedules on a uniform timeline that walks
                  no calendar, so it does not change the result here.)
                - 'ties':       list of {pred, succ, type, lag_days?}
                Optional: 'description'.
            output_dir: output dir for TIA_Report.txt + CSV (tempdir if "").
            project_name: optional override.
            preparer / company: optional, printed in the report header as
                who prepared the analysis. Both are blank unless supplied.

        Returns:
            {
              "report":      path to TIA_Report.txt,
              "impacts_csv": path to TIA_Impact_Details.csv,
              "baseline":    {"project_finish", "critical_count", ...},
              "per_fragnet": [{fragnet_id, name, liability,
                                completion_before, completion_after,
                                impact_days, impact_working_days,
                                affected_activities, status, error}, ...],
              "cumulative_days": int (sum of per-fragnet impacts),
              "cumulative_basis": str (BOTH modes — states the cumulative
                                  figure is the sum of independent
                                  per-fragnet impacts and overstates joint
                                  impact when fragnets share a path),
              "per_event_methodology": str (the method label, or why
                                      nothing was measured),
              "per_event_base_count": int (count of unique base XERs
                                      read; 0 when none could be read),
              "per_event_bases_used": {fragnet_id: sha256_hash8} (multi-base only),
              "per_event_unread": [fragnet_id] (multi-base only: events
                                  whose base could not be read, so not
                                  measured),
              "per_event_requested": int (multi-base only: every event
                                  asked for),
              "not_measured": bool (True when no base could be read: every
                              figure is 0 only because nothing was
                              measured, not a finding of no delay),
              "single_base_disclosure": str (whenever every event
                                      measured shared one base, MIP 3.6),
              "cumulative_caveat": str (multi-base only),
            }