#!/bin/bash
# downpour.sh -- back up your iCloud-stored data to a local folder.
# https://downpour.sh
# Copyright (c) 2026 downpour.sh. MIT licensed: https://opensource.org/licenses/MIT
#
# Usage:   bash <this script> [output_folder]   (default output base: ~/Desktop)
#          The dated  downpour-<user>-YYYY-MM-DD-HHMMSS/  subfolder is created
#          INSIDE output_folder. At most one positional path; positional and
#          flag order don't matter.
#
# Flags — each sets the env var shown in [brackets]; exporting that env var
# directly is equivalent (e.g. PHOTOS_SYS_COPY=no bash <this script>):
#   Photos, system library (default ON)
#     --no-system-originals         skip copying system-library originals  [PHOTOS_SYS_COPY=no]
#     --no-system-report            skip the system-library report         [PHOTOS_SYS_REPORT=no]
#   Photos, other libraries (default OFF)
#     --other-libraries             also process non-system libraries (copy + report)
#     --no-other-originals          other libraries: skip originals copy   [PHOTOS_OTHER_COPY=no]
#     --no-other-report             other libraries: skip the report       [PHOTOS_OTHER_REPORT=no]
#   Photos, shared albums (default ON)
#     --no-shared-originals         skip the per-album asset copy          [SHARED_COPY=no]
#     --no-shared-report            skip the shared-albums report rows      [SHARED_REPORT=no]
#     --no-verify-shared-matches    skip czkawka match verification + fetch [PHOTOS_VERIFY_SHARED_MATCHES=0]
#                                   (alias: --disable-verify-shared-matches)
#   Auto-fetch components
#     --disable-protoc              Notes: skip protoc fetch, use strings    [NOTES_FETCH_PROTOC=0]
#                                   (alias: --no-protoc)
#     --disable-imessage-exporter   Messages: skip binary fetch, use bash    [MESSAGES_USE_IMESSAGE_EXPORTER=0]
#                                   (alias: --no-imessage-exporter)
#     --disable-czkawka             Photos: skip czkawka fetch (shared-album  [PHOTOS_VERIFY_SHARED_MATCHES=0]
#                                   matches stay unchecked) (alias: --no-czkawka)
#     --disable-convert-docs        skip iWork->ODF conversion + LibreOffice  [CONVERT_DOCS=0]
#                                   (alias: --no-convert-docs)
#   -h / --help                     print this help and exit
#
# Console + GUI-menu only. SSH / headless / no-TTY / cron runs are refused
# (there is no unattended mode). Use the interactive menu to deselect leaves and to enable
# the off-by-default categories (Books, Freeform, Maps, Music Playlists,
# Safari Bookmarks, Stickies, Text Replacements, Voice Memos, Convert iWork
# Files) — the flags above cover only the Photos scopes and the auto-fetches.

if (return 0 2>/dev/null); then printf 'ERROR: this script must be executed, not sourced.\n' >&2; return 1; fi
: "${SKIP_ALIASES:=1}"
CLEAN_DOWNLOADS="${CLEAN_DOWNLOADS:-0}"
EXPORT_OVERHEAD_GB="${EXPORT_OVERHEAD_GB:-10}"
CONFIRM_AUTO_NO_SEC="${CONFIRM_AUTO_NO_SEC:-10}"
MENU_AUTO_CANCEL_SEC="${MENU_AUTO_CANCEL_SEC:-60}"

FILES_INCLUSIONS=(
    Documents     # wholesale mirror
    Downloads     # wholesale mirror
    Desktop       # wholesale mirror — prior downpour-/export- timestamped subfolders are pruned
    Public        # wholesale mirror (the shared / Drop Box folder)
    Pictures      # full minus *.photoslibrary (see FILES_INCLUDE_PHOTOSLIBRARY_BUNDLES)
    Movies        # full minus *.imovielibrary (see FILES_INCLUDE_IMOVIE_BUNDLES)
    Music         # full minus GarageBand/ (see FILES_INCLUDE_GARAGEBAND_BUNDLES)
)

FILES_EXCLUSIONS=(
    "Movies/iMovie Theater.theater"  # iMovie's shared-theater bundle
    "Movies/iMovie Theater"          # pre-bundle theater store (older macOS)
    "Movies/TV"                      # the TV.app media library
    "Music/Audio Music Apps"         # Audio Units / plug-in scratch
    "Music/Music"                    # the Music.app (iTunes) library
)
FILES_INCLUDE_IMOVIE_BUNDLES=1
FILES_INCLUDE_GARAGEBAND_BUNDLES=1
FILES_INCLUDE_PHOTOSLIBRARY_BUNDLES=0
FILES_INCLUDE_OTHER_HOME=1
: "${FREEFORM_GUI_WAIT_SEC:=20}"
: "${EXPORT_PASSWORDS_CONFIRM:=1}"
: "${PHOTOS_SYS_COPY:=yes}"
: "${PHOTOS_SYS_REPORT:=yes}"
: "${PHOTOS_OTHER_COPY:=no}"
: "${PHOTOS_OTHER_REPORT:=yes}"
: "${PHOTOS_INCLUDE_SHARED_SOURCE:=yes}"
: "${PHOTOS_PERLIB_HEADROOM_MB:=500}"
: "${PHOTO_LIBRARY_DOWNLOAD_MISSING:=1}"
: "${PHOTO_LIBRARY_DOWNLOAD_TIMEOUT_SEC:=60}"
SHARED_COPY="${SHARED_COPY:-yes}"
SHARED_REPORT="${SHARED_REPORT:-yes}"
: "${SHARED_ALBUMS_PER_ASSET_SEC:=60}"
: "${STICKIES_RTF_MAX_MB:=50}"
if (return 0 2>/dev/null); then
    printf 'ERROR: this script must be executed, not sourced.\n' >&2
    return 1
fi

trap '' USR1 2>/dev/null || true
[ -z "${BASH_VERSION:-}" ] && { printf 'ERROR: requires bash\n' >&2; exit 1; }
case "$BASH_VERSION" in [12].*|3.0*|3.1*)
    printf 'ERROR: bash 3.2+ required (found %s)\n' "$BASH_VERSION" >&2; exit 1 ;;
esac

_macos_pv="$(sw_vers -productVersion 2>/dev/null)"
if [ -z "$_macos_pv" ]; then
    printf 'ERROR: requires macOS (Tahoe 26+); could not read sw_vers -productVersion.\n' >&2
    exit 1
fi

_macos_major="${_macos_pv%%.*}"
case "$_macos_major" in
    ''|*[!0-9]*)
        printf 'ERROR: unexpected sw_vers -productVersion output: %s\n' "$_macos_pv" >&2
        exit 1 ;;
esac

_macos_major=$((10#$_macos_major))
if [ "$_macos_major" -lt 26 ]; then
    printf 'ERROR: macOS Tahoe (26) or newer required. This Mac reports %s.\n' "$_macos_pv" >&2
    printf '       Earlier macOS versions are not supported.\n' >&2
    exit 1
fi

unset _macos_pv _macos_major
if [ -z "${HOME:-}" ] || [ ! -d "$HOME" ]; then
    printf 'ERROR: HOME is unset or not a directory (got %q)\n' "${HOME:-}" >&2
    exit 1
fi

set -uo pipefail
IFS=$' \t\n'
export COPYFILE_DISABLE=1
WARN_COUNT=0
ERR_COUNT=0
: "${_LEAF_COUNTS_ID:=$$}"
SCRATCH_DIR=""

OUTPUT_PATHS_TO_CLEAN=()

CHILD_PIDS=()

_TEE_PIDS=()

_PRE_PREPARE_WARNS=()

_PRE_PREPARE_ERRS=()
SUCCESS_FLAG="no"
_CLEANUP_RUNNING=0
DOWNPOUR_TRACE_FILE=""
if [ -n "${DOWNPOUR_TRACE:-}" ]; then
    DOWNPOUR_TRACE_FILE="${TMPDIR:-/tmp}/downpour-trace.$$.log"
    : > "$DOWNPOUR_TRACE_FILE" 2>/dev/null || DOWNPOUR_TRACE_FILE=""
    if [ -n "$DOWNPOUR_TRACE_FILE" ]; then
        exec 2> >(tee -a "$DOWNPOUR_TRACE_FILE" >&2)
        set -x
    else
        printf 'warn: DOWNPOUR_TRACE set but cannot write %s — tracing disabled\n' \
            "${TMPDIR:-/tmp}/downpour-trace.$$.log" >&2
    fi
fi

_TM_SUSPENDED=0
_LAST_BLANK=0
[ "${_INVOKED_BY_WRAPPER:-0}" = "1" ] && _LAST_BLANK=1
_BANNER_SHOWN=0
: "${TCC_POLL_TIMEOUT:=20}"
case "$TCC_POLL_TIMEOUT" in
    ''|*[!0-9]*) TCC_POLL_TIMEOUT=20 ;;
    0|[1-9]*)    ;;
    *)           TCC_POLL_TIMEOUT=$((10#$TCC_POLL_TIMEOUT)) ;;
esac

: "${TCC_POLL_INTERVAL_SEC:=2}"
case "$TCC_POLL_INTERVAL_SEC" in
    ''|*[!0-9]*) TCC_POLL_INTERVAL_SEC=2 ;;
    0)           TCC_POLL_INTERVAL_SEC=1 ;;
    [1-9]*)      ;;
    *)           TCC_POLL_INTERVAL_SEC=$((10#$TCC_POLL_INTERVAL_SEC)) ;;
esac

if [ -t 1 ] || [ "${_DOWNPOUR_FORCE_TTY_OUT:-0}" = "1" ]; then
    _B=$'\033[1m'   # bold on
    _D=$'\033[2m'   # dim  on
    _N=$'\033[22m'  # bold + dim off (back to regular)
else
    _B=""; _D=""; _N=""
fi

_TAG_OK='ok:'; _TAG_WARN='warn:'; _TAG_ERR='error:'
_TAG_OK_W=${#_TAG_OK}; _TAG_WARN_W=${#_TAG_WARN}; _TAG_ERR_W=${#_TAG_ERR}
_C_OK=''; _C_WARN=''; _C_ERR=''; _C_RST1=''; _C_RST2=''
_C_BRAND=''; _C_BRAND_RST=''
_status_color=0
_TPUT_COLORS=0
if [ -z "${NO_COLOR:-}" ] && command -v tput >/dev/null 2>&1; then
    _sc_n="$(tput colors 2>/dev/null || echo 0)"
    case "$_sc_n" in ''|*[!0-9]*) _sc_n=0 ;; esac
    _TPUT_COLORS="$_sc_n"
    [ "$_sc_n" -ge 8 ] && _status_color=1
    unset _sc_n
fi

if [ -t 1 ] || [ "${_DOWNPOUR_FORCE_TTY_OUT:-0}" = "1" ]; then
    _TAG_OK='✓'; _TAG_OK_W=1
    if [ "$_status_color" = "1" ]; then
        _C_OK=$'\033[32m'; _C_RST1=$'\033[0m'
        if [ "${_TPUT_COLORS:-0}" -ge 256 ]; then _C_BRAND=$'\033[38;5;75m'; else _C_BRAND=$'\033[34m'; fi
        _C_BRAND_RST=$'\033[0m'
    fi
fi

if [ -t 2 ] || [ "${_DOWNPOUR_FORCE_TTY_ERR:-0}" = "1" ]; then
    _TAG_WARN='!'; _TAG_WARN_W=1; _TAG_ERR='✗'; _TAG_ERR_W=1
    [ "$_status_color" = "1" ] && { _C_WARN=$'\033[33m'; _C_ERR=$'\033[31m'; _C_RST2=$'\033[0m'; }
fi

unset _status_color

_blank() {
    [ "$_LAST_BLANK" = "1" ] && return
    printf '\n'
    _LAST_BLANK=1
}

_WRAP_WIDTH="${DOWNPOUR_WRAP_WIDTH:-120}"
case "$_WRAP_WIDTH" in ''|*[!0-9]*) _WRAP_WIDTH=120 ;; esac
{ [ "$_WRAP_WIDTH" -ge 40 ] && [ "$_WRAP_WIDTH" -le 200 ]; } || _WRAP_WIDTH=120
_REPORT_WIDTH="${DOWNPOUR_FILE_WRAP_WIDTH:-120}"
case "$_REPORT_WIDTH" in ''|*[!0-9]*) _REPORT_WIDTH=120 ;; esac
[ "$_REPORT_WIDTH" -gt 2000 ] && _REPORT_WIDTH=2000
[ "$_REPORT_WIDTH" -lt 40 ] && _REPORT_WIDTH=40

_log_fold() {
    _LF_P1="$1" _LF_W1="$2" _LF_CONT="$3" _LF_W="${_WRAP_WIDTH:-120}" \
    LC_ALL=C awk '
        BEGIN {
            p1 = ENVIRON["_LF_P1"]; w1 = ENVIRON["_LF_W1"] + 0
            cont = ENVIRON["_LF_CONT"]; W = ENVIRON["_LF_W"] + 0; if (W <= 0) W = 80
            a1 = W - w1;            if (a1 < 8) a1 = 8
            ac = W - length(cont);  if (ac < 8) ac = 8
        }
        {
            n = split($0, word, " "); line = ""; first = 1
            for (i = 1; i <= n; i++) {
                if (word[i] == "") continue
                lim = (first ? a1 : ac)
                if (line == "") line = word[i]
                else if (length(line) + 1 + length(word[i]) > lim) {
                    if (first) { printf "%s%s\n", p1, line; first = 0 }
                    else         printf "%s%s\n", cont, line
                    line = word[i]
                }
                else line = line " " word[i]
            }
            if (first) printf "%s%s\n", p1, line
            else        printf "%s%s\n", cont, line
        }'
}

log_info() {
    local _m="$*"
    case "$_m" in
        *": /"*|*": ~/"*) printf '  %s\n' "$_m"; _LAST_BLANK=0; return 0 ;;
    esac
    if [ "$(( ${#_m} + 2 ))" -le "${_WRAP_WIDTH:-120}" ]; then
        printf '  %s\n' "$_m"
    else
        local _lead="${_m%%[! ]*}" _txt
        _txt="${_m#"$_lead"}"
        printf '%s\n' "$_txt" | _log_fold "  $_lead" "$(( 2 + ${#_lead} ))" "  $_lead"
    fi
    _LAST_BLANK=0
}

log_ok()   {
    local _m="$*" _pw=$(( 2 + _TAG_OK_W + 1 ))
    if [ "$(( ${#_m} + _pw ))" -le "${_WRAP_WIDTH:-120}" ]; then
        printf '  %s%s%s %s\n' "$_C_OK" "$_TAG_OK" "$_C_RST1" "$_m"
    else
        printf '%s\n' "$_m" | _log_fold "  ${_C_OK}${_TAG_OK}${_C_RST1} " "$_pw" "    "
    fi
    _LAST_BLANK=0
}

log_warn() {
    local _m="$*" _pw=$(( 2 + _TAG_WARN_W + 1 ))
    if [ "$(( ${#_m} + _pw ))" -le "${_WRAP_WIDTH:-120}" ]; then
        printf '  %s%s%s %s\n' "$_C_WARN" "$_TAG_WARN" "$_C_RST2" "$_m" >&2
    else
        printf '%s\n' "$_m" | _log_fold "  ${_C_WARN}${_TAG_WARN}${_C_RST2} " "$_pw" "    " >&2
    fi
    WARN_COUNT=$((WARN_COUNT+1))
    local _msg="${*//$'\n'/ }"
    if [ -n "${_LEAF_COUNTS_DIR:-}" ] && [ -d "${_LEAF_COUNTS_DIR:-}" ] \
       && [ -w "${_LEAF_COUNTS_DIR:-}" ]; then
        printf '%s\n' "$_msg" >> "$_LEAF_COUNTS_DIR/$_LEAF_COUNTS_ID.warns" 2>/dev/null || true
    else
        _PRE_PREPARE_WARNS+=( "$_msg" )
    fi
    _LAST_BLANK=0
}

log_err()  {
    local _m="$*" _pw=$(( 2 + _TAG_ERR_W + 1 ))
    if [ "$(( ${#_m} + _pw ))" -le "${_WRAP_WIDTH:-120}" ]; then
        printf '  %s%s%s %s\n' "$_C_ERR" "$_TAG_ERR" "$_C_RST2" "$_m" >&2
    else
        printf '%s\n' "$_m" | _log_fold "  ${_C_ERR}${_TAG_ERR}${_C_RST2} " "$_pw" "    " >&2
    fi
    ERR_COUNT=$((ERR_COUNT+1))
    local _msg="${*//$'\n'/ }"
    if [ -n "${_LEAF_COUNTS_DIR:-}" ] && [ -d "${_LEAF_COUNTS_DIR:-}" ] \
       && [ -w "${_LEAF_COUNTS_DIR:-}" ]; then
        printf '%s\n' "$_msg" >> "$_LEAF_COUNTS_DIR/$_LEAF_COUNTS_ID.errs" 2>/dev/null || true
    else
        _PRE_PREPARE_ERRS+=( "$_msg" )
    fi
    _LAST_BLANK=0
}

log_step() { _blank; printf '%s%s── %s%s%s\n' "$_C_BRAND" "$_B" "$*" "$_N" "$_C_BRAND_RST"; _LAST_BLANK=0; }

die()      { log_err "$*"; exit 1; }

cleanup_handler() {
    local rc="${1:-$?}"
    trap '' INT TERM HUP QUIT USR1
    [ "$_CLEANUP_RUNNING" -eq 1 ] && return
    _CLEANUP_RUNNING=1
    local p _any_alive=0
    if declare -F _heartbeat_stop >/dev/null 2>&1; then
        _heartbeat_stop 2>/dev/null || true
    fi
    if declare -F leaf_cleanup_hook >/dev/null 2>&1; then
        ( leaf_cleanup_hook ) || true
    fi
    if [ -n "${_LEAF_COUNTS_DIR:-}" ]; then
        local _post_w _post_e
        if [ -s "$_LEAF_COUNTS_DIR/$_LEAF_COUNTS_ID.warns" ]; then
            _post_w="$(wc -l < "$_LEAF_COUNTS_DIR/$_LEAF_COUNTS_ID.warns" 2>/dev/null | tr -d ' ')"
            case "$_post_w" in ''|*[!0-9]*) _post_w=0 ;; esac
            [ "$_post_w" -gt "$WARN_COUNT" ] && WARN_COUNT="$_post_w"
        fi
        if [ -s "$_LEAF_COUNTS_DIR/$_LEAF_COUNTS_ID.errs" ]; then
            _post_e="$(wc -l < "$_LEAF_COUNTS_DIR/$_LEAF_COUNTS_ID.errs" 2>/dev/null | tr -d ' ')"
            case "$_post_e" in ''|*[!0-9]*) _post_e=0 ;; esac
            [ "$_post_e" -gt "$ERR_COUNT" ] && ERR_COUNT="$_post_e"
        fi
    fi
    _write_leaf_counts
    if [ "${#_TEE_PIDS[@]}" -gt 0 ]; then
            local _t _n
            for _t in "${_TEE_PIDS[@]+"${_TEE_PIDS[@]}"}"; do
                disown "$_t" 2>/dev/null || true
            done
            exec 1>/dev/null 2>/dev/null
            local _alive
            _n=0
            while [ "$_n" -lt 20 ]; do
                _alive=0
                for _t in "${_TEE_PIDS[@]+"${_TEE_PIDS[@]}"}"; do
                    kill -0 "$_t" 2>/dev/null && { _alive=1; break; }
                done
                [ "$_alive" = "0" ] && break
                sleep 0.1 2>/dev/null || true
                _n=$((_n + 1))
            done
            for _t in "${_TEE_PIDS[@]+"${_TEE_PIDS[@]}"}"; do
                kill -KILL "$_t" 2>/dev/null || true
                pkill -KILL -P "$_t" 2>/dev/null || true
            done
            local _new_cp=() _cp _tp _skip_cp
            for _cp in "${CHILD_PIDS[@]+"${CHILD_PIDS[@]}"}"; do
                _skip_cp=0
                for _tp in "${_TEE_PIDS[@]+"${_TEE_PIDS[@]}"}"; do
                    [ "$_cp" = "$_tp" ] && { _skip_cp=1; break; }
                done
                [ "$_skip_cp" = "1" ] && continue
                _new_cp+=( "$_cp" )
            done
            CHILD_PIDS=( "${_new_cp[@]+"${_new_cp[@]}"}" )
    fi
    for p in "${CHILD_PIDS[@]+"${CHILD_PIDS[@]}"}"; do
        [ -z "$p" ] && continue
        if kill -0 "$p" 2>/dev/null; then _any_alive=1; break; fi
    done
    if [ "$_any_alive" = "1" ]; then
        for p in "${CHILD_PIDS[@]+"${CHILD_PIDS[@]}"}"; do
            [ -z "$p" ] && continue
            kill -TERM "$p" 2>/dev/null || true
        done
        sleep 1 2>/dev/null || true
        for p in "${CHILD_PIDS[@]+"${CHILD_PIDS[@]}"}"; do
            [ -z "$p" ] && continue
            kill -KILL "$p" 2>/dev/null || true
        done
    fi
    [ "${#CHILD_PIDS[@]}" -gt 0 ] && CHILD_PIDS=()
    [ "${#_TEE_PIDS[@]}" -gt 0 ] && _TEE_PIDS=()
    if [ "$SUCCESS_FLAG" != "yes" ] && [ "${#OUTPUT_PATHS_TO_CLEAN[@]}" -gt 0 ]; then
      if [ "${_INVOKED_BY_WRAPPER:-0}" != "1" ]; then
          local _kept_root="${_OUT_DIR:-}"
          if [ -z "$_kept_root" ]; then
              local _cand
              for _cand in "${OUTPUT_PATHS_TO_CLEAN[@]+"${OUTPUT_PATHS_TO_CLEAN[@]}"}"; do
                  [ -d "$_cand" ] && { _kept_root="$_cand"; break; }
              done
          fi
          printf '  Keeping the partial (INCOMPLETE) export%s — scratch/temp removed.\n' "${_kept_root:+ at $_kept_root}" 2>/dev/null >/dev/tty \
              || printf '  Keeping the partial (INCOMPLETE) export — scratch/temp removed.\n' 2>/dev/null \
              || true
          if [ -n "$_kept_root" ] && [ -d "$_kept_root" ]; then
              {
                  printf '\357\273\277'   # UTF-8 BOM, as above
                  _report_frame "ABORTED — export interrupted"
                  printf '  Result:  INCOMPLETE \342\200\224 the run was interrupted before it finished.\n'
                  printf '\n'; _report_band "WHAT THIS MEANS"; printf '\n'
                  printf '    \342\200\242 The partial output was KEPT; only scratch / temporary files were removed.\n'
                  printf '    \342\200\242 Some categories may be missing, partial, or mid-write.\n'
                  printf '    \342\200\242 Completeness was NOT verified: the run never reached its summary step,\n'
                  printf '      so nothing here is a ledger of what you got. Do NOT treat this folder as\n'
                  printf '      a complete or trustworthy backup.\n'
                  printf '    \342\200\242 Re-run downpour.sh to produce a complete, verified export.\n'
              } > "$_kept_root/_downpour_report.txt" 2>/dev/null || true
          fi
      fi
    fi
    if [ -z "${_INVOKED_BY_WRAPPER:-}" ] && [ -n "${_LEAF_COUNTS_DIR:-}" ] \
       && [ -f "$_LEAF_COUNTS_DIR/leaf_scratch_dirs" ]; then
        local _lsd
        while IFS= read -r _lsd; do
            [ -n "$_lsd" ] && [ -d "$_lsd" ] || continue
            case "$_lsd" in */downpour.*) ;; *) continue ;; esac
            chmod -R u+w "$_lsd" 2>/dev/null || true
            rm -rf -- "$_lsd" 2>/dev/null || true
        done < "$_LEAF_COUNTS_DIR/leaf_scratch_dirs"
    fi
    if [ -n "$SCRATCH_DIR" ] && [ -d "$SCRATCH_DIR" ]; then
        chmod -R u+w "$SCRATCH_DIR" 2>/dev/null || true
        rm -rf -- "$SCRATCH_DIR" 2>/dev/null || true
    fi
    if [ -n "$DOWNPOUR_TRACE_FILE" ]; then
        if [ "$rc" -eq 0 ] && [ "$SUCCESS_FLAG" = "yes" ]; then
            rm -f -- "$DOWNPOUR_TRACE_FILE" 2>/dev/null || true
        else
            printf '  trace: %s\n' "$DOWNPOUR_TRACE_FILE" 2>/dev/null >/dev/tty \
                || printf '  trace: %s\n' "$DOWNPOUR_TRACE_FILE" >&2 \
                || true
        fi
    fi
    if [ -z "${_INVOKED_BY_WRAPPER:-}" ] && [ -z "${_LEAF_COUNTS_DIR:-}" ]; then
        _blank
    fi
    trap - INT TERM HUP QUIT EXIT
    exit "$rc"
}

resolve_output_dir() {
    local out="${1:-$HOME/Desktop}"
    case "$out" in
        [~])    out="$HOME" ;;
        [~]/*)  out="$HOME/${out#~/}" ;;
    esac
    [ -d "$out" ] || die "Output folder does not exist: $out"
    [ -w "$out" ] || die "Output folder is not writable: $out"
    case "$out" in
        *$'\n'*) die "Output folder path contains a newline (unsupported): $out" ;;
    esac
    local abs
    abs="$(cd "$out" 2>/dev/null && pwd -P)" || die "Cannot resolve output folder: $out"
    [ -n "$abs" ] || die "Cannot resolve output folder: $out"
    [ "$abs" = "/" ] && die "Refusing to use / as the output folder"
    case "$abs" in
        *$'\n'*) die "Output folder path contains a newline (unsupported): $out" ;;
    esac
    local prefix
    for prefix in "${SOURCE_PROTECTED_PREFIXES[@]+"${SOURCE_PROTECTED_PREFIXES[@]}"}"; do
        case "$abs/" in
            "$prefix"/*|"$prefix"/)
                die "Output folder is inside protected source-data path: $prefix
  Choose a destination outside ~/Library." ;;
        esac
    done
    printf '%s' "$abs"
}

_parse_output_folder_arg() {
    local out_arg="" arg end_opts=0 _seen=0
    while [ "$#" -gt 0 ]; do
        arg="$1"; shift
        if [ "$end_opts" -eq 0 ]; then
            case "$arg" in
                --) end_opts=1; continue ;;
                -*) die "Unknown flag: $arg" ;;
            esac
        fi
        if [ "$_seen" -eq 1 ]; then
            die "Too many positional arguments: '$arg' (already saw '$out_arg'). Pass at most one output folder."
        fi
        out_arg="$arg"; _seen=1
    done
    printf '%s' "$out_arg"
}

require_no_collision() {
    local p
    for p in "$@"; do
        if [ -e "$p" ] || [ -L "$p" ]; then
            die "Output exists, refusing to clobber: '$p'"
        fi
    done
}

_fda_grant_hint() {
    log_info "  Grant it in: System Settings > Privacy & Security > Full Disk Access"
    log_info "  Add your terminal (Terminal, iTerm, Ghostty, etc.) and enable the toggle."
}

check_full_disk_access() {
    local tcc="$HOME/Library/Application Support/com.apple.TCC/TCC.db"
    [ -n "$(head -c1 -- "$tcc" 2>/dev/null)" ] && return 0
    local _fda_path
    for _fda_path in \
        "$HOME/Library/Application Support/AddressBook" \
        "$HOME/Library/Mail" \
        "$HOME/Library/Messages" \
        "$HOME/Library/Group Containers/group.com.apple.calendar" \
        "$HOME/Library/Group Containers/group.com.apple.notes"; do
        [ -d "$_fda_path" ] || continue
        ls "$_fda_path" >/dev/null 2>&1 && return 0
    done
    return 1
}

require_full_disk_access() {
    case "${_FDA_STATE:-unknown}" in
        granted)
            return 0
            ;;
        denied)
            if check_full_disk_access; then
                log_ok "Full Disk Access: granted (after wrapper pre-flight)"
                return 0
            fi
            log_err "Full Disk Access not granted (wrapper pre-flight already polled and timed out)."
            _fda_grant_hint
            log_info "  Then re-run."
            exit 1
            ;;
        unknown|'')
            ;;
        *)
            log_warn "_FDA_STATE='$_FDA_STATE' unrecognized; treating as unset (full probe-and-poll path)."
            ;;
    esac
    check_full_disk_access && return 0
    log_info "Full Disk Access not yet granted — opening System Settings."
    log_info "  Add your terminal (Terminal, iTerm, Ghostty, etc.) to the"
    log_info "  Full Disk Access list and toggle it ON."
    log_info "  Polling for up to ${TCC_POLL_TIMEOUT} seconds; the run will proceed when you grant."
    open 'x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles' \
        >/dev/null 2>&1 || true
    if wait_for_grant check_full_disk_access "Full Disk Access" "$TCC_POLL_TIMEOUT"; then
        log_ok "Full Disk Access: granted"
        return 0
    fi
    log_err "Full Disk Access was not granted within ${TCC_POLL_TIMEOUT} s."
    _fda_grant_hint
    log_info "  If polling didn't pick up your grant, quit and re-launch the"
    log_info "  terminal, then re-run this script."
    exit 1
}

require_accessibility() {
    case "${_ACCESSIBILITY_STATE:-unknown}" in
        granted)
            return 0
            ;;
        denied|na)
            if check_accessibility; then
                return 0
            fi
            log_err "Accessibility not granted (wrapper pre-flight already probed)."
            log_info "  Grant it in: System Settings > Privacy & Security > Accessibility"
            log_info "  Add your terminal binary and enable the toggle, then re-run."
            return 1
            ;;
    esac
    log_info "Probing Accessibility..."
    if check_accessibility; then
        log_ok "Accessibility: granted"
        return 0
    fi
    log_info "Accessibility permission required — opening System Settings."
    log_info "  Add your terminal (Terminal, iTerm, Ghostty, etc.) to the"
    log_info "  Privacy & Security > Accessibility list and toggle it ON."
    log_info "  Polling for up to ${TCC_POLL_TIMEOUT} seconds; the run will proceed when you grant."
    open 'x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility' \
        >/dev/null 2>&1 || true
    if wait_for_grant check_accessibility "Accessibility" "$TCC_POLL_TIMEOUT"; then
        log_ok "Accessibility: granted"
        return 0
    fi
    log_err "Accessibility was not granted within ${TCC_POLL_TIMEOUT} s."
    log_info "  Grant it in: System Settings > Privacy & Security > Accessibility"
    log_info "  Add your terminal binary and enable the toggle, then re-run."
    return 1
}

print_summary() {
    _probe_disclose
    if [ "${_INVOKED_BY_WRAPPER:-0}" = "1" ]; then
        _write_leaf_counts
        return 0
    fi
    _blank
    if [ "$ERR_COUNT" -eq 0 ] && [ "$WARN_COUNT" -eq 0 ]; then
        printf '%sDone. No warnings or errors.%s\n' "$_D" "$_N"
    elif [ "$ERR_COUNT" -eq 0 ]; then
        printf '%sDone with %d %s.%s\n' \
            "$_D" "$WARN_COUNT" "$(_pluralize "$WARN_COUNT" warning)" "$_N"
    else
        printf '%sDone with %d %s and %d %s.%s\n' \
            "$_D" "$ERR_COUNT" "$(_pluralize "$ERR_COUNT" error)" \
            "$WARN_COUNT" "$(_pluralize "$WARN_COUNT" warning)" "$_N"
    fi
    _LAST_BLANK=0
    _blank
    _write_leaf_counts
    if [ -n "${_LEAF_REPORT_CATEGORY:-}" ] && [ -n "${_LEAF_REPORT_DIR:-}" ]; then
        if [ ! -d "$_LEAF_REPORT_DIR" ] && [ -s "$(_report_store)" ]; then
            mkdir -p "$_LEAF_REPORT_DIR" 2>/dev/null || true
        fi
        [ -d "$_LEAF_REPORT_DIR" ] && \
            finalize_leaf_report "$_LEAF_REPORT_CATEGORY" "$_LEAF_REPORT_DIR"
    fi
}

_write_leaf_counts() {
    [ "${_INVOKED_BY_WRAPPER:-0}" = "1" ] || return 0
    [ -n "${_LEAF_COUNTS_DIR:-}" ] || return 0
    [ -d "${_LEAF_COUNTS_DIR:-}" ] && [ -w "${_LEAF_COUNTS_DIR:-}" ] || return 0
    {
        printf 'WARN=%d\n' "$WARN_COUNT"
        printf 'ERR=%d\n'  "$ERR_COUNT"
    } > "$_LEAF_COUNTS_DIR/$_LEAF_COUNTS_ID.counts" 2>/dev/null || true
}

maybe_show_help() {
    local arg
    for arg in "$@"; do
        case "$arg" in
            -h|--help|-\?|--help=*)
                local src="${BASH_SOURCE[0]:-}"
                if [ -n "$src" ] && [ -f "$src" ] && [ -r "$src" ]; then
                    awk 'NR==1 { next }
                         /^$/ { exit }
                         { sub(/^# ?/, ""); print }' "$src"
                else
                    printf 'Help text lives in this script'\''s header comment (the spec is the script).\n'
                    printf 'View it with: curl -fsSL <url> | head -60\n'
                fi
                exit 0
                ;;
        esac
    done
}

_countdown_key_prompt() {
    local _ckp_sec="$1" _ckp_var="$2" _ckp_text="$3" _ckp_s _ckp_stty=""
    printf -v "$_ckp_var" '%s' '' 2>/dev/null || true
    case "$_ckp_sec" in ''|*[!0-9]*|0) _ckp_sec=10 ;; esac
    ( : </dev/tty ) 2>/dev/null || return 0
    local _ckp_kf; _ckp_kf="$(mktemp "${SCRATCH_DIR:-${TMPDIR:-/tmp}}/.ckp.XXXXXX" 2>/dev/null)" || return 0
    _ckp_stty="$(stty -g </dev/tty 2>/dev/null || true)"
    ( _ckp_k=""; IFS= read -r -n 1 _ckp_k </dev/tty 2>/dev/null \
        && printf '%s' "$_ckp_k" > "$_ckp_kf"; ) &
    local _ckp_rpid=$!
    for _ckp_s in $(LC_ALL=C seq "$_ckp_sec" -1 1); do
        printf '\r  %s (auto-no in %ds) ' "$_ckp_text" "$_ckp_s" >&2
        [ -s "$_ckp_kf" ] && break
        sleep 1 2>/dev/null || true
        [ -s "$_ckp_kf" ] && break
    done
    kill -KILL "$_ckp_rpid" 2>/dev/null || true
    wait "$_ckp_rpid" 2>/dev/null || true
    [ -n "$_ckp_stty" ] && stty "$_ckp_stty" </dev/tty 2>/dev/null || true
    printf -v "$_ckp_var" '%s' "$(cat "$_ckp_kf" 2>/dev/null)" 2>/dev/null || true
    rm -f "$_ckp_kf" 2>/dev/null
}

ensure_scratch() {
    [ -n "$SCRATCH_DIR" ] && [ -d "$SCRATCH_DIR" ] && return 0
    SCRATCH_DIR="$(mktemp -d -t downpour)" || die "Cannot create scratch directory"
    [ -n "$SCRATCH_DIR" ] && [ -d "$SCRATCH_DIR" ] || die "Cannot create scratch directory (mktemp produced no usable path)."
    case "$SCRATCH_DIR" in
        *[!A-Za-z0-9./_-]*)
            local _orphan="$SCRATCH_DIR"
            SCRATCH_DIR=""
            rm -rf -- "$_orphan" 2>/dev/null || true
            die "Unsafe scratch path '$_orphan' (contains characters outside [A-Za-z0-9./_-]).
  TMPDIR='$TMPDIR' produced this path; set TMPDIR to a path of safe characters and re-run."
            ;;
    esac
    if [ "${_INVOKED_BY_WRAPPER:-}" = "1" ] && [ -n "${_LEAF_COUNTS_DIR:-}" ] \
       && [ -d "$_LEAF_COUNTS_DIR" ]; then
        printf '%s\n' "$SCRATCH_DIR" >> "$_LEAF_COUNTS_DIR/leaf_scratch_dirs" 2>/dev/null || true
    fi
}

track_output_path() { OUTPUT_PATHS_TO_CLEAN+=( "$1" ); }

_untrack_output_path() {
    local _target="$1" _cp _new=() _removed=0
    for _cp in "${OUTPUT_PATHS_TO_CLEAN[@]+"${OUTPUT_PATHS_TO_CLEAN[@]}"}"; do
        if [ "$_removed" -eq 0 ] && [ "$_cp" = "$_target" ]; then
            _removed=1
            continue
        fi
        _new+=( "$_cp" )
    done
    OUTPUT_PATHS_TO_CLEAN=( "${_new[@]+"${_new[@]}"}" )
}

mark_success()      { SUCCESS_FLAG="yes"; }

_md5_hex() { md5 -q -- "$1" 2>/dev/null; }

_create_output_dir() {
    local _path="$1" _ctx="${2:-}"
    track_output_path "$_path"
    mkdir -p "$_path" || die "Cannot create $_path${_ctx:+ ($_ctx)}"
}

is_macos_junk_path() {
    case "$1" in
        .DS_Store|*/.DS_Store)                                 return 0 ;;
        .localized|*/.localized)                               return 0 ;;
        ._*|*/._*)                                             return 0 ;;
        .AppleDouble|.AppleDouble/*|*/.AppleDouble|*/.AppleDouble/*)             return 0 ;;
        .Spotlight-V100|.Spotlight-V100/*|*/.Spotlight-V100|*/.Spotlight-V100/*) return 0 ;;
        .fseventsd|.fseventsd/*|*/.fseventsd|*/.fseventsd/*)                     return 0 ;;
        .Trashes|.Trashes/*|*/.Trashes|*/.Trashes/*)                             return 0 ;;
        .TemporaryItems|.TemporaryItems/*|*/.TemporaryItems|*/.TemporaryItems/*) return 0 ;;
        .DocumentRevisions-V100|.DocumentRevisions-V100/*|*/.DocumentRevisions-V100|*/.DocumentRevisions-V100/*) return 0 ;;
        __MACOSX|__MACOSX/*|*/__MACOSX|*/__MACOSX/*)           return 0 ;;
        .VolumeIcon.icns|*/.VolumeIcon.icns)                   return 0 ;;
        .com.apple.timemachine|*/.com.apple.timemachine)       return 0 ;;
        .com.apple.timemachine.*|*/.com.apple.timemachine.*)   return 0 ;;
        .apdisk|*/.apdisk)                                     return 0 ;;
    esac
    return 1
}

is_macos_alias() {
    local f="$1" size magic hex
    _is_network_mount_for "$f" && return 1
    size="$(stat -f %z -- "$f" 2>/dev/null)"
    case "$size" in
        ''|*[!0-9]*) return 1 ;;
    esac
    [ "$size" -lt 200 ] && return 1
    [ "$size" -gt 32768 ] && return 1
    magic="$(LC_ALL=C od -An -tx1 -N 4 -- "$f" 2>/dev/null)"
    magic="${magic// /}"
    magic="${magic//$'\n'/}"
    case "$magic" in
        626f6f6b) return 0 ;;
    esac
    hex="$(xattr -px com.apple.FinderInfo -- "$f" 2>/dev/null | head -1)"
    hex="${hex// /}"
    hex="${hex:0:8}"
    hex="${hex//A/a}"
    hex="${hex//B/b}"
    hex="${hex//C/c}"
    hex="${hex//D/d}"
    hex="${hex//E/e}"
    hex="${hex//F/f}"
    case "$hex" in
        616c6973*|616c7973*) return 0 ;;
    esac
    return 1
}

should_skip_copy() {
    local f="$1" rel="${2:-$1}"
    [ -L "$f" ] && return 0
    is_macos_junk_path "$rel" && return 0
    [ "${SKIP_ALIASES:-0}" = "1" ] && is_macos_alias "$f" && return 0
    return 1
}

is_icloud_stub() {
    case "${1##*/}" in
        .?*.icloud) return 0 ;;
    esac
    return 1
}

_strip_icloud_stub_name() {
    local s="$1"
    s="${s%.icloud}"
    s="${s#.}"
    if [ -n "${2:-}" ]; then printf -v "$2" '%s' "$s"; return 0; fi
    printf '%s' "$s"
}

_expand_tilde() {
    local p="$1"
    case "$p" in
        [~]|[~]/*) printf '%s' "$HOME${p#~}" ;;
        *)         printf '%s' "$p" ;;
    esac
}

_is_gzipped() {
    local mb
    mb="$(LC_ALL=C head -c 2 -- "$1" 2>/dev/null | xxd -p 2>/dev/null)"
    [ "$mb" = "1f8b" ]
}

_icloud_stub_sibling_for() {
    local p="${1:-}"
    [ -z "$p" ] && return 1
    local _bn="${p##*/}"
    [ -z "$_bn" ] && return 1
    local _dir=""
    case "$p" in
        */*) _dir="${p%/*}/" ;;
    esac
    local _stub="${_dir}.${_bn}.icloud"
    [ -f "$_stub" ] && { printf '%s' "$_stub"; return 0; }
    return 1
}

is_dataless() {
    local _fl
    _fl="$(stat -f '%f' -- "${1:-}" 2>/dev/null)" || return 1
    case "$_fl" in ''|*[!0-9]*) return 1 ;; esac
    [ "$(( 10#$_fl & 1073741824 ))" -ne 0 ]
}

_materialized_copy_incomplete() {
    local _exp_size="$1" _dst="$2" _dst_size
    _dst_size="$(stat -f '%z' -- "$_dst" 2>/dev/null)"
    [ -n "$_dst_size" ] || return 0
    if [ -n "$_exp_size" ] && [ "$_exp_size" != "$_dst_size" ]; then
        return 0
    fi
    is_dataless "$_dst" && return 0
    return 1
}

_emit_html_index() {
    local _out="$1" _label="$2"
    local _tmp _rows_rc=1 _group_rc
    _tmp="$(mktemp "$_out.tmp.XXXXXX" 2>/dev/null)" || {
        log_warn "Could not stage $_label — index not written."
        return 1
    }
    track_output_path "$_tmp"
    {
        printf '<!DOCTYPE html>\n<html>\n<head>\n'
        printf '<meta charset="UTF-8">\n'
        printf '<title>%s</title>\n' "${_idx_title:-Index}"
        printf '<style>\n'
        printf 'html{background:#f4f4f6;margin:0;padding:2em 1em;min-height:100vh;}\n'
        printf 'body{font-family:-apple-system,BlinkMacSystemFont,"Helvetica Neue",sans-serif;max-width:900px;margin:0 auto;color:#222;}\n'
        printf 'h1{font-size:1.3em;font-weight:600;margin:0 0 1em;}\n'
        printf 'table{border-collapse:collapse;width:100%%;background:#fff;border-radius:8px;overflow:hidden;box-shadow:0 1px 3px rgba(0,0,0,0.08);}\n'
        printf 'th,td{text-align:left;padding:0.55em 0.8em;border-bottom:1px solid #eee;font-size:0.92em;}\n'
        printf 'th{background:#fafafa;font-weight:600;color:#555;}\n'
        printf 'tr:last-child td{border-bottom:none;}\n'
        printf 'a{color:#0b6cff;text-decoration:none;}\n'
        printf 'a:hover{text-decoration:underline;}\n'
        [ -n "${_idx_extra_css:-}" ] && printf '%s\n' "$_idx_extra_css"
        printf 'footer{margin-top:1.5em;color:#999;font-size:0.8em;}\n'
        printf '</style>\n</head>\n<body>\n'
        printf '<h1>%s</h1>\n' "${_idx_h1:-${_idx_title:-Index}}"
        printf '<table>\n<thead>%s</thead>\n<tbody>\n' "${_idx_thead:-}"
        "$_idx_rows_fn"
        _rows_rc=$?
        printf '</tbody>\n</table>\n'
        printf '<footer>Exported %s.</footer>\n' "$(_utc_now_iso8601)"
        printf '</body>\n</html>\n'
    } > "$_tmp"
    _group_rc=$?
    { [ "$_rows_rc" -eq 0 ] && [ "$_group_rc" -eq 0 ]; }
    _atomic_commit_tmp $? "$_tmp" "$_out" "$_label"
    _untrack_output_path "$_tmp"
}

_epoch_to_utc_iso_into() {
    local _e="${1:-}" _out="${2:-}"
    [ -n "$_out" ] || return 0
    case "$_e" in ''|*[!0-9]*) printf -v "$_out" '%s' ''; return 0 ;; esac
    _e=$((10#$_e))
    local _days=$((_e / 86400)) _sod=$((_e % 86400))
    local _z=$((_days + 719468))
    local _era=$((_z / 146097))
    local _doe=$((_z - _era * 146097))
    local _yoe=$(( (_doe - _doe/1460 + _doe/36524 - _doe/146096) / 365 ))
    local _y=$((_yoe + _era * 400))
    local _doy=$(( _doe - (365*_yoe + _yoe/4 - _yoe/100) ))
    local _mp=$(( (5*_doy + 2) / 153 ))
    local _d=$(( _doy - (153*_mp + 2)/5 + 1 ))
    local _m
    if [ "$_mp" -lt 10 ]; then _m=$((_mp + 3)); else _m=$((_mp - 9)); fi
    [ "$_m" -le 2 ] && _y=$((_y + 1))
    printf -v "$_out" '%04d-%02d-%02dT%02d:%02d:%02dZ' \
        "$_y" "$_m" "$_d" "$((_sod / 3600))" "$(((_sod % 3600) / 60))" "$((_sod % 60))"
    return 0
}

_var_key_into() {
    local _s="${1:-}" _out="${2:-}" _i=0 _len=${#1} _c _o _h=2166136261
    [ -n "$_out" ] || return 0
    while [ "$_i" -lt "$_len" ]; do
        _c="${_s:$_i:1}"
        printf -v _o '%d' "'$_c" 2>/dev/null || _o=0
        _h=$(( (_h ^ (_o & 255)) & 4294967295 ))
        _h=$(( (_h * 16777619) & 4294967295 ))
        _i=$((_i + 1))
    done
    printf -v "$_out" '%08x' "$_h"
    return 0
}

_record_icloud_stub() {
    local _cf="${1:-}" _label="${2:-}" _rel="${3:-}" _orig
    [ -n "$_cf" ] || return 0
    local _dir
    _strip_icloud_stub_name "${_rel##*/}" _orig
    tsv_escape "$_orig" _orig
    tsv_escape "$_label" _label
    case "$_rel" in
        */*) tsv_escape "${_rel%/*}" _dir
             printf '%s\t%s/%s\n' "$_label" "$_dir" "$_orig" >> "$_cf" ;;
        *)   printf '%s\t%s\n'    "$_label" "$_orig" >> "$_cf" ;;
    esac
    return 0
}

_ditto_dl_retry() {
    local _s="$1" _d="$2" _wdl="${3:-0}" _e _r _try=0 _max
    case "${ICLOUD_DOWNLOAD_RETRIES:-}" in
        ''|*[!0-9]*) _max=2 ;;
        *) _max=$((10#${ICLOUD_DOWNLOAD_RETRIES})); [ "$_max" -gt 10 ] && _max=2 ;;
    esac
    while :; do
        _e="$(ditto -- "$_s" "$_d" 2>&1 >/dev/null)"; _r=$?
        [ "$_r" -eq 0 ] && break
        [ "$_wdl" = "1" ] || break
        case "$_e" in *"Permission denied"*|*"Operation not permitted"*) break ;; esac
        [ "$_try" -ge "$_max" ] && break
        _try=$((_try + 1))
        rm -f -- "$_d" 2>/dev/null
        sleep "$(( _try * 2 ))" 2>/dev/null || true
    done
    printf '%s' "$_e"
    return "$_r"
}

_ditto_verified() {
    local _s="$1" _d="$2" _rt="${3:-0}" _ev="${4:-}" _st _sz _fl _wdl=0 _e _r
    _st="$(stat -f '%z %f' -- "$_s" 2>/dev/null)"
    _sz="${_st%% *}"; _fl="${_st##* }"
    case "$_sz" in ''|*[!0-9]*) _sz="" ;; esac
    case "$_fl" in
        ''|*[!0-9]*) ;;
        *) [ "$(( 10#$_fl & 1073741824 ))" -ne 0 ] && _wdl=1 ;;
    esac
    if [ "$_rt" = "1" ]; then
        _e="$(_ditto_dl_retry "$_s" "$_d" "$_wdl")"; _r=$?
    else
        _e="$(ditto -- "$_s" "$_d" 2>&1 >/dev/null)"; _r=$?
    fi
    [ -n "$_ev" ] && printf -v "$_ev" '%s' "$_e"
    if [ "$_r" -ne 0 ]; then
        rm -f -- "$_d" 2>/dev/null
        return 1
    fi
    if [ "$_wdl" = "1" ] && _materialized_copy_incomplete "$_sz" "$_d"; then
        rm -f -- "$_d" 2>/dev/null
        return 2
    fi
    return 0
}

_pluralize() {
    local n="$1" singular="$2" plural="${3:-${2}s}"
    n="${n#"${n%%[![:space:]]*}"}"
    case "$n" in ''|*[!0-9]*) n=0 ;; esac
    n=$((10#${n:-0}))
    if [ "$n" = "1" ]; then printf '%s' "$singular"; else printf '%s' "$plural"; fi
}

_sql_cd_to_unix() {
    local _col="$1"
    printf '(CASE WHEN %s > 4000000000 THEN %s/1e9 + 978307200 ELSE %s + 978307200 END)' \
        "$_col" "$_col" "$_col"
}

_count_lines() {
    local _cl_file="$1" _cl_default="${2:-0}" _cl_n
    _cl_n="$(LC_ALL=C awk 'END{print NR}' "$_cl_file" 2>/dev/null)"
    case "$_cl_n" in
        ''|*[!0-9]*) printf '%s\n' "$_cl_default" ;;
        *)           printf '%s\n' "$_cl_n" ;;
    esac
}

_count_csv_rows() {
    local _ccr_file="$1" _ccr_default="${2:-0}" _ccr_n
    _ccr_n="$(LC_ALL=C awk 'END{print NR-1}' "$_ccr_file" 2>/dev/null)"
    case "$_ccr_n" in
        ''|*[!0-9]*) printf '%s\n' "$_ccr_default" ;;
        *)           printf '%s\n' "$_ccr_n" ;;
    esac
}

_to_int() {
    local _ti_v="$1" _ti_default="${2:-0}"
    case "$_ti_v" in
        ''|*[!0-9]*) printf '%s\n' "$_ti_default" ;;
        *)           printf '%s\n' "$_ti_v" ;;
    esac
}

_clamp_env_int() {
    local _name="$1" _default="$2" _max="${3:-}"
    local _v="${!_name:-}"
    local _clamped_new="$_default"
    case "$_v" in
        ''|*[!0-9]*) _clamped_new="$_default" ;;
        0|0[0-9]*)   _clamped_new="$_default" ;;
        *)
            if ! _is_int64_safe "$_v"; then
                _clamped_new="$_default"
            elif [ -n "$_max" ] && [ "$_v" -gt "$_max" ]; then
                _clamped_new="$_default"
            else
                _clamped_new="$_v"
            fi
            ;;
    esac
    printf -v "$_name" '%s' "$_clamped_new"
    printf '%s' "$_clamped_new"
}

_dir_size_human() {
    local path="$1" _s
    [ -d "$path" ] || { printf '0B'; return; }
    _s="$(LC_ALL=C du -sh "$path" 2>/dev/null | LC_ALL=C awk 'NR==1 { print $1; exit }')"
    case "$_s" in
        ''|*[!0-9.BKMGTP]*|[!0-9]*) _s=0B ;;
    esac
    case "$_s" in
        *[BKMGTP]) ;;
        *)         _s="${_s}B" ;;
    esac
    printf '%s' "${_s:-0B}"
}

_df_mountpoint_of() {
    df -P "${1:-}" 2>/dev/null | LC_ALL=C awk '
        NR==2 && NF>=6 { m=$6; for (i=7;i<=NF;i++) m=m" "$i; print m }'
}

_mount_fstype_of() {
    LC_ALL=C mount 2>/dev/null | mp="$1" LC_ALL=C awk '
        BEGIN { mp = ENVIRON["mp"] }
        {
            needle = " on " mp " ("
            i = index($0, needle)
            if (i == 0) next
            fs = substr($0, i + length(needle))
            k = index(fs, ","); if (k > 0) fs = substr(fs, 1, k - 1)
            l = index(fs, ")");  if (l > 0) fs = substr(fs, 1, l - 1)
            print tolower(fs); exit
        }'
}

_target_filesystem_type() {
    local _path="${1:-}" _mp _fs
    [ -e "$_path" ] || return 0
    _mp="$(_df_mountpoint_of "$_path")"
    [ -z "$_mp" ] && return 0
    _fs="$(_mount_fstype_of "$_mp")"
    printf '%s' "$_fs"
}

_is_network_mount_for() {
    local _p="${1:-}" _mp _key _cached _cached_mp _fs
    [ -n "$_p" ] || return 1
    _mp="$(_df_mountpoint_of "$_p")"
    [ -n "$_mp" ] || return 1
    _mp="${_mp%/}"
    [ -n "$_mp" ] || _mp="/"
    _key="$(printf '%s' "$_mp" | LC_ALL=C tr -c 'A-Za-z0-9_' '_')"
    [ -n "$_key" ] || return 1
    local _mp_ref="_NETMOUNT_CACHE_MP_$_key"
    local _fs_ref="_NETMOUNT_CACHE_FS_$_key"
    _cached_mp="${!_mp_ref:-}"
    _cached="${!_fs_ref:-}"
    if [ -z "$_cached" ] || [ "$_cached_mp" != "$_mp" ]; then
        _fs="$(_mount_fstype_of "$_mp")"
        case "$_fs" in
            nfs|smbfs|afpfs|webdav|webdavfs|ftp|cifs) _cached=n ;;
            *) _cached=l ;;
        esac
        printf -v "$_mp_ref" '%s' "$_mp"
        printf -v "$_fs_ref" '%s' "$_cached"
    fi
    [ "$_cached" = "n" ]
}

warn_if_fragile_filesystem() {
    local _fs
    _fs="$(_target_filesystem_type "${1:-}")"
    case "$_fs" in
        exfat|msdos|ntfs)
            log_warn "Output volume is $_fs — case-insensitive (filenames differing only in case collide), no POSIX permissions, no extended attributes; some exported metadata cannot be preserved on this volume."
            ;;
        macfuse*|osxfuse*|tuxera_*|paragon_*|fuse|fuse-*|fuse_*|fusefs*|fuse[0-9]*)
            log_warn "Output volume is a FUSE / third-party driver ($_fs) — case-insensitivity and extended-attribute support depend on the driver. Some exported metadata may not preserve."
            ;;
        smbfs|nfs|webdav|webdavfs|cifs|afpfs|ftp)
            log_warn "Output volume is a network filesystem ($_fs) — permission and metadata fidelity depend on the server."
            ;;
    esac
    return 0
}

_fmt_duration() {
    local s="$1"
    case "$s" in ''|*[!0-9]*) s=0 ;; esac
    if [ "$s" -lt 60 ]; then
        printf '%ds' "$s"
    elif [ "$s" -lt 3600 ]; then
        printf '%dm %ds' "$((s / 60))" "$((s % 60))"
    else
        printf '%dh %dm' "$((s / 3600))" "$(((s % 3600) / 60))"
    fi
}

_fmt_relative_mtime() {
    local _p="${1:-}"
    [ -e "$_p" ] || { printf ''; return; }
    local _mtime _now _delta
    _mtime="$(stat -f '%m' -- "$_p" 2>/dev/null)"
    case "$_mtime" in
        ''|*[!0-9]*) printf ''; return ;;
    esac
    _now="$(date +%s 2>/dev/null)"
    case "$_now" in
        ''|*[!0-9]*) printf ''; return ;;
    esac
    _delta=$((_now - _mtime))
    [ "$_delta" -lt 0 ] && _delta=0
    if   [ "$_delta" -lt 60 ];      then printf 'just now'
    elif [ "$_delta" -lt 3600 ];    then printf '%dm ago'  "$((_delta / 60))"
    elif [ "$_delta" -lt 86400 ];   then printf '%dh ago'  "$((_delta / 3600))"
    elif [ "$_delta" -lt 2592000 ]; then printf '%dd ago'  "$((_delta / 86400))"
    elif [ "$_delta" -lt 31536000 ];then printf '%dmo ago' "$((_delta / 2592000))"
    else                                 printf '%dy ago'  "$((_delta / 31536000))"
    fi
}

_progress_tick() {
    if [ -z "${_pt_last+x}" ] || [ -z "${_pt_inline+x}" ]; then
        if [ -z "${_PROGRESS_TICK_WARNED:-}" ]; then
            log_warn "_progress_tick called without caller-side 'local _pt_last=0 _pt_inline=0' — progress display may misbehave; this is a leaf-code bug."
            _PROGRESS_TICK_WARNED=1
        fi
        _pt_last="${_pt_last:-0}"
        _pt_inline="${_pt_inline:-0}"
    fi
    if [ "${_pt_last:-0}" -eq 0 ]; then
        _pt_last=$((SECONDS + 1))
        return 0
    fi
    [ "$(( SECONDS - _pt_last ))" -ge 5 ] || return 0
    _pt_last=$SECONDS
    mark_activity
    local _d="${1:-0}" _t="${2:-0}" _n="${3:-items}" _msg
    case "$_d" in ''|*[!0-9]*) _d=0 ;; esac
    case "$_t" in ''|*[!0-9]*) _t=0 ;; esac
    if [ "$_t" -gt 0 ]; then
        _msg="$_d/$_t $_n ($(( _d * 100 / _t ))%)"
    else
        _msg="$_d $_n"
    fi
    if { [ -t 1 ] || [ "${_DOWNPOUR_FORCE_TTY_OUT:-0}" = "1" ]; }; then
        printf '\r  %s\033[K' "$_msg"
        _pt_inline=1
    else
        log_info "$_msg"
    fi
}

_progress_end() {
    [ "${_pt_inline:-0}" = "1" ] || return 0
    { [ -t 1 ] || [ "${_DOWNPOUR_FORCE_TTY_OUT:-0}" = "1" ]; } && printf '\n'
    _pt_inline=0
    _pt_last=0
    return 0
}

csv_field() {
    local s="$1"
    if [ "${#s}" -gt 1048576 ] && [ -z "${_CSV_OVERSIZE_WARNED:-}" ]; then
        local _bytes
        _bytes=$(printf '%s' "$s" | LC_ALL=C wc -c | LC_ALL=C tr -d ' ')
        if [ "${_bytes:-0}" -gt 1048576 ]; then
            log_warn "csv_field: emitting an oversized field (${_bytes} bytes) — typical RFC 4180 consumers cannot handle values this large; check the caller for an accidental BLOB pass-through."
            _CSV_OVERSIZE_WARNED=1
        fi
    fi
    s="${s//$'\r'/}"
    case "$s" in
        [=+@-]*|$'\t'*) s="'$s" ;;
    esac
    case "$s" in
        *,*|*'"'*|*$'\n'*)
            s="${s//\"/\"\"}"; s="${s//$'\n'/ }"
            s="\"$s\"" ;;
    esac
    if [ -n "${2:-}" ]; then printf -v "$2" '%s' "$s"; return 0; fi
    printf '%s' "$s"
}

_sanitize_name() {
    local s="$1"
    s="${s//\//_}"; s="${s//\\/_}"; s="${s//:/_}"
    s="${s//\"/_}"; s="${s//\?/_}"; s="${s//\*/_}"
    s="${s//|/_}";  s="${s//</_}";  s="${s//>/_}"
    s="${s//$'\t'/ }"; s="${s//$'\n'/ }"; s="${s//$'\r'/ }"
    s="${s//[[:cntrl:]]/}"
    while [ "${s# }" != "$s" ] || [ "${s#.}" != "$s" ]; do s="${s# }"; s="${s#.}"; done
    while [ "${s% }" != "$s" ] || [ "${s%.}" != "$s" ]; do s="${s% }"; s="${s%.}"; done
    if [ "${#s}" -gt 50 ]; then
    s="$(printf '%s' "$s" | LC_ALL=C awk '{
        s = $0
        if (length(s) > 200) {
            s = substr(s, 1, 200)
            last_lead = 0
            for (i = length(s); i > 0; i--) {
                c = substr(s, i, 1)
                if (c ~ /[\200-\277]/) continue
                if (c ~ /[\300-\377]/) last_lead = i
                break
            }
            if (last_lead > 0) {
                lead = substr(s, last_lead, 1)
                expected = 0
                if      (lead ~ /[\300-\337]/) expected = 1
                else if (lead ~ /[\340-\357]/) expected = 2
                else if (lead ~ /[\360-\367]/) expected = 3
                actual = length(s) - last_lead
                if (actual < expected) {
                    s = substr(s, 1, last_lead - 1)
                }
            }
        }
        print s
    }')"
    fi
    while [ "${s% }" != "$s" ] || [ "${s%.}" != "$s" ]; do s="${s% }"; s="${s%.}"; done
    [ -z "$s" ] && s="Untitled"
    printf '%s' "$s"
}

_snapshot_db_cleanup_partial() {
    local _snap="$1" _why="$2"
    if ! rm -f -- "$_snap" "$_snap-wal" "$_snap-shm" 2>/dev/null; then
        if [ -f "$_snap" ]; then
            mv -f -- "$_snap" "$_snap.partial.$$" 2>/dev/null || true
        fi
        log_warn "snapshot_db: failed to clean up partial snapshot family at $_snap ($_why; manual cleanup may be needed)"
    fi
}

snapshot_db() {
    local src="$1" src_md5 snap _src_bytes _need_kb _free_kb _src_mb
    local _headroom_kb=102400  # 100 MB
    local _progress_min_mb=50
    [ -f "$src" ] || return 1
    { : < "$src"; } 2>/dev/null || return 2
    ensure_scratch
    _src_bytes="$(stat -f %z -- "$src" 2>/dev/null || printf 0)"
    case "$_src_bytes" in ''|*[!0-9]*) _src_bytes=0 ;; esac
    local _sb _sbz
    for _sb in "$src-wal" "$src-shm"; do
        if [ -f "$_sb" ]; then
            _sbz="$(stat -f %z -- "$_sb" 2>/dev/null || printf 0)"
            case "$_sbz" in ''|*[!0-9]*) _sbz=0 ;; esac
            _src_bytes=$((_src_bytes + _sbz))
        fi
    done
    _need_kb=$((_src_bytes / 1024 + _headroom_kb))
    local _df_out
    _df_out="$(df -P -k "$SCRATCH_DIR" 2>/dev/null)"
    _free_kb="$(printf '%s\n' "$_df_out" | LC_ALL=C awk 'NR==2 && NF >= 4 {print $4+0}')"
    if [ -n "$_free_kb" ]; then
        if [ "$_free_kb" -eq 0 ]; then
            printf '  error: scratch volume reports 0 MB free; cannot snapshot %s\n' "$src" >&2
            return 5
        elif [ "$_free_kb" -lt "$_need_kb" ]; then
            printf '  error: scratch volume has %d MB free; need ~%d MB to snapshot %s\n' \
                "$((_free_kb / 1024))" "$((_need_kb / 1024))" "$src" >&2
            return 5
        fi
    fi
    local _src_base
    _src_base="$(printf '%s' "${src##*/}" | LC_ALL=C tr -c 'A-Za-z0-9._-' '_')"
    src_md5="$(printf '%s' "$src" | md5 -q 2>/dev/null)"
    case "${src_md5:-}" in
        ''|*[!0-9a-f]*)
            log_err "snapshot_db: md5 output is not a valid hex digest for '$src' (got: ${src_md5:-<empty>}; md5 missing, swapped for a different tool, or broken)"
            return 6 ;;
    esac
    [ "${#src_md5}" -eq 32 ] || {
        log_err "snapshot_db: md5 output is not 32 chars long for '$src' (got length ${#src_md5}; md5 output format unexpected)"
        return 6
    }
    snap="$SCRATCH_DIR/snap_${_src_base}_$src_md5.db"
    local _snap_just_created=0
    if [ ! -f "$snap" ]; then
        _snap_just_created=1
        _src_mb=$((_src_bytes / 1048576))
        if [ "$_src_mb" -ge "$_progress_min_mb" ]; then
            printf '  Snapshotting %s (%d MB)...\n' "${src##*/}" "$_src_mb" >&2
        fi
        if ! cp -f -- "$src" "$snap" 2>/dev/null; then
            rm -f -- "$snap" 2>/dev/null
            return 3
        fi
        if [ -f "$src-wal" ] && ! cp -f -- "$src-wal" "$snap-wal" 2>/dev/null; then
            _snapshot_db_cleanup_partial "$snap" "WAL copy failed"
            return 3
        fi
        if [ -f "$src-shm" ] && ! cp -f -- "$src-shm" "$snap-shm" 2>/dev/null; then
            _snapshot_db_cleanup_partial "$snap" "SHM copy failed"
            return 3
        fi
        if [ -f "$snap-wal" ]; then
            sqlite3 "$snap" "PRAGMA wal_checkpoint(TRUNCATE);" >/dev/null 2>&1 || true
        fi
    fi
    local _qpid _qrc=0 _qwatchdog
    trap '' USR1
    sqlite3 "$snap" "SELECT 1;" >/dev/null 2>&1 &
    _qpid=$!
    ( exec >/dev/null 2>&1 </dev/null
      sleep 30
      kill -0 "$_qpid" 2>/dev/null || exit 0
      kill -TERM "$_qpid" 2>/dev/null
      sleep 1
      kill -0 "$_qpid" 2>/dev/null && kill -KILL "$_qpid" 2>/dev/null
    ) </dev/null >/dev/null 2>&1 &
    _qwatchdog=$!
    wait "$_qpid" 2>/dev/null; _qrc=$?
    pkill -KILL -P "$_qwatchdog" 2>/dev/null || true
    kill -KILL "$_qwatchdog" 2>/dev/null
    wait "$_qwatchdog" 2>/dev/null || true
    trap _skip_handler USR1 2>/dev/null || true
    if [ "$_qrc" -ne 0 ]; then
        rm -f -- "$snap" "$snap-wal" "$snap-shm" 2>/dev/null
        return 4
    fi
    if [ "$_snap_just_created" -eq 1 ] && [ -n "$_src_mb" ] && [ "$_src_mb" -ge "$_progress_min_mb" ]; then
        local _wal_marker=""
        [ -f "$snap-wal" ] && _wal_marker=", WAL truncated"
        printf '  Snapshot OK: %s (%d MB%s, queryable)\n' \
            "${src##*/}" "$_src_mb" "$_wal_marker" >&2
    fi
    printf '%s' "$snap"
}

snapshot_db_or_die() {
    local _src="$1" _feature="$2" _snap _rc
    _snap="$(snapshot_db "$_src")"
    _rc=$?
    case "$_rc" in
        0)  printf '%s' "$_snap" ;;
        1)  die "${_feature} source database is missing: $_src" ;;
        2)  die "${_feature} source database is unreadable: $_src — Full Disk Access required?" ;;
        3)  die "${_feature} snapshot copy failed: $_src — scratch volume full or permission denied?" ;;
        4)  die "${_feature} source database is corrupt or unqueryable: $_src — try closing the owning app and retrying" ;;
        5)  die "${_feature} snapshot needs more scratch space than is available; free up the scratch volume ($TMPDIR) or set TMPDIR to a larger volume" ;;
        6)  die "${_feature} snapshot failed: $_src — the md5 hashing tool is missing or broken (see the error above)" ;;
        *)  die "${_feature} snapshot failed (rc=$_rc): $_src" ;;
    esac
}

require_db_tables() {
    local _snap="$1" _feature="$2"
    shift 2
    local _t _missing=""
    for _t in "$@"; do
        case "$_t" in
            ''|*[!A-Za-z0-9_]*)
                die "$_feature: invalid table name in schema check: '$_t'" ;;
        esac
        sqlite3 -readonly "$_snap" "SELECT 1 FROM \"$_t\" LIMIT 1;" \
            >/dev/null 2>&1 || _missing="${_missing:+$_missing }$_t"
    done
    [ -z "$_missing" ] && return 0
    local _present
    _present="$(sqlite3 -readonly "$_snap" \
        "SELECT GROUP_CONCAT(name, ' ') FROM sqlite_master \
         WHERE type='table';" 2>/dev/null)"
    die "$_feature: database schema unrecognised — expected table(s) not present: $_missing
  Apple may have changed the schema in a macOS update; please report this.
  Tables in this database: ${_present:-(none)}"
}

_col_present() {
    local snap="$1" table="$2" col="$3"
    [ -n "$snap" ] && [ -n "$table" ] && [ -n "$col" ] || return 1
    case "$table" in *[!A-Za-z0-9_]*) return 1 ;; esac
    case "$col"   in *[!A-Za-z0-9_]*) return 1 ;; esac
    local _cp_key _cp_var _cp_list
    _cp_key="${snap}__${table}"
    _cp_key="${_cp_key//[^A-Za-z0-9_]/_}"
    _cp_var="_col_present_cache_$_cp_key"
    _cp_list="${!_cp_var:-}"
    if [ -z "$_cp_list" ]; then
        local _cp_raw _cp_rc
        _cp_raw="$(sqlite3 -readonly "$snap" \
            "SELECT GROUP_CONCAT(name, ',') FROM pragma_table_info('$table');" \
            2>/dev/null)"
        _cp_rc=$?
        if [ "$_cp_rc" -ne 0 ]; then
            _probe_miss error "$table" "$col"
            return 1
        fi
        _cp_list=",$_cp_raw,"
        printf -v "$_cp_var" '%s' "$_cp_list"
    fi
    case "$_cp_list" in
        *,"$col",*) return 0 ;;
    esac
    _probe_miss absent "$table" "$col"
    return 1
}

_PROBE_KNOWN_ABSENT="
ZJOURNALENTRYMO.ZPLACENAME
ZJOURNALENTRYMO.ZSTATEOFMIND
ZJOURNALENTRYMO.ZTIMEZONE
ZJOURNALENTRYMO.ZWEATHERCONDITIONCODE
ZJOURNALENTRYMO.ZWEATHERHIGHTEMPERATURE
ZJOURNALENTRYMO.ZWEATHERHUMIDITY
ZJOURNALENTRYMO.ZWEATHERLOWTEMPERATURE
ZCLOUDRECORDING.ZISFAVORITE
ZCLOUDRECORDING.ZLOCALDELETEDDATE
ZCLOUDRECORDING.ZMODIFIEDDATE
ZCLOUDRECORDING.ZRECORDING_PARENT
ZCLOUDRECORDING.ZTRANSCRIPTION
ZCLOUDRECORDING.ZTRIMENDOFFSET
ZCLOUDRECORDING.ZTRIMSTARTOFFSET
ZFOLDER.ZPARENTFOLDER
ZFAVORITEITEM.ZLASTVISITEDTIME
ZFAVORITEITEM.ZPHONENUMBER
ZFAVORITEITEM.ZURL
ZTEXTREPLACEMENTENTRY.ZSYNCSTATE
ZTEXTREPLACEMENTENTRY.ZWASDELETEDFROMICLOUD
ZSHARE.ZCLOUDOWNERFIRSTNAME
ZSHARE.ZCLOUDOWNERHASHEDPERSONID
ZSHARE.ZCLOUDOWNERLASTNAME
ZREMCDREMINDER.ZRECURRENCERULE
"

_probe_store() {
    local _s; _s="$(_report_store)" || return 1
    printf '%s' "$_s.probes"
}

_probe_miss() {
    [ "${_PROBE_SUPPRESS:-0}" = "1" ] && return 0
    local _pk
    if [ "${1:-absent}" = "absent" ] && [ -n "${3:-}" ]; then
        _pk=$'\n'"${2:-}.${3}"$'\n'
        case "${_PROBE_KNOWN_ABSENT:-}" in *"$_pk"*) return 0 ;; esac
    fi
    local _st; _st="$(_probe_store)" || return 0
    printf '%s\t%s\t%s\t%s\n' \
        "$(_report_flat "$(_report_subject "${_LEAF_CATEGORY_DIR:-}")")" \
        "${1:-absent}" "${2:-}" "${3:-}" >> "$_st" 2>/dev/null || true
    return 0
}

_probe_disclose() {
    local _dir="${1:-${_LEAF_CATEGORY_DIR:-}}" _st _subj _kind _list _n
    _st="$(_probe_store)" || return 0
    [ -s "$_st" ] || return 0
    _subj="$(_report_flat "$(_report_subject "$_dir")")"
    [ -n "$_subj" ] || return 0
    for _kind in absent error; do
        _list="$(LC_ALL=C awk -F'\t' -v s="$_subj" -v k="$_kind" \
            '$1==s && $2==k {print $3 "." $4}' "$_st" 2>/dev/null \
            | LC_ALL=C sort -u)"
        [ -n "$_list" ] || continue
        _n="$(printf '%s\n' "$_list" | LC_ALL=C awk 'END{print NR}')"
        if [ "$_kind" = "absent" ]; then
            log_info "Schema probes: $_n optional $(_pluralize "$_n" column) absent on this macOS — the fields they carry are blank or omitted in this export$(_disclosure_pointer)."
            report_add schema "$_subj" "$_n" "" "$_list"
        else
            log_info "Schema probes: $_n column $(_pluralize "$_n" check) could not be completed (database busy or errored) — the features they gate were disabled WITHOUT confirming the columns are absent$(_disclosure_pointer)."
            report_incomplete "$_subj" "schema probes could not be completed" \
                "$_n column $(_pluralize "$_n" check) failed to run (the database was locked or returned an error), so downpour disabled the features they gate without being able to confirm those columns are really missing. Quit the source app and re-run; if the columns do exist, the affected content will be captured." \
                "$_list"
        fi
    done
    : > "$_st" 2>/dev/null || true
    return 0
}

_col_in_list() {
    printf '%s\n' "$1" | LC_ALL=C grep -qFx -- "$2"
}

_pick_first_col() {
    local _snap="$1" _table="$2"
    shift 2
    local _candidate _pfc_prev="${_PROBE_SUPPRESS:-0}"
    _PROBE_SUPPRESS=1
    for _candidate in "$@"; do
        if _col_present "$_snap" "$_table" "$_candidate"; then
            _PROBE_SUPPRESS="$_pfc_prev"
            printf '%s' "$_candidate"
            return 0
        fi
    done
    _PROBE_SUPPRESS="$_pfc_prev"
    _probe_miss absent "$_table" "$1"
    return 1
}

_resolve_entity_number() {
    case "$2" in ''|*[!A-Za-z0-9_]*) return 1 ;; esac
    local _ent
    _ent="$(sqlite3 -readonly "$1" \
        "SELECT Z_ENT FROM Z_PRIMARYKEY WHERE Z_NAME='$2' LIMIT 1;" \
        2>/dev/null)"
    case "$_ent" in ''|*[!0-9]*) return 1 ;; esac
    printf '%s' "$_ent"
}

_discover_z_join() {
    case "$2" in ''|*[!A-Za-z0-9_]*) return 1 ;; esac
    local _matches _n _t
    _matches="$(sqlite3 -readonly "$1" \
        "SELECT name FROM sqlite_master
          WHERE type='table' AND name GLOB 'Z_[0-9]*$2'
          ORDER BY name;" 2>/dev/null)"
    _n="$(printf '%s\n' "$_matches" | grep -c .)"
    case "${_n:-0}" in ''|*[!0-9]*) _n=0 ;; esac
    [ "$_n" -eq 0 ] && return 1
    [ "$_n" -gt 1 ] && return 2
    _t="$_matches"
    case "$_t" in Z_*) : ;; *) return 1 ;; esac
    case "$_t" in *[!A-Za-z0-9_]*) return 1 ;; esac
    printf '%s' "$_t"
}

report_no_source() {
    local feature="$1" reason="$2" path="${3:-}" icloud_app="${4:-}"
    log_warn "$feature $reason on this Mac — nothing to export"
    [ -n "$path" ] && log_info "(Looked for: $(tsv_escape "$path"))"
    _icloud_sync_hint "$icloud_app"
    _flag_no_content
    mark_success
    print_summary
    exit 0
}

report_empty_source() {
    local items="$1" icloud_app="${2:-}"
    log_warn "No $items to export — nothing to do."
    _icloud_sync_hint "$icloud_app"
    _flag_no_content
    mark_success
    print_summary
    exit 0
}

_flag_no_content() {
    [ -n "${_LEAF_COUNTS_DIR:-}" ] && [ -d "${_LEAF_COUNTS_DIR:-}" ] \
        && [ -w "${_LEAF_COUNTS_DIR:-}" ] || return 0
    : > "$_LEAF_COUNTS_DIR/$_LEAF_COUNTS_ID.nocontent" 2>/dev/null || true
}

_icloud_sync_hint() {
    [ -n "${1:-}" ] || return 0
    log_info "If $1 is in use on another Apple device, this may be an iCloud-sync gap — open $1 once to trigger sync, then re-run."
}

_url_encode_path() {
    _uep_in="$1" LC_ALL=C awk 'BEGIN{ for(i=0;i<256;i++) ord[sprintf("%c",i)]=i
      s=ENVIRON["_uep_in"]; out=""
      for(i=1;i<=length(s);i++){ c=substr(s,i,1)
          if (c ~ /[A-Za-z0-9._~\/-]/) out=out c
          else out=out sprintf("%%%02X", ord[c]) }
      print out }'
}

_bytes_human() {
    awk -v b="${1:-0}" 'BEGIN{
        split("B KB MB GB TB", u); s=1
        while (b>=1024 && s<5){ b=b/1024; s++ }
        if (s==1) printf "%d %s", b, u[s]; else printf "%.1f %s", b, u[s]
    }'
}

_optimize_storage_prose() {
    local _label="$1" _evicted="$2" _total="${3:-}" _recover="${4:-}"
    case "${_evicted:-0}" in ''|*[!0-9]*) return 0 ;; esac
    _is_int64_safe "$_evicted" || return 0
    _evicted=$((10#${_evicted:-0}))
    [ "$_evicted" -eq 0 ] && return 0
    local _msg="iCloud eviction (Optimize Mac Storage or app-equivalent) appears active for $_label — "
    if [ -n "$_total" ] && [ "$_total" != "0" ]; then
        case "$_total" in
            *[!0-9]*) _total="" ;;
            *)        if _is_int64_safe "$_total"; then _total=$((10#$_total)); else _total=""; fi ;;
        esac
    fi
    if [ -n "$_total" ] && [ "$_total" -gt 0 ]; then
        _msg="$_msg$_evicted of $_total $(_pluralize "$_total" item) cloud-only and not downloaded."
    else
        _msg="$_msg$_evicted $(_pluralize "$_evicted" item) cloud-only and not downloaded."
    fi
    if [ -n "$_recover" ]; then
        _msg="$_msg To capture them: $_recover, then re-run."
    else
        _msg="$_msg To capture them: disable iCloud's Optimize Mac Storage for $_label and wait for sync, then re-run."
    fi
    _OPTIMIZE_STORAGE_PROSE="$_msg"
    return 0
}

_disclose_optimize_storage() {
    _OPTIMIZE_STORAGE_PROSE=""
    _optimize_storage_prose "$@" || return 0
    [ -n "$_OPTIMIZE_STORAGE_PROSE" ] || return 0
    log_warn "$_OPTIMIZE_STORAGE_PROSE"
}

_disclosure_pointer() {
    [ "${_INVOKED_BY_WRAPPER:-0}" = "1" ] && return 0
    printf ' — see _downpour_report.txt'
}

_photos_report_header() {
    local lib="${1//$'\n'/ }"; lib="${lib//$'\r'/ }"
    printf '# downpour-photos-report v1\n'
    printf '# library: %s\n' "$lib"
    printf '# generated: %s\n' "$(_utc_now_iso8601)"
    printf '# host: %s\n' "$(hostname -s 2>/dev/null || printf 'unknown')"
    printf '# hash: md5\n'
}

_doc_header() {
    local _title="${1//$'\n'/ }"; _title="${_title//$'\r'/ }"; shift
    printf '%s\n' "$_title"
    if [ $# -ge 2 ]; then
        printf '\n'
        local _k _v
        while [ $# -ge 2 ]; do
            _k="${1//$'\n'/ }"; _k="${_k//$'\r'/ }"
            _v="${2//$'\n'/ }"; _v="${_v//$'\r'/ }"
            printf '%-8s  %s\n' "$_k:" "$_v"
            shift 2
        done
    fi
    printf '\n'
}

_report_store() {
    if [ -n "${_REPORT_STORE:-}" ]; then printf '%s' "$_REPORT_STORE"; return 0; fi
    [ -n "${SCRATCH_DIR:-}" ] || return 1
    _REPORT_STORE="$SCRATCH_DIR/_report_entries"
    printf '%s' "$_REPORT_STORE"
}

_report_store_init() {
    _report_store >/dev/null 2>&1 && return 0
    SCRATCH_DIR="$(mktemp -d -t downpour 2>/dev/null || printf '')"
    if [ -n "$SCRATCH_DIR" ] && [ -d "$SCRATCH_DIR" ]; then
        case "$SCRATCH_DIR" in
            *[!A-Za-z0-9./_-]*) rm -rf -- "$SCRATCH_DIR" 2>/dev/null || true
                                SCRATCH_DIR="" ;;
        esac
    else
        SCRATCH_DIR=""
    fi
    return 0
}

_report_flat() { printf '%s' "${1:-}" | LC_ALL=C tr -d '\011\012\015\035\037\000'; }

_report_subject() {
    local _s
    if [ -n "${_LEAF_REPORT_CATEGORY:-}" ]; then
        _s="$_LEAF_REPORT_CATEGORY"
    else
        local _d="${1:-}" _rel="${1:-}"
        if [ -n "${_EXPORT_ROOT:-}" ]; then
            case "$_d/" in "$_EXPORT_ROOT"/*) _rel="${_d#"$_EXPORT_ROOT"/}" ;; esac
        fi
        _rel="${_rel#/}"; _s="${_rel%%/*}"
    fi
    case "$_s" in
        'Music Playlists') _s='Music playlists' ;;
        'Voice Memos')     _s='Voice memos' ;;
        'Safari')          _s='Safari bookmarks' ;;
    esac
    printf '%s' "$_s"
}

report_add() {
    local _sev="${1:-}" _subj="${2:-}" _title="${3:-}" _prose="${4:-}" _items_raw="${5:-}"
    local _store; _store="$(_report_store)" || return 0
    local _items=""
    if [ -n "$_items_raw" ]; then
        _items="$(printf '%s' "$_items_raw" | LC_ALL=C tr -d '\015\035\037\000' | LC_ALL=C tr '\012\011' '\035 ')"
        _items="${_items%$'\035'}"
    fi
    printf '%s\037%s\037%s\037%s\037%s\n' \
        "$_sev" "$(_report_flat "$_subj")" "$(_report_flat "$_title")" \
        "$(_report_flat "$_prose")" "$_items" >> "$_store" 2>/dev/null || true
}

report_incomplete() { report_add incomplete "${1:-}" "${2:-}" "${3:-}" "${4:-}"; }

report_blocked()    { report_add blocked    "${1:-}" "${2:-}" "${3:-}" "${4:-}"; }

report_skipped()    { report_add skipped    "${1:-}" "${2:-}" "${3:-}" "${4:-}"; }  # retained for API symmetry + pinned by tests/fault-injection.sh (no live caller; skipped is emitted via _write_skipped_report)

report_review()     { report_add review     "${1:-}" "${2:-}" "${3:-}" "${4:-}"; }

report_warning()    { report_add warning    "${1:-}" "${2:-}" "" ""; }        # <source> <message>

report_status()     { report_add "${1:-}"   "${2:-}" "" "" ""; }              # <exported|deselected|empty> <subject>

_disclose_excluded() {
    local _short="${1:-}" _why="${2:-}" _subj
    [ -n "$_short" ] || return 0
    if [ -n "$_why" ]; then
        log_info "Excluded $_short — $_why"
    else
        log_info "Excluded $_short"
    fi
    _subj="$(_report_subject "${_LEAF_CATEGORY_DIR:-}")"
    [ -n "$_subj" ] && report_add excluded "$_subj" "$_short" "" ""
    return 0
}

_report_has_severity() {
    local _sev="${1:-}" _dir="${2:-}" _store _subj _us
    _store="$(_report_store)" || return 1
    [ -f "$_store" ] || return 1
    _subj="$(_report_flat "$(_report_subject "$_dir")")"
    _us=$'\037'
    s="$_sev" j="$_subj" awk -F"$_us" \
        'BEGIN { s=ENVIRON["s"]; j=ENVIRON["j"] } $1==s && $2==j { f=1; exit } END { exit !f }' "$_store" 2>/dev/null
}

report_have_incomplete() { _report_has_severity incomplete "${1:-}"; }

report_have_skipped()    { _report_has_severity skipped    "${1:-}"; }

_write_skipped_report() {
    local _dir="${1:-}" _feature="${2:-}" _ev="${3:-}" _tot="${4:-}" _rec="${5:-}"
    [ -n "$_dir" ] || { cat >/dev/null; return 0; }
    local _items; _items="$(cat)"
    local _prose="These were only in iCloud at export time (not on this Mac). Re-download them in Finder or the source app, then re-run."
    if [ -n "$_ev" ]; then
        _OPTIMIZE_STORAGE_PROSE=""
        _optimize_storage_prose "$_feature" "$_ev" "$_tot" "$_rec"
        [ -n "$_OPTIMIZE_STORAGE_PROSE" ] && _prose="$_OPTIMIZE_STORAGE_PROSE"
    fi
    report_add skipped "$(_report_subject "$_dir")" "$_feature — cloud-only items" \
        "$_prose" "$_items"
}

note_incomplete() {
    local _dir="${1:-}" _what="${2:-}" _why="${3:-}"
    [ -n "$_dir" ] || return 0
    local _subj; _subj="$(_report_subject "$_dir")"
    report_add incomplete "$_subj" "$_what" "$_why" ""
}

_incomplete_push() {
    local _ipn="$1"; shift
    case "$_ipn" in
        ''|*[!A-Za-z0-9_]*)
            die "_incomplete_push: invalid array name: '$_ipn'" ;;
    esac
    local _us; _us=$'\x1f'
    local _iw="${2:-}"
    eval "$_ipn+=( \"\$1\$_us\$_iw\" )"
}

_incomplete_drain() {
    local _iddir="${1:-}"; shift 2>/dev/null || true
    [ -n "$_iddir" ] || return 0
    local _us _ide; _us=$'\x1f'
    for _ide in "$@"; do
        note_incomplete "$_iddir" "${_ide%%$_us*}" "${_ide#*$_us}"
    done
}

_summary_wrap_text() {
    IND="$1" _W="${_REPORT_WIDTH:-120}" LC_ALL=C awk '
        BEGIN { ind = ENVIRON["IND"]; w = (ENVIRON["_W"] + 0) - length(ind); if (w < 20) w = 20 }
        {
            nn = split($0, word, " ")
            nl = 0; line = ""
            for (i = 1; i <= nn; i++) {
                if (word[i] == "") continue
                if (line == "")                                line = word[i]
                else if (length(line)+1+length(word[i]) > w) { lines[++nl] = line; line = word[i] }
                else                                           line = line " " word[i]
            }
            if (line != "") lines[++nl] = line
            if (nl >= 2 && index(lines[nl], " ") == 0) {
                p = lines[nl-1]; sp = 0
                for (k = length(p); k >= 1; k--) if (substr(p,k,1) == " ") { sp = k; break }
                if (sp > 0) {
                    merged = substr(p, sp+1) " " lines[nl]
                    if (length(merged) <= w) { lines[nl-1] = substr(p,1,sp-1); lines[nl] = merged }
                }
            }
            for (i = 1; i <= nl; i++) print ind lines[i]
            for (k in lines) delete lines[k]
        }'
}

_report_band() {
    local _label="${1:-}" _n="${2:-}"
    if [ -n "$_n" ]; then
        printf '  %s \302\267 %s\n' "$_label" "$_n"
    else
        printf '  %s\n' "$_label"
    fi
}

_render_entry() {
    local _rec="${1:-}" _title _prose _items _it
    _title="${_rec%%$'\037'*}"; _rec="${_rec#*$'\037'}"
    _prose="${_rec%%$'\037'*}"; _items="${_rec#*$'\037'}"
    printf '      \342\200\242 %s\n' "$_title"
    [ -n "$_prose" ] && printf '%s\n' "$_prose" | _summary_wrap_text '        '
    if [ -n "$_items" ]; then
        local _cap="${DOWNPOUR_REPORT_MAX_ITEMS:-100}" _n=0 _tot
        case "$_cap" in ''|*[!0-9]*) _cap=100 ;; esac
        _tot="$(printf '%s\n' "$_items" | LC_ALL=C tr '\035' '\012' | LC_ALL=C grep -c . )"
        printf '%s\n' "$_items" | LC_ALL=C tr '\035' '\012' | while IFS= read -r _it; do
            [ -n "$_it" ] || continue
            _n=$((_n + 1))
            if [ "$_cap" -gt 0 ] && [ "$_n" -gt "$_cap" ]; then
                printf '          \342\200\246 and %d more (set DOWNPOUR_REPORT_MAX_ITEMS=0 for the full list)\n' \
                    "$(( _tot - _cap ))"
                break
            fi
            printf '          %s\n' "$_it"
        done
    fi
}

_report_frame() {
    local _sub="${1:-}" _rule _rwid _i=0
    _rwid="${_REPORT_WIDTH:-120}"
    _rule="$(while [ "$_i" -lt "$_rwid" ]; do printf '\342\225\220'; _i=$((_i + 1)); done)"
    printf '%s\n' "$_rule"
    printf '  downpour   report\n'
    printf '  %s  \302\267  %s\n' "$(date '+%Y-%m-%d %H:%M' 2>/dev/null)" "$_sub"
    printf '%s\n' "$_rule"
    printf '\n'
}

_lc() { printf '%s' "${1:-}" | LC_ALL=C tr '[:upper:]' '[:lower:]'; }

_report_sort_names() {
    _SORTED_NAMES=()
    local _l
    while IFS= read -r _l; do
        [ -n "$_l" ] && _SORTED_NAMES+=( "$_l" )
    done
}

_report_collect() {
    _store="$(_report_store 2>/dev/null || printf '')"
    _att=() _rev=() _warn=() _exp=() _des=() _emp=() _exc=() _sch=()
    _seq=0
    if [ -n "$_store" ] && [ -f "$_store" ]; then
        while IFS=$'\037' read -r _sev _subj _title _prose _items; do
            case "$_sev" in
                incomplete|blocked|skipped|error)
                    _seq=$((_seq + 1))
                    case "$_sev" in blocked) _rk=0 ;; incomplete) _rk=1 ;; skipped) _rk=2 ;; *) _rk=3 ;; esac
                    _att+=( "$(_lc "$_subj")"$'\037'"$_rk"$'\037'"$(printf '%06d' "$_seq")"$'\037'"$_subj"$'\037'"$_title"$'\037'"$_prose"$'\037'"$_items" ) ;;
                review)
                    _seq=$((_seq + 1))
                    _rev+=( "$(_lc "$_subj")"$'\037'"0"$'\037'"$(printf '%06d' "$_seq")"$'\037'"$_subj"$'\037'"$_title"$'\037'"$_prose"$'\037'"$_items" ) ;;
                warning)    case "$_title" in
                                "$_subj "*) _title="${_title#"$_subj" }" ;;
                            esac
                            _warn+=( "$_subj"$'\037'"$_title" ) ;;
                exported)   _exp+=( "$_subj" ) ;;
                deselected) _des+=( "$_subj" ) ;;
                excluded)   _exc+=( "$_subj"$'\037'"$_title" ) ;;
                schema)     _sch+=( "$_subj"$'\037'"$_title"$'\037'"$_items" ) ;;
                empty)      _emp+=( "$_subj" ) ;;
            esac
        done < "$_store"
    fi
    _att_n=${#_att[@]} _rev_n=${#_rev[@]} _warn_n=${#_warn[@]}
    _exp_n=${#_exp[@]} _des_n=${#_des[@]} _emp_n=${#_emp[@]}
    _exc_n=${#_exc[@]}
}

_emit_report_html() {
    local -a _att=() _rev=() _warn=() _exp=() _des=() _emp=() _exc=() _sch=()
    local _att_n _rev_n _warn_n _exp_n _des_n _emp_n _exc_n _store _seq _rk
    local _sev _subj _title _prose _items
    _report_collect
    local _e _h1 _h2 _h3
    if [ "$_att_n" -eq 0 ]; then
        printf '<div class="verdict ok"><span class="dot"></span>COMPLETE — everything you selected exported in full.</div>\n'
    else
        html_escape "$_att_n" _h1
        printf '<div class="verdict bad"><span class="dot"></span>INCOMPLETE — %s %s your attention.</div>\n' \
            "$_h1" "$(_pluralize "$_att_n" "item needs" "items need")"
    fi
    _report_html_group() {   # <css-class> <label> <count> <entries...>
        local _cls="$1" _label="$2" _count="$3"; shift 3
        [ "$_count" -gt 0 ] || return 0
        local _cur="" _sk _sub _rest _title _prose _items _it _icap _in
        html_escape "$_label" _h1
        printf '<section class="band %s"><h2>%s</h2>\n' "$_cls" "$_h1"
        while IFS= read -r _e; do
            [ -n "$_e" ] || continue
            _sk="${_e#*$'\037'}"; _sk="${_sk#*$'\037'}"
            _rest="${_sk#*$'\037'}"
            _sub="${_rest%%$'\037'*}"
            if [ "$_sub" != "$_cur" ]; then
                [ -n "$_cur" ] && printf '</div>\n'
                html_escape "$_sub" _h1
                printf '<div class="subj"><h3>%s</h3>\n' "$_h1"
                _cur="$_sub"
            fi
            _sk="${_rest#*$'\037'}"
            _title="${_sk%%$'\037'*}"; _sk="${_sk#*$'\037'}"
            _prose="${_sk%%$'\037'*}"; _items="${_sk#*$'\037'}"
            html_escape "$_title" _h1
            printf '<div class="entry"><p class="t">%s</p>\n' "$_h1"
            if [ -n "$_prose" ]; then
                html_escape "$_prose" _h2
                printf '<p class="p">%s</p>\n' "$_h2"
            fi
            if [ -n "$_items" ]; then
                _icap="${DOWNPOUR_REPORT_MAX_ITEMS:-100}"; _in=0
                case "$_icap" in ''|*[!0-9]*) _icap=100 ;; esac
                printf '<ul class="items">\n'
                while IFS= read -r _it; do
                    [ -n "$_it" ] || continue
                    _in=$((_in + 1))
                    [ "$_icap" -gt 0 ] && [ "$_in" -gt "$_icap" ] && continue
                    html_escape "$_it" _h3
                    printf '<li>%s</li>\n' "$_h3"
                done <<EOF_RH_ITEMS
$(printf '%s' "$_items" | tr $'\035' '\n')
EOF_RH_ITEMS
                if [ "$_icap" -gt 0 ] && [ "$_in" -gt "$_icap" ]; then
                    printf '<li class="more">\342\200\246 and %d more (set DOWNPOUR_REPORT_MAX_ITEMS=0 for the full list)</li>\n' \
                        "$(( _in - _icap ))"
                fi
                printf '</ul>\n'
            fi
            printf '</div>\n'
        done < <(printf '%s\n' "$@" | LC_ALL=C sort -t"$(printf '\037')" -k1,1 -k2,2n -k3,3n)
        [ -n "$_cur" ] && printf '</div>\n'
        printf '</section>\n'
    }
    printf '<section class="band cats"><h2>CATEGORIES <span class="count">'
    html_escape "$_exp_n" _h1; printf '%s exported' "$_h1"
    [ "$_emp_n" -gt 0 ] && { html_escape "$_emp_n" _h1; printf ' &middot; %s empty' "$_h1"; }
    [ "$_des_n" -gt 0 ] && { html_escape "$_des_n" _h1; printf ' &middot; %s skipped' "$_h1"; }
    printf '</span></h2>\n<div class="chips">\n'
    local _c
    _report_sort_names < <(printf '%s\n' "${_exp[@]+"${_exp[@]}"}" | LC_ALL=C sort -f)
    for _c in "${_SORTED_NAMES[@]+"${_SORTED_NAMES[@]}"}"; do
        html_escape "$_c" _h1; printf '<span class="chip ok">%s</span>\n' "$_h1"
    done
    _report_sort_names < <(printf '%s\n' "${_emp[@]+"${_emp[@]}"}" | LC_ALL=C sort -f)
    for _c in "${_SORTED_NAMES[@]+"${_SORTED_NAMES[@]}"}"; do
        html_escape "$_c" _h1; printf '<span class="chip empty">%s <em>empty</em></span>\n' "$_h1"
    done
    _report_sort_names < <(printf '%s\n' "${_des[@]+"${_des[@]}"}" | LC_ALL=C sort -f)
    for _c in "${_SORTED_NAMES[@]+"${_SORTED_NAMES[@]}"}"; do
        html_escape "$_c" _h1; printf '<span class="chip off">%s <em>not selected</em></span>\n' "$_h1"
    done
    if [ $(( _exp_n + _emp_n + _des_n )) -eq 0 ]; then
        printf '<span class="chip off">(none)</span>\n'
    fi
    printf '</div></section>\n'
    _report_html_group "attention" "NEEDS ATTENTION" "$_att_n" "${_att[@]+"${_att[@]}"}"
    _report_html_group "review"    "REVIEW"          "$_rev_n" "${_rev[@]+"${_rev[@]}"}"
    if [ "$_exc_n" -gt 0 ]; then
        printf '<section class="band excluded"><h2>NOT CAPTURED <span class="count">by design</span></h2>\n'
        printf '<table class="rows">\n'
        local _xs _xt _cur="" _acc=""
        for _e in "${_exc[@]}"; do
            _xs="${_e%%$'\037'*}"; _xt="${_e#*$'\037'}"
            if [ "$_xs" = "$_cur" ]; then _acc="$_acc &middot; $(html_escape "$_xt")"
            else
                if [ -n "$_cur" ]; then html_escape "$_cur" _h1; printf '<tr><th>%s</th><td>%s</td></tr>\n' "$_h1" "$_acc"; fi
                _cur="$_xs"; _acc="$(html_escape "$_xt")"
            fi
        done
        if [ -n "$_cur" ]; then html_escape "$_cur" _h1; printf '<tr><th>%s</th><td>%s</td></tr>\n' "$_h1" "$_acc"; fi
        printf '</table></section>\n'
    fi
    if [ "${#_sch[@]}" -gt 0 ]; then
        local _ss _sc _si _stot=0 _scats=0
        for _e in "${_sch[@]}"; do
            _sc="${_e#*$'\037'}"; _sc="${_sc%%$'\037'*}"
            case "$_sc" in ''|*[!0-9]*) _sc=0 ;; esac
            _stot=$((_stot + _sc)); _scats=$((_scats + 1))
        done
        html_escape "$_stot" _h1; html_escape "$_scats" _h2
        printf '<section class="band schema"><h2>SCHEMA <span class="count">%s optional %s absent across %s %s</span></h2>\n' \
            "$_h1" "$(_pluralize "$_stot" column)" "$_h2" "$(_pluralize "$_scats" category categories)"
        printf '<p class="p">Expected when Apple changes a schema between macOS releases. The fields these columns carry are blank or omitted; no content was lost.</p>\n'
        printf '<table class="rows">\n'
        for _e in "${_sch[@]}"; do
            _ss="${_e%%$'\037'*}"
            _sc="${_e#*$'\037'}"; _sc="${_sc%%$'\037'*}"
            _si="${_e##*$'\037'}"
            html_escape "$_ss" _h1; html_escape "$_sc" _h2
            printf '<tr><th>%s</th><td class="n">%s</td><td class="cols">' "$_h1" "$_h2"
            local _first=1 _it
            while IFS= read -r _it; do
                [ -n "$_it" ] || continue
                html_escape "$_it" _h3
                [ "$_first" = 1 ] && _first=0 || printf ', '
                printf '<code>%s</code>' "$_h3"
            done <<EOF_RH_SCH
$(printf '%s' "$_si" | tr $'\035' '\n')
EOF_RH_SCH
            printf '</td></tr>\n'
        done
        printf '</table></section>\n'
    fi
    if [ "$_warn_n" -gt 0 ]; then
        printf '<section class="band warnings"><h2>WARNINGS</h2>\n<ul class="items">\n'
        local _ws _wt
        for _e in "${_warn[@]+"${_warn[@]}"}"; do
            _ws="${_e%%$'\037'*}"; _wt="${_e#*$'\037'}"
            html_escape "$_ws" _h1; html_escape "$_wt" _h2
            printf '<li><b>%s</b> — %s</li>\n' "$_h1" "$_h2"
        done
        printf '</ul></section>\n'
    fi
    return 0
}

_emit_report_body() {
    local -a _att=() _rev=() _warn=() _exp=() _des=() _emp=() _exc=() _sch=()
    local _att_n _rev_n _warn_n _exp_n _des_n _emp_n _exc_n _store _seq _rk
    local _sev _subj _title _prose _items
    _report_collect
    _RUN_ATTENTION_N="$_att_n"
    if [ "$_att_n" -eq 0 ]; then
        printf '  Result:  COMPLETE \342\200\224 everything you selected exported in full.\n'
    elif [ "$_att_n" -eq 1 ]; then
        printf '  Result:  INCOMPLETE \342\200\224 1 item needs your attention.\n'
    else
        printf '  Result:  INCOMPLETE \342\200\224 %d items need your attention.\n' "$_att_n"
    fi
    local _e _first _s
    _report_render_group() {   # $1 = band label, $2 = count, $3.. = entries
        local _label="$1" _count="$2"; shift 2
        [ "$_count" -gt 0 ] || return 0
        printf '\n'; _report_band "$_label"; printf '\n'
        local _cur="" _sk _sub _rest _gfirst=1
        while IFS= read -r _e; do
            [ -n "$_e" ] || continue
            _sk="${_e#*$'\037'}"; _sk="${_sk#*$'\037'}"        # drop lc-subject + rank
            _rest="${_sk#*$'\037'}"                            # drop sequence
            _sub="${_rest%%$'\037'*}"
            if [ "$_sub" != "$_cur" ]; then
                [ "$_gfirst" = 1 ] && _gfirst=0 || printf '\n'
                printf '    %s\n' "$_sub"
                _cur="$_sub"
            fi
            _render_entry "${_rest#*$'\037'}"
        done < <(printf '%s\n' "$@" | LC_ALL=C sort -t"$(printf '\037')" -k1,1 -k2,2n -k3,3n)
    }
    local _cat_count
    _cat_count="$(printf '%s exported' "$_exp_n")"
    [ "$_emp_n" -gt 0 ] && _cat_count="$(printf '%s \302\267 %s empty' "$_cat_count" "$_emp_n")"
    [ "$_des_n" -gt 0 ] && _cat_count="$(printf '%s \302\267 %s skipped' "$_cat_count" "$_des_n")"
    printf '\n'; _report_band "CATEGORIES" "$_cat_count"; printf '\n'
    _report_sort_names < <(printf '%s\n' "${_exp[@]+"${_exp[@]}"}" | LC_ALL=C sort -f)
    _exp=( "${_SORTED_NAMES[@]+"${_SORTED_NAMES[@]}"}" )
    _report_sort_names < <(printf '%s\n' "${_emp[@]+"${_emp[@]}"}" | LC_ALL=C sort -f)
    _emp=( "${_SORTED_NAMES[@]+"${_SORTED_NAMES[@]}"}" )
    _report_sort_names < <(printf '%s\n' "${_des[@]+"${_des[@]}"}" | LC_ALL=C sort -f)
    _des=( "${_SORTED_NAMES[@]+"${_SORTED_NAMES[@]}"}" )
    _RUN_CAT_EXPORTED="$(printf '%s\n' "${_exp[@]+"${_exp[@]}"}")"
    _RUN_CAT_EMPTY="$(printf '%s\n' "${_emp[@]+"${_emp[@]}"}")"
    _RUN_CAT_DESELECTED="$(printf '%s\n' "${_des[@]+"${_des[@]}"}")"
    if [ "$_exp_n" -eq 0 ] && [ "$_des_n" -eq 0 ] && [ "$_emp_n" -eq 0 ]; then
        printf '    (none)\n'
    else
        for _s in "${_exp[@]+"${_exp[@]}"}"; do
            printf '    \342\234\223 %s\n' "$_s"
        done
        if [ "$_emp_n" -gt 0 ] || [ "$_des_n" -gt 0 ]; then
            local _pad=0
            for _s in "${_emp[@]+"${_emp[@]}"}" "${_des[@]+"${_des[@]}"}"; do
                [ "${#_s}" -gt "$_pad" ] && _pad="${#_s}"
            done
            for _s in "${_emp[@]+"${_emp[@]}"}"; do
                printf '    \342\234\227 %-*s  (nothing to export)\n' "$_pad" "$_s"
            done
            for _s in "${_des[@]+"${_des[@]}"}"; do
                printf '    \342\234\227 %-*s  (not selected)\n' "$_pad" "$_s"
            done
        fi
    fi
    _report_render_group "NEEDS ATTENTION" "$_att_n" "${_att[@]+"${_att[@]}"}"
    _report_render_group "REVIEW" "$_rev_n" "${_rev[@]+"${_rev[@]}"}"
    if [ "$_exc_n" -gt 0 ]; then
        local _xs _xt _cur="" _acc="" _xpad=0 _xn=0 _mdot
        _mdot="$(printf '\302\267')"
        for _e in "${_exc[@]}"; do
            _xs="${_e%%$'\037'*}"
            [ "${#_xs}" -gt "$_xpad" ] && _xpad="${#_xs}"
            _xn=$((_xn + 1))
        done
        printf '\n'; _report_band "NOT CAPTURED" "by design"; printf '\n'
        for _e in "${_exc[@]}"; do
            _xs="${_e%%$'\037'*}"; _xt="${_e#*$'\037'}"
            if [ "$_xs" = "$_cur" ]; then
                _acc="$_acc $_mdot $_xt"
            else
                [ -n "$_cur" ] && printf '    %-*s  %s\n' "$_xpad" "$_cur" "$_acc"
                _cur="$_xs"; _acc="$_xt"
            fi
        done
        [ -n "$_cur" ] && printf '    %-*s  %s\n' "$_xpad" "$_cur" "$_acc"
    fi
    if [ "${#_sch[@]}" -gt 0 ]; then
        local _ss _sc _si _spad=0 _stot=0 _scats=0
        for _e in "${_sch[@]}"; do
            _ss="${_e%%$'\037'*}"
            [ "${#_ss}" -gt "$_spad" ] && _spad="${#_ss}"
            _sc="${_e#*$'\037'}"; _sc="${_sc%%$'\037'*}"
            case "$_sc" in ''|*[!0-9]*) _sc=0 ;; esac
            _stot=$((_stot + _sc)); _scats=$((_scats + 1))
        done
        printf '\n'
        _report_band "SCHEMA" "$_stot optional $(_pluralize "$_stot" column) absent across $_scats $(_pluralize "$_scats" category "categories")"
        printf '\n'
        printf '    Expected when Apple changes a schema between macOS releases. The fields\n'
        printf '    these columns carry are blank or omitted; no content was lost.\n\n'
        for _e in "${_sch[@]}"; do
            _ss="${_e%%$'\037'*}"
            _sc="${_e#*$'\037'}"; _sc="${_sc%%$'\037'*}"
            _si="${_e##*$'\037'}"
            local _slist="" _sitem _sn=0 _stbl="" _stbl_one=1 _scol _sshown=0 _sres
            local _sbudget=$(( ${_REPORT_WIDTH:-120} - _spad - 12 ))
            [ "$_sbudget" -lt 24 ] && _sbudget=24
            while IFS= read -r _sitem; do
                [ -n "$_sitem" ] || continue
                _sn=$((_sn + 1))
                case "$_sitem" in
                    *.*) if [ -z "$_stbl" ]; then _stbl="${_sitem%.*}"
                         elif [ "$_stbl" != "${_sitem%.*}" ]; then _stbl_one=0; fi ;;
                    *)   _stbl_one=0 ;;
                esac
            done <<EOF_SCHEMA_SCAN
$(printf '%s' "$_si" | tr $'\035' '\n')
EOF_SCHEMA_SCAN
            [ "$_stbl_one" = "1" ] && [ -n "$_stbl" ] && _sbudget=$(( _sbudget - ${#_stbl} - 2 ))
            [ "$_sbudget" -lt 20 ] && _sbudget=20
            while IFS= read -r _sitem; do
                [ -n "$_sitem" ] || continue
                if [ "$_stbl_one" = "1" ]; then _scol="${_sitem##*.}"; else _scol="$_sitem"; fi
                _sres=11; [ "$_sn" -eq $(( _sshown + 1 )) ] && _sres=2
                if [ -z "$_slist" ] || [ $(( ${#_slist} + ${#_scol} + _sres )) -le "$_sbudget" ]; then
                    _slist="${_slist:+$_slist, }$_scol"
                    _sshown=$((_sshown + 1))
                else
                    break
                fi
            done <<EOF_SCHEMA_ITEMS
$(printf '%s' "$_si" | tr $'\035' '\n')
EOF_SCHEMA_ITEMS
            [ "$_sn" -gt "$_sshown" ] && _slist="$_slist, +$((_sn - _sshown)) more"
            if [ "$_stbl_one" = "1" ] && [ -n "$_stbl" ]; then
                printf '    %-*s  %3s  %s: %s\n' "$_spad" "$_ss" "$_sc" "$_stbl" "$_slist"
            else
                printf '    %-*s  %3s  %s\n' "$_spad" "$_ss" "$_sc" "$_slist"
            fi
        done
    fi
    if [ "$_warn_n" -gt 0 ]; then
        printf '\n'; _report_band "WARNINGS"; printf '\n'
        local _ws _wt _wl _wfirst
        for _e in "${_warn[@]+"${_warn[@]}"}"; do
            _ws="${_e%%$'\037'*}"; _wt="${_e#*$'\037'}"
            _wfirst=1
            printf '%s \342\200\224 %s\n' "$_ws" "$_wt" | _summary_wrap_text '      ' | while IFS= read -r _wl; do
                if [ "$_wfirst" = 1 ]; then
                    printf '    \342\200\242 %s\n' "${_wl#      }"; _wfirst=0
                else
                    printf '%s\n' "$_wl"
                fi
            done
        done
    fi
}

finalize_leaf_report() {
    local _label="${1:-}" _cdir="${2:-}"
    [ -n "$_label" ] && [ -d "$_cdir" ] || return 0
    _report_store_init
    local _w
    for _w in "${_PRE_PREPARE_WARNS[@]+"${_PRE_PREPARE_WARNS[@]}"}"; do
        report_warning "$_label" "$_w"
    done
    local _e
    for _e in "${_PRE_PREPARE_ERRS[@]+"${_PRE_PREPARE_ERRS[@]}"}"; do
        report_incomplete "$_label" "$_e" ""
    done
    report_status exported "$_label"
    {
        printf '\357\273\277'
        _report_frame "$_label"
        _emit_report_body
    } > "$_cdir/_downpour_report.txt" 2>/dev/null || true
    if [ "${EXIT_NONZERO_ON_INCOMPLETE:-0}" = "1" ] && [ "${_RUN_ATTENTION_N:-0}" -gt 0 ]; then
        ERR_COUNT=$(( ${ERR_COUNT:-0} + 1 ))
    fi
}

_is_int64_safe() {
    local ts="${1:-}"
    case "$ts" in
        ''|*[!0-9]*) return 1 ;;
    esac
    [ "${#ts}" -le 18 ] && return 0
    [ "${#ts}" -ge 20 ] && return 1
    [ "$ts" \> "9223372036854775807" ] && return 1
    return 0
}

_cd_ts_to_unix() {
    local ts="$1"
    [ -z "$ts" ] && return 0
    case "$ts" in
        ''|*[!0-9.]*) return 0 ;;
        *.*.*)        return 0 ;;
    esac
    ts="${ts%%.*}"
    [ -z "$ts" ] && return 0
    case "${ts//0/}" in '') return 0 ;; esac
    _is_int64_safe "$ts" || return 0
    if [ "$((10#$ts))" -gt 4000000000 ]; then
        ts=$((10#$ts / 1000000000))
    fi
    printf '%s' "$((10#$ts + 978307200))"
}

_cd_ts_to_unix_signed() {
    local ts="$1" sign=1
    [ -z "$ts" ] && return 0
    case "$ts" in -*) sign=-1; ts="${ts#-}" ;; esac
    case "$ts" in
        ''|*[!0-9.]*) return 0 ;;
        *.*.*)        return 0 ;;
    esac
    ts="${ts%%.*}"
    [ -z "$ts" ] && return 0
    case "${ts//0/}" in '') return 0 ;; esac   # all-zero ⇒ absent (0-sentinel)
    _is_int64_safe "$ts" || return 0
    local cocoa=$((10#$ts))
    [ "$sign" -gt 0 ] && [ "$cocoa" -gt 4000000000 ] && cocoa=$((cocoa / 1000000000))
    [ "$sign" -lt 0 ] && cocoa=$((-cocoa))
    printf '%s' "$((cocoa + 978307200))"
}

_cd_ts_to_utc() {
    local u; u="$(_cd_ts_to_unix "$1")"; [ -z "$u" ] && return 0
    TZ=UTC date -r "$u" +%Y%m%dT%H%M%SZ 2>/dev/null
}

_format_touch_t() {
    local unix="$1" _out
    case "${unix:-0}" in
        0|*[!0-9]*) printf ''; return ;;
    esac
    [ "${#unix}" -ge 11 ] && { printf ''; return; }
    _out="$(LC_ALL=C date -r "$unix" '+%Y%m%d%H%M.%S' 2>/dev/null)"
    case "$_out" in
        [0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9].[0-9][0-9])
            printf '%s' "$_out" ;;
        *) printf '' ;;
    esac
}

_apply_touch_t() {
    [ -n "$1" ] && touch -c -t "$1" -- "$2" 2>/dev/null || true
}

print_banner() {
    [ -t 1 ] || return 0
    [ "${_BANNER_SHOWN:-0}" = "1" ] && return 0
    _BANNER_SHOWN=1
    printf '\n  %s%sdownpour.sh v1.0%s%s — iCloud data export for macOS\n\n' \
        "$_C_BRAND" "$_B" "$_N" "$_C_BRAND_RST"
    _LAST_BLANK=1
}

print_final_summary_box() {
    local _dir="$1" _oks="${2:-}" _total="${3:-}" _skips="${4:-}"
    local _rwid="${_WRAP_WIDTH:-120}" _rule _ri=0 _cols
    _cols="$(tput cols 2>/dev/null </dev/tty || printf '')"
    case "$_cols" in ''|*[!0-9]*) _cols="${COLUMNS:-0}" ;; esac
    case "$_cols" in ''|*[!0-9]*) _cols=0 ;; esac
    [ "$_cols" -ge 24 ] && [ "$(( _cols - 2 ))" -lt "$_rwid" ] && _rwid=$(( _cols - 2 ))
    [ "$_rwid" -lt 40 ] && _rwid=40
    _rule="$(while [ "$_ri" -lt "$_rwid" ]; do printf '\342\225\220'; _ri=$((_ri + 1)); done)"
    _blank
    printf '  %s%s%s\n' "$_C_BRAND" "$_rule" "$_C_BRAND_RST"
    if [ "${_RUN_ATTENTION_N:-0}" -eq 0 ]; then
        printf '  %s%s%s  %sExport complete%s \342\200\224 %s of %s %s exported%s\n' \
            "$_C_OK" "$_TAG_OK" "$_C_RST1" "$_B" "$_N" \
            "${_oks:-0}" "${_total:-0}" "$(_pluralize "${_total:-0}" category categories)" \
            "${_skips:+, $_skips}"
    else
        local _av="need"; [ "${_RUN_ATTENTION_N:-0}" -eq 1 ] && _av="needs"
        printf '  %s%s%s  %sExport INCOMPLETE%s \342\200\224 %s %s %s attention\n' \
            "$_C_WARN" "$_TAG_WARN" "$_C_RST2" "$_B" "$_N" \
            "$_RUN_ATTENTION_N" "$(_pluralize "$_RUN_ATTENTION_N" item)" "$_av"
    fi
    printf '  %s%s%s\n' "$_C_BRAND" "$_rule" "$_C_BRAND_RST"
    printf '    Folder:    %s\n' "$_dir"
    if [ "${_RUN_ATTENTION_N:-0}" -eq 0 ]; then
        printf '    Report:    _downpour_report.html \342\200\224 what you got, what you did not, and the files\n'
    else
        printf '    Report:    _downpour_report.html \342\200\224 read this first: what is missing and why\n'
    fi
    printf '    Run log:   _downpour_log.txt     \342\200\224 the full output of this run\n'
    printf '  %s%s%s\n' "$_C_BRAND" "$_rule" "$_C_BRAND_RST"
    _LAST_BLANK=0
}

_announce_step() {
    [ "${_INVOKED_BY_WRAPPER:-0}" = "1" ] && return 0
    print_banner
    log_step "$1"
    require_local_session
}

_announce_output_dir() {
    _report_store_init
    if [ "${_INVOKED_BY_WRAPPER:-0}" = "1" ]; then
        log_info "Output folder: $1/"
        _LEAF_CATEGORY_DIR="${_EXPORT_ROOT:+$_EXPORT_ROOT/}${1%%/*}"
    else
        local _od="${out_dir:-}"
        log_info "Output folder: ${_od%/}/$1"
        _LEAF_REPORT_CATEGORY="$1"
        _LEAF_REPORT_DIR="${_od%/}/$1"
        _LEAF_CATEGORY_DIR="${_od%/}/$1"
        [ -n "${_EXPORT_ROOT:-}" ] || _EXPORT_ROOT="${_od%/}"
        warn_if_fragile_filesystem "${_od%/}"
    fi
}

_fold_75_octets() {
    LC_ALL=C awk '
    function utf8_safe_cut(s, max,   p, c) {
        p = max
        while (p > 0) {
            c = _ord[substr(s, p + 1, 1)]
            if (c < 128 || c >= 192) break
            p--
        }
        return (p > 0) ? p : max
    }
    BEGIN { for (i = 0; i < 256; i++) _ord[sprintf("%c", i)] = i }
    {
        line = $0
        if (length(line) <= 75) { printf "%s\r\n", line; next }
        cut = utf8_safe_cut(line, 75)
        printf "%s\r\n", substr(line, 1, cut)
        line = substr(line, cut + 1)
        while (length(line) > 0) {
            if (length(line) <= 74) { printf " %s\r\n", line; break }
            cut = utf8_safe_cut(line, 74)
            printf " %s\r\n", substr(line, 1, cut)
            line = substr(line, cut + 1)
        }
    }
    '
}

html_escape() {
    local s="$1"
    s="${s//&/&amp;}"; s="${s//</&lt;}"; s="${s//>/&gt;}"
    s="${s//\"/&quot;}"; s="${s//\'/&#39;}"
    if [ -n "${2:-}" ]; then printf -v "$2" '%s' "$s"; return 0; fi
    printf '%s' "$s"
}

ics_escape() {
    local s="$1"
    s="${s//\\/\\\\}"; s="${s//,/\\,}"; s="${s//;/\\;}"
    s="${s//$'\r\n'/\\n}"; s="${s//$'\r'/\\n}"; s="${s//$'\n'/\\n}"
    printf '%s' "$s"
}

_rrule_by_fragment() {
    local _v; _v="$(printf '%s' "$2" | LC_ALL=C tr -cd "$3")"
    case "$_v" in *$4*) printf ';%s=%s' "$1" "$_v" ;; esac
}

_sql_tsv_safe() {
    local sql_clean='replace(replace(replace(replace(replace(COALESCE(VAL,'\'''\''), x'\''09'\'', '\'' '\''), x'\''0D'\'', '\'''\''), x'\''0A'\'', '\''\n'\''), x'\''1F'\'', '\'' '\''), x'\''00'\'', '\'''\'')'
    printf '%s' "${sql_clean//VAL/$1}"
}

_sql_tsv_bsafe() {
    local sql_clean='replace(replace(replace(replace(replace(replace(replace(COALESCE(VAL,'\'''\''), x'\''5C'\'', '\''\\'\''), x'\''02'\'', '\'''\''), x'\''09'\'', '\'' '\''), x'\''0D'\'', '\'''\''), x'\''0A'\'', '\''\n'\''), x'\''1F'\'', '\'' '\''), x'\''00'\'', '\'''\'')'
    printf '%s' "${sql_clean//VAL/$1}"
}

_unescape_bsafe() {
    local s="$1"
    s="${s//\\\\/$'\x02'}"   # escaped backslash -> placeholder byte
    s="${s//\\n/$'\n'}"      # newline sentinel  -> real LF
    s="${s//$'\x02'/\\}"    # placeholder       -> literal backslash
    printf '%s' "$s"
}

tsv_escape() {
    local s="$1"
    s="${s//$'\t'/ }"
    s="${s//$'\r'/ }"
    s="${s//$'\n'/ }"
    s="${s//$'\x1f'/ }"
    if [ -n "${2:-}" ]; then printf -v "$2" '%s' "$s"; return 0; fi
    printf '%s' "$s"
}

validate_count_parity() {
    local discovered="$1" accounted="$2" label="$3" _cat_dir="${4:-}"
    case "$discovered" in
        ''|*[!0-9]*)
            log_warn "$label: completeness could not be verified — the discovery count query failed (no count returned)."
            [ -n "$_cat_dir" ] && note_incomplete "$_cat_dir" \
                "$label — completeness could not be verified" \
                "the discovery COUNT(*) query failed, so the exported rows could not be cross-checked against the source; the export may or may not be complete — compare against the source app and re-run"
            return 1
            ;;
    esac
    case "$accounted"  in ''|*[!0-9]*) return 0 ;; esac
    [ "$discovered" -eq "$accounted" ] && return 0
    local _diff _direction
    if [ "$discovered" -gt "$accounted" ]; then
        _diff=$((discovered - accounted))
        _direction="under-counted"
    else
        _diff=$((accounted - discovered))
        _direction="over-counted"
    fi
    log_warn "$label count drift: discovered $discovered, accounted for $accounted (${_direction} by $_diff)"
    [ -n "$_cat_dir" ] && note_incomplete "$_cat_dir" \
        "$label — discovery and emit counts disagree" \
        "discovery counted $discovered but $accounted were accounted for (${_direction} by $_diff); rows were dropped or miscounted between discovery and emit, so this category's export may be missing entries — compare against the source app"
    return 1
}

_REQUIRED_HELPER_TOOLS=(
    "pgrep:built-in macOS tool at /usr/bin/pgrep (pre-probe app-launch tracking / quit_app_iff_we_launched_it)"
    "pkill:built-in macOS tool at /usr/bin/pkill (_heartbeat_stop reaps the heartbeat subshell's child sleep)"
    "osascript:built-in macOS tool at /usr/bin/osascript (TCC Automation probes)"
    "defaults:built-in macOS tool at /usr/bin/defaults (check_full_disk_access TCC.db path resolver)"
    "kill:built-in macOS tool (cleanup_handler subprocess reaping)"
    "sleep:built-in macOS tool (wait_for_grant polling)"
    "chmod:built-in macOS tool (cleanup_handler runs \`chmod -R u+w\` before rm)"
    "rm:built-in macOS tool (cleanup_handler scratch + output reaping)"
    "cp:built-in macOS tool (snapshot_db DB + WAL/SHM file copies)"
    "mv:built-in macOS tool (atomic tmp→final rename across the helpers + every leaf)"
    "mkdir:built-in macOS tool (note_incomplete creates the category dir on-demand)"
    "find:built-in macOS tool (sweep_junk_files / copy walks)"
    "stat:built-in macOS tool (is_macos_alias size pre-filter)"
    "xattr:built-in macOS tool (is_macos_alias Carbon FinderInfo fallback)"
    "md5:built-in macOS tool at /sbin/md5 (snapshot_db cache-key hashing)"
    "awk:built-in macOS tool at /usr/bin/awk (_sanitize_name UTF-8 boundary stripping, validators, table-driven decoders, per-row TSV parsing)"
    "hostname:built-in macOS tool (the downpour-photos-report \`# host:\` header line)"
)

check_dependencies() {
    local sys
    sys="$(uname -s 2>/dev/null)"
    [ "$sys" = "Darwin" ] || die "This script targets macOS — got '$sys'."
    date -r 0 +%Y >/dev/null 2>&1 \
        || die "'date' is not BSD-style. Ensure /bin and /usr/bin precede any GNU coreutils on PATH."
    stat -f %z /etc/hosts >/dev/null 2>&1 \
        || die "'stat' is not BSD-style. Ensure /usr/bin precedes any GNU coreutils on PATH."
    local _tmp="${TMPDIR:-/tmp}"
    [ -d "$_tmp" ] || die "TMPDIR is not a directory: $_tmp"
    [ -w "$_tmp" ] || die "TMPDIR is not writable: $_tmp (mktemp -d will fail)"
    local missing=0 entry cmd hint
    for entry in "${_REQUIRED_HELPER_TOOLS[@]+"${_REQUIRED_HELPER_TOOLS[@]}"}" "${REQUIRED_TOOLS[@]+"${REQUIRED_TOOLS[@]}"}"; do
        cmd="${entry%%:*}"; hint="${entry#*:}"
        if ! command -v "$cmd" >/dev/null 2>&1; then
            log_err "Missing required tool: $cmd ($hint)"
            missing=$((missing + 1))
        fi
    done
    [ "$missing" -gt 0 ] && { log_err "Cannot proceed without dependencies."; exit 1; }
}

wait_for_grant() {
    local probe="$1" label="$2" timeout="${3:-20}" interval="${4:-${TCC_POLL_INTERVAL_SEC:-2}}"
    case "$timeout"  in
        ''|*[!0-9]*) timeout=20 ;;
        0|[1-9]*)    ;;
        *)           timeout=$((10#$timeout)) ;;
    esac
    case "$interval" in
        ''|*[!0-9]*) interval=2 ;;
        0|[1-9]*)    ;;
        *)           interval=$((10#$interval)) ;;
    esac
    [ "$interval" -lt 1 ] && interval=1
    local _start=$SECONDS _deadline=$((SECONDS + timeout))
    local _next_progress=$((SECONDS + 15))
    while true; do
        if "$probe"; then
            return 0
        fi
        [ "$SECONDS" -ge "$_deadline" ] && break
        sleep "$interval"
        if [ "$SECONDS" -ge "$_next_progress" ] && [ "$SECONDS" -lt "$_deadline" ]; then
            log_info "... still waiting for $label grant ($((SECONDS - _start)) s / ${timeout} s)"
            _next_progress=$((SECONDS + 15))
        fi
    done
    return 1
}

warn_if_app_running() {
    local app="$1"
    pgrep -x "$app" >/dev/null 2>&1 || return 0
    log_warn "$app is running — recently-edited data may not be in the snapshot"
}

require_local_session() {
    [ "${_DOWNPOUR_TEST_HEADLESS:-}" = "1" ] && return 0
    if [ -n "${SSH_CLIENT:-}${SSH_TTY:-}${SSH_CONNECTION:-}" ]; then
        die "downpour.sh must be run from a local console session, not over SSH — macOS permission prompts and the menu need a local display on the Mac."
    fi
    return 0
}

sweep_junk_files() {
    [ -n "${1:-}" ] && [ -d "$1" ] || return 0
    find "$1" -type f \( \
        -name '.DS_Store' -o \
        -name '._*' -o \
        -name '.localized' -o \
        -name '.VolumeIcon.icns' -o \
        -name '.apdisk' -o \
        -name '.com.apple.timemachine' -o \
        -name '.com.apple.timemachine.*' \
        \) -delete 2>/dev/null || true
    find "$1" -type d \( \
        -name '.AppleDouble' -o \
        -name '.Spotlight-V100' -o \
        -name '.fseventsd' -o \
        -name '.Trashes' -o \
        -name '.TemporaryItems' -o \
        -name '.DocumentRevisions-V100' -o \
        -name '__MACOSX' \
        \) -empty -delete 2>/dev/null || true
}

_tcc_probe() {
    local _env="$1" _default="$2" _ascript="$3"
    local _probe_timeout
    _probe_timeout="${!_env-$_default}"
    [ -z "$_probe_timeout" ] && _probe_timeout="$_default"
    _probe_timeout="$(_clamp_env_int _probe_timeout "$_default" 600)"
    local r
    r="$(osascript -e "with timeout of ${_probe_timeout} seconds" \
                   -e "$_ascript" \
                   -e 'end timeout' 2>&1)" || return 1
    case "$r" in
        ''|*error*|*"not allowed"*|*"Not authorized"*|*"assistive access"*|*"-25211"*|*"-1719"*|*"timed out"*) return 1 ;;
    esac
    case "$r" in *[!0-9]*) return 1 ;; esac
    printf '%s' "$r"
    return 0
}

check_photos_automation() {
    _tcc_probe PHOTOS_PROBE_TIMEOUT_SEC 15 \
        'tell application "Photos" to count of albums' >/dev/null
}

check_music_automation() {
    local r
    r="$(_tcc_probe MUSIC_PROBE_TIMEOUT_SEC 30 \
            'tell application "Music" to count of playlists')" || return 1
    _MUSIC_PLAYLIST_COUNT="$(_to_int "$r")"
    return 0
}

check_system_events_automation() {
    local _t r
    _t="$(_clamp_env_int SYSEVENTS_PROBE_TIMEOUT_SEC 10 600)"
    r="$(osascript -e "with timeout of ${_t} seconds" \
                   -e 'tell application "System Events" to get name' \
                   -e 'end timeout' 2>&1)" || return 1
    case "$r" in
        ''|*error*|*"not allowed"*|*"Not authorized"*|*"assistive access"*|*"-1743"*|*"-600"*|*"timed out"*) return 1 ;;
    esac
    return 0
}

check_accessibility() {
    _tcc_probe ACCESSIBILITY_PROBE_TIMEOUT_SEC 10 \
        'tell application "System Events" to tell process "Finder" to count of menu bar items of menu bar 1' >/dev/null
}

_AX_VALIDATED_MACOS=26

_ax_os_check() {
    local _leaf="${1:-This leaf}" _pv _maj
    _pv="$(sw_vers -productVersion 2>/dev/null)"
    _maj="${_pv%%.*}"
    case "$_maj" in ''|*[!0-9]*) return 0 ;; esac
    _maj=$((10#$_maj))
    if [ "$_maj" -ne "$_AX_VALIDATED_MACOS" ]; then
        log_warn "$_leaf drives Accessibility GUI automation verified against macOS $_AX_VALIDATED_MACOS; this Mac reports ${_pv:-unknown}. If the export hangs or the button is not pressed, Apple may have changed the Accessibility tree — re-run with DOWNPOUR_PROBE_UI=1 to surface the GUI driver's button-resolution log."
    fi
    return 0
}

_as_debug() { [ -n "${DEBUG_APPLESCRIPT:-}${DOWNPOUR_PROBE_UI:-}" ] && log_info "AppleScript: $1"; }

_heartbeat_start() {
    local _interval="$1" _prefix="$2"
    case "$_interval" in
        ''|*[!0-9]*) _interval=30 ;;
        0)           _interval=30 ;;
        [1-9]*)      ;;
        *)           _interval=$((10#$_interval)) ;;
    esac
    [ "$_interval" -lt 1 ] && _interval=30
    local _hb_start_epoch
    _hb_start_epoch="$(date +%s 2>/dev/null)"
    case "${_hb_start_epoch:-}" in ''|*[!0-9]*) _hb_start_epoch=0 ;; esac
    local _parent_pid=$$
    ( _hb_sleep=""
      trap 'kill -TERM "${_hb_sleep:-}" 2>/dev/null; exit 0' TERM
      while :; do
          sleep "$_interval" & _hb_sleep=$!
          wait "$_hb_sleep" 2>/dev/null
          kill -0 "$_parent_pid" 2>/dev/null || exit 0
          _now="$(date +%s 2>/dev/null)"
          case "${_now:-}" in ''|*[!0-9]*) _now="$_hb_start_epoch" ;; esac
          _el=$((_now - _hb_start_epoch))
          log_info "$_prefix (${_el}s elapsed)"
      done ) &
    _HB_PID=$!
    CHILD_PIDS+=( "$_HB_PID" )
}

_heartbeat_stop() {
    [ -n "${_HB_PID:-}" ] || return 0
    pkill -KILL -P "$_HB_PID" 2>/dev/null || true
    kill -KILL "$_HB_PID" 2>/dev/null || true
    wait "$_HB_PID" 2>/dev/null
    local _i _new=()
    for _i in "${CHILD_PIDS[@]+"${CHILD_PIDS[@]}"}"; do
        [ "$_i" = "$_HB_PID" ] && continue
        _new+=( "$_i" )
    done
    CHILD_PIDS=( "${_new[@]+"${_new[@]}"}" )
    _HB_PID=""
}

timemachine_suspend() {
    command -v tmutil >/dev/null 2>&1 || return 0
    local _tm_auto
    _tm_auto="$(defaults read /Library/Preferences/com.apple.TimeMachine AutoBackup 2>/dev/null)" \
        || _tm_auto=""
    [ "$_tm_auto" = "1" ] || return 0
    _TM_SUSPENDED=1
    if tmutil disable >/dev/null 2>&1; then
        log_info "Time Machine suspended for the duration of this run"
    else
        _TM_SUSPENDED=0
        log_warn "Could not suspend Time Machine (likely needs admin); continuing."
    fi
}

timemachine_resume() {
    [ "$_TM_SUSPENDED" = "1" ] || return 0
    if tmutil enable >/dev/null 2>&1; then
        _TM_SUSPENDED=0
    else
        log_warn "Could not re-enable Time Machine — please re-enable it manually."
    fi
}

_sips_to_jpeg() {
    local _src="$1" _dst="$2" _opts="${3-best}"
    if [ -n "$_opts" ]; then
        sips -s format jpeg -s formatOptions "$_opts" "$_src" --out "$_dst" >/dev/null 2>&1
    else
        sips -s format jpeg "$_src" --out "$_dst" >/dev/null 2>&1
    fi
}

_maybe_sips_heic_sibling() {
    local _src="$1" _jpg="${2:-}"
    case "$_src" in
        *.[Hh][Ee][Ii][CcFf]) ;;
        *) return 0 ;;
    esac
    [ -n "$_jpg" ] || _jpg="${_src%.*}.jpg"
    if [ ! -e "$_jpg" ] && [ ! -L "$_jpg" ]; then
        _sips_to_jpeg "$_src" "$_jpg" best || true
    fi
    return 0
}

_atomic_commit_tmp() {
    local _rc="$1" _tmp="$2" _final="$3" _label="${4:-$3}"
    case "$_rc" in ''|*[!0-9]*) _rc=1 ;; esac
    if [ "$_rc" -eq 0 ] && mv -f -- "$_tmp" "$_final" 2>/dev/null; then
        return 0
    fi
    rm -f -- "$_tmp" 2>/dev/null
    log_warn "Failed to write $_label atomically."
    return 1
}

_tcc_recheck_or_die() {
    local _name="$1" _probe="$2" _suffix="$3" _extra="${4:-Then re-run.}"
    if "$_probe" >/dev/null 2>&1; then
        log_ok "$_name: granted (after wrapper pre-flight)"
        return 0
    fi
    log_err "$_name not granted (wrapper pre-flight already polled and timed out)."
    log_info "  Grant it in: System Settings > Privacy & Security > $_suffix"
    log_info "  $_extra"
    exit 1
}

_utc_now_iso8601() { TZ=UTC date +%Y-%m-%dT%H:%M:%SZ 2>/dev/null; }

leaf_cleanup_hook() {
    timemachine_resume
}

_kill_with_grace() {
    local _pid="$1"
    kill -TERM "$_pid" 2>/dev/null || true
    sleep 1
    if kill -0 "$_pid" 2>/dev/null; then
        kill -KILL "$_pid" 2>/dev/null || true
    fi
}

_kill_tree() {
    local _p="$1" _c
    for _c in $(pgrep -P "$_p" 2>/dev/null); do _kill_tree "$_c"; done
    kill -KILL "$_p" 2>/dev/null || true
}

_run_with_timeout() {
    local _to="$1"; shift
    case "$_to" in ''|*[!0-9]*|0) _to=60 ;; esac
    ensure_scratch
    "$@" &
    local _cpid=$!
    CHILD_PIDS+=( "$_cpid" )
    local _wd_flag="${SCRATCH_DIR:-${TMPDIR:-/tmp}}/.rwt-timeout.$$.$_cpid"
    rm -f "$_wd_flag" 2>/dev/null
    ( _e=0
      while kill -0 "$_cpid" 2>/dev/null; do
          if [ "$_e" -ge "$_to" ]; then : > "$_wd_flag" 2>/dev/null; _kill_tree "$_cpid"; break; fi
          sleep 1; _e=$(( _e + 1 ))
      done ) &
    local _wpid=$!
    wait "$_cpid" 2>/dev/null; local _rc=$?
    wait "$_wpid" 2>/dev/null   # watchdog self-exits within ~1 s of the cmd ending
    local _np=() _p
    for _p in "${CHILD_PIDS[@]+"${CHILD_PIDS[@]}"}"; do [ "$_p" = "$_cpid" ] || _np+=( "$_p" ); done
    if [ "${#_np[@]}" -gt 0 ]; then CHILD_PIDS=( "${_np[@]}" ); else CHILD_PIDS=(); fi
    { [ "$_rc" -eq 137 ] && [ -f "$_wd_flag" ]; } && _rc=124
    rm -f "$_wd_flag" 2>/dev/null
    return "$_rc"
}

_fetch_download() {
    local _u="$1" _o="$2" _label="$3" _maxt="${4:-300}" _approx="${5:-}"
    case "$_maxt" in ''|*[!0-9]*) _maxt=300 ;; esac
    local _cpid _start _now _el _bytes _mb _kbps _rc _last=0 _tty=0 _drew=0 _drawn=0 _den=""
    [ -n "$_approx" ] && _den=" / ~${_approx} MB"
    { [ -t 1 ] || [ "${_DOWNPOUR_FORCE_TTY_OUT:-0}" = "1" ]; } && _tty=1
    log_info "Fetching ${_label}..."
    curl -fsSL --retry 3 --connect-timeout 30 --max-time "$_maxt" \
        --speed-limit 1024 --speed-time 30 -o "$_o" "$_u" &
    _cpid=$!
    CHILD_PIDS+=( "$_cpid" )
    _start="$(date +%s)"
    while kill -0 "$_cpid" 2>/dev/null; do
        sleep 0.5
        kill -0 "$_cpid" 2>/dev/null || break
        _now="$(date +%s)"; _el=$(( _now - _start )); [ "$_el" -lt 1 ] && _el=1
        [ $(( _el - _drawn )) -ge 2 ] || continue
        _drawn="$_el"
        _bytes="$(stat -f%z -- "$_o" 2>/dev/null || printf 0)"
        case "$_bytes" in ''|*[!0-9]*) _bytes=0 ;; esac
        _mb=$(( _bytes / 1048576 )); _kbps=$(( _bytes / 1024 / _el ))
        if [ "$_tty" = 1 ]; then
            printf '\r  Downloading %s... %s MB%s (%ss, %s KB/s)\033[K' \
                "$_label" "$_mb" "$_den" "$_el" "$_kbps"
            _drew=1
        elif [ $(( _el - _last )) -ge 60 ]; then
            _last="$_el"
            log_info "  Downloading ${_label}... ${_mb} MB${_den} (${_el}s, ${_kbps} KB/s)"
        fi
    done
    [ "$_drew" = 1 ] && printf '\n'
    wait "$_cpid"; _rc=$?
    local _np=() _p
    for _p in "${CHILD_PIDS[@]+"${CHILD_PIDS[@]}"}"; do [ "$_p" = "$_cpid" ] || _np+=( "$_p" ); done
    if [ "${#_np[@]}" -gt 0 ]; then CHILD_PIDS=( "${_np[@]}" ); else CHILD_PIDS=(); fi
    return "$_rc"
}

_photos_export_asset() {
    local uuid="$1" _timeout="$2" _prefix="${3:-photos_export}"
    _dl_path=""
    _dl_extra=()
    _PHOTOS_EXPORT_TMPDIR=""
    case "$uuid" in
        [0-9A-Fa-f][0-9A-Fa-f][0-9A-Fa-f][0-9A-Fa-f][0-9A-Fa-f][0-9A-Fa-f][0-9A-Fa-f][0-9A-Fa-f]-[0-9A-Fa-f][0-9A-Fa-f][0-9A-Fa-f][0-9A-Fa-f]-[0-9A-Fa-f][0-9A-Fa-f][0-9A-Fa-f][0-9A-Fa-f]-[0-9A-Fa-f][0-9A-Fa-f][0-9A-Fa-f][0-9A-Fa-f]-[0-9A-Fa-f][0-9A-Fa-f][0-9A-Fa-f][0-9A-Fa-f][0-9A-Fa-f][0-9A-Fa-f][0-9A-Fa-f][0-9A-Fa-f][0-9A-Fa-f][0-9A-Fa-f][0-9A-Fa-f][0-9A-Fa-f]) ;;
        *) return 1 ;;
    esac
    case "$_timeout" in ''|*[!0-9]*) _timeout=60 ;; esac
    ensure_scratch
    local exp_tmp
    exp_tmp="$(mktemp -d "$SCRATCH_DIR/${_prefix}.XXXXXX")" || return 1
    _PHOTOS_EXPORT_TMPDIR="$exp_tmp"
    local _wall=$(( _timeout + 5 ))
    _as_debug "exporting asset $uuid (${_timeout}s timeout)"
    osascript \
        -e "with timeout of $_timeout seconds" \
        -e "    tell application \"Photos\"" \
        -e "        try" \
        -e "            set mi to media item id \"$uuid\"" \
        -e "            export {mi} to POSIX file \"$exp_tmp\" with using originals" \
        -e "        on error errMsg number errNum" \
        -e "            error \"asset $uuid: \" & errMsg & \" (\" & errNum & \")\"" \
        -e "        end try" \
        -e "    end tell" \
        -e "end timeout" \
        >/dev/null 2>&1 &
    local pid=$!
    CHILD_PIDS+=( "$pid" )
    local elapsed=0
    while kill -0 "$pid" 2>/dev/null; do
        sleep 1
        elapsed=$((elapsed + 1))
        if [ "${_SKIP_REQUESTED:-0}" = "1" ] || [ "$elapsed" -ge "$_wall" ]; then
            _kill_with_grace "$pid"
            break
        fi
    done
    wait "$pid" 2>/dev/null || true
    local _i _new=()
    for _i in "${CHILD_PIDS[@]+"${CHILD_PIDS[@]}"}"; do
        [ "$_i" = "$pid" ] && continue
        _new+=( "$_i" )
    done
    CHILD_PIDS=( "${_new[@]+"${_new[@]}"}" )
    local _f _all=() _main=""
    while IFS= read -r -d '' _f; do _all+=( "$_f" ); done \
        < <(find "$exp_tmp" -type f -print0 2>/dev/null)
    for _f in "${_all[@]+"${_all[@]}"}"; do
        case "${_f##*.}" in
            heic|HEIC|heif|HEIF|jpg|JPG|jpeg|JPEG|png|PNG|gif|GIF|tif|tiff|TIF|TIFF|bmp|BMP|webp|WEBP)
                if [ -z "$_main" ]; then _main="$_f"; else _dl_extra+=( "$_f" ); fi ;;
            *) _dl_extra+=( "$_f" ) ;;
        esac
    done
    if [ -z "$_main" ] && [ "${#_dl_extra[@]}" -gt 0 ]; then
        _main="${_dl_extra[0]}"; _dl_extra=( "${_dl_extra[@]:1}" )
    fi
    if [ -n "$_main" ] && [ -s "$_main" ]; then
        _dl_path="$_main"; return 0
    fi
    rm -rf -- "$exp_tmp" 2>/dev/null || true
    _PHOTOS_EXPORT_TMPDIR=""
    _dl_extra=()
    return 1
}

_save_defaults_pref() {
    local _p="$1" _domain="$2" _key="$3" _newval="$4"
    local _orig_var="${_p}_PREF_ORIGINAL"
    local _had_var="${_p}_PREF_HAD_VALUE"
    local _skip_var="${_p}_PREF_SKIP"
    local _written_var="${_p}_PREF_WRITTEN"
    printf -v "$_orig_var"    '%s' ''
    printf -v "$_had_var"     '%s' '0'
    printf -v "$_skip_var"    '%s' '0'
    printf -v "$_written_var" '%s' '0'
    printf -v "${_p}_PREF_RESTORED" '%s' '0'
    local _orig
    if _orig="$(defaults read "$_domain" "$_key" 2>/dev/null)"; then
        case "$_orig" in
            *$'\n'*|*$'\r'*)
                log_info "Existing $_domain $_key pref contains newline/CR — leaving it untouched (cannot round-trip it safely)."
                printf -v "$_skip_var" '%s' '1'
                return 0
                ;;
            *)
                printf -v "$_orig_var" '%s' "$_orig"
                printf -v "$_had_var"  '%s' '1'
                ;;
        esac
    fi
    if defaults write "$_domain" "$_key" -string "$_newval" 2>/dev/null; then
        printf -v "$_written_var" '%s' '1'
    fi
    return 0
}

_restore_defaults_pref() {
    local _p="$1" _domain="$2" _key="$3"
    local _r_var="${_p}_PREF_RESTORED"
    local _s_var="${_p}_PREF_SKIP"
    local _h_var="${_p}_PREF_HAD_VALUE"
    local _o_var="${_p}_PREF_ORIGINAL"
    local _w_var="${_p}_PREF_WRITTEN"
    [ "${!_r_var:-0}" = "1" ] && return 0
    printf -v "$_r_var" '1'
    if [ "${!_s_var:-0}" = "1" ]; then
        printf -v "$_h_var" '0'
        printf -v "$_o_var" '%s' ''
        return 0
    fi
    if [ "${!_h_var:-0}" = "1" ]; then
        defaults write "$_domain" "$_key" -string "${!_o_var}" 2>/dev/null || true
    elif [ "${!_w_var:-0}" = "1" ]; then
        defaults delete "$_domain" "$_key" 2>/dev/null || true
    fi
    printf -v "$_h_var" '0'
    printf -v "$_o_var" '%s' ''
    printf -v "$_w_var" '0'
}

_snapshot_app_launch() {
    local _app="$1" _var="$2"
    if pgrep -x "$_app" >/dev/null 2>&1; then
        printf -v "$_var" '0'
    else
        printf -v "$_var" '1'
    fi
}

_rfc_unfold_lines() {
    LC_ALL=C awk '
    BEGIN { first = 1 }
    {
        line = $0
        sub(/\r$/, "", line)
        if (first) { sub(/^\xef\xbb\xbf/, "", line); first = 0 }
        if (line == "") {
            if (buffer != "") print buffer
            buffer = ""
            next
        }
        if (line ~ /^[ \t]/) {
            buffer = buffer substr(line, 2)
        } else {
            if (buffer != "") print buffer
            buffer = line
        }
    }
    END { if (buffer != "") print buffer }
    '
}

_VCF_AWK_ABLABEL='
function map_label(raw, kind,    s) {
    gsub(/_\$!<|>!\$_/, "", raw)
    if (raw == "Home" || raw == "home")  return "Home"
    if (raw == "Work" || raw == "work")  return "Work"
    if (raw == "Other" || raw == "other") return "Other"
    if (raw == "Mobile" || raw == "mobile" || raw == "iPhone") {
        return (kind == "tel") ? "Cell" : "Other"
    }
    if (raw == "Main" || raw == "main")  return "Voice"
    if (raw == "Pager" || raw == "pager") return "Pager"
    if (raw == "HomeFAX" || raw == "HomeFax" || raw == "homefax") return "HomeFax"
    if (raw == "WorkFAX" || raw == "WorkFax" || raw == "workfax") return "WorkFax"
    if (raw == "OtherFAX" || raw == "OtherFax") return "Fax"
    s = raw
    gsub(/[^A-Za-z0-9]/, "", s)
    return s
}

function get_kind(line,   p, q) {
    p = line
    sub(/^[^.:]+\./, "", p)
    q = index(p, ":")
    if (q > 0) p = substr(p, 1, q - 1)
    sub(/;.*$/, "", p)
    if (p == "TEL")   return "tel"
    if (p == "EMAIL") return "email"
    if (p == "ADR")   return "adr"
    if (p == "URL")   return "url"
    return "other"
}

function strip_item(line) {
    if (line ~ /^item[A-Za-z0-9]+\./) {
        sub(/^item[A-Za-z0-9]+\./, "", line)
    }
    return line
}

function inject_type(line, label,    prop, rest, colon_pos, m_start, m_len, head, tail) {
    if (label == "") return line
    colon_pos = index(line, ":")
    prop = substr(line, 1, colon_pos - 1)
    rest = substr(line, colon_pos)
    if (prop ~ /;TYPE=/) {
        match(prop, /;TYPE=[^;]*/)
        m_start = RSTART
        m_len   = RLENGTH
        head = substr(prop, 1, m_start + m_len - 1)
        tail = substr(prop, m_start + m_len)
        prop = head "," label tail
    } else {
        prop = prop ";TYPE=" label
    }
    return prop rest
}

{
    line = $0
    if (line ~ /^([^.:]+\.)?X-ABLabel:/) {
        raw_label = line
        sub(/^([^.:]+\.)?X-ABLabel:/, "", raw_label)
        kind = (prev != "") ? get_kind(prev) : "other"
        clean_label = map_label(raw_label, kind)
        if (prev != "") {
            prev = strip_item(prev)
            if (clean_label != "") prev = inject_type(prev, clean_label)
        }
        next
    }
    if (prev != "") print prev
    prev = line
}

END { if (prev != "") print prev }
'

_vcf_ablabel_to_type() { LC_ALL=C awk "$_VCF_AWK_ABLABEL"; }

_strip_inline_apple_params() {
    LC_ALL=C awk '
    {
        line = $0
        while (match(line, /;[Xx]-[Aa][Bb][^=;:]*=[^;:]*/) > 0) {
            line = substr(line, 1, RSTART - 1) substr(line, RSTART + RLENGTH)
        }
        while (match(line, /;[Xx]-[Aa][Pp][Pp][Ll][Ee]-[^=;:]*=[^;:]*/) > 0) {
            line = substr(line, 1, RSTART - 1) substr(line, RSTART + RLENGTH)
        }
        print line
    }
    '
}

_strip_item_prefixes() {
    LC_ALL=C awk '{ sub(/^item[0-9]+\./, ""); print }'
}

_VCF_AWK_TEL='
function normalize_tel(line,    prop, val, extnum, extsuffix, digits, i, tmp) {
    i = index(line, ":")
    prop = substr(line, 1, i - 1)
    val  = substr(line, i + 1)
    extnum = ""
    if (prop ~ /;ext=/) {
        match(prop, /;ext=[^;]*/)
        tmp = substr(prop, RSTART, RLENGTH)
        gsub(/[^0-9]/, "", tmp)
        extnum = tmp
        sub(/;ext=[^;]*/, "", prop)
    } else if (val ~ /[xX][0-9]+$/) {
        match(val, /[xX]([0-9]+)$/)
        extnum = substr(val, RSTART + 1, RLENGTH - 1)
        sub(/[xX][0-9]+$/, "", val)
    } else if (val ~ /[eE][xX][tT][.[:space:]]*[0-9]+$/) {
        match(val, /[eE][xX][tT][.[:space:]]*[0-9]+$/)
        tmp = substr(val, RSTART, RLENGTH)
        gsub(/[^0-9]/, "", tmp)
        extnum = tmp
        sub(/[eE][xX][tT][.[:space:]]*[0-9]+$/, "", val)
    }
    sub(/[[:space:]]+$/, "", val)
    extsuffix = (extnum == "") ? "" : " x" extnum
    if (val ~ /^[[:space:]]*\+/) {
        print prop ":" val extsuffix
        return
    }
    digits = val
    gsub(/[^0-9]/, "", digits)
    if (length(digits) == 11 && substr(digits, 1, 1) == "1") {
        digits = substr(digits, 2)
    }
    if (length(digits) == 10) {
        val = "(" substr(digits, 1, 3) ") " substr(digits, 4, 3) "-" substr(digits, 7, 4)
    }
    print prop ":" val extsuffix
}

{
    if ($0 ~ /^([^.:]+\.)?TEL[;:]/) { normalize_tel($0) }
    else { print }
}

'

_vcf_normalize_tel_numbers() { LC_ALL=C awk "$_VCF_AWK_TEL"; }

clean_vcf_file() {
    local infile="$1" tmpfile
    [ -f "$infile" ] || return 1
    tmpfile="$(mktemp "${infile}.tmp.XXXXXX")" || return 1
    track_output_path "$tmpfile"
    local _vcf_discard='^([^.:]+\.)?(X-AB[A-Za-z-]+[;:]|X-ADDRESSBOOKSERVER-|X-SOCIALPROFILE[;:]|X-IMAGETYPE[;:]|X-IMAGEHASH[;:]|X-ACTIVITY-ALERT[;:]|X-APPLE-|X-PHONETIC-FIRST-NAME[;:]|X-PHONETIC-MIDDLE-NAME[;:]|X-PHONETIC-LAST-NAME[;:]|X-ALTBDAY[;:]|X-AIM[;:]|X-MSN[;:]|X-YAHOO[;:]|X-ICQ[;:]|X-JABBER[;:]|X-GADUGADU[;:]|X-GROUPWISE[;:]|X-SKYPE[;:]|X-SKYPE-USERNAME[;:]|REV[;:])'
    if _rfc_unfold_lines < "$infile" \
        | _strip_inline_apple_params \
        | _vcf_ablabel_to_type \
        | LC_ALL=C sed -E \
            -e 's|^PRODID[;:].*|PRODID:-//Unknown//Unknown//EN|' \
        | LC_ALL=C dr="$_vcf_discard" awk 'BEGIN{dr=ENVIRON["dr"]} $0 ~ dr { next } { print }' \
        | _vcf_normalize_tel_numbers \
        | _strip_item_prefixes \
        | _fold_75_octets > "$tmpfile"; then
        if [ -s "$tmpfile" ] && grep -q '^BEGIN:VCARD' "$tmpfile" 2>/dev/null; then
            if mv -f -- "$tmpfile" "$infile"; then
                _untrack_output_path "$tmpfile"
                validate_vcf_rfc6350 "$infile" || true
                return 0
            fi
        fi
    fi
    _untrack_output_path "$tmpfile"
    rm -f -- "$tmpfile" 2>/dev/null
    return 1
}

_ics_remove_empty_valarms() {
    LC_ALL=C awk '
    /^BEGIN:VALARM$/ {
        in_alarm = 1; alarm_buf = $0 "\n"
        has_action = 0; has_trigger = 0
        next
    }
    in_alarm {
        alarm_buf = alarm_buf $0 "\n"
        if ($0 ~ /^ACTION:/)  has_action = 1
        if ($0 ~ /^TRIGGER[;:]/) has_trigger = 1
        if ($0 ~ /^END:VALARM$/) {
            in_alarm = 0
            if (has_action && has_trigger) { printf "%s", alarm_buf }
            alarm_buf = ""
        }
        next
    }
    { print }
    END { if (in_alarm) printf "%s", alarm_buf }
    '
}

clean_ics_file() {
    local infile="$1" tmpfile
    [ -f "$infile" ] || return 1
    tmpfile="$(mktemp "${infile}.tmp.XXXXXX")" || return 1
    track_output_path "$tmpfile"
    local _ics_discard='^(X-WR-RELCALID[;:]|X-APPLE-|X-CALENDARSERVER-|X-ADDRESSBOOKSERVER-|X-ABUID[;:]|X-LIC-LOCATION[;:]|ACKNOWLEDGED[;:]|SOURCE[;:]|REFRESH-INTERVAL[;:]|PROXIMITY[;:]|CREATED[;:]|LAST-MODIFIED[;:]|SEQUENCE[;:]|ATTENDEE[;:]|ORGANIZER[;:]|METHOD[;:]|ATTACH[;:]|TZURL[;:]|IMAGE[;:]|CONFERENCE[;:]|GEO[;:])'
    if _rfc_unfold_lines < "$infile" \
        | LC_ALL=C sed -E \
            -e 's|^PRODID[;:].*|PRODID:-//Unknown//Unknown//EN|' \
            -e 's|^DTSTAMP[;:].*|DTSTAMP:19700101T000000Z|' \
        | LC_ALL=C dr="$_ics_discard" awk 'BEGIN{dr=ENVIRON["dr"]} $0 ~ dr { next } { print }' \
        | _ics_remove_empty_valarms \
        | _fold_75_octets > "$tmpfile"; then
        if [ -s "$tmpfile" ] && grep -q '^BEGIN:VCALENDAR' "$tmpfile" 2>/dev/null; then
            if mv -f -- "$tmpfile" "$infile"; then
                _untrack_output_path "$tmpfile"
                validate_ics_rfc5545 "$infile" || true
                return 0
            fi
        fi
    fi
    _untrack_output_path "$tmpfile"
    rm -f -- "$tmpfile" 2>/dev/null
    return 1
}

validate_mbox_rfc4155() {
    local file="$1"
    [ -f "$file" ] || return 0
    [ -s "$file" ] || return 0
    local _v
    _v="$(LC_ALL=C awk '
    BEGIN { first_seen = 0; preamble = 0; from_n = 0; bad_envelope = 0; no_blank = 0; last_blank = 1 }
    {
        sub(/\r$/, "")
        is_blank = ($0 ~ /^[[:space:]]*$/) ? 1 : 0
        is_from  = ($0 ~ /^From [^[:space:]]/) ? 1 : 0
        if (is_from) {
            from_n++
            if (NF < 4) bad_envelope++
            if (!first_seen) {
                first_seen = 1
            } else if (!last_blank) {
                no_blank++
            }
        } else if (!is_blank && !first_seen) {
            preamble++
        }
        last_blank = is_blank
    }
    END {
        if (preamble > 0)     printf "%d non-From preamble line(s); ", preamble
        if (from_n == 0)      printf "no From-envelope(s) found; "
        if (bad_envelope > 0) printf "%d malformed envelope(s) (<4 fields); ", bad_envelope
        if (no_blank > 0)     printf "%d From-line(s) not preceded by blank; ", no_blank
    }
    ' "$file")"
    if [ -n "$_v" ]; then
        log_warn "mbox/RFC 4155: $file: ${_v%; }"
        return 1
    fi
    return 0
}

validate_ics_rfc5545() {
    local file="$1"
    [ -f "$file" ] || return 0
    local _v
    _v="$(LC_ALL=C awk '
    BEGIN { state = "outside"; n_event = 0; n_todo = 0; mu = 0; md = 0; mds = 0 }
    { sub(/\r$/, "") }
    /^BEGIN:VEVENT$/ { state = "ev"; n_event++; uid = 0; dts = 0; dst = 0; next }
    /^BEGIN:VTODO$/  { state = "td"; n_todo++;  uid = 0; dts = 0; next }
    state == "ev" || state == "td" {
        if ($0 ~ /^UID[;:]/)     uid = 1
        if ($0 ~ /^DTSTAMP[;:]/) dts = 1
        if (state == "ev" && $0 ~ /^DTSTART[;:]/) dst = 1
    }
    /^END:VEVENT$/ && state == "ev" {
        if (!uid) mu++
        if (!dts) md++
        if (!dst) mds++
        state = "outside"; next
    }
    /^END:VTODO$/ && state == "td" {
        if (!uid) mu++
        if (!dts) md++
        state = "outside"; next
    }
    END {
        if (n_event == 0 && n_todo == 0) printf "no VEVENT/VTODO components; "
        if (mu > 0)  printf "%d component(s) missing UID; ", mu
        if (md > 0)  printf "%d component(s) missing DTSTAMP; ", md
        if (mds > 0) printf "%d VEVENT(s) missing DTSTART; ", mds
    }
    ' "$file")"
    if [ -n "$_v" ]; then
        log_warn "iCal/RFC 5545: $file: ${_v%; }"
        return 1
    fi
    return 0
}

validate_vcf_rfc6350() {
    local file="$1"
    [ -f "$file" ] || return 0
    local _v
    _v="$(LC_ALL=C awk '
    BEGIN { state = "outside"; n_card = 0; mfn = 0; mver = 0; nested = 0 }
    { sub(/\r$/, "") }
    /^BEGIN:VCARD$/ {
        if (state == "incard") nested++
        state = "incard"; n_card++; fn = 0; ver = 0
        next
    }
    state == "incard" {
        if ($0 ~ /^FN[;:]/)      fn = 1
        if ($0 ~ /^VERSION[;:]/) ver = 1
    }
    /^END:VCARD$/ && state == "incard" {
        if (!fn)  mfn++
        if (!ver) mver++
        state = "outside"; next
    }
    END {
        if (n_card == 0)  printf "no VCARD blocks; "
        if (mfn > 0)      printf "%d VCARD(s) missing FN; ", mfn
        if (mver > 0)     printf "%d VCARD(s) missing VERSION; ", mver
        if (nested > 0)   printf "%d nested VCARD(s) (missing END); ", nested
    }
    ' "$file")"
    if [ -n "$_v" ]; then
        log_warn "vCard/RFC 6350: $file: ${_v%; }"
        return 1
    fi
    return 0
}

validate_csv_rfc4180() {
    local file="$1"
    [ -f "$file" ] || return 0
    local _v
    _v="$(LC_ALL=C tr -d '\200-\277' < "$file" | LC_ALL=C awk '
    BEGIN { header_n = -1; mismatched = 0; unbalanced = 0; total_rows = 0 }
    {
        sub(/\r$/, "")
        if ($0 == "") next
        total_rows++
        in_q = 0
        commas = 0
        n = length($0)
        i = 1
        while (i <= n) {
            c = substr($0, i, 1)
            if (c == "\"") {
                if (in_q && i < n && substr($0, i+1, 1) == "\"") {
                    i += 2; continue
                }
                in_q = !in_q
            } else if (c == "," && !in_q) {
                commas++
            }
            i++
        }
        if (in_q) unbalanced++
        nf = commas + 1
        if (header_n == -1) header_n = nf
        else if (nf != header_n) mismatched++
    }
    END {
        if (total_rows == 0)  printf "empty file; "
        if (unbalanced > 0)   printf "%d row(s) with unbalanced quotes; ", unbalanced
        if (mismatched > 0)   printf "%d row(s) with field count != header (%d); ", mismatched, header_n
    }
    ')"
    if [ -n "$_v" ]; then
        log_warn "CSV/RFC 4180: $file: ${_v%; }"
        return 1
    fi
    return 0
}

validate_html_structure() {
    local file="$1" _v
    [ -f "$file" ] || return 0
    _v="$(LC_ALL=C awk '
        {
            line = $0
            while (match(line, /<\/?[A-Za-z][A-Za-z0-9]*/)) {
                tag  = substr(line, RSTART, RLENGTH)
                line = substr(line, RSTART + RLENGTH)
                isclose = (substr(tag, 2, 1) == "/")
                name = tolower(isclose ? substr(tag, 3) : substr(tag, 2))
                if (name ~ /^(html|head|body|div|table|style|script|title|ul|ol)$/) {
                    if (isclose) c[name]++; else o[name]++
                }
            }
        }
        END {
            split("html head body", _sk, " ")
            for (i = 1; i <= 3; i++) {
                n = _sk[i]
                if ((o[n] + 0) != 1 || (c[n] + 0) != 1)
                    printf "missing/duplicated <%s> skeleton; ", n
            }
            split("div table style script title ul ol", _bal, " ")
            for (i = 1; i <= 7; i++) {
                n = _bal[i]
                if ((o[n] + 0) != (c[n] + 0))
                    printf "%d <%s> vs %d </%s>; ", o[n] + 0, n, c[n] + 0, n
            }
        }
    ' "$file")"
    if [ -n "$_v" ]; then
        log_warn "HTML structure: $file: ${_v%; }"
        return 1
    fi
    return 0
}

_unique_path() {
    local base="$1" candidate="$1" n=2 dir name stem ext
    case "$base" in
        */*) dir="${base%/*}"; name="${base##*/}" ;;
        *)   dir=".";          name="$base" ;;
    esac
    [ -z "$name" ] && { printf '%s' "$base"; return 0; }
    case "$name" in
        .*.*) stem="${name%.*}"; ext=".${name##*.}" ;;
        .*)   stem="$name"; ext="" ;;
        *.*)  stem="${name%.*}"; ext=".${name##*.}" ;;
        *)    stem="$name"; ext="" ;;
    esac
    local _max=10000
    while [ -e "$candidate" ] || [ -L "$candidate" ]; do
        if [ "$n" -gt "$_max" ]; then
            candidate="$dir/${stem}_$$_${n}${ext}"
            break
        fi
        candidate="$dir/${stem}_${n}${ext}"
        n=$((n + 1))
    done
    printf '%s' "$candidate"
}

cleanup_empty_dirs() {
    [ -n "${1:-}" ] && [ -d "$1" ] || return 0
    find "$1" -mindepth 1 -type d -empty -delete 2>/dev/null || true
    rmdir "$1" 2>/dev/null || true
}

quit_app_iff_we_launched_it() {
    local app="$1" launched_var="$2"
    [ "${!launched_var:-0}" = "1" ] || return 0
    log_info "Quitting $app — waiting for it to close..."
    osascript -e 'with timeout of 15 seconds' \
              -e "tell application \"$app\" to quit" \
              -e 'end timeout' >/dev/null 2>&1 &
    local _q_pid=$!
    ( exec >/dev/null 2>&1 </dev/null
      sleep 16
      kill -0 "$_q_pid" 2>/dev/null || exit 0
      kill -TERM "$_q_pid" 2>/dev/null
      sleep 1
      kill -0 "$_q_pid" 2>/dev/null && kill -KILL "$_q_pid" 2>/dev/null
    ) </dev/null >/dev/null 2>&1 &
    local _q_wd=$!
    wait "$_q_pid" 2>/dev/null || true
    pkill -KILL -P "$_q_wd" 2>/dev/null || true
    kill -KILL "$_q_wd" 2>/dev/null
    wait "$_q_wd" 2>/dev/null || true
    printf -v "$launched_var" '%s' 0 2>/dev/null || true
}

_ACTIVITY_TS=""

mark_activity() {
    _ACTIVITY_TS=$(date +%s 2>/dev/null) || _ACTIVITY_TS=""
}

info_handler() {
    local _now _elapsed _stale="" _self
    _now=$(date +%s 2>/dev/null) || _now=""
    if [ -n "${_ACTIVITY_TS:-}" ] && [ -n "$_now" ]; then
        _elapsed=$((_now - _ACTIVITY_TS))
        _stale=" (last activity: ${_elapsed}s ago)"
    fi
    _self="${0##*/}"
    case "$_self" in
        ''|bash|-bash|sh|-sh|dash|zsh|-zsh|[0-9]*) _self="downpour.sh" ;;
    esac
    printf '  [info] %s running%s\n' "$_self" "$_stale" >&2 || true
    declare -F info_handler_hook >/dev/null 2>&1 && info_handler_hook 2>/dev/null || true
}

_skip_handler() {
    return 0
}

_abort_ack() {
    [ "${_INVOKED_BY_WRAPPER:-0}" = "1" ] && return 0
    if [ "${_LAST_BLANK:-0}" = "1" ]; then
        printf '  Aborting and cleaning up...\n\n' 2>/dev/null \
            || printf '  Aborting and cleaning up...\n\n' 2>/dev/null >/dev/tty \
            || true
    else
        printf '\n  Aborting and cleaning up...\n\n' 2>/dev/null \
            || printf '\n  Aborting and cleaning up...\n\n' 2>/dev/null >/dev/tty \
            || true
    fi
}

trap 'trap "" INT TERM HUP QUIT USR1; _abort_ack; cleanup_handler 130' INT
trap 'trap "" INT TERM HUP QUIT USR1; _abort_ack; cleanup_handler 143' TERM
trap 'trap "" INT TERM HUP QUIT USR1; _abort_ack; cleanup_handler 129' HUP
trap 'trap "" INT TERM HUP QUIT USR1; _abort_ack; cleanup_handler 131' QUIT
trap cleanup_handler EXIT
trap info_handler INFO 2>/dev/null || true
trap _skip_handler USR1 2>/dev/null || true
trap '' PIPE

REQUIRED_TOOLS=(
    "awk:built-in macOS tool at /usr/bin/awk (XML walker that emits Netscape HTML)"
    "awk:built-in macOS tool at /usr/bin/awk"
    "awk:built-in macOS tool"
    "base64:built-in macOS tool at /usr/bin/base64 (vCard PHOTO encoding)"
    "base64:built-in macOS tool"
    "basename:built-in macOS tool"
    "bash:built-in macOS shell"
    "bash:built-in macOS tool"
    "cat:built-in macOS tool"
    "cp:built-in macOS tool"
    "curl:built-in macOS tool at /usr/bin/curl (LibreOffice download)"
    "curl:built-in macOS tool at /usr/bin/curl (only required if SERVER is set)"
    "curl:built-in macOS tool"
    "cut:built-in macOS tool"
    "date:built-in macOS tool (Core Data → epoch + epoch → mtime)"
    "date:built-in macOS tool"
    "dd:built-in macOS tool (run-loop output-volume write-probe)"
    "defaults:built-in macOS tool (bracket the DiskImages skip-verify pref over the mount)"
    "defaults:built-in macOS tool at /usr/bin/defaults (points Freeform's Save-panel NSNavLastRootDirectory at our scratch staging dir, restored on exit)"
    "defaults:built-in macOS tool at /usr/bin/defaults (used to locate the Photos library)"
    "df:built-in macOS tool (disk-space sanity-check free-space probe)"
    "df:built-in macOS tool (per-library free-space check before each originals copy)"
    "df:built-in macOS tool"
    "df:built-in macOS tool; check /bin in PATH"
    "dirname:built-in macOS tool"
    "ditto:built-in macOS tool (attachment copy with xattr/resource-fork preservation)"
    "ditto:built-in macOS tool (book-file + cover-image copies, preserving xattrs/resource forks)"
    "ditto:built-in macOS tool (copies .rtfd attachment files, preserving xattrs/resource forks)"
    "ditto:built-in macOS tool (copy LibreOffice.app out of the DMG)"
    "ditto:built-in macOS tool (per-file copy preserving xattrs / Finder tags / ACLs / resource forks)"
    "ditto:built-in macOS tool (preserves xattrs / Finder tags / resource forks on attachment copies)"
    "ditto:built-in macOS tool (shared-album + downloaded-original copies, preserving xattrs / resource forks)"
    "ditto:built-in macOS tool"
    "ditto:built-in macOS tool; check /usr/bin in PATH"
    "du:built-in macOS tool (disk-space sanity-check buckets)"
    "du:built-in macOS tool (per-library size estimate)"
    "du:built-in macOS tool"
    "du:built-in macOS tool; check /usr/bin in PATH"
    "find:built-in macOS tool"
    "find:built-in macOS tool; if missing your /usr/bin is corrupt — try reinstalling macOS or check that /usr/bin is in PATH"
    "grep:built-in macOS tool (single-column pragma_table_info probes)"
    "grep:built-in macOS tool (social-section companion-file counts in the consolidated report)"
    "grep:built-in macOS tool"
    "grep:built-in macOS tool; check /usr/bin in PATH"
    "gzcat:built-in macOS tool at /usr/bin/gzcat (used for the gzipped protobuf body)"
    "hdiutil:built-in macOS tool (mount the LibreOffice DMG)"
    "head:built-in macOS tool (bounded reads in the menu/AppleScript plumbing)"
    "head:built-in macOS tool (truncates the AppleScript error excerpt)"
    "head:built-in macOS tool"
    "hostname:built-in macOS tool"
    "iconv:built-in macOS tool (UTF-8 validation of textutil output before the byte-level cut)"
    "iconv:built-in macOS tool"
    "id:built-in macOS tool (authoritative short-username resolution for the export folder name)"
    "md5:built-in macOS tool at /sbin/md5"
    "md5:built-in macOS tool"
    "mdls:built-in macOS tool (diagnostic-only: surfaces the Freeform.app version when the export-menu smoke probe fails)"
    "mkdir:built-in macOS tool"
    "mkdir:built-in macOS tool; check /bin in PATH"
    "mktemp:built-in macOS tool (per-run scratch + per-PID counts file dir)"
    "mktemp:built-in macOS tool"
    "mktemp:built-in macOS tool; check /usr/bin in PATH"
    "mv:built-in macOS tool"
    "od:built-in macOS tool at /usr/bin/od (UUID -> hex key for the sticky-meta hash map)"
    "od:built-in macOS tool"
    "open:built-in macOS tool (auto-opens System Settings on a Photos-Automation denial)"
    "open:built-in macOS tool (auto-opens the Automation pane on permission failure)"
    "open:built-in macOS tool (auto-opens the relevant System Settings pane on a TCC denial)"
    "open:built-in macOS tool at /usr/bin/open (drives the freeform:// URL scheme to open each Freeform board by UUID before AppleScript-driven PDF export)"
    "osascript:built-in macOS tool at /usr/bin/osascript (drives Freeform's File > Export Board as PDF menu via System Events)"
    "osascript:built-in macOS tool at /usr/bin/osascript (drives Passwords.app via System Events)"
    "osascript:built-in macOS tool at /usr/bin/osascript (used to download cloud-only assets via Photos.app)"
    "osascript:built-in macOS tool at /usr/bin/osascript (used to drive Music.app — Music has no on-disk database we can query directly)"
    "pgrep:built-in macOS tool (gates the per-board retry/bail logic — detects whether Freeform is still alive before retrying a board or recording a failure)"
    "pgrep:built-in macOS tool (probes whether Music.app was already running)"
    "pgrep:built-in macOS tool (probes whether Photos.app was already running so we can quit it iff we launched it)"
    "pgrep:built-in macOS tool"
    "plutil:built-in macOS tool at /usr/bin/plutil (.SavedStickiesState binary plist -> XML)"
    "plutil:built-in macOS tool at /usr/bin/plutil (Freeform board metadata)"
    "plutil:built-in macOS tool at /usr/bin/plutil (binary-plist → XML conversion)"
    "plutil:built-in macOS tool at /usr/bin/plutil; required for the .emlx → Thunderbird mbox conversion (parses each message's trailing Apple plist for date-received and the deleted-flag bit)"
    "readlink:built-in macOS tool"
    "readlink:built-in macOS tool; check /usr/bin in PATH"
    "rm:built-in macOS tool"
    "rmdir:built-in macOS tool"
    "rmdir:built-in macOS tool; check /bin in PATH"
    "sed:built-in macOS tool (log-pipeline escape/CR strip + menu AppleScript placeholder substitution)"
    "sed:built-in macOS tool at /usr/bin/sed"
    "sed:built-in macOS tool"
    "seq:built-in macOS tool (the auto-no y/N countdown prompts)"
    "seq:built-in macOS tool"
    "seq:built-in macOS tool; check /usr/bin in PATH"
    "shasum:built-in macOS tool (verify the LibreOffice DMG against its published SHA-256)"
    "sips:built-in macOS tool at /usr/bin/sips (HEIC → JPEG for inline browser rendering)"
    "sips:built-in macOS tool at /usr/bin/sips (HEIC/HEIF embedded image -> JPEG copy)"
    "sips:built-in macOS tool at /usr/bin/sips (HEIC→JPEG for browser-renderable attachment previews)"
    "sips:built-in macOS tool at /usr/bin/sips (convert AddressBook TIFF photos to JPEG before vCard emit; TIFF is not a recognized vCard IMAGETYPE per RFC 6350 §6.5.2 and major importers silently drop it)"
    "sips:built-in macOS tool"
    "sort:built-in macOS tool (de-dupes the evicted / fallback cloud-only lists)"
    "sort:built-in macOS tool (enumerate-mode Photos-library discovery ordering)"
    "sort:built-in macOS tool"
    "sort:built-in macOS tool; check /usr/bin in PATH"
    "sqlite3:built-in macOS tool (iCloud-managed content + runtime-estimate Photos/Freeform DB probes)"
    "sqlite3:built-in macOS tool at /usr/bin/sqlite3 (Books AEAnnotation/BKLibrary join, BKLibraryDataSourceItem rows)"
    "sqlite3:built-in macOS tool at /usr/bin/sqlite3 (Maps MapsSync_* Core Data joins)"
    "sqlite3:built-in macOS tool at /usr/bin/sqlite3 (Text Replacements ZTEXTREPLACEMENTENTRY)"
    "sqlite3:built-in macOS tool at /usr/bin/sqlite3 (read AddressBook DBs)"
    "sqlite3:built-in macOS tool at /usr/bin/sqlite3 (reads the Freeform board list from boards.db)"
    "sqlite3:built-in macOS tool at /usr/bin/sqlite3"
    "stat:built-in macOS tool"
    "stat:built-in macOS tool; check /usr/bin in PATH"
    "stty:built-in macOS tool (the Photos 's'-skip keystroke poll; the GUI menu is Cocoa and never touches the tty)"
    "tail:built-in macOS tool"
    "tee:built-in macOS tool (the _downpour_log.txt log-capture pipeline)"
    "textutil:built-in macOS tool at /usr/bin/textutil (RTF → HTML primary, → plain-text fallback)"
    "textutil:built-in macOS tool at /usr/bin/textutil (Stickies RTF blob -> HTML per note)"
    "touch:built-in macOS tool (sets each .m4a mtime to the recording date)"
    "tr:built-in macOS tool at /usr/bin/tr"
    "tr:built-in macOS tool"
    "tr:built-in macOS tool; check /usr/bin in PATH"
    "uname:built-in macOS tool (selects the protoc release matching this CPU arch)"
    "uname:built-in macOS tool"
    "uniq:built-in macOS tool"
    "wc:built-in macOS tool (per-PID counts / warns file aggregation)"
    "wc:built-in macOS tool"
    "wc:built-in macOS tool; check /usr/bin in PATH"
    "xargs:built-in macOS tool (batched stat in the dataless-byte iCloud probe)"
    "xargs:built-in macOS tool"
    "xargs:built-in macOS tool; check /usr/bin in PATH"
    "xattr:built-in macOS tool (clear the LibreOffice quarantine + provenance flags)"
    "xattr:built-in macOS tool (only required if SKIP_ALIASES=1 — Carbon-alias detection)"
    "xattr:built-in macOS tool"
    "xxd:built-in macOS tool at /usr/bin/xxd (binary photo magic-byte probe)"
    "xxd:built-in macOS tool at /usr/bin/xxd (used for gzip magic-byte sniffing)"
)

SOURCE_PROTECTED_PREFIXES=(
    "$HOME/Library"
    "$HOME/Library/Application Support/AddressBook"
    "$HOME/Library/Application Support/com.apple.voicememos"
    "$HOME/Library/Containers/com.apple.BKAgentService"
    "$HOME/Library/Containers/com.apple.Maps"
    "$HOME/Library/Containers/com.apple.Stickies"
    "$HOME/Library/Containers/com.apple.freeform"
    "$HOME/Library/Containers/com.apple.iBooksX"
    "$HOME/Library/Group Containers/group.com.apple.VoiceMemos.shared"
    "$HOME/Library/Group Containers/group.com.apple.calendar"
    "$HOME/Library/Group Containers/group.com.apple.freeform"
    "$HOME/Library/Group Containers/group.com.apple.moments"
    "$HOME/Library/Group Containers/group.com.apple.notes"
    "$HOME/Library/Group Containers/group.com.apple.reminders"
    "$HOME/Library/KeyboardServices"
    "$HOME/Library/Mail"
    "$HOME/Library/Messages"
    "$HOME/Library/Mobile Documents"
    "$HOME/Library/Safari"
    "$HOME/Pictures"
)
SERVER="${SERVER-https://downpour.sh}"
SERVER="${SERVER%/}"

SCRIPTS_IN_ORDER=(
    "export_passwords:Passwords export:accessibility"
    "export_contacts:Contacts export:fda"
    "export_calendars:Calendars export:fda"
    "export_reminders:Reminders export:fda"
    "export_notes:Notes export:fda"
    "export_journal:Journal export:fda"
    "export_mail:Mail export:fda"
    "export_icloud_drive:iCloud Drive export:"
    "export_files:Files export:fda"
    "export_books:Books export:fda"
    "export_freeform:Freeform export:fda,accessibility"
    "export_maps:Maps export:fda"
    "export_music_playlists:Music playlists export:music"
    "export_safari_bookmarks:Safari bookmarks export:fda"
    "export_stickies:Stickies export:fda"
    "export_text_replacements:Text Replacements export:fda"
    "export_voice_memos:Voice memos export:fda"
    "export_photos:Photos export:fda"
    "export_messages:Messages export:fda"
    "export_converted_docs:Converted Docs export:"
)

MENU_ORDER=(
    "export_passwords:Passwords export:accessibility"
    "export_contacts:Contacts export:fda"
    "export_calendars:Calendars export:fda"
    "export_reminders:Reminders export:fda"
    "export_notes:Notes export:fda"
    "export_journal:Journal export:fda"
    "export_messages:Messages export:fda"
    "export_mail:Mail export:fda"
    "export_icloud_drive:iCloud Drive export:"
    "export_files:Files export:fda"
    "export_books:Books export:fda"
    "export_freeform:Freeform export:fda,accessibility"
    "export_maps:Maps export:fda"
    "export_music_playlists:Music playlists export:music"
    "export_safari_bookmarks:Safari bookmarks export:fda"
    "export_stickies:Stickies export:fda"
    "export_text_replacements:Text Replacements export:fda"
    "export_voice_memos:Voice memos export:fda"
    "export_photos:Photos export:fda"
    "_pseudo_photos_other:Other Libraries:fda"
    "export_converted_docs:Converted Docs export:"
)

_OFF_BY_DEFAULT_LEAVES=(
    export_books
    export_freeform
    export_maps
    export_music_playlists
    export_safari_bookmarks
    export_stickies
    export_text_replacements
    export_voice_memos
)

_LEAF_SUBTOOLS_LEAF=()

_LEAF_SUBTOOLS_DEP=()

_build_leaf_index() {
    local _i _name _key
    for ((_i = 0; _i < ${#MENU_ORDER[@]}; _i++)); do
        _name="${MENU_ORDER[$_i]%%:*}"
        _key="_LEAF_IDX_${_name//./_}"
        printf -v "$_key" '%d' "$_i"
    done
}

_build_leaf_index

_wrapper_walk_photo_libraries() {
    local dir="$1" remaining="$2" entry
    for entry in "$dir"/*; do
        case "$entry" in
            *.photoslibrary)
                printf '%s\0' "$entry"
                ;;
            *)
                if [ "$remaining" -gt 1 ] && [ -d "$entry" ]; then
                    _wrapper_walk_photo_libraries "$entry" "$((remaining - 1))"
                fi
                ;;
        esac
    done
}

_wrapper_discover_system_photo_library() {
    local raw lib
    raw="$(defaults read com.apple.Photos SystemLibraryPath 2>/dev/null || true)"
    if [ -n "$raw" ]; then
        lib="$(_expand_tilde "$raw")"
        if [ -d "$lib" ] && [ -f "$lib/database/Photos.sqlite" ]; then
            printf '%s' "$lib"; return 0
        fi
    fi
    raw="$(defaults read com.apple.cloudphotod LibraryPath 2>/dev/null || true)"
    if [ -n "$raw" ]; then
        lib="$(_expand_tilde "$raw")"
        if [ -d "$lib" ] && [ -f "$lib/database/Photos.sqlite" ]; then
            printf '%s' "$lib"; return 0
        fi
    fi
    raw="$(defaults read com.apple.Photos LibraryLocation 2>/dev/null || true)"
    if [ -n "$raw" ]; then
        lib="$(_expand_tilde "$raw")"
        if [ -d "$lib" ] && [ -f "$lib/database/Photos.sqlite" ]; then
            printf '%s' "$lib"; return 0
        fi
    fi
    lib="$HOME/Pictures/Photos Library.photoslibrary"
    if [ -d "$lib" ] && [ -f "$lib/database/Photos.sqlite" ]; then
        printf '%s' "$lib"; return 0
    fi
    return 1
}

_wrapper_discover_all_photo_libraries() {
    local depth="${PHOTOS_DISCOVERY_DEPTH:-4}"
    case "$depth" in
        ''|*[!0-9]*) depth=4 ;;
        0|[1-9]*)    ;;
        *)           depth=$((10#$depth)) ;;
    esac
    [ "$depth" -lt 1 ] && depth=4
    local root="$HOME/Pictures"
    [ -d "$root" ] || return 0
    local _had_nullglob=0
    shopt -q nullglob && _had_nullglob=1
    shopt -s nullglob
    _wrapper_walk_photo_libraries "$root" "$depth" | LC_ALL=C sort -uz
    local _rc=$?
    [ "$_had_nullglob" -eq 1 ] || shopt -u nullglob
    return "$_rc"
}

_setup_enumerate_menu() {
    [ "${DOWNPOUR_MENU_FORMAT:-default}" = "enumerate" ] || return 0
    [ -n "${_ENUMERATE_SETUP_DONE:-}" ] && return 0
    _ENUMERATE_SETUP_DONE=1
    local -a _libs=()
    local p
    while IFS= read -r -d '' p; do
        _libs+=( "$p" )
    done < <(_wrapper_discover_all_photo_libraries)
    local sys_lib="" _default_sys="$HOME/Pictures/Photos Library.photoslibrary" _l
    for _l in "${_libs[@]+"${_libs[@]}"}"; do
        if [ "$_l" = "$_default_sys" ]; then sys_lib="$_default_sys"; break; fi
    done
    if [ "${#_libs[@]}" -eq 0 ]; then
        if [ ! -d "$HOME/Pictures" ]; then
            printf '  note: ~/Pictures not present — enumerate mode fell back to default Photos rows.\n' >/dev/tty 2>/dev/null || true
        fi
        return 0
    fi
    local _enum_cap="${PHOTOS_ENUM_CAP:-3}"
    case "$_enum_cap" in
        ''|*[!0-9]*|0) _enum_cap=3 ;;
        *) _enum_cap=$((10#$_enum_cap)) ;;
    esac
    [ "$_enum_cap" -gt 50 ] && _enum_cap=3
    if [ "${#_libs[@]}" -gt "$_enum_cap" ]; then
        printf '  note: enumerate-mode fell back to default Photos rows — %d libraries discovered (cap: %d).\n' "${#_libs[@]}" "$_enum_cap" >/dev/tty 2>/dev/null || true
        printf '        Use PHOTOS_ENUM_CAP=N to raise the cap, or PHOTO_LIBRARIES_EXPLICIT=... directly.\n' >/dev/tty 2>/dev/null || true
        return 0
    fi
    _PHOTOS_ENUM_LIBRARIES=( "${_libs[@]}" )
    _PHOTOS_ENUM_TAGS=()
    local _lib _tag idx=0
    for _lib in "${_libs[@]}"; do
        _tag="other"
        [ -z "$sys_lib" ] && _tag="system"
        [ -n "$sys_lib" ] && [ "$_lib" = "$sys_lib" ] && _tag="system"
        _PHOTOS_ENUM_TAGS+=( "$_tag" )
        idx=$((idx + 1))
    done
    _PHOTOS_ENUM_COUNT=$idx
    local -a _new_menu=() _replaced_names=()
    local row name _inserted=0 _stem _label _def_copy _def_report
    for row in "${MENU_ORDER[@]}"; do
        name="${row%%:*}"
        case "$name" in
            _pseudo_photos_lib_*)
                _new_menu+=( "$row" )
                ;;
            export_photos|_pseudo_photos_*)
                if [ "$_inserted" = "0" ]; then
                    local i
                    for ((i = 0; i < _PHOTOS_ENUM_COUNT; i++)); do
                        _stem="${_PHOTOS_ENUM_LIBRARIES[$i]##*/}"
                        _stem="${_stem%.photoslibrary}"
                        _stem="${_stem//:/_}"
                        _stem="${_stem//$'\x1f'/_}"
                        [ -n "$_stem" ] || _stem="lib_${i}"
                        _label="${_stem} [${_PHOTOS_ENUM_TAGS[$i]}]"
                        _new_menu+=( "_pseudo_photos_lib_${i}:${_label}:fda" )
                    done
                    _inserted=1
                fi
                _replaced_names+=( "$name" )
                continue
                ;;
            *)
                _new_menu+=( "$row" )
                ;;
        esac
    done
    MENU_ORDER=( "${_new_menu[@]}" )
    local -a _new_subflags=()
    local sf parent
    local _other_copy_default=0;   [ "${PHOTOS_OTHER_COPY:-no}"   = "yes" ] && _other_copy_default=1
    local _other_report_default=1; [ "${PHOTOS_OTHER_REPORT:-yes}" = "no" ] && _other_report_default=0
    local _sys_copy_default=1;     [ "${PHOTOS_SYS_COPY:-yes}"    = "no"  ] && _sys_copy_default=0
    local _sys_report_default=1;   [ "${PHOTOS_SYS_REPORT:-yes}"  = "no"  ] && _sys_report_default=0
    local _ss_default=1; [ "${PHOTOS_INCLUDE_SHARED_SOURCE:-yes}" = "no" ] && _ss_default=0
    local _dl_default=1; [ "${PHOTO_LIBRARY_DOWNLOAD_MISSING:-1}"  = "0"  ] && _dl_default=0
    local _sa_default=1; [ "${SHARED_COPY:-yes}"   = "no" ] && _sa_default=0
    local _sar_default=1; [ "${SHARED_REPORT:-yes}" = "no" ] && _sar_default=0
    for ((i = 0; i < _PHOTOS_ENUM_COUNT; i++)); do
        if [ "${_PHOTOS_ENUM_TAGS[$i]}" = "system" ]; then
            _def_copy="$_sys_copy_default"
            _def_report="$_sys_report_default"
        else
            _def_copy="$_other_copy_default"
            _def_report="$_other_report_default"
        fi
        _new_subflags+=( "_pseudo_photos_lib_${i}"$'\x1f'"copy"$'\x1f'"Copy originals"$'\x1f'"${_def_copy}"$'\x1f'"_PHOTOS_LIB_${i}_COPY" )
        _new_subflags+=( "_pseudo_photos_lib_${i}"$'\x1f'"report"$'\x1f'"Generate report"$'\x1f'"${_def_report}"$'\x1f'"_PHOTOS_LIB_${i}_REPORT" )
        if [ "${_PHOTOS_ENUM_TAGS[$i]}" = "system" ]; then
            _new_subflags+=( "_pseudo_photos_lib_${i}"$'\x1f'"sharedsrc"$'\x1f'"Include Shared with You + moments"$'\x1f'"${_ss_default}"$'\x1f'"_PHOTOS_INCLUDE_SHARED_SOURCE" )
            _new_subflags+=( "_pseudo_photos_lib_${i}"$'\x1f'"sharedalbums"$'\x1f'"Include shared albums"$'\x1f'"${_sa_default}"$'\x1f'"_SHARED_COPY" )
            _new_subflags+=( "_pseudo_photos_lib_${i}"$'\x1f'"sharedalbumsrep"$'\x1f'"Shared albums report"$'\x1f'"${_sar_default}"$'\x1f'"_SHARED_REPORT" )
            _new_subflags+=( "_pseudo_photos_lib_${i}"$'\x1f'"dlmissing"$'\x1f'"Download iCloud-only originals"$'\x1f'"${_dl_default}"$'\x1f'"_PHOTO_LIBRARY_DOWNLOAD_MISSING" )
        fi
    done
    for sf in "${_MENU_LEAF_SUBFLAGS[@]}"; do
        parent="${sf%%$'\x1f'*}"
        case "$parent" in
            export_photos|_pseudo_photos_other) continue ;;
            *) _new_subflags+=( "$sf" ) ;;
        esac
    done
    _MENU_LEAF_SUBFLAGS=( "${_new_subflags[@]}" )
    local _rn
    for _rn in "${_replaced_names[@]+"${_replaced_names[@]}"}"; do
        unset "_LEAF_IDX_${_rn//./_}"
    done
    _build_leaf_index
}

_LEAF_FLAGS=(
    "--no-system-originals:PHOTOS_SYS_COPY=no"
    "--no-system-report:PHOTOS_SYS_REPORT=no"
    "--other-libraries:PHOTOS_OTHER_COPY=yes"
    "--other-libraries:PHOTOS_OTHER_REPORT=yes"
    "--no-other-originals:PHOTOS_OTHER_COPY=no"
    "--no-other-report:PHOTOS_OTHER_REPORT=no"
    "--no-shared-originals:SHARED_COPY=no"
    "--no-shared-report:SHARED_REPORT=no"
    "--no-verify-shared-matches|--disable-verify-shared-matches:PHOTOS_VERIFY_SHARED_MATCHES=0"
    "--disable-protoc|--no-protoc:NOTES_FETCH_PROTOC=0"
    "--disable-imessage-exporter|--no-imessage-exporter:MESSAGES_USE_IMESSAGE_EXPORTER=0"
    "--disable-czkawka|--no-czkawka:PHOTOS_VERIFY_SHARED_MATCHES=0"
    "--disable-convert-docs|--no-convert-docs:CONVERT_DOCS=0"
)

_validate_leaf_flags() {
    local _entry _aliases _assign _env _alias _value
    for _entry in "${_LEAF_FLAGS[@]+"${_LEAF_FLAGS[@]}"}"; do
        case "$_entry" in
            *:*) ;;
            *) printf 'FATAL: malformed _LEAF_FLAGS entry (no colon): %s\n' "$_entry" >&2; exit 1 ;;
        esac
        _aliases="${_entry%%:*}"
        _assign="${_entry#*:}"
        case "$_assign" in
            [A-Za-z_]*=*) ;;
            *) printf 'FATAL: malformed _LEAF_FLAGS entry (expected NAME=VALUE assign): %s\n' "$_entry" >&2; exit 1 ;;
        esac
        _env="${_assign%%=*}"
        case "$_env" in
            *[!A-Za-z0-9_]*)
                printf 'FATAL: malformed _LEAF_FLAGS env name (must be [A-Za-z0-9_]+): %s\n' "$_env" >&2
                exit 1 ;;
        esac
        _value="${_assign#*=}"
        case "$_value" in
            *:*)
                printf 'FATAL: _LEAF_FLAGS value contains colon (reserved as the alias/assign separator; future parsers may split on it): %s\n' "$_entry" >&2
                exit 1 ;;
        esac
        case "$_aliases" in
            ''|':'*) printf 'FATAL: _LEAF_FLAGS entry has no aliases: %s\n' "$_entry" >&2; exit 1 ;;
        esac
        local _alias_arr=() _rest="$_aliases"
        while [ -n "$_rest" ]; do
            _alias_arr+=( "${_rest%%|*}" )
            case "$_rest" in *'|'*) _rest="${_rest#*|}" ;; *) _rest="" ;; esac
        done
        for _alias in "${_alias_arr[@]}"; do
            case "$_alias" in
                *:*)
                    printf 'FATAL: _LEAF_FLAGS alias contains colon (would corrupt parser): %s\n' "$_alias" >&2
                    exit 1 ;;
                '')
                    printf 'FATAL: _LEAF_FLAGS entry has empty alias in: %s\n' "$_entry" >&2
                    exit 1 ;;
            esac
        done
    done
}

_validate_leaf_flags

DOWNLOADED_SCRIPTS=()
_PHOTOS_LAUNCHED_BY_US=0
_MUSIC_LAUNCHED_BY_US=0
_MENU_SAVED_STTY=""

_du_kb() {
    local p="$1" k=0
    if [ -d "$p" ] && ls -- "$p" >/dev/null 2>&1; then
        k=$(du -skL "$p" 2>/dev/null | awk 'END{print $1}')
        case "$k" in ''|*[!0-9]*) k=0 ;; esac
    fi
    printf '%s' "$k"
}

_du_kb_warn_if_unreadable() {
    local p="$1"
    [ -d "$p" ] && ! ls -- "$p" >/dev/null 2>&1 && \
        log_warn "Can't read $p — excluding from the disk-space estimate."
}

_du_kb_excl_prior() {
    local p="$1" total prior=0 _c _ck
    total=$(_du_kb "$p")
    if [ -d "$p" ] && ls -- "$p" >/dev/null 2>&1; then
        while IFS= read -r -d '' _c; do
            _ck=$(du -skL "$_c" 2>/dev/null | awk 'END{print $1}')
            case "$_ck" in ''|*[!0-9]*) _ck=0 ;; esac
            prior=$((prior + _ck))
        done < <(find "$p" -mindepth 1 -maxdepth 1 -type d \
                    \( -name 'downpour-[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]-[0-9][0-9][0-9][0-9][0-9][0-9]' \
                       -o -name 'downpour-*-[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]-[0-9][0-9][0-9][0-9][0-9][0-9]' \
                       -o -name 'export-[0-9]*-[0-9]*-[0-9]*-[0-9]*' \) \
                    -print0 2>/dev/null)
    fi
    local _net=$((total - prior))
    [ "$_net" -lt 0 ] && _net=0
    printf '%s' "$_net"
}

_leaf_is_selected() {
    local target="$1"
    if [ "$target" = "export_photos" ] \
       && [ "${DOWNPOUR_MENU_FORMAT:-default}" = "enumerate" ] \
       && [ "${_PHOTOS_ENUM_COUNT:-0}" -gt 0 ]; then
        local _enum_idx _enum_sel_var _enum_sel _copy_var _rep_var _any_lib_sel=0
        for ((_enum_idx = 0; _enum_idx < _PHOTOS_ENUM_COUNT; _enum_idx++)); do
            _enum_sel_var="_LEAF_IDX__pseudo_photos_lib_${_enum_idx}"
            _enum_sel="${!_enum_sel_var:-}"
            [ -z "$_enum_sel" ] && continue
            [ "${_LEAF_SELECTED[$_enum_sel]:-1}" = "1" ] || continue
            _any_lib_sel=1
            _copy_var="_PHOTOS_LIB_${_enum_idx}_COPY"
            _rep_var="_PHOTOS_LIB_${_enum_idx}_REPORT"
            if [ "${!_copy_var:-0}" = "1" ] || [ "${!_rep_var:-0}" = "1" ]; then
                return 0
            fi
        done
        if [ "$_any_lib_sel" = "1" ] \
           && { [ "${_SHARED_COPY:-1}" = "1" ] || [ "${_SHARED_REPORT:-1}" = "1" ] \
                || [ "${_PHOTOS_INCLUDE_SHARED_SOURCE:-1}" = "1" ] \
                || [ "${_PHOTO_LIBRARY_DOWNLOAD_MISSING:-0}" = "1" ]; }; then
            return 0
        fi
        return 1
    fi
    local _idx_var="_LEAF_IDX_${target//./_}"
    local _i="${!_idx_var:-}"
    [ -z "$_i" ] && return 0
    [ "${_LEAF_SELECTED[$_i]:-1}" = "1" ] || return 1
    if [ "$target" = "export_photos" ]; then
        if ! _menu_parent_has_active_subflag "export_photos" \
           && ! _menu_parent_has_active_subflag "_pseudo_photos_other"; then
            return 1
        fi
    fi
    return 0
}

sanity_check_disk_space() {
    local target="$1"
    log_step "Disk-space sanity check"
    local path
    local files_kb=0 _dataless_probe _dataless_kb
    if _leaf_is_selected export_files; then
        for path in "$HOME/Documents" "$HOME/Downloads" "$HOME/Desktop" "$HOME/Public"; do
            _du_kb_warn_if_unreadable "$path"
            files_kb=$((files_kb + $(_du_kb_excl_prior "$path")))
            _dataless_probe=$(_bounded_icloud_probe "$path" dataless)
            _dataless_kb="${_dataless_probe##* }"
            case "$_dataless_kb" in ''|*[!0-9]*) _dataless_kb=0 ;; esac
            files_kb=$((files_kb + _dataless_kb))
        done
        local _fsec
        for _fsec in Pictures Movies Music; do
            [ -d "$HOME/$_fsec" ] || continue
            _du_kb_warn_if_unreadable "$HOME/$_fsec"
            files_kb=$((files_kb + $(_du_kb "$HOME/$_fsec")))
        done
        if [ -d "$HOME/Pictures" ]; then
            local _photos_lib_kb=0
            local _photos_lib_paths=()
            local _photos_lib
            for _photos_lib in "$HOME/Pictures"/*.photoslibrary; do
                [ -d "$_photos_lib" ] || continue
                _photos_lib_paths+=("$_photos_lib")
            done
            if [ "${#_photos_lib_paths[@]}" -gt 0 ]; then
                _photos_lib_kb=$(LC_ALL=C du -skL "${_photos_lib_paths[@]}" 2>/dev/null \
                    | LC_ALL=C awk '{ s += $1 } END { print s+0 }')
                case "$_photos_lib_kb" in ''|*[!0-9]*) _photos_lib_kb=0 ;; esac
                files_kb=$((files_kb - _photos_lib_kb))
            fi
        fi
        local _isk_paths=()
        for path in "$HOME/Movies/iMovie Theater.theater" \
                    "$HOME/Movies/iMovie Theater" "$HOME/Movies/TV" \
                    "$HOME/Music/Audio Music Apps" "$HOME/Music/Music"; do
            [ -e "$path" ] || continue
            _isk_paths+=("$path")
        done
        if [ "${#_isk_paths[@]}" -gt 0 ]; then
            local _isk_kb
            _isk_kb=$(LC_ALL=C du -skL "${_isk_paths[@]}" 2>/dev/null \
                | LC_ALL=C awk '{ s += $1 } END { print s+0 }')
            case "$_isk_kb" in ''|*[!0-9]*) _isk_kb=0 ;; esac
            files_kb=$((files_kb - _isk_kb))
        fi
        [ "$files_kb" -lt 0 ] && files_kb=0
        local _home_other _home_other_name
        while IFS= read -r -d '' _home_other; do
            _home_other_name="${_home_other##*/}"
            case "$_home_other_name" in
                Documents|Downloads|Desktop|Public|Movies|Music|Pictures|Library|Sites|Applications) continue ;;
                .*) continue ;;
                downpour-[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]-[0-9][0-9][0-9][0-9][0-9][0-9]) continue ;;
                downpour-*-[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]-[0-9][0-9][0-9][0-9][0-9][0-9]) continue ;;
                export-[0-9]*-[0-9]*-[0-9]*-[0-9]*) continue ;;
            esac
            files_kb=$((files_kb + $(_du_kb "$_home_other")))
        done < <(find "$HOME" -mindepth 1 -maxdepth 1 -type d -print0 2>/dev/null)
        local _lf _lf_size
        while IFS= read -r -d '' _lf; do
            case "${_lf##*/}" in .*) continue ;; esac
            _lf_size="$(stat -f '%z' "$_lf" 2>/dev/null)"
            case "$_lf_size" in ''|*[!0-9]*) _lf_size=0 ;; esac
            files_kb=$((files_kb + _lf_size / 1024))
        done < <(find "$HOME" -maxdepth 1 -type f -print0 2>/dev/null)
        [ "$files_kb" -lt 0 ] && files_kb=0
    fi
    ensure_scratch
    local _du_par_dir="$SCRATCH_DIR/du_par.$$"
    mkdir -p "$_du_par_dir" 2>/dev/null || log_warn "Could not create disk-estimate scratch dir ($_du_par_dir) — some size buckets may read 0 in the estimate."
    local -a _du_par_pids=()
    if _leaf_is_selected export_mail; then
        _du_kb_warn_if_unreadable "$HOME/Library/Mail"
        ( _du_kb "$HOME/Library/Mail" > "$_du_par_dir/mail" ) &
        _du_par_pids+=("$!")
        CHILD_PIDS+=("$!")
    fi
    if _leaf_is_selected export_messages; then
        _du_kb_warn_if_unreadable "$HOME/Library/Messages/Attachments"
        ( _du_kb "$HOME/Library/Messages/Attachments" > "$_du_par_dir/messages" ) &
        _du_par_pids+=("$!")
        CHILD_PIDS+=("$!")
    fi
    local mail_src_kb=0 mail_kb=0
    local messages_kb=0
    local icloud_kb=0 _idl _idl_kb
    if _leaf_is_selected export_icloud_drive; then
        _du_kb_warn_if_unreadable "$HOME/Library/Mobile Documents"
        icloud_kb=$(_du_kb "$HOME/Library/Mobile Documents")
        _idl=$(_bounded_icloud_probe "$HOME/Library/Mobile Documents" dataless)
        _idl_kb="${_idl##* }"
        case "$_idl_kb" in ''|*[!0-9]*) _idl_kb=0 ;; esac
        icloud_kb=$((icloud_kb + _idl_kb))
    fi
    local notes_kb=0 journal_kb=0 voice_kb=0 other_kb=0
    if _leaf_is_selected export_notes; then
        _du_kb_warn_if_unreadable "$HOME/Library/Group Containers/group.com.apple.notes/Accounts"
        notes_kb=$(_du_kb "$HOME/Library/Group Containers/group.com.apple.notes/Accounts")
    fi
    if _leaf_is_selected export_journal; then
        _du_kb_warn_if_unreadable "$HOME/Library/Group Containers/group.com.apple.moments/Library/Attachments"
        journal_kb=$(_du_kb "$HOME/Library/Group Containers/group.com.apple.moments/Library/Attachments")
    fi
    if _leaf_is_selected export_voice_memos; then
        local _vm_group="$HOME/Library/Group Containers/group.com.apple.VoiceMemos.shared/Recordings"
        local _vm_appsup="$HOME/Library/Application Support/com.apple.voicememos/Recordings"
        _du_kb_warn_if_unreadable "$_vm_group"
        _du_kb_warn_if_unreadable "$_vm_appsup"
        voice_kb=$(( $(_du_kb "$_vm_group") + $(_du_kb "$_vm_appsup") ))
    fi
    other_kb=$((notes_kb + journal_kb + voice_kb))
    local _pp _du_par_val
    for _pp in "${_du_par_pids[@]+"${_du_par_pids[@]}"}"; do
        wait "$_pp" 2>/dev/null
    done
    if [ "${#_du_par_pids[@]}" -gt 0 ]; then
        local _cp _new_cp=() _is_du
        for _cp in "${CHILD_PIDS[@]+"${CHILD_PIDS[@]}"}"; do
            _is_du=0
            for _pp in "${_du_par_pids[@]+"${_du_par_pids[@]}"}"; do
                [ "$_cp" = "$_pp" ] && { _is_du=1; break; }
            done
            [ "$_is_du" = "1" ] || _new_cp+=( "$_cp" )
        done
        CHILD_PIDS=( "${_new_cp[@]+"${_new_cp[@]}"}" )
    fi
    if [ -f "$_du_par_dir/mail" ]; then
        _du_par_val="$(cat "$_du_par_dir/mail" 2>/dev/null)"
        case "$_du_par_val" in ''|*[!0-9]*) _du_par_val=0 ;; esac
        mail_src_kb="$_du_par_val"
        mail_kb=$((mail_src_kb * 2))
    fi
    if [ -f "$_du_par_dir/messages" ]; then
        _du_par_val="$(cat "$_du_par_dir/messages" 2>/dev/null)"
        case "$_du_par_val" in ''|*[!0-9]*) _du_par_val=0 ;; esac
        messages_kb=$((_du_par_val * 3))
    fi
    rm -rf -- "$_du_par_dir" 2>/dev/null
    _DS_FILES_KB="$files_kb"
    _DS_MAIL_KB="$mail_kb"
    _DS_MESSAGES_KB="$messages_kb"
    _DS_ICLOUD_KB="$icloud_kb"
    _DS_NOTES_KB="$notes_kb"
    _DS_JOURNAL_KB="$journal_kb"
    _DS_VOICE_KB="$voice_kb"
    local total_kb=$((files_kb + mail_kb + messages_kb + icloud_kb + other_kb))
    local required_kb=$((total_kb + EXPORT_OVERHEAD_GB * 1024 * 1024))
    local files_gb mail_gb messages_gb icloud_gb other_gb required_gb avail_kb avail_gb
    files_gb=$(LC_ALL=C awk -v k="$files_kb" 'BEGIN{printf "%.1f", k/1048576}')
    mail_gb=$(LC_ALL=C awk -v k="$mail_kb" 'BEGIN{printf "%.1f", k/1048576}')
    messages_gb=$(LC_ALL=C awk -v k="$messages_kb" 'BEGIN{printf "%.1f", k/1048576}')
    icloud_gb=$(LC_ALL=C awk -v k="$icloud_kb" 'BEGIN{printf "%.1f", k/1048576}')
    other_gb=$(LC_ALL=C awk -v k="$other_kb" 'BEGIN{printf "%.1f", k/1048576}')
    required_gb=$(LC_ALL=C awk -v k="$required_kb" 'BEGIN{printf "%.1f", k/1048576}')
    avail_kb=$(df -P -k "$target" 2>/dev/null | awk 'END{print $4}')
    case "$avail_kb" in ''|*[!0-9]*) avail_kb=0 ;; esac
    avail_gb=$(LC_ALL=C awk -v k="$avail_kb" 'BEGIN{printf "%.1f", k/1048576}')
    if _leaf_is_selected export_files; then
        log_info "Files sources:         ${files_gb} GB"
    fi
    _leaf_is_selected export_mail     && log_info "Mail (×2 Thunderbird): ${mail_gb} GB"
    _leaf_is_selected export_messages && log_info "Messages attach. (×3): ${messages_gb} GB"
    _leaf_is_selected export_icloud_drive && log_info "iCloud Drive:          ${icloud_gb} GB"
    if _leaf_is_selected export_notes \
        || _leaf_is_selected export_journal \
        || _leaf_is_selected export_voice_memos; then
        log_info "Notes/Journal/Voice:   ${other_gb} GB"
    fi
    log_info "Overhead allowance:    ${EXPORT_OVERHEAD_GB} GB (set EXPORT_OVERHEAD_GB=N to override)"
    log_info "Estimated requirement: ${required_gb} GB"
    log_info "Available on target:   ${avail_gb} GB"
    local _SCRATCH_MIN_GB=5
    local _scratch="${TMPDIR:-/tmp}"
    local _target_dev _scratch_dev
    _target_dev="$(stat -f %d "$target" 2>/dev/null)"
    _scratch_dev="$(stat -f %d "$_scratch" 2>/dev/null)"
    if [ -n "$_target_dev" ] && [ -n "$_scratch_dev" ] \
       && [ "$_target_dev" != "$_scratch_dev" ]; then
        local scratch_avail_kb scratch_avail_gb
        scratch_avail_kb=$(df -P -k "$_scratch" 2>/dev/null | awk 'END{print $4}')
        case "$scratch_avail_kb" in ''|*[!0-9]*) scratch_avail_kb=0 ;; esac
        scratch_avail_gb=$(LC_ALL=C awk -v k="$scratch_avail_kb" 'BEGIN{printf "%.1f", k/1048576}')
        log_info "Available on scratch:  ${scratch_avail_gb} GB ($_scratch)"
        if [ "$scratch_avail_kb" -lt $((_SCRATCH_MIN_GB * 1024 * 1024)) ]; then
            log_warn "Scratch volume has < ${_SCRATCH_MIN_GB} GB free; mid-run snapshot/staging may fail."
        fi
    fi
    if _leaf_is_selected export_photos; then
        log_info "(Photos libraries are checked per-library at copy time, not here.)"
    fi
    local _target_fs
    _target_fs="$(_target_filesystem_type "$target")"
    case "$_target_fs" in
        ''|apfs|hfs|hfs+) : ;;
        exfat|msdos|fat32|ntfs)
            log_warn "Target volume filesystem is $_target_fs — case-insensitive, no POSIX permissions, no extended attributes."
            if _leaf_is_selected export_passwords; then
                log_warn "Passwords.csv on $_target_fs has no POSIX permissions — treat the destination drive as plaintext-sensitive."
            fi
            ;;
        smbfs|nfs|webdav|cifs|afpfs)
            log_warn "Target volume is a network filesystem ($_target_fs) — POSIX behavior depends on the server."
            if _leaf_is_selected export_passwords; then
                log_warn "Passwords.csv on $_target_fs may have server-side permissions you don't control — verify the file's accessibility post-run before sharing the export."
            fi
            ;;
        *)
            log_warn "Target volume filesystem is $_target_fs (uncommon) — behavior may differ from APFS/HFS+."
            ;;
    esac
    if [ "$avail_kb" -ge "$required_kb" ]; then
        log_ok "Space OK"
        if [ -n "${SCRATCH_DIR:-}" ] && [ -f "$SCRATCH_DIR/.icloud_probe_incomplete" ]; then
            log_warn "Disk-space estimate may be undercounted: one or more iCloud-only-content probes timed out (the actual on-disk need could be GBs higher when those iCloud-only files are downloaded on first access). Raise ICLOUD_PROBE_TIMEOUT_SEC for a more accurate figure."
            rm -f -- "$SCRATCH_DIR/.icloud_probe_incomplete" 2>/dev/null || true
        fi
        return 0
    fi
    log_warn "Free space (${avail_gb} GB) is less than the estimate (${required_gb} GB)"
    if ! [ -t 0 ]; then
        die "Insufficient space; aborting (no TTY for prompt). Free up space, lower EXPORT_OVERHEAD_GB, or set it to 0 to bypass and re-run."
    fi
    local ans=""
    _countdown_key_prompt "$CONFIRM_AUTO_NO_SEC" ans "Proceed anyway? [y/N]"
    if [ -z "$ans" ]; then
        printf '\r  Proceed anyway? [y/N] — auto-no (no input within %d s)\n' "$CONFIRM_AUTO_NO_SEC" >&2
    else
        printf '\n' >&2
    fi
    _LAST_BLANK=0
    case "$ans" in
        y|Y) log_info "Proceeding despite space warning." ;;
        *)   die "Aborted. Free up space, lower EXPORT_OVERHEAD_GB, or set it to 0 to bypass and re-run." ;;
    esac
}

_bounded_icloud_probe() {
    local path="$1" mode="$2" timeout_s="${3:-${ICLOUD_PROBE_TIMEOUT_SEC:-30}}"
    case "$timeout_s" in
        ''|*[!0-9]*) timeout_s=30 ;;
    esac
    [ "$timeout_s" -gt 3600 ] && timeout_s=30
    local _zero
    case "$mode" in
        dataless) _zero="0 0" ;;
        *)        _zero="0"   ;;
    esac
    [ -d "$path" ] || { printf '%s' "$_zero"; return; }
    ensure_scratch
    local out_f find_pid watch_pid raw timeout_sentinel
    out_f=$(mktemp "$SCRATCH_DIR/icloud-probe.XXXXXX") \
        || { printf '%s' "$_zero"; return; }
    timeout_sentinel="$out_f.timeout"
    case "$mode" in
        dataless)
            ( set -o pipefail
              find "$path" -type f -flags +dataless -print0 2>/dev/null \
                | xargs -0 stat -f '%z' 2>/dev/null \
                | awk '{ c++; s += $1 } END { printf "%d %d", c+0, int(s/1024) }' \
                > "$out_f" ) & ;;
        *)
            ( set -o pipefail
              find "$path" -type f -name '*.icloud' 2>/dev/null | wc -l > "$out_f" ) & ;;
    esac
    find_pid=$!
    CHILD_PIDS+=( "$find_pid" )
    if [ "$timeout_s" -gt 0 ]; then
        ( sleep "$timeout_s"
          if kill -0 "$find_pid" 2>/dev/null; then
              : > "$timeout_sentinel" 2>/dev/null
              kill -TERM "$find_pid" 2>/dev/null
              sleep 1
              kill -0 "$find_pid" 2>/dev/null && kill -KILL "$find_pid" 2>/dev/null
          fi
        ) >/dev/null 2>&1 &
        watch_pid=$!
        CHILD_PIDS+=( "$watch_pid" )
    fi
    wait "$find_pid" 2>/dev/null
    local find_rc=$?
    if [ -n "${watch_pid:-}" ]; then
        pkill -KILL -P "$watch_pid" 2>/dev/null || true
        kill -KILL "$watch_pid" 2>/dev/null
        wait "$watch_pid" 2>/dev/null
    fi
    _untrack_child_pid "$find_pid"
    [ -n "${watch_pid:-}" ] && _untrack_child_pid "$watch_pid"
    local _timed_out=0 _probe_failed=0
    if [ -f "$timeout_sentinel" ] \
       && [ "$find_rc" -ge 128 ] && [ "$find_rc" -le 165 ]; then
        _timed_out=1
    elif [ "$find_rc" -ne 0 ] && [ "$find_rc" -ne 1 ]; then
        _probe_failed=1
    fi
    if [ "$_timed_out" -eq 1 ]; then
        log_warn "iCloud $mode probe timed out (>${timeout_s}s) on $path — skipping (raise ICLOUD_PROBE_TIMEOUT_SEC if your iCloud tree is on a slow mount or holds many files)"
        if [ -n "${SCRATCH_DIR:-}" ] && [ -d "$SCRATCH_DIR" ]; then
            : > "$SCRATCH_DIR/.icloud_probe_incomplete" 2>/dev/null || true
        fi
        rm -f -- "$out_f" "$timeout_sentinel" 2>/dev/null
        printf '%s' "$_zero"
        return
    fi
    if [ "$_probe_failed" -eq 1 ]; then
        log_warn "iCloud $mode probe failed (rc=$find_rc) on $path — skipping (unexpected find/stat failure; not a timeout)"
        if [ -n "${SCRATCH_DIR:-}" ] && [ -d "$SCRATCH_DIR" ]; then
            : > "$SCRATCH_DIR/.icloud_probe_incomplete" 2>/dev/null || true
        fi
        rm -f -- "$out_f" "$timeout_sentinel" 2>/dev/null
        printf '%s' "$_zero"
        return
    fi
    rm -f -- "$timeout_sentinel" 2>/dev/null
    raw="$(cat "$out_f" 2>/dev/null)"
    rm -f -- "$out_f" 2>/dev/null
    if [ "$mode" = "dataless" ]; then
        case "$raw" in '') raw="$_zero" ;; esac
    else
        raw="$(printf '%s' "$raw" | tr -d ' \n')"
        case "$raw" in ''|*[!0-9]*) raw=0 ;; esac
    fi
    printf '%s' "$raw"
}

_bounded_icloud_stub_count() {
    _bounded_icloud_probe "$1" stubs "${2:-}"
}

_icloud_onoff() {
    case "$1" in
        1|true|YES) printf 'ON' ;;
        0|false|NO) printf 'off' ;;
        *)          printf 'unknown (not set / not signed in to iCloud)' ;;
    esac
}

sanity_check_icloud_status() {
    if ! _leaf_is_selected export_photos \
        && ! _leaf_is_selected export_icloud_drive \
        && ! _leaf_is_selected export_files \
        && ! _leaf_is_selected export_messages \
        && ! _leaf_is_selected export_notes \
        && ! _leaf_is_selected export_journal; then
        return 0
    fi
    log_step "iCloud-managed content"
    local _os_li _os_v
    _os_li="$(defaults read com.apple.finder FXICloudLoggedIn 2>/dev/null)"
    log_info "Optimize Storage / iCloud sync settings (offloaded content is iCloud-only and not in a local export):"
    if [ "$_os_li" = "0" ]; then
        log_info "  • Not signed in to iCloud on this Mac — the iCloud-sync toggles below read as off, and no iCloud offloading applies."
    fi
    _os_v="$(defaults read com.apple.finder FXICloudDriveEnabled 2>/dev/null)"
    log_info "  • iCloud Drive: $(_icloud_onoff "$_os_v")"
    _os_v="$(defaults read com.apple.finder FXICloudDriveDesktop 2>/dev/null)"
    log_info "  • Desktop folder syncing to iCloud (Desktop & Documents): $(_icloud_onoff "$_os_v")"
    _os_v="$(defaults read com.apple.finder FXICloudDriveDocuments 2>/dev/null)"
    log_info "  • Documents folder syncing to iCloud (Desktop & Documents): $(_icloud_onoff "$_os_v")"
    _os_v="$(defaults read com.apple.madrid CloudKitSyncEnabled 2>/dev/null)"
    log_info "  • Messages in iCloud: $(_icloud_onoff "$_os_v")"
    log_info "  • \"Optimize Mac Storage\" (offloads Photos + iCloud Drive content): no readable setting — see the per-category evicted counts below."
    local total_evicted=0
    local photos_lib="" photos_snap=""
    if _leaf_is_selected export_photos; then
        photos_lib="$(_wrapper_discover_system_photo_library 2>/dev/null || true)"
        if [ -n "$photos_lib" ]; then
            ensure_scratch
            local photos_db="$photos_lib/database/Photos.sqlite"
            photos_snap="$(snapshot_db "$photos_db" 2>/dev/null)"
            local photos_stat="" p_total="" p_cloud=""
            if [ -n "$photos_snap" ]; then
                p_total=$(sqlite3 -readonly "$photos_snap" \
                    "SELECT COUNT(*) FROM ZASSET
                     WHERE COALESCE(ZTRASHEDSTATE, 0) = 0;" 2>/dev/null)
                p_cloud=$(sqlite3 -readonly "$photos_snap" \
                    "SELECT COUNT(*) FROM ZASSET
                     WHERE COALESCE(ZTRASHEDSTATE, 0) = 0
                       AND COALESCE(ZCOMPLETE, 1) = 0
                       AND COALESCE(ZCLOUDLOCALSTATE, 0) = 1;" 2>/dev/null)
                if [ -n "$p_total" ] || [ -n "$p_cloud" ]; then
                    photos_stat="ok"
                fi
            fi
            if [ -n "$photos_stat" ]; then
                case "$p_total" in ''|*[!0-9]*) p_total=0 ;; esac
                case "$p_cloud" in ''|*[!0-9]*) p_cloud=0 ;; esac
                if [ "$p_cloud" -gt 0 ]; then
                    log_info "Photos library: $p_cloud of $p_total $(_pluralize "$p_total" original) flagged cloud-only in the database (Optimize Mac Storage). The library export copies whatever is present in originals/ on this Mac; any original kept only in iCloud isn't included. This DB flag is a rough heads-up — it under-counts and doesn't always match what's physically on disk."
                    total_evicted=$((total_evicted + p_cloud))
                else
                    log_info "Photos library: $p_total $(_pluralize "$p_total" original) in the database (own photos + iCloud Shared Album / Shared-with-You members). Own photos go to Photos/<library>/ (Not Shared / Shared by Me / Shared with You), shared albums to Shared Albums/ — so a per-library report count below $p_total is expected (it excludes the shared-source members), not a loss."
                fi
            else
                log_info "Photos library: count query failed — DB may be locked or schema-shifted."
            fi
        else
            log_info "Photos library: no system library located (Photos.app may need to be opened once)."
        fi
    fi
    if _leaf_is_selected export_photos; then
        if [ -z "$photos_lib" ]; then
            photos_lib="$(_wrapper_discover_system_photo_library 2>/dev/null || true)"
        fi
        if [ -n "$photos_lib" ] && [ -z "$photos_snap" ]; then
            ensure_scratch
            photos_snap="$(snapshot_db "$photos_lib/database/Photos.sqlite" 2>/dev/null)"
        fi
        if [ -n "$photos_snap" ]; then
            local sa_cached
            sa_cached=$(sqlite3 -readonly "$photos_snap" \
                "SELECT COALESCE(SUM(COALESCE(ZCACHEDPHOTOSCOUNT,0)
                                   + COALESCE(ZCACHEDVIDEOSCOUNT,0)), 0)
                   FROM ZGENERICALBUM
                  WHERE ZKIND IN (1505, 3571)
                    AND COALESCE(ZTRASHEDSTATE, 0) = 0
                    AND ZTITLE IS NOT NULL AND ZTITLE != '';" 2>/dev/null)
            if [ "${sa_cached:-0}" = "0" ]; then
                sa_cached=$(sqlite3 -readonly "$photos_snap" \
                    "SELECT COALESCE(SUM(ZASSETCOUNT), 0)
                       FROM ZSHARE
                      WHERE ZASSETCOUNT > 0;" 2>/dev/null)
            fi
            case "${sa_cached:-0}" in ''|*[!0-9]*) sa_cached=0 ;; esac
            if [ "$sa_cached" -gt 0 ] && { [ "${_SHARED_COPY:-1}" = "1" ] || [ "${_SHARED_REPORT:-1}" = "1" ]; }; then
                log_info "Shared albums: $sa_cached $(_pluralize "$sa_cached" asset) to fetch/catalog from Photos.app when the category runs."
            else
                log_info "Shared albums: none found (or all empty)."
            fi
            _DS_SHARED_COUNT="$sa_cached"
            _DS_SHARED_LIB="$photos_lib"
        else
            log_info "Shared albums: no system library located (Photos.app may need to be opened once)."
        fi
    fi
    if _leaf_is_selected export_icloud_drive; then
        local mobile_docs="$HOME/Library/Mobile Documents"
        if [ -d "$mobile_docs" ]; then
            local md_stubs md_dl md_dl_n
            md_stubs=$(_bounded_icloud_stub_count "$mobile_docs")
            if [ "$md_stubs" -gt 0 ]; then
                log_info "Mobile Documents: $md_stubs legacy cloud-only $(_pluralize "$md_stubs" stub) (skipped)."
                total_evicted=$((total_evicted + md_stubs))
            fi
            md_dl=$(_bounded_icloud_probe "$mobile_docs" dataless)
            md_dl_n="${md_dl%% *}"
            case "$md_dl_n" in ''|*[!0-9]*) md_dl_n=0 ;; esac
            if [ "$md_dl_n" -gt 0 ]; then
                log_info "Mobile Documents: $md_dl_n file(s) evicted to iCloud — will download on demand during the export (adds time + disk; not skipped)."
            fi
            [ "$md_stubs" -eq 0 ] && [ "$md_dl_n" -eq 0 ] && \
                log_info "Mobile Documents: all content is local."
        else
            log_info "Mobile Documents: not present (iCloud Drive disabled or new account)."
        fi
    fi
    if _leaf_is_selected export_files; then
        local files_stubs=0 files_path _path_stubs
        local files_dl_n=0 _fp_dl
        for files_path in "$HOME/Documents" "$HOME/Desktop" "$HOME/Downloads" "$HOME/Public"; do
            [ -d "$files_path" ] || continue
            _path_stubs=$(_bounded_icloud_stub_count "$files_path")
            files_stubs=$((files_stubs + _path_stubs))
            _fp_dl=$(_bounded_icloud_probe "$files_path" dataless)
            _fp_dl="${_fp_dl%% *}"
            case "$_fp_dl" in ''|*[!0-9]*) _fp_dl=0 ;; esac
            files_dl_n=$((files_dl_n + _fp_dl))
        done
        if [ "$files_stubs" -gt 0 ]; then
            log_info "Files (Documents/Desktop/Downloads/Public): $files_stubs legacy cloud-only $(_pluralize "$files_stubs" stub) (skipped)."
            total_evicted=$((total_evicted + files_stubs))
        fi
        if [ "$files_dl_n" -gt 0 ]; then
            log_info "Files (Documents/Desktop/Downloads/Public): $files_dl_n file(s) evicted to iCloud — will download on demand during the export (adds time + disk; not skipped)."
        fi
        [ "$files_stubs" -eq 0 ] && [ "$files_dl_n" -eq 0 ] && \
            log_info "Files (Documents/Desktop/Downloads/Public): all content is local."
    fi
    _icloud_probe() {
        local leaf="$1" path="$2" label="$3"
        _leaf_is_selected "$leaf" || return 0
        [ -d "$path" ] || return 0
        local count
        count=$(_bounded_icloud_stub_count "$path")
        if [ "$count" -gt 0 ]; then
            log_info "$label: $count cloud-only $(_pluralize "$count" stub) (skipped)."
            total_evicted=$((total_evicted + count))
        else
            log_info "$label: no cloud-only stubs."
        fi
    }
    _icloud_probe export_messages \
        "$HOME/Library/Messages/Attachments" \
        "Messages attachments"
    _icloud_probe export_notes \
        "$HOME/Library/Group Containers/group.com.apple.notes" \
        "Notes attachments"
    _icloud_probe export_journal \
        "$HOME/Library/Group Containers/group.com.apple.moments/Library/Attachments" \
        "Journal attachments"
    if [ "$total_evicted" -eq 0 ]; then
        log_ok "All exportable content is locally available"
    else
        log_warn "$total_evicted $(_pluralize "$total_evicted" file) cloud-only — they will be skipped or previewed"
        _blank
        log_info "To force-download before re-running, use the GUI:"
        log_info "  • iCloud Drive: Finder > right-click folder > Keep Downloaded"
        log_info "  • Photos: Photos > Settings > iCloud > Download Originals to this Mac"
        log_info "Wait for sync to finish, then re-run for a complete export."
    fi
    unset -f _icloud_probe 2>/dev/null || true
}

_LEAF_POSTPASS_HOOKS=()

preflight_tcc_gate() {
    local need_var="$1" state_var="$2" pretty="$3" probe="$4"
    local url_anchor="$5" app="$6" launch_var="$7" deny_subj="$8"
    shift 8
    [ "${!need_var:-1}" = "1" ] || return 0
    if [ -n "$app" ]; then
        if [ ! -d "/System/Applications/$app.app" ] \
           && [ ! -d "/Applications/$app.app" ] \
           && [ ! -d "$HOME/Applications/$app.app" ]; then
            export "$state_var=na"
            return 0
        fi
        local _pre
        _pre="$(pgrep -x "$app" >/dev/null 2>&1 && printf 1 || printf 0)"
        if [ -n "$launch_var" ]; then
            if [ "$_pre" = "0" ]; then printf -v "$launch_var" '1'; else printf -v "$launch_var" '0'; fi
        fi
    fi
    log_info "Checking $pretty (macOS may prompt for permission)..."
    if "$probe"; then
        log_ok "$pretty: granted"
        export "$state_var=granted"
        return 0
    fi
    log_info "$pretty not yet granted — opening System Settings."
    local _hint
    for _hint in "$@"; do
        log_info "  $_hint"
    done
    log_info "  Polling for up to ${TCC_POLL_TIMEOUT} seconds; the run will proceed when you grant."
    open "x-apple.systempreferences:com.apple.preference.security?$url_anchor" \
        >/dev/null 2>&1 || true
    if wait_for_grant "$probe" "$pretty" "$TCC_POLL_TIMEOUT"; then
        log_ok "$pretty: granted"
        export "$state_var=granted"
    else
        log_warn "$pretty not granted within ${TCC_POLL_TIMEOUT} s — $deny_subj will be skipped."
        export "$state_var=denied"
    fi
}

pre_flight_permissions() {
    if ! ( : </dev/tty ) 2>/dev/null; then
        if [ "${_NEED_FDA:-1}" = "1" ]; then
            if check_full_disk_access; then
                export _FDA_STATE=granted
            else
                die "Full Disk Access denied and no controlling TTY is available to prompt for it. Grant FDA in System Settings > Privacy & Security > Full Disk Access from a console session on the Mac, then re-run."
            fi
        fi
        return 0
    fi
    if [ "${_NEED_FDA:-1}" != "1" ] \
        && [ "${_NEED_PHOTOS_AUTO:-1}" != "1" ] \
        && [ "${_NEED_MUSIC_AUTO:-1}" != "1" ] \
        && [ "${_NEED_ACCESSIBILITY:-1}" != "1" ]; then
        return 0
    fi
    log_step "Pre-flight permissions"
    preflight_tcc_gate \
        "_NEED_FDA" "_FDA_STATE" "Full Disk Access" \
        "check_full_disk_access" "Privacy_AllFiles" \
        "" "" "FDA-requiring leaves" \
        "Add your terminal in Privacy & Security > Full Disk Access and toggle it ON."
    if [ "${_FDA_STATE:-}" = "denied" ]; then
        die "Full Disk Access denied — most categories need it, so the run would be nearly empty. Grant FDA in System Settings > Privacy & Security > Full Disk Access, then re-run."
    fi
    preflight_tcc_gate \
        "_NEED_PHOTOS_AUTO" "_PHOTOS_AUTOMATION_STATE" "Photos Automation" \
        "check_photos_automation" "Privacy_Automation" \
        "Photos" "_PHOTOS_LAUNCHED_BY_US" "export_photos" \
        "Enable Terminal → Photos in Privacy & Security > Automation."
    preflight_tcc_gate \
        "_NEED_MUSIC_AUTO" "_MUSIC_AUTOMATION_STATE" "Music Automation" \
        "check_music_automation" "Privacy_Automation" \
        "Music" "_MUSIC_LAUNCHED_BY_US" "export_music_playlists" \
        "Enable Terminal → Music in Privacy & Security > Automation."
    preflight_tcc_gate \
        "_NEED_ACCESSIBILITY" "_SYSEVENTS_AUTOMATION_STATE" "Automation (control System Events)" \
        "check_system_events_automation" "Privacy_Automation" \
        "" "" "export_passwords / export_freeform" \
        "Enable Terminal → System Events in Privacy & Security > Automation."
    if [ "${_SYSEVENTS_AUTOMATION_STATE:-}" = "denied" ]; then
        log_warn "Accessibility check skipped — 'control System Events' was denied, which the Passwords/Freeform export needs. Grant Terminal → System Events under Privacy & Security > Automation, then re-run."
        export _ACCESSIBILITY_STATE=denied
    else
        preflight_tcc_gate \
            "_NEED_ACCESSIBILITY" "_ACCESSIBILITY_STATE" "Accessibility" \
            "check_accessibility" "Privacy_Accessibility" \
            "" "" "export_passwords / export_freeform" \
            "Add your terminal in Privacy & Security > Accessibility and toggle it ON."
    fi
    quit_app_iff_we_launched_it Photos _PHOTOS_LAUNCHED_BY_US; _PHOTOS_LAUNCHED_BY_US=0
    quit_app_iff_we_launched_it Music  _MUSIC_LAUNCHED_BY_US;  _MUSIC_LAUNCHED_BY_US=0
}

wrapper_leaf_cleanup_hook() {
    quit_app_iff_we_launched_it Photos _PHOTOS_LAUNCHED_BY_US
    quit_app_iff_we_launched_it Music  _MUSIC_LAUNCHED_BY_US
    ( printf '\033[?25h' >/dev/tty ) 2>/dev/null || true
    if [ -n "$_MENU_SAVED_STTY" ]; then
        stty "$_MENU_SAVED_STTY" </dev/tty 2>/dev/null || true
        _MENU_SAVED_STTY=""
    fi
    timemachine_resume
}

_MENU_LEAF_SUBFLAGS=(
    "export_photos"$'\x1f'"copy"$'\x1f'"Copy your photos"$'\x1f'"1"$'\x1f'"_PHOTOS_SYS_COPY"
    "export_photos"$'\x1f'"report"$'\x1f'"Generate report"$'\x1f'"1"$'\x1f'"_PHOTOS_SYS_REPORT"
    "export_photos"$'\x1f'"sharedsrc"$'\x1f'"Include Shared with You + moments"$'\x1f'"1"$'\x1f'"_PHOTOS_INCLUDE_SHARED_SOURCE"
    "export_photos"$'\x1f'"sharedalbums"$'\x1f'"Include shared albums"$'\x1f'"1"$'\x1f'"_SHARED_COPY"
    "export_photos"$'\x1f'"sharedalbumsrep"$'\x1f'"Shared albums report"$'\x1f'"1"$'\x1f'"_SHARED_REPORT"
    "export_photos"$'\x1f'"dlmissing"$'\x1f'"Download iCloud-only originals"$'\x1f'"1"$'\x1f'"_PHOTO_LIBRARY_DOWNLOAD_MISSING"
    "_pseudo_photos_other"$'\x1f'"copy"$'\x1f'"Copy originals"$'\x1f'"0"$'\x1f'"_PHOTOS_OTHER_COPY"
    "_pseudo_photos_other"$'\x1f'"report"$'\x1f'"Generate report"$'\x1f'"1"$'\x1f'"_PHOTOS_OTHER_REPORT"
)

_MENU_FETCH_SUB=(
    "protoc"$'\x1f'"protoc — better Notes-body decoding"$'\x1f'"1"$'\x1f'"_FETCH_PROTOC"
    "imessage_exporter"$'\x1f'"imessage-exporter — better Messages HTML rendering"$'\x1f'"1"$'\x1f'"_FETCH_IMESSAGE_EXPORTER"
    "czkawka"$'\x1f'"czkawka — content-verify shared-album matches (Photos)"$'\x1f'"1"$'\x1f'"_FETCH_CZKAWKA"
    "libreoffice"$'\x1f'"LibreOffice — required to convert iWork files (~350 MB download)"$'\x1f'"0"$'\x1f'"_FETCH_LIBREOFFICE"
)
_PHOTOS_ENUM_COUNT=0

_PHOTOS_ENUM_LIBRARIES=()

_PHOTOS_ENUM_TAGS=()

_LEAF_FETCH_COUPLINGS=(
    "export_notes:protoc:_FETCH_PROTOC"
    "export_messages:imessage_exporter:_FETCH_IMESSAGE_EXPORTER"
    "export_photos:czkawka:_FETCH_CZKAWKA"
    "export_converted_docs:libreoffice:_FETCH_LIBREOFFICE:bidi"
)
_MENU_HEADERS_FETCH="Auto-fetch components (improves fidelity)"

_menu_parse_sub() {
    local _rest="$1" _f1 _f2 _f3 _f4 _f5 _sep=$'\x1f'
    _f1="${_rest%%${_sep}*}"
    case "$_rest" in *"$_sep"*) _rest="${_rest#*${_sep}}" ;; *) _rest="" ;; esac
    _f2="${_rest%%${_sep}*}"
    case "$_rest" in *"$_sep"*) _rest="${_rest#*${_sep}}" ;; *) _rest="" ;; esac
    _f3="${_rest%%${_sep}*}"
    case "$_rest" in *"$_sep"*) _rest="${_rest#*${_sep}}" ;; *) _rest="" ;; esac
    _f4="${_rest%%${_sep}*}"
    case "$_rest" in *"$_sep"*) _rest="${_rest#*${_sep}}" ;; *) _rest="" ;; esac
    _f5="$_rest"
    if [ -n "$_f5" ]; then
        _sub_parent="$_f1"
        _sub_key="$_f2"
        _sub_label="$_f3"
        _sub_state="$_f4"
        _sub_var="$_f5"
    else
        _sub_parent=""
        _sub_key="$_f1"
        _sub_label="$_f2"
        _sub_state="$_f3"
        _sub_var="$_f4"
    fi
}

_menu_subflags_for_leaf() {
    local _q="$1" _e
    for _e in "${_MENU_LEAF_SUBFLAGS[@]+"${_MENU_LEAF_SUBFLAGS[@]}"}"; do
        case "$_e" in
            "$_q"$'\x1f'*) printf '%s\n' "$_e" ;;
        esac
    done
}

_menu_parent_state() {
    local _q="$1" _e _on=0 _total=0
    while IFS= read -r _e; do
        [ -z "$_e" ] && continue
        _menu_parse_sub "$_e"
        _total=$((_total + 1))
        [ "${!_sub_var:-0}" = "1" ] && _on=$((_on + 1))
    done < <(_menu_subflags_for_leaf "$_q")
    if [ "$_total" -eq 0 ]; then
        printf ''
    elif [ "$_on" -eq "$_total" ]; then
        printf 'on'
    elif [ "$_on" -eq 0 ]; then
        printf 'off'
    else
        printf 'mixed'
    fi
}

_menu_parent_has_active_subflag() {
    local _s
    _s="$(_menu_parent_state "$1")"
    [ "$_s" = "on" ] || [ "$_s" = "mixed" ]
}

_leaf_description_into() {
    local _out=""
    case "$1" in
        export_contacts)         _out='vCard 3.0 + groups .csv' ;;
        export_calendars)        _out='.ics files + subscriptions .csv' ;;
        export_reminders)        _out='.ics + .csv' ;;
        export_notes)            _out='.html files + attachments' ;;
        export_journal)          _out='.html files + attachments' ;;
        export_safari_bookmarks) _out='Netscape .html' ;;
        export_passwords)        _out='plaintext .csv via Passwords.app' ;;
        export_messages)         _out='chat.db + attachments + .html' ;;
        export_mail)             _out='mbox + .emlx + attachments' ;;
        export_music_playlists)  _out='.csv + .m3u files' ;;
        export_voice_memos)      _out='.m4a audio files + transcripts' ;;
        export_photos)           _out='your photos, shared albums + Shared with You' ;;
        _pseudo_photos_other)       _out='other (non-system) photo libraries' ;;
        export_icloud_drive)     _out='iCloud Drive (locally cached)' ;;
        export_files)            _out='Documents, Downloads, etc.' ;;
        export_converted_docs)   _out='OpenDocument .odt / .ods / .odp' ;;
        export_books)            _out='Apple Books + annotations .csv' ;;
        export_stickies)         _out='.html files' ;;
        export_freeform)         _out='board files in .pdf format' ;;
        export_maps)             _out='saved places / collections / recents .csv' ;;
        export_text_replacements) _out='replacements .csv' ;;
    esac
    printf -v "$2" '%s' "$_out"
}

_leaf_menu_label_into() {
    local entry="$1" _out=""
    local name="${entry%%:*}"
    case "$name" in
        export_photos)         _out='System library' ;;
        _pseudo_photos_other)     _out='Other Libraries' ;;
        export_converted_docs) _out='Convert iWork Files' ;;
        *)
            local rest="${entry#*:}"
            local title="${rest%%:*}"
            title="${title% export}"
            if [ -z "$title" ]; then
                title="${name#export_}"
                title="${title%.sh}"
            fi
            _out="$title"
            ;;
    esac
    printf -v "$2" '%s' "$_out"
}

_menu_leaf_category_into() {
    local _out=""
    case "$1" in
        export_contacts|export_calendars|export_reminders|export_notes|export_journal|export_passwords)
            _out='Personal information' ;;
        export_messages|export_mail)
            _out='Communications' ;;
        export_photos|_pseudo_photos_other|_pseudo_photos_lib_*)
            _out='Photos' ;;
        export_icloud_drive|export_files|export_converted_docs)
            _out='Files' ;;
        *)  _out='Other' ;;
    esac
    printf -v "$2" '%s' "$_out"
}

_update_parent_state() {
    local _parent="$1" _idx="$2"
    local _s
    _s="$(_menu_parent_state "$_parent")"
    case "$_s" in
        on|mixed) _LEAF_SELECTED[$_idx]=1 ;;
        off)      _LEAF_SELECTED[$_idx]=0 ;;
    esac
}

: "${DOWNPOUR_MENU_FORMAT=enumerate}"

show_leaf_menu() {
    [ "${_DOWNPOUR_TEST_HEADLESS:-}" = "1" ] && return 0
    if ! ( : </dev/tty >/dev/tty ) 2>/dev/null; then
        die "downpour.sh requires an interactive console session on the Mac — headless / piped / cron / backgrounded runs are not supported."
    fi
    show_leaf_menu_gui
}

show_leaf_menu_gui() {
    local total_leaves=${#MENU_ORDER[@]}
    ensure_scratch
    local tsv="$SCRATCH_DIR/menu_gui_leaves.tsv"
    : > "$tsv"
    local idx leaf _label desc state _grp
    for ((idx = 0; idx < total_leaves; idx++)); do
        leaf="${MENU_ORDER[$idx]%%:*}"
        _leaf_menu_label_into "${MENU_ORDER[$idx]}" _label
        _leaf_description_into "$leaf" desc
        state="${_LEAF_SELECTED[$idx]:-1}"
        _menu_leaf_category_into "$leaf" _grp
        printf '%s\t%s\t%s\t%s\t%s\t%s\n' \
            "$idx" \
            "$(tsv_escape "$leaf")" \
            "$(tsv_escape "$_label")" \
            "$(tsv_escape "$desc")" \
            "$state" \
            "$_grp" >> "$tsv"
    done
    local sub_tsv="$SCRATCH_DIR/menu_gui_subflags.tsv"
    : > "$sub_tsv"
    local _sub _sub_parent _sub_key _sub_label _sub_state _sub_var
    for _sub in "${_MENU_LEAF_SUBFLAGS[@]+"${_MENU_LEAF_SUBFLAGS[@]}"}"; do
        _menu_parse_sub "$_sub"
        printf '%s\t%s\t%s\t%s\n' \
            "$_sub_parent" "$_sub_key" "$_sub_label" "${!_sub_var:-$_sub_state}" \
            >> "$sub_tsv"
    done
    local fetch_tsv="$SCRATCH_DIR/menu_gui_fetch.tsv"
    : > "$fetch_tsv"
    for _sub in "${_MENU_FETCH_SUB[@]}"; do
        _menu_parse_sub "$_sub"
        printf '%s\t%s\t%s\n' \
            "$_sub_key" "$_sub_label" "${!_sub_var:-$_sub_state}" >> "$fetch_tsv"
    done
    local script_file="$SCRATCH_DIR/menu_gui.applescript"
    cat > "$script_file" <<'APPLESCRIPT'
use framework "AppKit"
use scripting additions

property _countdown : __DOWNPOUR_COUNTDOWN__
property _countdownLabel : missing value
property _cancelTimer : missing value
property leafBoxes : {}
property subBoxes    : {}
property fetchBoxes  : {}
property parentBoxes : {}
property couplings : __DOWNPOUR_COUPLINGS__
property selectedCountLabel : missing value
property totalLeafCount     : 0
property chosenOutBase : "__DOWNPOUR_OUTBASE__"
property outBaseUser   : "__DOWNPOUR_OUTUSER__"
property outBaseLabel  : missing value

on readTsv(_path)
    set ca to current application
    set nsPath to ca's NSString's stringWithString:_path
    set nsStr to ca's NSString's stringWithContentsOfFile:nsPath encoding:(ca's NSUTF8StringEncoding) |error|:(missing value)
    if nsStr is missing value then return {}
    set txt to nsStr as text
    if txt is "" then return {}
    set AppleScript's text item delimiters to linefeed
    set rawLines to text items of txt
    set AppleScript's text item delimiters to ""
    set out to {}
    repeat with ln in rawLines
        if (contents of ln) is not "" then set end of out to contents of ln
    end repeat
    return out
end readTsv

on splitTab(s)
    set AppleScript's text item delimiters to tab
    set parts to text items of s
    set AppleScript's text item delimiters to ""
    return parts
end splitTab

on timerFired_(aTimer)
    set _countdown to _countdown - 1
    if _countdown <= 0 then
        aTimer's invalidate()
        (current application's NSApplication's sharedApplication())'s abortModal()
        return
    end if
    _countdownLabel's setStringValue_("Auto-canceling in " & (_countdown as text) & "s...")
end timerFired_

on _cancelModal()
    try
        if _cancelTimer is not missing value then _cancelTimer's invalidate()
    end try
    (current application's NSApplication's sharedApplication())'s abortModal()
end _cancelModal

on windowShouldClose_(sender)
    my _cancelModal()
    return true
end windowShouldClose_

on windowWillClose_(notification)
    my _cancelModal()
end windowWillClose_

on selectAll_(sender)
    repeat with entry in leafBoxes
        (item 1 of entry)'s setState_(1)
    end repeat
    repeat with entry in subBoxes
        (item 1 of entry)'s setState_(1)
    end repeat
    repeat with entry in fetchBoxes
        (item 1 of entry)'s setState_(1)
    end repeat
    my refreshAllParents()
    my updateConvertGating()
    my updateSelectedCount()
end selectAll_

on deselectAll_(sender)
    repeat with entry in leafBoxes
        (item 1 of entry)'s setState_(0)
    end repeat
    repeat with entry in subBoxes
        (item 1 of entry)'s setState_(0)
    end repeat
    repeat with pair in couplings
        my syncCoupledFetch(item 1 of pair, 0)
    end repeat
    my refreshAllParents()
    my updateConvertGating()
    my updateSelectedCount()
end deselectAll_

on parentCheckboxClicked_(sender)
    set _pname to missing value
    repeat with entry in parentBoxes
        if (item 1 of entry) is sender then
            set _pname to item 2 of entry
            exit repeat
        end if
    end repeat
    if _pname is missing value then return
    set _allOn to true
    set _anySubFound to false
    repeat with entry in subBoxes
        if (item 2 of entry) is _pname then
            set _anySubFound to true
            if ((item 1 of entry)'s state() as integer) is not 1 then set _allOn to false
        end if
    end repeat
    if not _anySubFound then return
    set _target to 1
    if _allOn then set _target to 0
    repeat with entry in subBoxes
        if (item 2 of entry) is _pname then
            (item 1 of entry)'s setState_(_target)
        end if
    end repeat
    my syncCoupledFetch(_pname, _target)
    my refreshParentBox(sender)
    my updateSelectedCount()
end parentCheckboxClicked_

on subCheckboxClicked_(sender)
    set _pname to missing value
    repeat with entry in subBoxes
        if (item 1 of entry) is sender then
            set _pname to item 2 of entry
            exit repeat
        end if
    end repeat
    if _pname is missing value then
        my updateSelectedCount()
        return
    end if
    set _anyOn to false
    repeat with entry in subBoxes
        if (item 2 of entry) is _pname then
            if ((item 1 of entry)'s state() as integer) is 1 then set _anyOn to true
        end if
    end repeat
    repeat with pentry in parentBoxes
        if (item 2 of pentry) is _pname then
            my refreshParentBox(item 1 of pentry)
            exit repeat
        end if
    end repeat
    if _anyOn then
        my syncCoupledFetch(_pname, 1)
    else
        my syncCoupledFetch(_pname, 0)
    end if
    my updateSelectedCount()
end subCheckboxClicked_

on checkboxChanged_(sender)
    set _name to missing value
    repeat with entry in leafBoxes
        if (item 1 of entry) is sender then
            if (count of entry) ≥ 3 then set _name to item 3 of entry
            exit repeat
        end if
    end repeat
    if _name is not missing value then
        my syncCoupledFetch(_name, (sender's state()) as integer)
    end if
    my updateConvertGating()
    my updateSelectedCount()
end checkboxChanged_

on updateConvertGating()
    set _anyDep to false
    repeat with entry in leafBoxes
        if (count of entry) ≥ 3 then
            set _ln to item 3 of entry
            if (_ln is "export_files") or (_ln is "export_icloud_drive") or (_ln is "export_mail") or (_ln is "export_messages") or (_ln is "export_notes") or (_ln is "export_journal") then
                if ((item 1 of entry)'s state() as integer) is 1 then set _anyDep to true
            end if
        end if
    end repeat
    set _convertBox to missing value
    repeat with entry in leafBoxes
        if (count of entry) ≥ 3 and (item 3 of entry) is "export_converted_docs" then
            set _convertBox to item 1 of entry
            exit repeat
        end if
    end repeat
    set _loBox to missing value
    repeat with fentry in fetchBoxes
        if (item 2 of fentry) is "libreoffice" then
            set _loBox to item 1 of fentry
            exit repeat
        end if
    end repeat
    if _convertBox is missing value then return
    if _anyDep then
        _convertBox's setEnabled_(true)
        if _loBox is not missing value then _loBox's setEnabled_(true)
    else
        _convertBox's setState_(0)
        _convertBox's setEnabled_(false)
        if _loBox is not missing value then
            _loBox's setState_(0)
            _loBox's setEnabled_(false)
        end if
    end if
end updateConvertGating

on syncCoupledFetch(_leafName, _state)
    set _matchName to _leafName
    if (_matchName as string) starts with "_pseudo_photos_" then set _matchName to "export_photos"
    repeat with pair in couplings
        if (item 1 of pair) is _matchName then
            set _key to item 2 of pair
            repeat with fentry in fetchBoxes
                if (item 2 of fentry) is _key then
                    (item 1 of fentry)'s setState_(_state)
                    exit repeat
                end if
            end repeat
        end if
    end repeat
end syncCoupledFetch

on fetchChanged_(sender)
    set _key to missing value
    repeat with fentry in fetchBoxes
        if (item 1 of fentry) is sender then
            set _key to item 2 of fentry
            exit repeat
        end if
    end repeat
    if _key is not missing value then
        set _newState to (sender's state()) as integer
        repeat with pair in couplings
            if (count of pair) ≥ 3 and (item 2 of pair) is _key and (item 3 of pair) is true then
                set _leafName to item 1 of pair
                repeat with entry in leafBoxes
                    if (count of entry) ≥ 3 and (item 3 of entry) is _leafName then
                        (item 1 of entry)'s setState_(_newState)
                        exit repeat
                    end if
                end repeat
            end if
        end repeat
    end if
    my updateSelectedCount()
end fetchChanged_

on refreshParentBox(_parentBox)
    set _pname to missing value
    repeat with entry in parentBoxes
        if (item 1 of entry) is _parentBox then
            set _pname to item 2 of entry
            exit repeat
        end if
    end repeat
    if _pname is missing value then return
    set _on to 0
    set _total to 0
    repeat with entry in subBoxes
        if (item 2 of entry) is _pname then
            set _total to _total + 1
            if ((item 1 of entry)'s state() as integer) is 1 then set _on to _on + 1
        end if
    end repeat
    if _total is 0 then return
    if _on is _total then
        _parentBox's setState_(1)
    else if _on is 0 then
        _parentBox's setState_(0)
    else
        _parentBox's setState_(-1)
    end if
end refreshParentBox

on refreshAllParents()
    repeat with entry in parentBoxes
        my refreshParentBox(item 1 of entry)
    end repeat
end refreshAllParents

on updateSelectedCount()
    if selectedCountLabel is missing value then return
    set _cnt to 0
    repeat with entry in leafBoxes
        set _box to item 1 of entry
        set _pname to missing value
        repeat with pe in parentBoxes
            if (item 1 of pe) is _box then
                set _pname to item 2 of pe
                exit repeat
            end if
        end repeat
        if _pname is not missing value then
            repeat with se in subBoxes
                if (item 2 of se) is _pname and ((item 1 of se)'s state() as integer) is 1 then
                    set _cnt to _cnt + 1
                    exit repeat
                end if
            end repeat
        else
            set _bs to (_box's state()) as integer
            if _bs is 1 or _bs is -1 then set _cnt to _cnt + 1
        end if
    end repeat
    selectedCountLabel's setStringValue_("Selected: " & (_cnt as text) & " of " & (totalLeafCount as text))
end updateSelectedCount

on countSubsForParent(_pn, _lines)
    set _c to 0
    repeat with _sr in _lines
        set _sf to my splitTab(contents of _sr)
        if (count of _sf) ≥ 4 and item 1 of _sf is _pn then
            set _c to _c + 1
        end if
    end repeat
    return _c
end countSubsForParent

on outBaseDisplay()
    set _h to (current application's NSHomeDirectory()) as text
    if chosenOutBase is _h then return "~"
    if chosenOutBase starts with (_h & "/") then
        return "~/" & (text ((count of _h) + 2) thru -1 of chosenOutBase)
    end if
    return chosenOutBase
end outBaseDisplay

on chooseFolder_(sender)
    set op to current application's NSOpenPanel's openPanel()
    op's setCanChooseFiles_(false)
    op's setCanChooseDirectories_(true)
    op's setAllowsMultipleSelection_(false)
    op's setCanCreateDirectories_(true)
    op's setPrompt_("Choose")
    op's setMessage_("Choose the folder to export into. A dated downpour-… folder is created inside it.")
    try
        op's setDirectoryURL_(current application's NSURL's fileURLWithPath_(chosenOutBase))
    end try
    set rc to (op's runModal()) as integer
    if rc is 1 then
        set chosenURL to op's |URL|()
        if chosenURL is not missing value then
            set chosenOutBase to (chosenURL's |path|()) as text
            if outBaseLabel is not missing value then
                outBaseLabel's setStringValue_(my outBaseDisplay())
            end if
        end if
    end if
end chooseFolder_

on run argv
    set leavesPath to (item 1 of argv) as text
    set subPath    to (item 2 of argv) as text
    set fetchPath  to (item 3 of argv) as text

    set leafLines  to my readTsv(leavesPath)
    set subLines   to my readTsv(subPath)
    set fetchLines to my readTsv(fetchPath)

    set ca to current application
    set theApp to ca's NSApplication's sharedApplication()

    set winWidth to 880
    set rowH to 22
    set headerH to 26
    set padding to 20
    set buttonAreaH to 56
    set sectionGap to 12
    set outputBandH to headerH + (sectionGap * 2) + 1
    set subIndent to 24
    set colGap to 28
    set colWidth to (winWidth - (padding * 2) - colGap) / 2
    set xL to padding
    set xR to padding + colWidth + colGap

    set leafCount  to count of leafLines
    set subCount   to count of subLines
    set fetchCount to count of fetchLines


    set hL to 0
    set hR to 0
    set lGroup to "__none__"
    set rGroup to "__none__"
    repeat with rawLine in leafLines
        set _pf to my splitTab(contents of rawLine)
        if (count of _pf) ≥ 5 then
            set _pgrp to ""
            if (count of _pf) ≥ 6 then set _pgrp to item 6 of _pf
            set _pname to item 2 of _pf
            set _psubH to (my countSubsForParent(_pname, subLines)) * rowH
            if _pgrp is "Personal information" or _pgrp is "Communications" or _pgrp is "Files" then
                if _pgrp is not lGroup then
                    if lGroup is not "__none__" then set hL to hL + sectionGap
                    set hL to hL + headerH
                    set lGroup to _pgrp
                end if
                set hL to hL + rowH + _psubH
            else
                if _pgrp is not rGroup then
                    if rGroup is not "__none__" then set hR to hR + sectionGap
                    set hR to hR + headerH
                    set rGroup to _pgrp
                end if
                set hR to hR + rowH + _psubH
            end if
        end if
    end repeat
    set leafAreaH to hL
    if hR > hL then set leafAreaH to hR

    set fetchBlockHeight to 0
    if fetchCount > 0 then
        set fetchBlockHeight to headerH + (fetchCount * rowH) + (sectionGap * 2) + 1
    end if
    set winHeight to (padding * 2) + outputBandH + headerH + leafAreaH + fetchBlockHeight + buttonAreaH

    set winRect to {{0, 0}, {winWidth, winHeight}}
    set theWindow to ca's NSWindow's alloc()
    theWindow's initWithContentRect_styleMask_backing_defer_(winRect, 3, 2, false)
    theWindow's setTitle_("downpour.sh — choose what to export")
    theWindow's |center|()
    theWindow's setReleasedWhenClosed_(false)
    theWindow's setLevel_(3)
    theWindow's setDelegate_(me)

    set content to ca's NSView's alloc()'s initWithFrame_(winRect)
    theWindow's setContentView_(content)

    set headerFont to ca's NSFont's boldSystemFontOfSize_(13)
    set secondaryColor to ca's NSColor's secondaryLabelColor()

    set yCursor to winHeight - padding

    set bandCenterY to yCursor - (headerH / 2)
    set ofHdrRect to {{padding, bandCenterY - 9}, {110, 18}}
    set ofHdr to ca's NSTextField's alloc()'s initWithFrame_(ofHdrRect)
    ofHdr's setStringValue_("Output folder")
    ofHdr's setBezeled_(false)
    ofHdr's setDrawsBackground_(false)
    ofHdr's setEditable_(false)
    ofHdr's setSelectable_(false)
    ofHdr's setFont_(headerFont)
    ofHdr's setTextColor_(secondaryColor)
    content's addSubview_(ofHdr)

    set changeRect to {{padding + 116, bandCenterY - 13}, {96, 26}}
    set changeBtn to ca's NSButton's alloc()'s initWithFrame_(changeRect)
    changeBtn's setTitle_("Change…")
    changeBtn's setBezelStyle_(1)
    changeBtn's setTarget_(me)
    changeBtn's setAction_("chooseFolder:")
    content's addSubview_(changeBtn)

    set obRect to {{padding + 226, bandCenterY - 9}, {winWidth - (padding * 2) - 226, 18}}
    set obLbl to ca's NSTextField's alloc()'s initWithFrame_(obRect)
    obLbl's setStringValue_(my outBaseDisplay())
    obLbl's setBezeled_(false)
    obLbl's setDrawsBackground_(false)
    obLbl's setEditable_(false)
    obLbl's setSelectable_(true)
    obLbl's setFont_(headerFont)
    content's addSubview_(obLbl)
    set outBaseLabel to obLbl

    set yCursor to yCursor - headerH - sectionGap
    set ofSepRect to {{padding, yCursor - 1}, {winWidth - (padding * 2), 1}}
    set ofSep to ca's NSBox's alloc()'s initWithFrame_(ofSepRect)
    ofSep's setBoxType_(2)
    content's addSubview_(ofSep)
    set yCursor to yCursor - 1 - sectionGap

    set selAllRect to {{winWidth - padding - 202, yCursor - headerH + 2}, {98, 22}}
    set selAllBtn to ca's NSButton's alloc()'s initWithFrame_(selAllRect)
    selAllBtn's setTitle_("Select all")
    selAllBtn's setBezelStyle_(1)
    selAllBtn's setTarget_(me)
    selAllBtn's setAction_("selectAll:")
    content's addSubview_(selAllBtn)

    set deselRect to {{winWidth - padding - 100, yCursor - headerH + 2}, {100, 22}}
    set deselBtn to ca's NSButton's alloc()'s initWithFrame_(deselRect)
    deselBtn's setTitle_("Deselect all")
    deselBtn's setBezelStyle_(1)
    deselBtn's setTarget_(me)
    deselBtn's setAction_("deselectAll:")
    content's addSubview_(deselBtn)

    set yCursor to yCursor - headerH

    set leafBoxes to {}
    set subBoxes to {}
    set parentBoxes to {}
    set totalLeafCount to 0
    set yLeafTop to yCursor
    set yL to yLeafTop
    set yR to yLeafTop
    set lGroup to "__none__"
    set rGroup to "__none__"
    repeat with rawLine in leafLines
        set fields to my splitTab(contents of rawLine)
        if (count of fields) ≥ 5 then
            set rowIdx to item 1 of fields
            set rowName to item 2 of fields
            set rowTitle to item 3 of fields
            set rowDesc to item 4 of fields
            set rowState to item 5 of fields
            set rowGroup to ""
            if (count of fields) ≥ 6 then set rowGroup to item 6 of fields
            set totalLeafCount to totalLeafCount + 1

            set inLeft to (rowGroup is "Personal information" or rowGroup is "Communications" or rowGroup is "Files")
            if inLeft then
                set colX to xL
                set colY to yL
                set curG to lGroup
            else
                set colX to xR
                set colY to yR
                set curG to rGroup
            end if

            if rowGroup is not curG then
                if curG is not "__none__" then set colY to colY - sectionGap
                set ghRect to {{colX, colY - headerH}, {colWidth, headerH}}
                set gh to ca's NSTextField's alloc()'s initWithFrame_(ghRect)
                gh's setStringValue_(rowGroup)
                gh's setBezeled_(false)
                gh's setDrawsBackground_(false)
                gh's setEditable_(false)
                gh's setSelectable_(false)
                gh's setFont_(headerFont)
                gh's setTextColor_(secondaryColor)
                content's addSubview_(gh)
                set colY to colY - headerH
                set curG to rowGroup
            end if

            set cbRect to {{colX + 8, colY - rowH}, {colWidth - 16, rowH}}
            set cb to ca's NSButton's alloc()'s initWithFrame_(cbRect)
            cb's setButtonType_(3) -- NSSwitchButton (checkbox style)
            set attrTitle to ca's NSMutableAttributedString's alloc()'s initWithString_(rowTitle)
            if rowDesc is not "" then
                set descPart to "   —   " & rowDesc
                set descAttr to ca's NSMutableAttributedString's alloc()'s initWithString_(descPart)
                descAttr's addAttribute_value_range_((ca's NSForegroundColorAttributeName), secondaryColor, {0, (count of descPart)})
                attrTitle's appendAttributedString_(descAttr)
            end if
            cb's setAttributedTitle_(attrTitle)
            if rowState is "1" then
                cb's setState_(1)
            else
                cb's setState_(0)
            end if
            cb's setTarget_(me)
            cb's setAction_("checkboxChanged:")
            content's addSubview_(cb)
            set end of leafBoxes to {cb, rowIdx, rowName}
            set colY to colY - rowH

            set _hasSubs to false
            repeat with subRaw in subLines
                set sf to my splitTab(contents of subRaw)
                if (count of sf) ≥ 4 and item 1 of sf is rowName then
                    if not _hasSubs then
                        cb's setAllowsMixedState_(1)
                        cb's setAction_("parentCheckboxClicked:")
                        set end of parentBoxes to {cb, rowName}
                        set _hasSubs to true
                    end if
                    set scbRect to {{colX + subIndent + 8, colY - rowH}, {colWidth - subIndent - 16, rowH}}
                    set scb to ca's NSButton's alloc()'s initWithFrame_(scbRect)
                    scb's setButtonType_(3)
                    scb's setTitle_(item 3 of sf)
                    if (item 4 of sf) is "1" then
                        scb's setState_(1)
                    else
                        scb's setState_(0)
                    end if
                    scb's setTarget_(me)
                    scb's setAction_("subCheckboxClicked:")
                    content's addSubview_(scb)
                    set end of subBoxes to {scb, rowName, item 2 of sf}
                    set colY to colY - rowH
                end if
            end repeat
            if _hasSubs then
                my refreshParentBox(cb)
            end if

            if inLeft then
                set yL to colY
                set lGroup to curG
            else
                set yR to colY
                set rGroup to curG
            end if
        end if
    end repeat

    set yCursor to yL
    if yR < yCursor then set yCursor to yR

    set fetchBoxes to {}
    if fetchCount > 0 then
        set yCursor to yCursor - sectionGap
        set sepRect to {{padding, yCursor - 1}, {winWidth - (padding * 2), 1}}
        set sepBox to ca's NSBox's alloc()'s initWithFrame_(sepRect)
        sepBox's setBoxType_(2)
        content's addSubview_(sepBox)
        set yCursor to yCursor - 1 - sectionGap
        set h3Rect to {{padding + subIndent, yCursor - headerH}, {winWidth - (padding * 2) - subIndent, headerH}}
        set h3 to ca's NSTextField's alloc()'s initWithFrame_(h3Rect)
        h3's setStringValue_("__DOWNPOUR_FETCH_HEADER__")
        h3's setBezeled_(false)
        h3's setDrawsBackground_(false)
        h3's setEditable_(false)
        h3's setSelectable_(false)
        h3's setFont_(headerFont)
        h3's setTextColor_(secondaryColor)
        content's addSubview_(h3)
        set yCursor to yCursor - headerH

        repeat with rawLine in fetchLines
            set fields to my splitTab(contents of rawLine)
            if (count of fields) ≥ 3 then
                set fetchKey to item 1 of fields
                set fetchLabel to item 2 of fields
                set fetchState to item 3 of fields

                set cbRect to {{padding + subIndent + 8, yCursor - rowH}, {winWidth - (padding * 2) - subIndent - 8, rowH}}
                set cb to ca's NSButton's alloc()'s initWithFrame_(cbRect)
                cb's setButtonType_(3)
                cb's setTitle_(fetchLabel)
                if fetchState is "1" then
                    cb's setState_(1)
                else
                    cb's setState_(0)
                end if
                cb's setTarget_(me)
                cb's setAction_("fetchChanged:")
                content's addSubview_(cb)
                set end of fetchBoxes to {cb, fetchKey}
                set yCursor to yCursor - rowH
            end if
        end repeat
    end if

    set okRect to {{winWidth - padding - 110, 14}, {110, 32}}
    set okBtn to ca's NSButton's alloc()'s initWithFrame_(okRect)
    okBtn's setTitle_("Continue")
    okBtn's setBezelStyle_(1)
    okBtn's setKeyEquivalent_(return)
    okBtn's setTarget_(theApp)
    okBtn's setAction_("stopModal")
    content's addSubview_(okBtn)

    set cancelRect to {{winWidth - padding - 230, 14}, {110, 32}}
    set cancelBtn to ca's NSButton's alloc()'s initWithFrame_(cancelRect)
    cancelBtn's setTitle_("Cancel")
    cancelBtn's setBezelStyle_(1)
    cancelBtn's setKeyEquivalent_(ASCII character 27)
    cancelBtn's setTarget_(theApp)
    cancelBtn's setAction_("abortModal")
    content's addSubview_(cancelBtn)

    set scLblRect to {{padding, 20}, {180, 18}}
    set scLbl to ca's NSTextField's alloc()'s initWithFrame_(scLblRect)
    scLbl's setStringValue_("Selected: …")
    scLbl's setBezeled_(false)
    scLbl's setDrawsBackground_(false)
    scLbl's setEditable_(false)
    scLbl's setSelectable_(false)
    scLbl's setFont_(ca's NSFont's systemFontOfSize_(11.0))
    scLbl's setTextColor_(secondaryColor)
    content's addSubview_(scLbl)
    set selectedCountLabel to scLbl

    set labelRect to {{padding + 200, 20}, {winWidth - padding - 270 - 200, 18}}
    set countdownLbl to ca's NSTextField's alloc()'s initWithFrame_(labelRect)
    countdownLbl's setStringValue_("Auto-canceling in __DOWNPOUR_COUNTDOWN__s...")
    countdownLbl's setBezeled_(false)
    countdownLbl's setDrawsBackground_(false)
    countdownLbl's setEditable_(false)
    countdownLbl's setSelectable_(false)
    countdownLbl's setFont_(ca's NSFont's systemFontOfSize_(11.0))
    countdownLbl's setTextColor_(secondaryColor)
    content's addSubview_(countdownLbl)
    set _countdownLabel to countdownLbl

    my updateConvertGating()
    my updateSelectedCount()

    set _cancelTimer to ca's NSTimer's timerWithTimeInterval_target_selector_userInfo_repeats_(1.0, me, "timerFired:", missing value, true)
    (ca's NSRunLoop's currentRunLoop())'s addTimer_forMode_(_cancelTimer, ca's NSRunLoopCommonModes)

    theApp's setActivationPolicy_(0)
    theApp's activateIgnoringOtherApps_(true)
    theWindow's makeKeyAndOrderFront_(theApp)
    theWindow's orderFrontRegardless()

    set responseCode to (theApp's runModalForWindow_(theWindow)) as integer
    _cancelTimer's invalidate()
    theWindow's orderOut_(missing value)

    if responseCode is not -1000 then return "CANCEL"

    set out to ""
    repeat with entry in leafBoxes
        set theBox to item 1 of entry
        set theIdx to item 2 of entry
        set _bs to (theBox's state()) as integer
        if _bs is 1 or _bs is -1 then
            if out is not "" then set out to out & "|"
            set out to out & "leaf:" & theIdx
        end if
    end repeat
    repeat with entry in subBoxes
        set theBox to item 1 of entry
        set theParent to item 2 of entry
        set theKey to item 3 of entry
        if ((theBox's state()) as integer) is 1 then
            if out is not "" then set out to out & "|"
            set out to out & "sub:" & theParent & ":" & theKey
        end if
    end repeat
    repeat with entry in fetchBoxes
        set theBox to item 1 of entry
        set theKey to item 2 of entry
        if ((theBox's state()) as integer) is 1 then
            if out is not "" then set out to out & "|"
            set out to out & "fetch:" & theKey
        end if
    end repeat
    if out is not "" then set out to out & "|"
    set out to out & "outbase:" & chosenOutBase
    return out
end run
APPLESCRIPT
    local _fetch_hdr_esc
    _fetch_hdr_esc="$(printf '%s' "$_MENU_HEADERS_FETCH" | LC_ALL=C tr -d '\r\n' | sed 's/[&/\]/\\&/g')"
    local _entry _l _rest _k _after _bidi _items=""
    for _entry in "${_LEAF_FETCH_COUPLINGS[@]+"${_LEAF_FETCH_COUPLINGS[@]}"}"; do
        _l="${_entry%%:*}"
        _rest="${_entry#*:}"        # key:var[:bidi]
        _k="${_rest%%:*}"
        _after="${_rest#*:}"        # var[:bidi]
        _bidi="false"
        case "$_after" in *:bidi) _bidi="true" ;; esac
        if [ -n "$_items" ]; then
            _items="${_items}, {\"${_l}\", \"${_k}\", ${_bidi}}"
        else
            _items="{\"${_l}\", \"${_k}\", ${_bidi}}"
        fi
    done
    local _couplings_as="{${_items}}"
    local _couplings_esc
    _couplings_esc="$(printf '%s' "$_couplings_as" | LC_ALL=C tr -d '\r\n' | sed 's/[&/\]/\\&/g')"
    local _outbase_raw _outbase_esc _outuser_esc
    _outbase_raw="${_OUT_BASE:-$HOME/Desktop}"
    _outbase_esc="$(printf '%s' "$_outbase_raw" | LC_ALL=C tr -d '\r\n' | LC_ALL=C sed -e 's/\\/\\\\/g' -e 's/"/\\"/g' -e 's/[&/\]/\\&/g')"
    _outuser_esc="$(id -un 2>/dev/null)"
    [ -n "$_outuser_esc" ] && _outuser_esc="$(_sanitize_name "$_outuser_esc")"
    [ -n "$_outuser_esc" ] || _outuser_esc="user"
    LC_ALL=C sed -i '' \
        -e "s/__DOWNPOUR_COUNTDOWN__/${MENU_AUTO_CANCEL_SEC}/g" \
        -e "s/__DOWNPOUR_FETCH_HEADER__/${_fetch_hdr_esc}/g" \
        -e "s/__DOWNPOUR_COUPLINGS__/${_couplings_esc}/g" \
        -e "s/__DOWNPOUR_OUTBASE__/${_outbase_esc}/g" \
        -e "s/__DOWNPOUR_OUTUSER__/${_outuser_esc}/g" \
        "$script_file"
    local _gui_result _gui_rc
    local _gui_err_file="$SCRATCH_DIR/menu_gui.err"
    printf '  Opening menu...\n\n' >/dev/tty 2>/dev/null || true
    _gui_result="$(osascript "$script_file" "$tsv" "$sub_tsv" "$fetch_tsv" 2>"$_gui_err_file")" || _gui_rc=$?
    _gui_rc=${_gui_rc:-0}
    if [ "$_gui_result" = "CANCEL" ]; then
        printf '  Canceling...\n\n'
        exit 1
    fi
    if [ "$_gui_rc" -ne 0 ]; then
        local _err_line
        while IFS= read -r _err_line; do
            [ -n "$_err_line" ] && log_err "  $_err_line"
        done < <(head -3 "$_gui_err_file" 2>/dev/null)
        die "Native (osascript) menu failed to run — cannot show the selection menu. Re-run from the Mac's console with a logged-in desktop session."
    fi
    case "$_gui_result" in
        *outbase:*)
            local _gui_ob _gui_ob_resolved
            _gui_ob="${_gui_result#*outbase:}"
            _gui_result="${_gui_result%%outbase:*}"
            _gui_result="${_gui_result%|}"
            if [ -n "$_gui_ob" ]; then
                _gui_ob_resolved="$(resolve_output_dir "$_gui_ob" 2>/dev/null)"
                if [ $? -eq 0 ] && [ -n "$_gui_ob_resolved" ]; then
                    _OUT_BASE="$_gui_ob_resolved"
                else
                    log_warn "Chosen output folder unusable (must exist and be writable): $_gui_ob — falling back to the default (~/Desktop)."
                    _OUT_BASE=""
                fi
            fi
            ;;
    esac
    local _j
    for ((_j = 0; _j < total_leaves; _j++)); do
        _LEAF_SELECTED[$_j]=0
    done
    local _rs _rs_var
    for _rs in "${_MENU_LEAF_SUBFLAGS[@]+"${_MENU_LEAF_SUBFLAGS[@]}"}"; do
        _rs_var="${_rs##*$'\x1f'}"
        case "$_rs_var" in _[A-Za-z]*) printf -v "$_rs_var" '%s' 0 ;; esac
    done
    for _rs in "${_MENU_FETCH_SUB[@]+"${_MENU_FETCH_SUB[@]}"}"; do
        _rs_var="${_rs##*$'\x1f'}"
        case "$_rs_var" in _[A-Za-z]*) printf -v "$_rs_var" '%s' 0 ;; esac
    done
    local _tok _kind _val
    local _ifs_save="$IFS"
    IFS='|'
    set -f
    set -- $_gui_result
    set +f
    IFS="$_ifs_save"
    for _tok in "$@"; do
        _kind="${_tok%%:*}"
        _val="${_tok#*:}"
        case "$_kind" in
            leaf)
                case "$_val" in ''|*[!0-9]*) continue ;; esac
                if [ "$_val" -lt "$total_leaves" ]; then
                    _LEAF_SELECTED[$_val]=1
                fi
                ;;
            sub)
                local _sub_parent_token="${_val%%:*}"
                local _sub_key_token="${_val#*:}"
                local _smatch
                for _smatch in "${_MENU_LEAF_SUBFLAGS[@]+"${_MENU_LEAF_SUBFLAGS[@]}"}"; do
                    _menu_parse_sub "$_smatch"
                    if [ "$_sub_parent" = "$_sub_parent_token" ] \
                       && [ "$_sub_key" = "$_sub_key_token" ]; then
                        printf -v "$_sub_var" '1'
                        break
                    fi
                done
                ;;
            fetch)
                local _smatch
                for _smatch in "${_MENU_FETCH_SUB[@]+"${_MENU_FETCH_SUB[@]}"}"; do
                    _menu_parse_sub "$_smatch"
                    if [ "$_sub_key" = "$_val" ]; then
                        printf -v "$_sub_var" '1'
                        break
                    fi
                done
                ;;
        esac
    done
    local _coalesce_parent _coalesce_idx _coalesce_entry _coalesce_seen=""
    for _coalesce_entry in "${_MENU_LEAF_SUBFLAGS[@]+"${_MENU_LEAF_SUBFLAGS[@]}"}"; do
        _coalesce_parent="${_coalesce_entry%%$'\x1f'*}"
        case " $_coalesce_seen " in *" $_coalesce_parent "*) continue ;; esac
        _coalesce_seen="$_coalesce_seen $_coalesce_parent"
        local _cv="_LEAF_IDX_${_coalesce_parent//./_}"
        _coalesce_idx="${!_cv:-}"
        [ -z "$_coalesce_idx" ] && continue
        if _menu_parent_has_active_subflag "$_coalesce_parent"; then
            _LEAF_SELECTED[$_coalesce_idx]=1
        else
            _LEAF_SELECTED[$_coalesce_idx]=0
        fi
    done
    return 0
}

_HERE=""
_PIPED_MODE="no"
_OUT_DIR=""
_OKS=0
_FAILS=0
_MENU_SKIPS=0
_PERM_SKIPS=0
_USER_SKIPS=0

_LEAF_OUTCOMES=()
_RUN_ATTENTION_N=0

_RUN_WARNINGS=()
_CURRENT_LEAF_IDX=""
_CURRENT_LEAF_TOTAL=""
_CURRENT_LEAF_NAME=""
_CURRENT_LEAF_PID=""

wrapper_info_handler_hook() {
    if [ -n "$_CURRENT_LEAF_NAME" ] && [ -n "$_CURRENT_LEAF_IDX" ]; then
        printf '  [info] active category: [%s/%s] %s (pid %s)\n' \
            "$_CURRENT_LEAF_IDX" "$_CURRENT_LEAF_TOTAL" \
            "$_CURRENT_LEAF_NAME" "${_CURRENT_LEAF_PID:-?}" >&2
    fi
}

parse_args() {
    local arg
    local _entry _aliases _assign _env _value
    local _alias _matched
    _OUT_BASE=""
    local _positional_count=0
    local _end_opts=0
    for arg in "$@"; do
        if [ "$_end_opts" -eq 0 ]; then
            case "$arg" in
                --) _end_opts=1; continue ;;
                --no-menu|--unattended|--skip-menu)
                    die "Unattended runs are not supported — downpour.sh requires the interactive console GUI menu (the --no-menu / --unattended / --skip-menu flags were removed)." ;;
            esac
        fi
        _matched=0
        if [ "$_end_opts" -eq 0 ]; then
            for _entry in "${_LEAF_FLAGS[@]+"${_LEAF_FLAGS[@]}"}"; do
                _aliases="${_entry%%:*}"
                _assign="${_entry#*:}"
                _env="${_assign%%=*}"
                _value="${_assign#*=}"
                local _this_matched=0
                local _alias_arr=() _arest="$_aliases"
                while [ -n "$_arest" ]; do
                    _alias_arr+=( "${_arest%%|*}" )
                    case "$_arest" in *'|'*) _arest="${_arest#*|}" ;; *) _arest="" ;; esac
                done
                for _alias in "${_alias_arr[@]+"${_alias_arr[@]}"}"; do
                    if [ "$_alias" = "$arg" ]; then
                        _this_matched=1
                        break
                    fi
                done
                if [ "$_this_matched" = "1" ]; then
                    export "$_env=$_value"
                    _matched=1
                fi
            done
            [ "$_matched" = "1" ] && continue
        fi
        case "$arg" in
            -*) [ "$_end_opts" -eq 0 ] && die "Unknown flag: $arg" ;;
        esac
        case "$arg" in
            *)
                _positional_count=$((_positional_count + 1))
                if [ "$_positional_count" -gt 1 ]; then
                    die "Too many positional arguments: '$arg' (already saw '$_OUT_BASE'). Pass exactly one output base folder; the dated subfolder is appended automatically."
                fi
                _OUT_BASE="$arg"
                ;;
        esac
    done
}

run_menu() {
    _validate_menu_auto_cancel
    local _i
    _LEAF_SELECTED=()
    for ((_i = 0; _i < ${#MENU_ORDER[@]}; _i++)); do
        _LEAF_SELECTED[$_i]=1
    done
    local _off_leaf _off_var _off_idx
    for _off_leaf in "${_OFF_BY_DEFAULT_LEAVES[@]+"${_OFF_BY_DEFAULT_LEAVES[@]}"}"; do
        _off_var="_LEAF_IDX_${_off_leaf}"
        _off_idx="${!_off_var:-}"
        [ -n "$_off_idx" ] && _LEAF_SELECTED[$_off_idx]=0
    done
    case "${CONVERT_DOCS:-0}" in
        n*|N*|0|f*|F*)
            local _cd_idx="${_LEAF_IDX_export_converted_docs:-}"
            [ -n "$_cd_idx" ] && _LEAF_SELECTED[$_cd_idx]=0
            ;;
    esac
    _PHOTOS_SYS_COPY=1
    _PHOTOS_SYS_REPORT=1
    _PHOTOS_OTHER_COPY=0
    _PHOTOS_OTHER_REPORT=1
    _SHARED_COPY=1
    _SHARED_REPORT=1
    _PHOTOS_INCLUDE_SHARED_SOURCE=1
    _PHOTO_LIBRARY_DOWNLOAD_MISSING=1
    [ "${PHOTOS_SYS_COPY:-yes}"    = "no"  ] && _PHOTOS_SYS_COPY=0
    [ "${PHOTOS_SYS_REPORT:-yes}"  = "no"  ] && _PHOTOS_SYS_REPORT=0
    [ "${PHOTOS_OTHER_COPY:-no}"   = "yes" ] && _PHOTOS_OTHER_COPY=1
    [ "${PHOTOS_OTHER_REPORT:-yes}" = "no" ] && _PHOTOS_OTHER_REPORT=0
    [ "${SHARED_COPY:-yes}"        = "no"  ] && _SHARED_COPY=0
    [ "${SHARED_REPORT:-yes}"      = "no"  ] && _SHARED_REPORT=0
    [ "${PHOTOS_INCLUDE_SHARED_SOURCE:-yes}" = "no" ] && _PHOTOS_INCLUDE_SHARED_SOURCE=0
    [ "${PHOTO_LIBRARY_DOWNLOAD_MISSING:-1}" = "0"  ] && _PHOTO_LIBRARY_DOWNLOAD_MISSING=0
    _FETCH_PROTOC=1
    _FETCH_IMESSAGE_EXPORTER=1
    _FETCH_CZKAWKA=1
    _FETCH_LIBREOFFICE=1
    [ "${NOTES_FETCH_PROTOC:-1}" = "0" ] && _FETCH_PROTOC=0
    [ "${MESSAGES_USE_IMESSAGE_EXPORTER:-1}" = "0" ] && _FETCH_IMESSAGE_EXPORTER=0
    [ "${PHOTOS_VERIFY_SHARED_MATCHES:-1}" = "0" ] && _FETCH_CZKAWKA=0
    case "${CONVERT_DOCS:-0}" in n*|N*|0|f*|F*) _FETCH_LIBREOFFICE=0 ;; esac
    if [ "${DOWNPOUR_MENU_FORMAT:-default}" = "enumerate" ] \
       && [ "${_PHOTOS_ENUM_COUNT:-0}" -gt 0 ]; then
        local _sf _sf_parent _sub_parent _sub_key _sub_label _sub_state _sub_var
        for _sf in "${_MENU_LEAF_SUBFLAGS[@]}"; do
            _sf_parent="${_sf%%$'\x1f'*}"
            case "$_sf_parent" in
                _pseudo_photos_lib_*) ;;
                *) continue ;;
            esac
            _menu_parse_sub "$_sf"
            if [ -z "${!_sub_var:-}" ]; then
                printf -v "$_sub_var" '%s' "$_sub_state"
            fi
        done
    fi
    show_leaf_menu
    if [ "$_FETCH_PROTOC" = "0" ]; then NOTES_FETCH_PROTOC=0; else NOTES_FETCH_PROTOC=1; fi
    export NOTES_FETCH_PROTOC
    if [ "$_FETCH_IMESSAGE_EXPORTER" = "0" ]; then MESSAGES_USE_IMESSAGE_EXPORTER=0; else MESSAGES_USE_IMESSAGE_EXPORTER=1; fi
    export MESSAGES_USE_IMESSAGE_EXPORTER
    if [ "$_FETCH_CZKAWKA" = "0" ]; then PHOTOS_VERIFY_SHARED_MATCHES=0; else PHOTOS_VERIFY_SHARED_MATCHES=1; fi
    export PHOTOS_VERIFY_SHARED_MATCHES
    if [ "$_FETCH_LIBREOFFICE" = "0" ]; then CONVERT_DOCS=0; else CONVERT_DOCS=1; fi
    export CONVERT_DOCS
    local _rec_parent _rec_idx _rec_var
    local _seen_parents=""
    local _sub_entry _sf_parent
    for _sub_entry in "${_MENU_LEAF_SUBFLAGS[@]+"${_MENU_LEAF_SUBFLAGS[@]}"}"; do
        _sf_parent="${_sub_entry%%$'\x1f'*}"
        case "$_seen_parents " in *" $_sf_parent "*) continue ;; esac
        _seen_parents="$_seen_parents $_sf_parent"
        _rec_var="_LEAF_IDX_${_sf_parent//./_}"
        _rec_idx="${!_rec_var:-}"
        [ -n "$_rec_idx" ] && _update_parent_state "$_sf_parent" "$_rec_idx"
    done
    if [ "${DOWNPOUR_MENU_FORMAT:-default}" = "enumerate" ] \
       && [ "${_PHOTOS_ENUM_COUNT:-0}" -gt 0 ]; then
        local _enum_idx
        for ((_enum_idx = 0; _enum_idx < _PHOTOS_ENUM_COUNT; _enum_idx++)); do
            _rec_parent="_pseudo_photos_lib_${_enum_idx}"
            _rec_var="_LEAF_IDX__pseudo_photos_lib_${_enum_idx}"
            _rec_idx="${!_rec_var:-}"
            [ -n "$_rec_idx" ] && _update_parent_state "$_rec_parent" "$_rec_idx"
        done
    fi
}

compute_run_scope() {
    _NEED_FDA=0
    _NEED_PHOTOS_AUTO=0
    _NEED_MUSIC_AUTO=0
    _NEED_ACCESSIBILITY=0
    _SELECTED_COUNT=0
    local _i _name _entry _rest _perms
    for ((_i = 0; _i < ${#SCRIPTS_IN_ORDER[@]}; _i++)); do
        _entry="${SCRIPTS_IN_ORDER[$_i]}"
        _name="${_entry%%:*}"
        _leaf_is_selected "$_name" || continue
        _SELECTED_COUNT=$((_SELECTED_COUNT + 1))
        _rest="${_entry#*:}"
        case "$_rest" in *:*) _perms="${_rest#*:}" ;; *) _perms="" ;; esac
        case ",$_perms," in *,fda,*|*,fda[?],*)                     _NEED_FDA=1 ;; esac
        case ",$_perms," in *,photos,*|*,photos[?],*)               _NEED_PHOTOS_AUTO=1 ;; esac
        case ",$_perms," in *,music,*|*,music[?],*)                 _NEED_MUSIC_AUTO=1 ;; esac
        case ",$_perms," in *,accessibility,*|*,accessibility[?],*) _NEED_ACCESSIBILITY=1 ;; esac
    done
    if _leaf_is_selected export_photos \
       && { [ "${_PHOTO_LIBRARY_DOWNLOAD_MISSING:-1}" = "1" ] \
            || [ "${_SHARED_COPY:-1}" != "0" ]; }; then
        _NEED_PHOTOS_AUTO=1
    fi
    if [ "$_SELECTED_COUNT" -eq 0 ]; then
        log_info "Nothing selected — exiting without changes."
        mark_success
        print_summary
        exit 0
    fi
}

surface_photos_passthroughs() {
    if [ "${DOWNPOUR_MENU_FORMAT:-default}" = "enumerate" ] \
       && [ "${_PHOTOS_ENUM_COUNT:-0}" -gt 0 ]; then
        unset PHOTO_LIBRARIES_EXPLICIT
    fi
    if [ "${_PHOTOS_SYS_COPY:-1}"     = "1" ]; then PHOTOS_SYS_COPY=yes;     else PHOTOS_SYS_COPY=no;     fi
    if [ "${_PHOTOS_SYS_REPORT:-1}"   = "1" ]; then PHOTOS_SYS_REPORT=yes;   else PHOTOS_SYS_REPORT=no;   fi
    if [ "${_PHOTOS_OTHER_COPY:-0}"   = "1" ]; then PHOTOS_OTHER_COPY=yes;   else PHOTOS_OTHER_COPY=no;   fi
    if [ "${_PHOTOS_OTHER_REPORT:-0}" = "1" ]; then PHOTOS_OTHER_REPORT=yes; else PHOTOS_OTHER_REPORT=no; fi
    if [ "${_SHARED_COPY:-1}"         = "1" ]; then SHARED_COPY=yes;         else SHARED_COPY=no;         fi
    if [ "${_SHARED_REPORT:-1}"       = "1" ]; then SHARED_REPORT=yes;       else SHARED_REPORT=no;       fi
    if [ "${_PHOTOS_INCLUDE_SHARED_SOURCE:-1}" = "1" ]; then PHOTOS_INCLUDE_SHARED_SOURCE=yes; else PHOTOS_INCLUDE_SHARED_SOURCE=no; fi
    if [ "${_PHOTO_LIBRARY_DOWNLOAD_MISSING:-1}" = "1" ]; then PHOTO_LIBRARY_DOWNLOAD_MISSING=1; else PHOTO_LIBRARY_DOWNLOAD_MISSING=0; fi
    export PHOTOS_SYS_COPY PHOTOS_SYS_REPORT PHOTOS_OTHER_COPY PHOTOS_OTHER_REPORT
    export SHARED_COPY SHARED_REPORT
    export PHOTOS_INCLUDE_SHARED_SOURCE PHOTO_LIBRARY_DOWNLOAD_MISSING
    if [ "${DOWNPOUR_MENU_FORMAT:-default}" = "enumerate" ] \
       && [ "${_PHOTOS_ENUM_COUNT:-0}" -gt 0 ]; then
        local _enum_idx _enum_sel_var _enum_sel _copy_var _rep_var _copy _rep _tuple _tuples=""
        for ((_enum_idx = 0; _enum_idx < _PHOTOS_ENUM_COUNT; _enum_idx++)); do
            _enum_sel_var="_LEAF_IDX__pseudo_photos_lib_${_enum_idx}"
            _enum_sel="${!_enum_sel_var:-}"
            [ -z "$_enum_sel" ] && continue
            [ "${_LEAF_SELECTED[$_enum_sel]:-1}" = "1" ] || continue
            _copy_var="_PHOTOS_LIB_${_enum_idx}_COPY"
            _rep_var="_PHOTOS_LIB_${_enum_idx}_REPORT"
            _copy=no; _rep=no
            [ "${!_copy_var:-0}" = "1" ] && _copy=yes
            [ "${!_rep_var:-0}"  = "1" ] && _rep=yes
            [ "$_copy" = "no" ] && [ "$_rep" = "no" ] && continue
            local _enum_lib_path="${_PHOTOS_ENUM_LIBRARIES[$_enum_idx]}"
            _enum_lib_path="${_enum_lib_path//$'\x1f'/ }"
            _enum_lib_path="${_enum_lib_path//$'\x1e'/ }"
            _tuple="$_enum_lib_path"$'\x1e'"$_copy"$'\x1e'"$_rep"
            if [ -z "$_tuples" ]; then
                _tuples="$_tuple"
            else
                _tuples="${_tuples}"$'\x1f'"$_tuple"
            fi
        done
        if [ -n "$_tuples" ]; then
            PHOTO_LIBRARIES_EXPLICIT="$_tuples"
            export PHOTO_LIBRARIES_EXPLICIT
            local _sep_only="${_tuples//[!$'\x1f']/}"
            local _ec=$((${#_sep_only} + 1))
            log_info "Photos enumerate mode: $_ec $(_pluralize "$_ec" library libraries) selected"
        fi
    fi
    if [ "${DOWNPOUR_MENU_FORMAT:-default}" != "enumerate" ]; then
        if _leaf_is_selected export_photos; then
            if [ "$PHOTOS_SYS_COPY" = "no" ] || [ "$PHOTOS_SYS_REPORT" = "no" ]; then
                log_info "Photos system library: copy=${PHOTOS_SYS_COPY}, report=${PHOTOS_SYS_REPORT}"
            fi
            if [ "$PHOTOS_OTHER_COPY" = "yes" ] || [ "$PHOTOS_OTHER_REPORT" = "yes" ]; then
                log_info "Photos other libraries: copy=${PHOTOS_OTHER_COPY}, report=${PHOTOS_OTHER_REPORT}"
            fi
            if [ "$SHARED_COPY" = "no" ] || [ "$SHARED_REPORT" = "no" ]; then
                log_info "Shared albums: copy=${SHARED_COPY}, report=${SHARED_REPORT}"
            fi
        fi
    fi
}

_validate_menu_auto_cancel() {
    case "$MENU_AUTO_CANCEL_SEC" in
        ''|*[!0-9]*) log_warn "MENU_AUTO_CANCEL_SEC must be a positive integer; got '$MENU_AUTO_CANCEL_SEC' — using 60."
                     MENU_AUTO_CANCEL_SEC=60 ;;
        0|[1-9]*)    ;;
        *)           MENU_AUTO_CANCEL_SEC=$((10#$MENU_AUTO_CANCEL_SEC)) ;;
    esac
    [ "$MENU_AUTO_CANCEL_SEC" = "0" ] && MENU_AUTO_CANCEL_SEC=60
    [ "$MENU_AUTO_CANCEL_SEC" -gt 86400 ] && MENU_AUTO_CANCEL_SEC=60
}

_validate_runtime_config() {
    case "$EXPORT_OVERHEAD_GB" in
        ''|*[!0-9]*) log_warn "EXPORT_OVERHEAD_GB must be a non-negative integer; got '$EXPORT_OVERHEAD_GB' — using 10."
                     EXPORT_OVERHEAD_GB=10 ;;
        0|[1-9]*)    ;;
        *)           EXPORT_OVERHEAD_GB=$((10#$EXPORT_OVERHEAD_GB)) ;;
    esac
    if [ "$EXPORT_OVERHEAD_GB" -gt 1048576 ]; then
        log_warn "EXPORT_OVERHEAD_GB=$EXPORT_OVERHEAD_GB is implausibly large — using 10."
        EXPORT_OVERHEAD_GB=10
    fi
    case "$CONFIRM_AUTO_NO_SEC" in
        ''|*[!0-9]*) log_warn "CONFIRM_AUTO_NO_SEC must be a positive integer; got '$CONFIRM_AUTO_NO_SEC' — using 10."
                     CONFIRM_AUTO_NO_SEC=10 ;;
        0|[1-9]*)    ;;
        *)           CONFIRM_AUTO_NO_SEC=$((10#$CONFIRM_AUTO_NO_SEC)) ;;
    esac
    [ "$CONFIRM_AUTO_NO_SEC" = "0" ] && CONFIRM_AUTO_NO_SEC=1
}

prepare_workspace() {
    if [ -f "${BASH_SOURCE[0]:-}" ] && [ -r "${BASH_SOURCE[0]}" ]; then
        _HERE="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" 2>/dev/null && pwd)" || \
            die "Cannot resolve the directory containing this script"
    else
        ensure_scratch
        _HERE="$SCRATCH_DIR/scripts"
        mkdir -p "$_HERE" || die "Cannot create scripts directory under scratch"
        _PIPED_MODE="yes"
        CLEAN_DOWNLOADS=1
    fi
    local _out_base_resolved
    _out_base_resolved="$(resolve_output_dir "${_OUT_BASE:-}")" || exit 1
    local stamp _mac_user
    _mac_user="$(id -un 2>/dev/null)"
    [ -n "$_mac_user" ] || _mac_user="${USER:-user}"
    _mac_user="$(_sanitize_name "$_mac_user")"
    case "$_mac_user" in ''|Untitled) _mac_user="user" ;; esac
    stamp="$(date +%Y-%m-%d-%H%M%S)"
    [ -n "$stamp" ] || die "date command failed — cannot timestamp the export folder."
    _OUT_DIR="$_out_base_resolved/downpour-$_mac_user-$stamp"
    if [ -e "$_OUT_DIR" ] || [ -L "$_OUT_DIR" ]; then
        die "Output folder already exists: $_OUT_DIR
  Wait a second and re-run."
    fi
    track_output_path "$_OUT_DIR"
    mkdir "$_OUT_DIR" || die "Cannot create $_OUT_DIR (already exists or parent unwritable)"
    log_info "Output folder: $_OUT_DIR"
    local _logfile="$_OUT_DIR/_downpour_log.txt"
    local _ansi_strip='s/'$'\033''\[[0-9;?]*[A-Za-z]//g; s/.*'$'\r''//g'
    [ -t 1 ] && export _DOWNPOUR_FORCE_TTY_OUT=1
    [ -t 2 ] && export _DOWNPOUR_FORCE_TTY_ERR=1
    local _sel_names="" _sn _sn_title
    for _sn in "${SCRIPTS_IN_ORDER[@]}"; do
        _leaf_is_selected "${_sn%%:*}" || continue
        _sn_title="${_sn#*:}"; _sn_title="${_sn_title%%:*}"
        _sel_names="${_sel_names:+$_sel_names, }${_sn_title% export}"
    done
    {
        printf '\357\273\277'
        printf 'downpour.sh — iCloud data export for macOS\n'
        printf 'Run:      %s\n' "$(date '+%Y-%m-%d %H:%M:%S %z' 2>/dev/null)"
        printf 'Host:     %s\n' "$(hostname -s 2>/dev/null || printf 'unknown')"
        printf 'macOS:    %s\n' "$(sw_vers -productVersion 2>/dev/null || printf 'unknown')"
        printf 'Folder:   %s\n' "$_OUT_DIR"
        printf 'Selected: %s\n' "${_sel_names:-(none)}"
        printf '%s\n' '────────────────────────────────────────────────────────────────────'
    } >> "$_logfile" 2>/dev/null || true
    exec > >(tee >(LC_ALL=C sed -E -l "$_ansi_strip" >> "$_logfile"))
    CHILD_PIDS+=( "$!" )
    _TEE_PIDS+=( "$!" )
    exec 2> >(tee >(LC_ALL=C sed -E -l "$_ansi_strip" >> "$_logfile") >&2)
    CHILD_PIDS+=( "$!" )
    _TEE_PIDS+=( "$!" )
    ensure_scratch
    _LEAF_COUNTS_DIR="$SCRATCH_DIR/leaf_counts"
    mkdir -p "$_LEAF_COUNTS_DIR" || die "Cannot create leaf-counts directory"
    export _LEAF_COUNTS_DIR
    _REPORT_STORE="$SCRATCH_DIR/_report_entries"
    : > "$_REPORT_STORE" 2>/dev/null || die "Cannot create the report entries store"
    _EXPORT_ROOT="$_OUT_DIR"
    export _REPORT_STORE _EXPORT_ROOT
    if [ "${#_PRE_PREPARE_WARNS[@]}" -gt 0 ]; then
        local _bw
        for _bw in "${_PRE_PREPARE_WARNS[@]+"${_PRE_PREPARE_WARNS[@]}"}"; do
            printf '%s\n' "$_bw" >> "$_LEAF_COUNTS_DIR/$$.warns" 2>/dev/null || true
        done
        _PRE_PREPARE_WARNS=()
    fi
    if [ "${#_PRE_PREPARE_ERRS[@]}" -gt 0 ]; then
        local _be
        for _be in "${_PRE_PREPARE_ERRS[@]+"${_PRE_PREPARE_ERRS[@]}"}"; do
            printf '%s\n' "$_be" >> "$_LEAF_COUNTS_DIR/$$.errs" 2>/dev/null || true
        done
        _PRE_PREPARE_ERRS=()
    fi
    _validate_runtime_config
}

run_preflight() {
    pre_flight_permissions
    sanity_check_disk_space "$_OUT_DIR"
    sanity_check_icloud_status
    estimate_leaf_runtimes
    timemachine_suspend
}

estimate_leaf_runtimes() {
    _RUNTIME_TOTAL_SEC=0
    _rt_set() {
        local _name="$1" _sec="$2"
        case "$_sec" in ''|*[!0-9]*) _sec=0 ;; esac
        local _key="_LEAF_RT_${_name//[^A-Za-z0-9_]/_}"
        printf -v "$_key" '%s' "$_sec"
        _RUNTIME_TOTAL_SEC=$((_RUNTIME_TOTAL_SEC + _sec))
    }
    _rt_bytes_sec() {
        local _kb="${1:-0}"
        case "$_kb" in ''|*[!0-9]*) _kb=0 ;; esac
        local _sec=$((_kb / 256000))
        [ "$_sec" -lt 5 ] && _sec=5
        printf '%s' "$_sec"
    }
    local _name
    for _name in export_contacts export_calendars \
                 export_reminders export_notes \
                 export_journal export_maps \
                 export_text_replacements export_safari_bookmarks \
                 export_stickies export_music_playlists; do
        _leaf_is_selected "$_name" || continue
        _rt_set "$_name" 5
    done
    _leaf_is_selected export_passwords && _rt_set export_passwords 60
    if _leaf_is_selected export_freeform; then
        local _ff_db="$HOME/Library/Group Containers/group.com.apple.freeform/Boards/boards.db"
        local _ff_n=0 _ff_snap _ff_sec
        if [ -f "$_ff_db" ]; then
            ensure_scratch
            _ff_snap="$(snapshot_db "$_ff_db" 2>/dev/null)" || _ff_snap=""
            if [ -n "$_ff_snap" ]; then
                _ff_n="$(sqlite3 -readonly "$_ff_snap" \
                    "SELECT COUNT(*) FROM boards WHERE COALESCE(deleted_time, 0) = 0;" \
                    2>/dev/null)"
                case "$_ff_n" in ''|*[!0-9]*) _ff_n=0 ;; esac
            fi
        fi
        _ff_sec=$((_ff_n * 15 + 5))
        _rt_set export_freeform "$_ff_sec"
    fi
    _leaf_is_selected export_files        && _rt_set export_files        "$(_rt_bytes_sec "${_DS_FILES_KB:-0}")"
    _leaf_is_selected export_mail         && _rt_set export_mail         "$(_rt_bytes_sec "${_DS_MAIL_KB:-0}")"
    _leaf_is_selected export_messages     && _rt_set export_messages     "$(_rt_bytes_sec "${_DS_MESSAGES_KB:-0}")"
    _leaf_is_selected export_icloud_drive && _rt_set export_icloud_drive "$(_rt_bytes_sec "${_DS_ICLOUD_KB:-0}")"
    _leaf_is_selected export_voice_memos  && _rt_set export_voice_memos  "$(_rt_bytes_sec "${_DS_VOICE_KB:-0}")"
    if _leaf_is_selected export_books; then
        local _books_kb
        _books_kb="$(_du_kb "$HOME/Library/Containers/com.apple.BKAgentService/Data/Documents")"
        _rt_set export_books "$(_rt_bytes_sec "$_books_kb")"
    fi
    if _leaf_is_selected export_photos; then
        local _ph_kb=0 _ph _ph_seen=""
        if [ -n "${_DS_SHARED_LIB:-}" ] && [ -d "$_DS_SHARED_LIB" ]; then
            _ph_kb=$((_ph_kb + $(_du_kb "$_DS_SHARED_LIB")))
            _ph_seen="$_DS_SHARED_LIB"
        fi
        for _ph in "$HOME/Pictures"/*.photoslibrary; do
            [ -d "$_ph" ] || continue
            [ "$_ph" = "$_ph_seen" ] && continue
            _ph_kb=$((_ph_kb + $(_du_kb "$_ph")))
        done
        _rt_set export_photos "$(_rt_bytes_sec "$_ph_kb")"
    fi
    if _leaf_is_selected export_photos \
       && { [ "${_SHARED_COPY:-1}" = "1" ] || [ "${_SHARED_REPORT:-1}" = "1" ]; }; then
        local _sa_cached_kb=0 _sa_count="${_DS_SHARED_COUNT:-0}"
        local _sa_scope="${_DS_SHARED_LIB:-}/scopes/cloudsharing/data"
        case "$_sa_count" in ''|*[!0-9]*) _sa_count=0 ;; esac
        if [ -n "${_DS_SHARED_LIB:-}" ] && [ -d "$_sa_scope" ]; then
            _sa_cached_kb="$(_du_kb "$_sa_scope")"
            case "$_sa_cached_kb" in ''|*[!0-9]*) _sa_cached_kb=0 ;; esac
        fi
        local _sa_sec=$(( _sa_cached_kb / 256000 + _sa_count * 5 ))
        [ "$_sa_sec" -lt 5 ] && _sa_sec=5
        local _pr="_LEAF_RT_export_photos" _prc
        _prc="${!_pr:-0}"; case "$_prc" in ''|*[!0-9]*) _prc=0 ;; esac
        printf -v "$_pr" '%s' "$(( _prc + _sa_sec ))"
        _RUNTIME_TOTAL_SEC=$(( _RUNTIME_TOTAL_SEC + _sa_sec ))
    fi
    if _leaf_is_selected export_converted_docs; then
        case "${CONVERT_DOCS:-1}" in
            n*|N*|0|f*|F*) : ;;
            *) _rt_set export_converted_docs 90 ;;
        esac
    fi
    unset -f _rt_set _rt_bytes_sec 2>/dev/null || true
}

_launch_leaf() {
    local _leaf_name="$1" _leaf_out="$2"
    export _INVOKED_BY_WRAPPER=1
    export _LEAF_COUNTS_ID="${3:-$$}"
    local _cat="${_leaf_name#export_}"; _cat="${_cat%.sh}"
    trap '' USR1 2>/dev/null || true
    WARN_COUNT=0; ERR_COUNT=0; SUCCESS_FLAG="no"; _CLEANUP_RUNNING=0
    SCRATCH_DIR=""
    OUTPUT_PATHS_TO_CLEAN=(); CHILD_PIDS=(); _TEE_PIDS=()
    _PRE_PREPARE_WARNS=(); _PRE_PREPARE_ERRS=()
    _TM_SUSPENDED=0; _LAST_BLANK=0; [ "${_INVOKED_BY_WRAPPER:-0}" = "1" ] && _LAST_BLANK=1
    DOWNPOUR_TRACE_FILE=""; _BANNER_SHOWN=0; _ACTIVITY_TS=""
    _HB_PID=""; _PROGRESS_TICK_WARNED=""; _CSV_OVERSIZE_WARNED=""
    if declare -F "${_cat}_leaf_cleanup_hook" >/dev/null 2>&1; then
        eval "leaf_cleanup_hook() { ${_cat}_leaf_cleanup_hook; }"
    else
        eval 'leaf_cleanup_hook() { timemachine_resume; }'
    fi
    if declare -F "${_cat}_info_handler_hook" >/dev/null 2>&1; then
        eval "info_handler_hook() { ${_cat}_info_handler_hook; }"
    else
        unset -f info_handler_hook 2>/dev/null || true
    fi
    if declare -F "${_cat}__skip_handler" >/dev/null 2>&1; then
        eval "_skip_handler() { ${_cat}__skip_handler; }"
    else
        eval '_skip_handler() { return 0; }'
    fi
    trap 'trap "" INT TERM HUP QUIT USR1; _abort_ack; cleanup_handler 130' INT
    trap 'trap "" INT TERM HUP QUIT USR1; _abort_ack; cleanup_handler 143' TERM
    trap 'trap "" INT TERM HUP QUIT USR1; _abort_ack; cleanup_handler 129' HUP
    trap 'trap "" INT TERM HUP QUIT USR1; _abort_ack; cleanup_handler 131' QUIT
    trap cleanup_handler EXIT
    trap info_handler INFO 2>/dev/null || true
    trap _skip_handler USR1 2>/dev/null || true
    trap '' PIPE
    "${_cat}_main" "$_leaf_out"
}

_untrack_child_pid() {
    local _target="$1" _cp _new=()
    for _cp in "${CHILD_PIDS[@]+"${CHILD_PIDS[@]}"}"; do
        [ "$_cp" = "$_target" ] && continue
        _new+=( "$_cp" )
    done
    CHILD_PIDS=( "${_new[@]+"${_new[@]}"}" )
}

run_leaves() {
    local s name title perms _rest skip_reason rc
    local total=${#SCRIPTS_IN_ORDER[@]}
    local idx=0
    local _sel_total=0 _sel_idx=0 _desel_names="" _pp _pp_name _pp_title
    for _pp in "${SCRIPTS_IN_ORDER[@]}"; do
        _pp_name="${_pp%%:*}"; _pp_title="${_pp#*:}"; _pp_title="${_pp_title%%:*}"
        if _leaf_is_selected "$_pp_name"; then
            _sel_total=$((_sel_total + 1))
        else
            _desel_names="${_desel_names:+$_desel_names, }${_pp_title% export}"
        fi
    done
    _CURRENT_LEAF_TOTAL="$_sel_total"
    log_step "Running exports"
    if [ -n "${_RUNTIME_TOTAL_SEC:-}" ]; then
        log_info "Estimated total runtime: ~$(_fmt_duration "$_RUNTIME_TOTAL_SEC")"
    fi
    [ -n "$_desel_names" ] && \
        log_info "Not selected ($((total - _sel_total))): $_desel_names"
    if ( : </dev/tty >/dev/tty ) 2>/dev/null; then
        _leaf_is_selected export_photos \
            && log_info "While Photos is running, press 's' to skip its current copy / hash / download operation and continue."
        log_info "Ctrl-C aborts the whole run — partial output is kept (flagged incomplete); re-run for a complete export."
    fi
    for s in "${SCRIPTS_IN_ORDER[@]}"; do
        idx=$((idx + 1))
        name="${s%%:*}"
        _rest="${s#*:}"
        title="${_rest%%:*}"
        case "$_rest" in
            *:*) perms="${_rest#*:}" ;;
            *)   perms="" ;;
        esac
        _CURRENT_LEAF_NAME="$name"
        mark_activity
        skip_reason=""
        if ! _leaf_is_selected "$name"; then
            skip_reason="deselected via menu"
        fi
        if [ -z "$skip_reason" ]; then
            local _perm_check _perm_token _state_var _denied_msg _na_msg _advisory
            for _perm_check in \
                "fda:_FDA_STATE:FDA not granted:" \
                "photos:_PHOTOS_AUTOMATION_STATE:Photos Automation not granted:Photos.app not installed" \
                "music:_MUSIC_AUTOMATION_STATE:Music Automation not granted:Music.app not installed" \
                "accessibility:_ACCESSIBILITY_STATE:Accessibility not granted:"; do
                [ -n "$skip_reason" ] && break
                _perm_token="${_perm_check%%:*}"
                local _pc_rest="${_perm_check#*:}"
                _state_var="${_pc_rest%%:*}"
                _pc_rest="${_pc_rest#*:}"
                _denied_msg="${_pc_rest%%:*}"
                _na_msg="${_pc_rest#*:}"
                _advisory=0
                case ",$perms," in
                    *,${_perm_token}[?],*) _advisory=1 ;;
                    *,$_perm_token,*)    ;;
                    *)           continue ;;
                esac
                [ "$_advisory" = "1" ] && continue
                case "${!_state_var:-}" in
                    denied) skip_reason="$_denied_msg" ;;
                    na)     [ -n "$_na_msg" ] && skip_reason="$_na_msg" ;;
                esac
            done
        fi
        if [ "$skip_reason" = "deselected via menu" ]; then
            _MENU_SKIPS=$((_MENU_SKIPS + 1))
            _LEAF_OUTCOMES+=( "$title"$'\x1f'"skipped — $skip_reason" )
            continue
        fi
        _sel_idx=$((_sel_idx + 1))
        _CURRENT_LEAF_IDX="$_sel_idx"
        log_step "[$_sel_idx/$_sel_total] $title"
        if [ -n "$skip_reason" ]; then
            log_warn "Skipping $name — $skip_reason."
            _PERM_SKIPS=$((_PERM_SKIPS + 1))
            _LEAF_OUTCOMES+=( "$title"$'\x1f'"skipped — $skip_reason" )
            continue
        fi
        local _probe
        if ! _probe="$(mktemp "$_OUT_DIR/.downpour-writeprobe.XXXXXX" 2>/dev/null)"; then
            _probe="$_OUT_DIR/.downpour-writeprobe.$$"
        fi
        track_output_path "$_probe"
        if [ ! -d "$_OUT_DIR" ] || ! ( dd if=/dev/zero of="$_probe" bs=1024 count=1 2>/dev/null ); then
            die "Export folder is no longer writable — the output drive was likely ejected or filled mid-run. $((idx - 1)) of $total categories completed before this point; reconnect or free space on the drive and re-run. Path: $_OUT_DIR"
        fi
        rm -f -- "$_probe" 2>/dev/null
        _untrack_output_path "$_probe"
        local _leaf_id="l$idx"
        if [ "$name" = "export_passwords" ]; then
            _launch_leaf "$name" "$_OUT_DIR" "$_leaf_id" &
        else
            _launch_leaf "$name" "$_OUT_DIR" "$_leaf_id" </dev/null &
        fi
        local pid=$!
        CHILD_PIDS+=( "$pid" )
        [ -n "${_LEAF_COUNTS_DIR:-}" ] && rm -f -- "$_LEAF_COUNTS_DIR/$_leaf_id".* 2>/dev/null
        _CURRENT_LEAF_PID="$pid"
        local _key _reader_pid=""
        if [ "$name" = "export_photos" ] \
            && ( : </dev/tty >/dev/tty ) 2>/dev/null; then
            _MENU_SAVED_STTY="$(stty -g </dev/tty 2>/dev/null || true)"
            if [ -n "$_MENU_SAVED_STTY" ]; then
                stty -echo -icanon min 1 time 0 </dev/tty 2>/dev/null || true
                (
                    _r_streak=0 _r_sec=-1
                    while kill -0 "$pid" 2>/dev/null; do
                        if IFS= read -r -t 1 -n 1 _key </dev/tty 2>/dev/null; then
                            _r_streak=0; _r_sec=-1
                            case "$_key" in
                                s|S)
                                    if kill -0 "$pid" 2>/dev/null; then
                                        printf '\n' >&2
                                        log_info "Skip requested — sending SIGUSR1 to $name (pid $pid)"
                                        kill -USR1 "$pid" 2>/dev/null || true
                                    fi ;;
                            esac
                        else
                            if [ "$SECONDS" = "$_r_sec" ]; then
                                _r_streak=$((_r_streak + 1))
                            else
                                _r_sec="$SECONDS"; _r_streak=1
                            fi
                            if [ "$_r_streak" -gt 5 ]; then
                                log_warn "/dev/tty unreadable; abandoning keystroke poll for the rest of $name (s/skip won't work for this category)"
                                break
                            fi
                        fi
                    done
                ) &
                _reader_pid=$!
                CHILD_PIDS+=( "$_reader_pid" )
            fi
        fi
        while :; do
            wait "$pid"
            rc=$?
            [ "$rc" -gt 128 ] && kill -0 "$pid" 2>/dev/null && continue
            break
        done
        if [ -n "$_reader_pid" ]; then
            kill -KILL "$_reader_pid" 2>/dev/null || true
            wait "$_reader_pid" 2>/dev/null || true
            _untrack_child_pid "$_reader_pid"
            _reader_pid=""
        fi
        if [ -n "$_MENU_SAVED_STTY" ]; then
            stty "$_MENU_SAVED_STTY" </dev/tty 2>/dev/null || true
            _MENU_SAVED_STTY=""
        fi
        _CURRENT_LEAF_PID=""
        _CURRENT_LEAF_IDX=""
        _CURRENT_LEAF_NAME=""
        _LAST_BLANK=0
        _untrack_child_pid "$pid"
        if [ "$rc" -eq 0 ]; then
            if [ -n "${_LEAF_COUNTS_DIR:-}" ] && [ -e "$_LEAF_COUNTS_DIR/$_leaf_id.skipped" ]; then
                _USER_SKIPS=$((_USER_SKIPS + 1))
                _LEAF_OUTCOMES+=( "$title"$'\x1f'"skipped — user pressed 's'" )
            elif [ -n "${_LEAF_COUNTS_DIR:-}" ] && [ -e "$_LEAF_COUNTS_DIR/$_leaf_id.nocontent" ]; then
                _OKS=$((_OKS + 1))
                _LEAF_OUTCOMES+=( "$title"$'\x1f'"completed — no content" )
            else
                _OKS=$((_OKS + 1))
                _LEAF_OUTCOMES+=( "$title"$'\x1f'"completed" )
            fi
        elif [ "$rc" -eq 158 ]; then
            _USER_SKIPS=$((_USER_SKIPS + 1))
            log_warn "$name was killed by the skip signal before it finished starting up — treating as skipped. (Wait for a category's own header line before pressing 's' to avoid this.)"
            _LEAF_OUTCOMES+=( "$title"$'\x1f'"skipped — landed before the leaf could install its handler" )
        elif [ "$rc" -ge 128 ] && [ "$rc" -le 165 ]; then
            trap '' INT TERM HUP QUIT
            log_err "$name killed by signal (exit code $rc) — aborting the rest of the run."
            _LEAF_OUTCOMES+=( "$title"$'\x1f'"ABORTED (signal $((rc - 128)))" )
            _FAILS=$((_FAILS + 1))
            _CURRENT_LEAF_PID=""
            _CURRENT_LEAF_IDX=""
            _CURRENT_LEAF_NAME=""
            if [ -n "${_LEAF_COUNTS_DIR:-}" ] \
               && [ -s "$_LEAF_COUNTS_DIR/$_leaf_id.warns" ]; then
                local _wl_abort
                while IFS= read -r _wl_abort; do
                    _wl_abort="${_wl_abort//$'\x1f'/ }"
                    _RUN_WARNINGS+=( "$title"$'\x1f'"$_wl_abort" )
                done < "$_LEAF_COUNTS_DIR/$_leaf_id.warns"
            fi
            trap '' INT TERM HUP QUIT USR1
            if [ "${#_TEE_PIDS[@]}" -gt 0 ]; then
                exec >/dev/null 2>&1
            fi
            exit "$rc"
        else
            _FAILS=$((_FAILS + 1))
            log_err "$name exited with code $rc"
            _LEAF_OUTCOMES+=( "$title"$'\x1f'"FAILED (exit code $rc)" )
            if [ -n "${_LEAF_COUNTS_DIR:-}" ]; then
                : > "$_LEAF_COUNTS_DIR/$_leaf_id.failed" 2>/dev/null || true
            fi
        fi
        if [ -n "${_LEAF_COUNTS_DIR:-}" ] \
           && [ -s "$_LEAF_COUNTS_DIR/$_leaf_id.warns" ]; then
            local _wl
            while IFS= read -r _wl; do
                _wl="${_wl//$'\x1f'/ }"
                _RUN_WARNINGS+=( "$title"$'\x1f'"$_wl" )
            done < "$_LEAF_COUNTS_DIR/$_leaf_id.warns"
        fi
    done
    _CURRENT_LEAF_IDX=""
    _CURRENT_LEAF_NAME=""
    _CURRENT_LEAF_PID=""
}

write_export_summary() {
    local out_dir="$1"
    local manifest="$out_dir/_downpour_report.txt"
    local _entry _title _name _status _fail_tail
    for _entry in "${_LEAF_OUTCOMES[@]+"${_LEAF_OUTCOMES[@]}"}"; do
        _title="${_entry%%$'\x1f'*}"
        _status="${_entry#*$'\x1f'}"
        _name="${_title% export}"
        case "$_status" in
            completed)
                report_status exported "$_name" ;;
            "completed — no content")
                report_status empty "$_name" ;;
            "skipped — deselected via menu")
                report_status deselected "$_name" ;;
            "skipped — user pressed 's'")
                report_incomplete "$_name" "you skipped this category" \
                    "you pressed 's' during this leaf, so it produced no output — re-run the wrapper without skipping this category for a complete export." ;;
            FAILED*)
                _fail_tail="${_status#FAILED}"; _fail_tail="${_fail_tail# }"
                report_incomplete "$_name" "the export failed${_fail_tail:+ $_fail_tail}" \
                    "the leaf exited with an error — see the run log for the cause, fix it, then re-run." ;;
            skipped*)
                report_incomplete "$_name" "not run (${_status#skipped — })" \
                    "a category you selected could not run — resolve the cause shown in the run log, then re-run." ;;
            *)
                report_incomplete "$_name" "$_status" "" ;;
        esac
    done
    local _ww
    if [ -n "${_LEAF_COUNTS_DIR:-}" ] && [ -s "$_LEAF_COUNTS_DIR/$$.warns" ]; then
        while IFS= read -r _ww; do
            case "$_ww" in
                "Skipping "*) continue ;;
            esac
            report_warning "downpour.sh" "$_ww"
        done < "$_LEAF_COUNTS_DIR/$$.warns"
    fi
    for _entry in "${_RUN_WARNINGS[@]+"${_RUN_WARNINGS[@]}"}"; do
        _ww="${_entry%%$'\x1f'*}"; report_warning "${_ww% export}" "${_entry#*$'\x1f'}"
    done
    local _report_tmp="${SCRATCH_DIR:-/tmp}/_downpour_report.body.$$"
    { printf '\357\273\277'; _report_frame "${out_dir##*/}"; _emit_report_body; } > "$_report_tmp" 2>/dev/null
    if [ -s "$_report_tmp" ] && cp -- "$_report_tmp" "$manifest" 2>/dev/null; then
        mark_success
        rm -f -- "$_report_tmp" 2>/dev/null
        return 0
    else
        rm -f -- "$_report_tmp" 2>/dev/null
        log_err "Could not write _downpour_report.txt to $manifest — the export volume may be read-only or full."
        [ "${_RUN_ATTENTION_N:-0}" -eq 0 ] && _RUN_ATTENTION_N=1
        return 1
    fi
}

_manifest_human_size() {
    local _b="${1:-0}"
    case "$_b" in ''|*[!0-9]*) _b=0 ;; esac
    if [ "$_b" -lt 1024 ]; then _MAN_HS="$_b B"; return; fi
    local _tenths=$(( _b * 10 )) _unit=B
    set -- KB MB GB TB PB
    while [ "$_tenths" -ge 10240 ] && [ "$#" -gt 0 ]; do
        _unit="$1"; shift
        _tenths=$(( (_tenths + 512) / 1024 ))
    done
    if [ $(( _tenths % 10 )) -eq 0 ]; then
        _MAN_HS="$(( _tenths / 10 )) $_unit"
    else
        _MAN_HS="$(( _tenths / 10 )).$(( _tenths % 10 )) $_unit"
    fi
}

_manifest_emit_children() {
    local _dir="$1" _entry _name _esc _kb _fcount _b _noun _rel _href
    for _entry in "$_dir"/*; do
        [ -e "$_entry" ] || continue        # backstop if nullglob is off (empty dir)
        _name="${_entry##*/}"
        case "$_name" in
            .DS_Store|_downpour_report.html|_downpour_report.html.tmp.*) continue ;;
            _downpour_log.txt|_downpour_report.txt) continue ;;
        esac
        _esc="$_name"
        _esc="${_esc//&/&amp;}"; _esc="${_esc//</&lt;}"; _esc="${_esc//>/&gt;}"
        _esc="${_esc//\"/&quot;}"; _esc="${_esc//\'/&#39;}"
        if [ -d "$_entry" ] && [ ! -L "$_entry" ]; then
            _fcount="$(find "$_entry" -type f ! -name '.DS_Store' 2>/dev/null | wc -l | tr -d ' ')"
            case "$_fcount" in ''|*[!0-9]*) _fcount=0 ;; esac
            _kb="$(du -sk "$_entry" 2>/dev/null | awk 'NR==1{print $1}')"
            case "$_kb" in ''|*[!0-9]*) _kb=0 ;; esac
            _noun=files; [ "$_fcount" = "1" ] && _noun=file
            _manifest_human_size $(( _kb * 1024 ))
            printf '<details><summary><span class="dir">%s</span><span class="meta">%s %s &middot; %s</span></summary><div class="kids">\n' \
                "$_esc" "$_fcount" "$_noun" "$_MAN_HS"
            _manifest_emit_children "$_entry"
            printf '</div></details>\n'
        else
            _b="$(stat -f%z "$_entry" 2>/dev/null)"
            case "$_b" in ''|*[!0-9]*) _b=0 ;; esac
            _manifest_human_size "$_b"
            _rel="${_entry#"$_MAN_ROOT"/}"
            _href="$_rel"
            _href="${_href//%/%25}"; _href="${_href//#/%23}"
            _href="${_href//\?/%3F}"; _href="${_href// /%20}"
            _href="${_href//&/&amp;}"; _href="${_href//</&lt;}"
            _href="${_href//>/&gt;}"; _href="${_href//\"/&quot;}"
            printf '<div class="file"><a class="fname" href="%s">%s</a><span class="meta">%s</span></div>\n' \
                "$_href" "$_esc" "$_MAN_HS"
        fi
    done
}

write_report_html() {
    local _out="$1"
    [ -n "$_out" ] && [ -d "$_out" ] || return 0
    local _tree=1 _tree_off_by_knob=0
    case "${DOWNPOUR_HTML_MANIFEST:-1}" in 0|n*|N*|f*|F*) _tree=0; _tree_off_by_knob=1 ;; esac
    _MAN_ROOT="${_out%/}"
    local _total_files _total_kb _cap _name_esc _gen _tmp
    _total_files="$(find "$_out" -type f ! -name '.DS_Store' ! -name '_downpour_report.html' ! -name '_downpour_report.html.tmp.*' ! -name '_downpour_log.txt' ! -name '_downpour_report.txt' 2>/dev/null | wc -l | tr -d ' ')"
    case "$_total_files" in ''|*[!0-9]*) _total_files=0 ;; esac
    _cap="${DOWNPOUR_MANIFEST_MAX_FILES:-50000}"
    case "$_cap" in ''|*[!0-9]*) _cap=50000 ;; esac
    if [ "$_total_files" -gt "$_cap" ]; then
        log_info "Report written without the file tree — $_total_files files exceeds the $_cap cap (raise DOWNPOUR_MANIFEST_MAX_FILES to force)."
        _tree=0
    fi
    _total_kb="$(du -sk "$_out" 2>/dev/null | awk 'NR==1{print $1}')"
    case "$_total_kb" in ''|*[!0-9]*) _total_kb=0 ;; esac
    _name_esc="${_out##*/}"
    _name_esc="${_name_esc//&/&amp;}"; _name_esc="${_name_esc//</&lt;}"; _name_esc="${_name_esc//>/&gt;}"
    _name_esc="${_name_esc//\"/&quot;}"; _name_esc="${_name_esc//\'/&#39;}"
    _gen="$(date '+%Y-%m-%d %H:%M' 2>/dev/null)"
    _tmp="$(mktemp "$_out/_downpour_report.html.tmp.XXXXXX" 2>/dev/null)" || return 0
    track_output_path "$_tmp"
    local _man_ng=0 _man_dg=0
    shopt -q nullglob && _man_ng=1; shopt -q dotglob && _man_dg=1
    shopt -s nullglob dotglob
    {
        cat <<'HTML_HEAD'
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>downpour report</title>
<style>
  /* RULE: every colour literal lives in a :root block; dark + print :root
     come LAST (a media query adds no specificity). See docs/output-contract
     "The report stylesheet" before changing any of this. */
  :root {
    color-scheme: light dark;
    --bg:#f5f5f7; --card:#fff; --tile:rgba(0,0,0,.025); --chip:rgba(0,0,0,.055);
    --hover:rgba(0,0,0,.05); --ink:#1d1d1f; --dim2:#515154; --dim:#6e6e73;
    --line:rgba(0,0,0,.10); --line2:rgba(0,0,0,.16);
    --accent:#0066cc; --accentbg:rgba(0,102,204,.10); --accentline:rgba(0,102,204,.28);
    --ok:#14672c; --okbg:rgba(26,127,55,.12); --okline:rgba(26,127,55,.30);
    --err:#c11c26; --errbg:rgba(209,36,47,.12); --errline:rgba(209,36,47,.30);
    --warn:#8f6100; --shadow:0 1px 2px rgba(0,0,0,.05);
    /* Six type steps, ~10% apart. Set sizes ONLY from these. */
    --fs-xs:.75rem; --fs-sm:.85rem; --fs-md:.95rem;
    --fs-lg:1.05rem; --fs-num:1.2rem; --fs-xl:1.3rem;
    --font:-apple-system, BlinkMacSystemFont, "SF Pro Text", system-ui, sans-serif;
    --head:-apple-system, BlinkMacSystemFont, "SF Pro Display", system-ui, sans-serif;
    --mono:ui-monospace, "SF Mono", SFMono-Regular, Menlo, Consolas, monospace;
  }
  * { box-sizing: border-box; }
  body { margin: 0; padding: 2rem 1rem 4rem; background: var(--bg);
         color: var(--ink); font: 15px/1.55 var(--font);
         -webkit-text-size-adjust: 100%; }
  .wrap { max-width: 880px; margin: 0 auto; }
  a { color: var(--accent); text-decoration: none; }
  a:hover { text-decoration: underline; }
  a:focus-visible, button:focus-visible, input:focus-visible,
  summary:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
  header.card { background: var(--card); border: 1px solid var(--line);
         border-radius: 14px; padding: 1.35rem 1.5rem 1.5rem;
         margin-bottom: 1.25rem; box-shadow: var(--shadow); }
  header.card h1 { display: flex; flex-wrap: wrap; align-items: baseline;
         gap: .6rem; margin: 0 0 .3rem; font: 600 var(--fs-xl)/1.2 var(--head);
         letter-spacing: -.015em; }
  .wm { color: var(--accent); }
  header.card .sub { color: var(--dim); font-size: var(--fs-sm);
         font-family: var(--mono); word-break: break-all; }
  .stats { display: grid; grid-template-columns: repeat(auto-fit, minmax(9.5rem, 1fr));
         gap: .5rem; margin-top: 1.1rem; }
  .stat { display: flex; flex-direction: column; gap: .15rem;
         padding: .6rem .75rem; border: 1px solid var(--line);
         border-radius: 10px; background: var(--tile); }
  .stat b { font-size: var(--fs-num); font-weight: 600; letter-spacing: -.01em;
         font-variant-numeric: tabular-nums; }
  .stat.gen b { font-size: var(--fs-md); font-weight: 500; font-family: var(--mono); }
  .stat span { color: var(--dim); font-size: var(--fs-xs); font-weight: 600;
         text-transform: uppercase; letter-spacing: .06em; }
  /* A horizontal rule means ONE thing: a new band starts. Not used here. */
  .artifacts { margin-top: 1.5rem; font-size: var(--fs-xs); color: var(--dim); }
  .verdict { display: flex; align-items: center; gap: .5rem; margin: 1.15rem 0 0;
         padding: .6rem .85rem; border: 1px solid transparent; border-radius: 9px;
         font-weight: 600; font-size: var(--fs-md); line-height: 1.35; }
  .verdict .dot { flex: 0 0 auto; width: .5rem; height: .5rem;
         border-radius: 50%; background: currentColor; }
  .verdict.ok  { background: var(--okbg);  color: var(--ok);  border-color: var(--okline); }
  .verdict.bad { background: var(--errbg); color: var(--err); border-color: var(--errline); }
  .verdict a { color: inherit; text-decoration: underline; }
  /* Report bands — the .txt bands as sections, same classification. */
  .band { margin-top: 1.6rem; padding-top: 1rem; border-top: 1px solid var(--line); }
  .band h2 { display: flex; flex-wrap: wrap; align-items: baseline; gap: .5rem;
         margin: 0 0 .75rem; font-size: var(--fs-xs); font-weight: 700;
         letter-spacing: .1em; text-transform: uppercase; color: var(--dim); }
  /* span.count, NOT .count — (0,2,1) ties with .band.attention h2. */
  .band h2 span.count { font-size: var(--fs-sm); font-weight: 400; text-transform: none;
         letter-spacing: 0; color: var(--dim); font-variant-numeric: tabular-nums; }
  .band.attention h2 { color: var(--err); }
  .band.review h2    { color: var(--warn); }
  .band .subj { margin: .7rem 0 1.1rem; }
  .band .subj h3 { margin: 0 0 .35rem; font-size: var(--fs-lg); font-weight: 600;
         letter-spacing: -.005em; }
  .band .entry { margin: .45rem 0 .8rem; padding-left: .85rem;
         border-left: 2px solid var(--line2); }
  .band .entry .t { margin: 0; font-size: var(--fs-md); font-weight: 500; }
  /* Bare .p — the SCHEMA blurb and tree note sit OUTSIDE .entry. */
  .p { margin: .25rem 0 0; max-width: 70ch; color: var(--dim); font-size: var(--fs-sm); }
  .note { margin: 1.25rem 0 0; }
  ul.items { margin: .35rem 0 0; padding-left: 1.15rem; color: var(--dim);
         font-size: var(--fs-sm); }
  /* pre-wrap: items encode hierarchy as leading spaces, which HTML would
     collapse. Never `pre` — long paths must still wrap. */
  ul.items li { margin: .1rem 0; word-break: break-word; white-space: pre-wrap; }
  /* Dim markers so the indentation above reads as the structure. */
  ul.items li::marker { color: var(--line2); }
  ul.items li.more { color: var(--dim2); }
  table.rows { border-collapse: collapse; width: 100%; font-size: var(--fs-sm); }
  table.rows th { text-align: left; font-weight: 600;
         padding: .32rem .8rem .32rem 0; white-space: nowrap; vertical-align: top; }
  table.rows td { padding: .32rem 0; color: var(--dim); vertical-align: top; }
  table.rows td.n { text-align: right; padding-right: .8rem; white-space: nowrap;
         font-variant-numeric: tabular-nums; }
  table.rows td.cols { line-height: 1.9; }
  /* Rows separated by space, not lines — see the rule discipline above. */
  table.rows tr + tr th, table.rows tr + tr td { padding-top: .55rem; }
  table.rows code { font-family: var(--mono); font-size: .88em; color: var(--dim2);
         background: var(--chip); padding: .05rem .3rem; border-radius: 5px; }
  .chips { display: flex; flex-wrap: wrap; gap: .35rem .4rem; margin-top: .6rem; }
  .chip { font-size: var(--fs-xs); line-height: 1.55; padding: .15rem .55rem;
         border: 1px solid transparent; border-radius: 999px; white-space: nowrap;
         background: var(--chip); color: var(--ink); }
  .chip.ok { background: var(--okbg); color: var(--ok); border-color: var(--okline); }
  .chip.empty, .chip.off { background: transparent; color: var(--dim2);
         border-color: var(--line2); }
  .chip em { font-style: normal; color: var(--dim); }
  .toolbar { display: flex; flex-wrap: wrap; gap: .5rem; align-items: center;
         margin: 1.25rem 0 .75rem; }
  .toolbar button, .toolbar input { font: inherit; border: 1px solid var(--line2);
         border-radius: 9px; background: var(--card); color: var(--ink); }
  .toolbar button { font-size: var(--fs-sm); font-weight: 500; padding: .42rem .85rem;
         cursor: pointer; }
  .toolbar button:hover { background: var(--accentbg);
         border-color: var(--accentline); color: var(--accent); }
  .toolbar input { flex: 1 1 14rem; min-width: 11rem; font-size: var(--fs-md);
         padding: .45rem .7rem; }
  .toolbar input::placeholder { color: var(--dim); }
  .tree { background: var(--card); border: 1px solid var(--line);
         border-radius: 14px; padding: .45rem .6rem; box-shadow: var(--shadow); }
  details { margin: 0; }
  summary { display: flex; align-items: baseline; gap: .5rem; padding: .3rem .45rem;
         border-radius: 7px; list-style: none; cursor: pointer; }
  summary::-webkit-details-marker { display: none; }
  summary::before { content: "\25B8"; flex: 0 0 auto; color: var(--dim);
         font-size: .75em; transition: transform .12s ease; }
  details[open] > summary::before { transform: rotate(90deg); }
  summary:hover, .file:hover { background: var(--hover); }
  .kids { margin-left: 1.1rem; padding-left: .5rem;
         border-left: 1px solid var(--line); }
  .dir { font-weight: 600; }
  .file { display: flex; align-items: baseline; gap: .5rem;
         padding: .3rem .45rem .3rem 1.75rem; border-radius: 7px; }
  .fname { word-break: break-all; }
  .meta { margin-left: auto; color: var(--dim); font-size: var(--fs-xs);
         white-space: nowrap; font-family: var(--mono);
         font-variant-numeric: tabular-nums; }
  @media (prefers-reduced-motion: reduce) { summary::before { transition: none; } }
  @media (prefers-color-scheme: dark) {
    :root {
      --bg:#000; --card:#141417; --tile:rgba(255,255,255,.045);
      --chip:rgba(255,255,255,.09); --hover:rgba(255,255,255,.08);
      --ink:#f5f5f7; --dim2:#c7c7cc; --dim:#8e8e93;
      --line:rgba(255,255,255,.10); --line2:rgba(255,255,255,.18);
      --accent:#64b5ff; --accentbg:rgba(100,181,255,.14); --accentline:rgba(100,181,255,.30);
      --ok:#5dd76f; --okbg:rgba(93,215,111,.14); --okline:rgba(93,215,111,.30);
      --err:#ff8a82; --errbg:rgba(255,138,130,.14); --errline:rgba(255,138,130,.30);
      --warn:#e3b341; --shadow:0 1px 2px rgba(0,0,0,.6);
    }
  }
  /* Print. Last, so it beats the dark swap when printing from dark mode. */
  @media print {
    :root {
      --bg:#fff; --card:#fff; --tile:#fff; --chip:#f2f2f2; --hover:#fff;
      --ink:#000; --dim2:#333; --dim:#444;
      --line:#bbb; --line2:#999;
      --accent:#004; --accentbg:#fff; --accentline:#999;
      --ok:#0a5a24; --okbg:#fff; --okline:#0a5a24;
      --err:#8f0f18; --errbg:#fff; --errline:#8f0f18;
      --warn:#6b4900; --shadow:none;
    }
    body { padding: 0; font-size: 10.5pt; }
    .toolbar { display: none; }
    .band, .subj, .entry, .file, details { break-inside: avoid; }
  }
</style>
</head>
<body>
<div class="wrap">
HTML_HEAD
        printf '<header class="card"><h1><span class="wm">downpour</span>report</h1>'
        printf '<div class="sub">%s</div>' "$_name_esc"
        printf '<div class="stats"><div class="stat"><b>%s</b><span>files</span></div>' "$_total_files"
        _manifest_human_size $(( _total_kb * 1024 ))
        printf '<div class="stat"><b>%s</b><span>exported data</span></div>' "$_MAN_HS"
        printf '<div class="stat gen"><b>%s</b><span>generated</span></div></div>' "$_gen"
        _emit_report_html
        printf '<div class="artifacts">Also written: <a href="_downpour_log.txt">_downpour_log.txt</a> \342\200\224 the full output of this run</div>'
        printf '</header>\n'
        if [ "$_tree" = "1" ]; then
            cat <<'HTML_TOOLBAR'
<div class="toolbar">
  <button type="button" onclick="dpAll(true)">Expand all</button>
  <button type="button" onclick="dpAll(false)">Collapse all</button>
  <input id="dpf" type="search" placeholder="Filter files and folders…"
         oninput="dpFilter(this.value)" autocomplete="off">
</div>
<div class="tree" id="dptree">
HTML_TOOLBAR
            _manifest_emit_children "$_out"
            printf '</div>\n'
            cat <<'HTML_TREE_JS'
<script>
(function () {
  var tree = document.getElementById('dptree');
  if (!tree) { return; }
  window.dpAll = function (open) {
    var ds = tree.querySelectorAll('details');
    for (var i = 0; i < ds.length; i++) ds[i].open = open;
  };
  function rowText(el) { return (el.textContent || '').toLowerCase(); }
  window.dpFilter = function (q) {
    q = (q || '').trim().toLowerCase();
    var rows = tree.querySelectorAll('.file, details');
    if (!q) {
      for (var i = 0; i < rows.length; i++) rows[i].style.display = '';
      return;
    }
    // Hide everything, then reveal matches and their ancestors.
    for (var j = 0; j < rows.length; j++) rows[j].style.display = 'none';
    var files = tree.querySelectorAll('.file');
    for (var k = 0; k < files.length; k++) {
      var f = files[k];
      if (rowText(f).indexOf(q) === -1) continue;
      f.style.display = '';
      var p = f.parentNode;
      while (p && p !== tree) {
        if (p.tagName === 'DETAILS') { p.style.display = ''; p.open = true; }
        p = p.parentNode;
      }
    }
    // A folder whose own name matches reveals (and opens) itself too.
    var dets = tree.querySelectorAll('details');
    for (var m = 0; m < dets.length; m++) {
      var s = dets[m].querySelector('summary');
      if (s && rowText(s).indexOf(q) !== -1) {
        dets[m].style.display = ''; dets[m].open = true;
        var a = dets[m].parentNode;
        while (a && a !== tree) {
          if (a.tagName === 'DETAILS') { a.style.display = ''; a.open = true; }
          a = a.parentNode;
        }
      }
    }
  };
})();
</script>
HTML_TREE_JS
        else
            local _why
            if [ "$_tree_off_by_knob" = "1" ]; then
                _why="DOWNPOUR_HTML_MANIFEST=0"
            else
                _why="over the $_cap-file cap"
            fi
            printf '<p class="p note">File tree omitted (%s). The report above is complete; browse the folder directly.</p>\n' "$_why"
        fi
        cat <<'HTML_FOOT'
</div>
</body>
</html>
HTML_FOOT
    } > "$_tmp" 2>/dev/null
    [ "$_man_ng" = 1 ] || shopt -u nullglob
    [ "$_man_dg" = 1 ] || shopt -u dotglob
    if [ -s "$_tmp" ] && mv -f "$_tmp" "$_out/_downpour_report.html" 2>/dev/null; then
        _untrack_output_path "$_tmp"
    else
        rm -f "$_tmp" 2>/dev/null
        _untrack_output_path "$_tmp"
        log_warn "Could not write _downpour_report.html."
    fi
}

finalize_run() {
    local total=${#SCRIPTS_IN_ORDER[@]}
    local _hook _hook_rc
    for _hook in "${_LEAF_POSTPASS_HOOKS[@]+"${_LEAF_POSTPASS_HOOKS[@]}"}"; do
        "$_hook" "$_OUT_DIR"
        _hook_rc=$?
        [ "$_hook_rc" -eq 0 ] || log_warn "Post-pass hook '$_hook' returned non-zero (rc=$_hook_rc); export itself is unaffected but cross-leaf processing for that hook was incomplete."
    done
    local _skip_phrase=""
    if [ "$_MENU_SKIPS" -gt 0 ] && [ "$_PERM_SKIPS" -gt 0 ]; then
        _skip_phrase="$((_MENU_SKIPS + _PERM_SKIPS)) skipped ($_MENU_SKIPS deselected, $_PERM_SKIPS permissions)"
    elif [ "$_MENU_SKIPS" -gt 0 ]; then
        _skip_phrase="$_MENU_SKIPS skipped (deselected)"
    elif [ "$_PERM_SKIPS" -gt 0 ]; then
        _skip_phrase="$_PERM_SKIPS skipped (permissions)"
    fi
    if [ "$_USER_SKIPS" -gt 0 ]; then
        if [ -n "$_skip_phrase" ]; then
            _skip_phrase="$_skip_phrase, $_USER_SKIPS user-skipped"
        else
            _skip_phrase="$_USER_SKIPS skipped (user pressed 's')"
        fi
    fi
    if [ -d "${_LEAF_COUNTS_DIR:-}" ]; then
        local _f _key _val _saw_warn _corrupt_n=0 _leaf_failed
        local _leaf_warn_reported _leaf_err_reported _leaf_warn_file _leaf_err_file _leaf_pidbase
        for _f in "$_LEAF_COUNTS_DIR"/*.counts; do
            [ -f "$_f" ] || continue
            _saw_warn=0
            _leaf_failed=0
            [ -f "${_f%.counts}.failed" ] && _leaf_failed=1
            _leaf_warn_reported=0
            _leaf_err_reported=0
            while IFS='=' read -r _key _val; do
                case "$_key" in
                    WARN)
                        case "$_val" in ''|*[!0-9]*) continue ;; esac
                        _leaf_warn_reported="$_val"
                        WARN_COUNT=$((WARN_COUNT + _val))
                        _saw_warn=1
                        continue ;;
                    ERR)
                        case "$_val" in ''|*[!0-9]*) continue ;; esac
                        _leaf_err_reported="$_val"
                        if [ "$_leaf_failed" = "1" ]; then
                            local _fold_val=$((_val - 1))
                            [ "$_fold_val" -lt 0 ] && _fold_val=0
                            ERR_COUNT=$((ERR_COUNT + _fold_val))
                        else
                            ERR_COUNT=$((ERR_COUNT + _val))
                        fi
                        continue ;;
                    *) continue ;;
                esac
            done < "$_f"
            _leaf_pidbase="${_f%.counts}"
            _leaf_warn_file="$_leaf_pidbase.warns"
            if [ -s "$_leaf_warn_file" ]; then
                local _lw_n
                _lw_n=$(_count_lines "$_leaf_warn_file")
                if [ "$_lw_n" -gt "$_leaf_warn_reported" ]; then
                    WARN_COUNT=$((WARN_COUNT + _lw_n - _leaf_warn_reported))
                fi
            fi
            _leaf_err_file="$_leaf_pidbase.errs"
            if [ -s "$_leaf_err_file" ]; then
                local _le_n
                _le_n=$(_count_lines "$_leaf_err_file")
                if [ "$_le_n" -gt "$_leaf_err_reported" ]; then
                    ERR_COUNT=$((ERR_COUNT + _le_n - _leaf_err_reported))
                fi
            fi
            [ "$_saw_warn" -eq 0 ] && _corrupt_n=$((_corrupt_n + 1))
        done
        if [ "$_corrupt_n" -gt 0 ]; then
            log_warn "Leaf-counts aggregation: $_corrupt_n malformed counts $(_pluralize "$_corrupt_n" file) skipped; per-leaf warning totals may undercount."
        fi
        local _wrapper_warns="$_LEAF_COUNTS_DIR/$$.warns" _wn
        if [ -s "$_wrapper_warns" ]; then
            _wn=$(_count_lines "$_wrapper_warns")
            case "$_wn" in
                ''|*[!0-9]*) _wn=0 ;;
            esac
            [ "$_wn" -gt "$WARN_COUNT" ] && WARN_COUNT="$_wn"
        fi
        local _wrapper_errs="$_LEAF_COUNTS_DIR/$$.errs" _en
        if [ -s "$_wrapper_errs" ]; then
            _en=$(_count_lines "$_wrapper_errs")
            case "$_en" in
                ''|*[!0-9]*) _en=0 ;;
            esac
            [ "$_en" -gt "$ERR_COUNT" ] && ERR_COUNT="$_en"
        fi
    fi
    write_export_summary "$_OUT_DIR"; local _wes_rc=$?
    [ "$_wes_rc" -eq 0 ] && mark_success
    find "$_OUT_DIR" -mindepth 1 -depth -type d -empty -delete 2>/dev/null || true
    if [ "$_PIPED_MODE" = "no" ] && [ "$CLEAN_DOWNLOADS" = "1" ] \
       && [ "${#DOWNLOADED_SCRIPTS[@]}" -gt 0 ]; then
        local p
        for p in "${DOWNLOADED_SCRIPTS[@]}"; do
            rm -f -- "$p" 2>/dev/null || true
        done
        log_info "Removed ${#DOWNLOADED_SCRIPTS[@]} auto-downloaded $(_pluralize "${#DOWNLOADED_SCRIPTS[@]}" script scripts)"
    elif [ "$_PIPED_MODE" = "yes" ] && [ "${#DOWNLOADED_SCRIPTS[@]}" -gt 0 ]; then
        log_info "Removing ${#DOWNLOADED_SCRIPTS[@]} transient $(_pluralize "${#DOWNLOADED_SCRIPTS[@]}" script) from scratch on exit"
    fi
    sweep_junk_files "$_OUT_DIR"
    find "$_OUT_DIR" -mindepth 1 -depth -type d -empty -delete 2>/dev/null || true
    write_report_html "$_OUT_DIR"
    if [ -s "$_OUT_DIR/_downpour_report.html" ] \
       && [ -f "$_OUT_DIR/_downpour_report.txt" ]; then
        rm -f -- "$_OUT_DIR/_downpour_report.txt" 2>/dev/null || true
    fi
    print_summary
    print_final_summary_box "$_OUT_DIR" "$_OKS" "$total" "$_skip_phrase"
    prompt_tccutil_reset
    timemachine_resume
    _blank
    exec 1>/dev/null 2>/dev/null
    local _p
    for _p in "${CHILD_PIDS[@]+"${CHILD_PIDS[@]}"}"; do
        wait "$_p" 2>/dev/null || true
    done
    _TEE_PIDS=()
    CHILD_PIDS=()
    [ "${_wes_rc:-0}" -ne 0 ] && exit 1
    [ "$_FAILS" -gt 0 ] && exit 1
    [ "$_PERM_SKIPS" -gt 0 ] && exit 1
    if [ "${EXIT_NONZERO_ON_INCOMPLETE:-0}" = "1" ] \
       && [ "${_RUN_ATTENTION_N:-0}" -gt 0 ]; then
        exit 1
    fi
    exit 0
}

wrapper_main() {
    maybe_show_help "$@"
    require_local_session
    check_dependencies
    print_banner
    parse_args "$@"
    _setup_enumerate_menu
    run_menu
    compute_run_scope
    log_step "iCloud full export"
    surface_photos_passthroughs
    prepare_workspace
    run_preflight
    run_leaves
    finalize_run
}

prompt_tccutil_reset() {
    ( : </dev/tty ) 2>/dev/null || return 0
    local ans=""
    _countdown_key_prompt "$CONFIRM_AUTO_NO_SEC" ans "Reset Terminal'\''s TCC permissions (FDA + Automation + Accessibility)? [y/N]"
    if [ -z "$ans" ]; then
        printf '\r  Reset Terminal'\''s TCC permissions (FDA + Automation + Accessibility)? [y/N] — auto-no (no input within %d s)\n' "$CONFIRM_AUTO_NO_SEC" >&2
    else
        printf '\n' >&2
    fi
    _LAST_BLANK=0
    case "$ans" in
        y|Y)
            if sudo -p '  Password: ' tccutil reset All com.apple.Terminal \
                </dev/tty >/dev/null; then
                log_ok "TCC entries for com.apple.Terminal reset"
            else
                log_warn "tccutil reset failed (sudo declined or tccutil error)"
            fi
            ;;
        *)
            log_info "Permission reset skipped (existing grants kept)"
            ;;
    esac
    _blank
}

_bk_table_cols() {
    case "$2" in *[!A-Za-z0-9_]*) return 1 ;; esac
    local _bkt_out _bkt_rc
    _bkt_out="$(sqlite3 -readonly "$1" \
        "SELECT name FROM pragma_table_info('$2');" 2>/dev/null)"
    _bkt_rc=$?
    if [ "$_bkt_rc" -ne 0 ]; then
        _probe_miss error "$2" '*'
        return 1
    fi
    if [ -n "$_bkt_out" ]; then
        printf '#%s\n%s\n' "$2" "$_bkt_out"
    else
        printf '#%s\n' "$2"
    fi
    return 0
}

_bk_has_col() {
    local _bkh_list="$1" _bkh_want="$2" _bkh_tbl=""
    case "$_bkh_list" in
        '#'*)
            _bkh_tbl="${_bkh_list%%$'\n'*}"; _bkh_tbl="${_bkh_tbl#\#}"
            _bkh_list="${_bkh_list#*$'\n'}"
            ;;
    esac
    _col_in_list "$_bkh_list" "$_bkh_want" && return 0
    [ -n "$_bkh_tbl" ] && _probe_miss absent "$_bkh_tbl" "$_bkh_want"
    return 1
}

_bk_col_or_empty() {
    local _list="$1" _want="$2" _expr="${3:-}"
    if _bk_has_col "$_list" "$_want"; then
        if [ -n "$_expr" ]; then printf '%s' "$_expr"
        else printf "COALESCE(%s,'')" "$_want"; fi
    else
        printf "''"
    fi
}

_bk_discover_z_join() {
    local _t _rc
    _t="$(_discover_z_join "$1" "$2")"; _rc=$?
    if [ "$_rc" -eq 2 ]; then
        log_warn "Books: multiple Z_<N>$2 join tables match in $1; refusing to guess which is canonical — skipping the related dataset for this run."
        return 0
    fi
    printf '%s' "$_t"
}

_bk_pick_newest() {
    find "$1" -name "$2" -type f -not -name '*.bak' \
        -print0 2>/dev/null | xargs -0 stat -f '%m%t%N' 2>/dev/null \
        | LC_ALL=C sort -t $'\t' -k1,1rn -k2,2 | head -1 | cut -f2-
}

export_books() {
    local out_root="$1"
    local _books_root="$out_root/Books"
    local _bk_dirs=(
        "$HOME/Library/Containers/com.apple.BKAgentService/Data/Documents"
        "$HOME/Library/Mobile Documents/iCloud~com~apple~iBooks/Documents"
        "$HOME/Library/Containers/com.apple.iBooksX/Data/Documents"
    )
    local _d _have=0
    for _d in "${_bk_dirs[@]}"; do
        [ -d "$_d" ] && { _have=1; break; }
    done
    if [ "$_have" = "0" ]; then
        report_no_source "Books" "not configured" \
            "~/Library/Containers/com.apple.{BKAgentService,iBooksX}/Data/Documents and ~/Library/Mobile Documents/iCloud~com~apple~iBooks" \
            "Books"
    fi
    local _src_present=""
    for _d in "${_bk_dirs[@]}"; do
        [ -d "$_d" ] && { _src_present="$_d"; break; }
    done
    log_info "Source: $_src_present"
    local _bf _ef _total=0 _evicted=0 _evicted_names=""
    for _d in "${_bk_dirs[@]}"; do
        [ -d "$_d" ] || continue
        _bf=$(find "$_d" -type f \
            \( -iname '*.epub' -o -iname '*.pdf' -o -iname '*.ibooks' \) \
            2>/dev/null | wc -l | tr -d ' ')
        _total=$((_total + _bf))
        while IFS= read -r _ef; do
            [ -n "$_ef" ] || continue
            _evicted=$((_evicted + 1))
            _evicted_names="$_evicted_names$(_strip_icloud_stub_name "${_ef##*/}")
"
        done < <(find "$_d" -type f \
            \( -iname '*.epub.icloud' -o -iname '*.pdf.icloud' -o -iname '*.ibooks.icloud' \) \
            2>/dev/null)
    done
    local _bk_meta_count=0 _bk_meta_unreadable=0
    if [ "$_total" = "0" ] && [ "$_evicted" = "0" ]; then
        local _meta_db_dir="$HOME/Library/Containers/com.apple.iBooksX/Data/Documents"
        local _meta_bk_db=""
        [ -d "$_meta_db_dir/BKLibrary" ] && \
            _meta_bk_db=$(_bk_pick_newest "$_meta_db_dir/BKLibrary" 'BKLibrary*.sqlite')
        if [ -n "$_meta_bk_db" ] && [ -f "$_meta_bk_db" ]; then
            ensure_scratch
            local _meta_snap=""
            _meta_snap=$(snapshot_db "$_meta_bk_db" 2>/dev/null) || _meta_snap=""
            if [ -n "$_meta_snap" ]; then
                _bk_meta_count=$(sqlite3 -readonly "$_meta_snap" \
                    "SELECT COUNT(*) FROM ZBKLIBRARYASSET;" 2>/dev/null)
                case "$_bk_meta_count" in ''|*[!0-9]*) _bk_meta_count=0 ;; esac
            else
                _bk_meta_unreadable=1
            fi
        fi
        if [ "$_bk_meta_count" -eq 0 ]; then
            if [ "$_bk_meta_unreadable" = "1" ]; then
                log_warn "Books: BKLibrary database present but unreadable (snapshot failed) — if you have cloud-only books, their metadata (Library/Annotations/Collections) could not be read and is absent from this export."
            fi
            report_no_source "Books" "not configured" "" "Books"
        fi
        log_info "No physical book files on disk, but BKLibrary has $_bk_meta_count $(_pluralize "$_bk_meta_count" entry entries) — emitting metadata-only export (Library.csv / Annotations.csv / Collections.csv)."
    fi
    require_no_collision "$_books_root"
    _create_output_dir "$_books_root" "permission denied / disk full?"
    if [ "$_bk_meta_count" -eq 0 ]; then
        if [ "$_evicted" -gt 0 ]; then
            log_info "Found $_total $(_pluralize "$_total" book) on disk, $_evicted in iCloud only"
        else
            log_info "Found $_total $(_pluralize "$_total" book) on disk"
        fi
    fi
    if [ "$_evicted" -gt 0 ]; then
        printf '%s' "$_evicted_names" \
            | _write_skipped_report "$_books_root" "Books" \
                "$_evicted" "$((_total + _evicted))" \
                "open Books.app and right-click each cloud-only book > Download Now"
    fi
    local _copied=0 _bn _dst _src _bk_src_sz _bk_was_dataless _bk_ditto_err
    for _d in "${_bk_dirs[@]}"; do
        [ -d "$_d" ] || continue
        while IFS= read -r -d '' _src; do
            is_icloud_stub "$_src" && continue
            _bn="${_src##*/}"
            _dst="$(_unique_path "$_books_root/$_bn")"
            _bk_was_dataless=0
            is_dataless "$_src" && _bk_was_dataless=1
            _bk_src_sz="$(stat -f%z "$_src" 2>/dev/null || printf '')"
            _bk_ditto_err="$(_ditto_dl_retry "$_src" "$_dst" "$_bk_was_dataless")"
            if [ $? -eq 0 ] \
               && [ -s "$_dst" ] \
               && { [ "$_bk_was_dataless" -eq 0 ] \
                    || ! _materialized_copy_incomplete "$_bk_src_sz" "$_dst"; }; then
                _copied=$((_copied + 1))
            else
                rm -f -- "$_dst" 2>/dev/null
                log_warn "Cannot copy book: $_src."
                note_incomplete "$_books_root" "Book file: $_bn" \
                    "the file copy failed (source: $_src) — this book is not in the export"
            fi
        done < <(find "$_d" -type f \
            \( -iname '*.epub' -o -iname '*.pdf' -o -iname '*.ibooks' \) \
            -print0 2>/dev/null)
    done
    local _books_db_dir="$HOME/Library/Containers/com.apple.iBooksX/Data/Documents"
    local _bk_db="" _ae_db=""
    if [ -d "$_books_db_dir/BKLibrary" ]; then
        _bk_db=$(_bk_pick_newest "$_books_db_dir/BKLibrary" 'BKLibrary*.sqlite')
    fi
    if [ -d "$_books_db_dir/AEAnnotation" ]; then
        _ae_db=$(_bk_pick_newest "$_books_db_dir/AEAnnotation" 'AEAnnotation*.sqlite')
    fi
    local _ann_count=0 _lib_count=0
    if { [ -n "$_ae_db" ] && [ -f "$_ae_db" ]; } || \
       { [ -n "$_bk_db" ] && [ -f "$_bk_db" ]; }; then
        ensure_scratch
        local _ae_snap="" _bk_snap=""
        if [ -n "$_ae_db" ] && [ -f "$_ae_db" ]; then
            _ae_snap=$(snapshot_db "$_ae_db" 2>/dev/null) || _ae_snap=""
            if [ -z "$_ae_snap" ]; then
                log_warn "AEAnnotation snapshot failed — annotations not exported."
                note_incomplete "$_books_root" "Annotations.csv" \
                    "the AEAnnotation source database is present but could not be snapshotted (corrupt DB, companion-file copy failure, or insufficient scratch space) — highlights and notes are not in this export"
            fi
        fi
        if [ -n "$_bk_db" ] && [ -f "$_bk_db" ]; then
            _bk_snap=$(snapshot_db "$_bk_db" 2>/dev/null) || _bk_snap=""
            if [ -z "$_bk_snap" ]; then
                log_warn "BKLibrary snapshot failed — annotations will lack book titles."
                note_incomplete "$_books_root" "Library.csv / Collections.csv" \
                    "the BKLibrary source database is present but could not be snapshotted — Library.csv / Collections.csv / cover-image map are not in this export, and annotations (if any) lack book-title context"
            fi
        fi
        local _style_sql="CASE ZANNOTATIONSTYLE
            WHEN 0 THEN 'Underline' WHEN 1 THEN 'Green' WHEN 2 THEN 'Blue'
            WHEN 3 THEN 'Yellow' WHEN 4 THEN 'Pink' WHEN 5 THEN 'Purple'
            ELSE 'Other' END"
        if [ -n "$_ae_snap" ] && \
           sqlite3 -readonly "$_ae_snap" "SELECT Z_PK FROM ZAEANNOTATION LIMIT 1;" >/dev/null 2>&1; then
            local _ae_cols
            _ae_cols="$(_bk_table_cols "$_ae_snap" "ZAEANNOTATION")"
            local _ann_e_chapter _ann_e_modified
            local _ann_e_created _ann_e_loc _ann_e_note _ann_e_repr _ann_e_sel
            _ann_e_sel="$(_bk_col_or_empty "$_ae_cols" "ZANNOTATIONSELECTEDTEXT")"
            _ann_e_note="$(_bk_col_or_empty "$_ae_cols" "ZANNOTATIONNOTE")"
            _ann_e_repr="$(_bk_col_or_empty "$_ae_cols" "ZANNOTATIONREPRESENTATIVETEXT")"
            _ann_e_loc="$(_bk_col_or_empty "$_ae_cols" "ZANNOTATIONLOCATION")"
            if _bk_has_col "$_ae_cols" "ZFUTUREPROOFING5"; then
                _ann_e_chapter="ZFUTUREPROOFING5"
            else
                _ann_e_chapter="''"
                log_info "Schema: ZAEANNOTATION.ZFUTUREPROOFING5 absent — Chapter column will be empty."
            fi
            if _bk_has_col "$_ae_cols" "ZANNOTATIONCREATIONDATE"; then
                _ann_e_created="COALESCE(CASE WHEN ZANNOTATIONCREATIONDATE <= 0 THEN '' ELSE datetime($(_sql_cd_to_unix ZANNOTATIONCREATIONDATE), 'unixepoch', 'localtime') END, '')"
            else
                _ann_e_created="''"
            fi
            if _bk_has_col "$_ae_cols" "ZANNOTATIONMODIFICATIONDATE"; then
                _ann_e_modified="COALESCE(CASE WHEN ZANNOTATIONMODIFICATIONDATE <= 0 THEN '' ELSE datetime($(_sql_cd_to_unix ZANNOTATIONMODIFICATIONDATE), 'unixepoch', 'localtime') END, '')"
            else
                _ann_e_modified="''"
                log_info "Schema: ZAEANNOTATION.ZANNOTATIONMODIFICATIONDATE absent — Modified column will be empty."
            fi
            local _ann_style_expr="$_style_sql"
            if ! _bk_has_col "$_ae_cols" "ZANNOTATIONSTYLE"; then
                _ann_style_expr="'Other'"
                log_info "Schema: ZAEANNOTATION.ZANNOTATIONSTYLE absent — Style column defaults to Other."
            fi
            local _ann_e_deleted="'no'"
            if _bk_has_col "$_ae_cols" "ZANNOTATIONDELETED"; then
                _ann_e_deleted="CASE WHEN COALESCE(ZANNOTATIONDELETED,0)=0 THEN 'no' ELSE 'yes' END"
            else
                log_info "Schema: ZAEANNOTATION.ZANNOTATIONDELETED absent — Deleted column defaults to no."
            fi
            local _ann_disc _ann_counts _ann_expect _ann_deleted
            local _ann_where="1=1"
            local _ann_has_sel=0 _ann_has_note=0
            _bk_has_col "$_ae_cols" "ZANNOTATIONSELECTEDTEXT" && _ann_has_sel=1
            _bk_has_col "$_ae_cols" "ZANNOTATIONNOTE" && _ann_has_note=1
            if [ "$_ann_has_sel" -eq 1 ] && [ "$_ann_has_note" -eq 1 ]; then
                _ann_where="$_ann_where AND (ZANNOTATIONSELECTEDTEXT IS NOT NULL OR (ZANNOTATIONNOTE IS NOT NULL AND TRIM(ZANNOTATIONNOTE) <> ''))"
            elif [ "$_ann_has_sel" -eq 1 ]; then
                _ann_where="$_ann_where AND ZANNOTATIONSELECTEDTEXT IS NOT NULL"
            elif [ "$_ann_has_note" -eq 1 ]; then
                _ann_where="$_ann_where AND ZANNOTATIONNOTE IS NOT NULL AND TRIM(ZANNOTATIONNOTE) <> ''"
            fi
            local _ann_del_pred="0"
            _bk_has_col "$_ae_cols" "ZANNOTATIONDELETED" && \
                _ann_del_pred="COALESCE(ZANNOTATIONDELETED,0)<>0"
            _ann_counts=$(sqlite3 -readonly "$_ae_snap" -separator $'\x1f' \
                "SELECT (SELECT COUNT(*) FROM ZAEANNOTATION),
                        (SELECT COUNT(*) FROM ZAEANNOTATION WHERE $_ann_where),
                        (SELECT COUNT(*) FROM ZAEANNOTATION WHERE ($_ann_where) AND ($_ann_del_pred));" \
                2>/dev/null)
            if [ -z "$_ann_counts" ]; then
                log_warn "Books: AEAnnotation count query failed — drift-check skipped."
                note_incomplete "$_books_root" "Annotations.csv completeness" \
                    "a completeness check on the Books database failed, so the export could not verify it captured every highlight/note — Annotations.csv may be partial"
                _ann_disc=0
                _ann_expect=-1
                _ann_deleted=0
            else
                _ann_disc="${_ann_counts%%$'\x1f'*}"
                local _ann_rest="${_ann_counts#*$'\x1f'}"
                _ann_expect="${_ann_rest%%$'\x1f'*}"
                _ann_deleted="${_ann_rest#*$'\x1f'}"
            fi
            case "$_ann_disc"    in ''|*[!0-9]*)   _ann_disc=0 ;; esac
            case "$_ann_expect"  in ''|*[!0-9-]*)  _ann_expect=-1 ;; esac
            case "$_ann_deleted" in ''|*[!0-9]*)   _ann_deleted=0 ;; esac
            local _ann_orphans=0
            local _ann_csv="$_books_root/Annotations.csv"
            local _ann_order_joined="a.Z_PK" _ann_order_plain="Z_PK"
            local _ann_bk_cols=""
            if [ -n "$_bk_snap" ]; then
                _ann_bk_cols="$(_bk_table_cols "$_bk_snap" "ZBKLIBRARYASSET")"
            fi
            if _bk_has_col "$_ann_bk_cols" "ZTITLE"; then
                if _bk_has_col "$_ae_cols" "ZANNOTATIONLOCATION"; then
                    _ann_order_joined="b.ZTITLE, a.ZANNOTATIONLOCATION, a.Z_PK"
                else
                    _ann_order_joined="b.ZTITLE, a.Z_PK"
                fi
            elif _bk_has_col "$_ae_cols" "ZANNOTATIONLOCATION"; then
                _ann_order_joined="a.ZANNOTATIONLOCATION, a.Z_PK"
            fi
            if _bk_has_col "$_ae_cols" "ZANNOTATIONASSETID"; then
                if _bk_has_col "$_ae_cols" "ZANNOTATIONLOCATION"; then
                    _ann_order_plain="ZANNOTATIONASSETID, ZANNOTATIONLOCATION, Z_PK"
                else
                    _ann_order_plain="ZANNOTATIONASSETID, Z_PK"
                fi
            elif _bk_has_col "$_ae_cols" "ZANNOTATIONLOCATION"; then
                _ann_order_plain="ZANNOTATIONLOCATION, Z_PK"
            fi
            local _bk_has_assetid=0
            _bk_has_col "$_ann_bk_cols" "ZASSETID" && _bk_has_assetid=1
            local _ae_has_assetid=0
            _bk_has_col "$_ae_cols" "ZANNOTATIONASSETID" && _ae_has_assetid=1
            local _ann_tmp
            _ann_tmp="$(mktemp "$_ann_csv.tmp.XXXXXX" 2>/dev/null)" || _ann_tmp="$_ann_csv.tmp.$$"
            track_output_path "$_ann_tmp"
            {
                printf 'Book Title,Book Author,Book ID,Chapter,Highlight,Note,Context,Style,Created,Modified,Location,Deleted\r\n'
                if [ -n "$_bk_snap" ] && \
                   [ "$_bk_has_assetid" -eq 1 ] && \
                   [ "$_ae_has_assetid" -eq 1 ] && \
                   sqlite3 -readonly "$_bk_snap" "SELECT Z_PK FROM ZBKLIBRARYASSET LIMIT 1;" >/dev/null 2>&1 && \
                   sqlite3 -readonly "$_bk_snap" "
                        ATTACH DATABASE '${_ae_snap//\'/\'\'}' AS ann;
                        SELECT 1 FROM ann.ZAEANNOTATION LIMIT 1;
                   " >/dev/null 2>&1; then
                    local _bk_asset_derived="ZASSETID"
                    _bk_has_col "$_ann_bk_cols" "ZTITLE" \
                        && _bk_asset_derived="$_bk_asset_derived, MIN(ZTITLE) AS ZTITLE"
                    _bk_has_col "$_ann_bk_cols" "ZAUTHOR" \
                        && _bk_asset_derived="$_bk_asset_derived, MIN(ZAUTHOR) AS ZAUTHOR"
                    sqlite3 -readonly "$_bk_snap" "
                        ATTACH DATABASE '${_ae_snap//\'/\'\'}' AS ann;
                        SELECT $(_bk_col_or_empty "$_ann_bk_cols" "ZTITLE" "$(_sql_tsv_safe "b.ZTITLE")"),
                               $(_bk_col_or_empty "$_ann_bk_cols" "ZAUTHOR" "$(_sql_tsv_safe "b.ZAUTHOR")"),
                               COALESCE(a.ZANNOTATIONASSETID, ''),
                               $(_sql_tsv_safe "$(_bk_col_or_empty "$_ae_cols" "ZFUTUREPROOFING5" "a.ZFUTUREPROOFING5")"),
                               $(_sql_tsv_safe "${_ann_e_sel//ZANNOTATION/a.ZANNOTATION}"),
                               $(_sql_tsv_safe "${_ann_e_note//ZANNOTATION/a.ZANNOTATION}"),
                               $(_sql_tsv_safe "${_ann_e_repr//ZANNOTATION/a.ZANNOTATION}"),
                               ${_ann_style_expr//ZANNOTATIONSTYLE/a.ZANNOTATIONSTYLE},
                               ${_ann_e_created//ZANNOTATIONCREATIONDATE/a.ZANNOTATIONCREATIONDATE},
                               ${_ann_e_modified//ZANNOTATIONMODIFICATIONDATE/a.ZANNOTATIONMODIFICATIONDATE},
                               $(_sql_tsv_safe "$(_bk_col_or_empty "$_ae_cols" "ZANNOTATIONLOCATION" "COALESCE(a.ZANNOTATIONLOCATION,'')")"),
                               ${_ann_e_deleted//ZANNOTATIONDELETED/a.ZANNOTATIONDELETED}
                        FROM ann.ZAEANNOTATION a
                        LEFT JOIN (SELECT $_bk_asset_derived FROM ZBKLIBRARYASSET GROUP BY ZASSETID) b ON a.ZANNOTATIONASSETID = b.ZASSETID
                        WHERE ${_ann_where//ZANNOTATION/a.ZANNOTATION}
                        ORDER BY $_ann_order_joined;
                    " -separator $'\x1f' 2>/dev/null
                else
                    sqlite3 -readonly "$_ae_snap" "
                        SELECT '',
                               '',
                               $(_bk_col_or_empty "$_ae_cols" "ZANNOTATIONASSETID"),
                               $(_sql_tsv_safe "$_ann_e_chapter"),
                               $(_sql_tsv_safe "$_ann_e_sel"),
                               $(_sql_tsv_safe "$_ann_e_note"),
                               $(_sql_tsv_safe "$_ann_e_repr"),
                               $_ann_style_expr,
                               $_ann_e_created,
                               $_ann_e_modified,
                               $(_sql_tsv_safe "$_ann_e_loc"),
                               $_ann_e_deleted
                        FROM ZAEANNOTATION
                        WHERE $_ann_where
                        ORDER BY $_ann_order_plain;
                    " -separator $'\x1f' 2>/dev/null
                fi | while IFS=$'\x1f' read -r _btitle _bauthor _bid _chapter _highlight _note _context _style _created _modified _loc _deleted; do
                    printf '%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s\r\n' \
                        "$(csv_field "$_btitle")" "$(csv_field "$_bauthor")" \
                        "$(csv_field "$_bid")" "$(csv_field "$_chapter")" \
                        "$(csv_field "$_highlight")" "$(csv_field "$_note")" \
                        "$(csv_field "$_context")" \
                        "$(csv_field "$_style")" "$(csv_field "$_created")" \
                        "$(csv_field "$_modified")" "$(csv_field "$_loc")" \
                        "$(csv_field "$_deleted")"
                done
            } > "$_ann_tmp"
            _atomic_commit_tmp $? "$_ann_tmp" "$_ann_csv"; local _ann_commit_ok=$?
            _untrack_output_path "$_ann_tmp"
            [ "$_ann_commit_ok" -eq 0 ] || note_incomplete "$_books_root" "Annotations.csv" \
                "the atomic CSV write failed (disk-full / read-only output volume / permission error) — book annotations (highlights and notes) were not exported"
            if [ -n "$_bk_snap" ] && [ "$_bk_has_assetid" -eq 1 ] && \
               sqlite3 -readonly "$_bk_snap" "SELECT Z_PK FROM ZBKLIBRARYASSET LIMIT 1;" >/dev/null 2>&1; then
                local _ann_orphan_q
                _ann_orphan_q=$(sqlite3 -readonly "$_bk_snap" "
                    ATTACH DATABASE '${_ae_snap//\'/\'\'}' AS ann;
                    SELECT COUNT(*)
                    FROM ann.ZAEANNOTATION a
                    LEFT JOIN ZBKLIBRARYASSET b ON a.ZANNOTATIONASSETID = b.ZASSETID
                    WHERE ${_ann_where//ZANNOTATION/a.ZANNOTATION}
                      AND b.ZASSETID IS NULL;
                " 2>/dev/null)
                case "$_ann_orphan_q" in ''|*[!0-9]*) _ann_orphans=0 ;; *) _ann_orphans="$_ann_orphan_q" ;; esac
            fi
            _ann_count=$(_count_csv_rows "$_ann_csv")
            local _ann_contentless=0
            [ "$_ann_expect" -ge 0 ] && _ann_contentless=$((_ann_disc - _ann_expect))
            if [ "$_ann_deleted" -gt 0 ]; then
                log_info "Exported $_ann_deleted deleted annotation(s) (marked Deleted=yes) — review and discard if not needed."
            fi
            if [ "$_ann_contentless" -gt 0 ]; then
                _disclose_excluded "$_ann_contentless contentless annotation(s)" "bookmarks with no highlight or note"
            fi
            if [ "$_ann_orphans" -gt 0 ]; then
                log_info "$_ann_orphans annotation(s) reference a book no longer in the library (Book Title left blank)"
            fi
            if [ "$_ann_commit_ok" -eq 0 ] && [ "$_ann_expect" -ge 0 ] && \
               [ "$_ann_count" -lt "$_ann_expect" ]; then
                log_warn "Books drift: expected $_ann_expect annotation row(s), emitted $_ann_count."
                note_incomplete "$_books_root" "Annotations.csv — expected and emitted counts disagree" \
                    "expected $_ann_expect annotation row(s) (has highlight or note) but only $_ann_count landed in Annotations.csv — rows were dropped between query and emit; Annotations.csv may be missing highlights/notes"
            fi
            if [ "$_ann_count" = "0" ]; then
                rm -f -- "$_ann_csv" 2>/dev/null
            else
                validate_csv_rfc4180 "$_ann_csv" || true
            fi
        elif [ -n "$_ae_snap" ]; then
            log_warn "Books: AEAnnotation DB unreadable — annotations not exported."
            note_incomplete "$_books_root" "Annotations.csv (highlights and notes)" \
                "the AEAnnotation database was snapshotted but is not queryable (corrupt DB or unrecognised schema) — book files and Library.csv may still have exported"
        fi
        if [ -n "$_bk_snap" ] && \
           sqlite3 -readonly "$_bk_snap" "SELECT Z_PK FROM ZBKLIBRARYASSET LIMIT 1;" >/dev/null 2>&1; then
            local _bk_cols
            _bk_cols="$(_bk_table_cols "$_bk_snap" "ZBKLIBRARYASSET")"
            local _lib_e_title _lib_e_author _lib_e_genre _lib_e_assetid
            local _lib_e_pages _lib_e_lastopen _lib_e_progress _lib_e_finished
            local _lib_e_ctype _lib_e_added _lib_e_finisheddate _lib_e_rating _lib_e_lang
            _lib_e_title="$(_bk_col_or_empty "$_bk_cols" "ZTITLE" "$(_sql_tsv_safe "COALESCE(NULLIF(TRIM(COALESCE(ZTITLE,'')), ''), '(Untitled)')")")"
            _lib_e_author="$(_bk_col_or_empty "$_bk_cols" "ZAUTHOR" "$(_sql_tsv_safe "COALESCE(NULLIF(TRIM(COALESCE(ZAUTHOR,'')), ''), '')")")"
            _lib_e_genre="$(_bk_col_or_empty "$_bk_cols" "ZGENRE" "$(_sql_tsv_safe "COALESCE(ZGENRE,'')")")"
            _lib_e_assetid="$(_bk_col_or_empty "$_bk_cols" "ZASSETID")"
            _lib_e_lang="$(_bk_col_or_empty "$_bk_cols" "ZLANGUAGE" "$(_sql_tsv_safe "COALESCE(ZLANGUAGE,'')")")"
            if _bk_has_col "$_bk_cols" "ZPAGECOUNT"; then
                _lib_e_pages="COALESCE(ZPAGECOUNT,0)"
            else
                _lib_e_pages="0"
            fi
            if _bk_has_col "$_bk_cols" "ZISFINISHED"; then
                _lib_e_finished="COALESCE(ZISFINISHED,0)"
            else
                _lib_e_finished="0"
            fi
            if _bk_has_col "$_bk_cols" "ZRATING"; then
                _lib_e_rating="COALESCE(ZRATING,0)"
            else
                _lib_e_rating="0"
                log_info "Schema: ZBKLIBRARYASSET.ZRATING absent — Rating column defaults to 0."
            fi
            if _bk_has_col "$_bk_cols" "ZREADINGPROGRESS"; then
                _lib_e_progress="CAST(COALESCE(ZREADINGPROGRESS,0)*100 AS INT) || '%'"
            else
                _lib_e_progress="''"
                log_info "Schema: ZBKLIBRARYASSET.ZREADINGPROGRESS absent — Progress column will be empty."
            fi
            if _bk_has_col "$_bk_cols" "ZCONTENTTYPE"; then
                _lib_e_ctype="CASE ZCONTENTTYPE
                    WHEN 1 THEN 'Ebook' WHEN 2 THEN 'PDF' WHEN 3 THEN 'Audiobook'
                    ELSE 'Other' END"
            else
                _lib_e_ctype="''"
                log_info "Schema: ZBKLIBRARYASSET.ZCONTENTTYPE absent — Content Type column will be empty."
            fi
            if _bk_has_col "$_bk_cols" "ZLASTOPENDATE"; then
                _lib_e_lastopen="CASE WHEN ZLASTOPENDATE IS NULL OR ZLASTOPENDATE <= 0 THEN ''
                        ELSE datetime($(_sql_cd_to_unix ZLASTOPENDATE), 'unixepoch', 'localtime') END"
            else
                _lib_e_lastopen="''"
            fi
            if _bk_has_col "$_bk_cols" "ZCREATIONDATE"; then
                _lib_e_added="CASE WHEN ZCREATIONDATE IS NULL OR ZCREATIONDATE <= 0 THEN ''
                        ELSE datetime($(_sql_cd_to_unix ZCREATIONDATE), 'unixepoch', 'localtime') END"
            else
                _lib_e_added="''"
                log_info "Schema: ZBKLIBRARYASSET.ZCREATIONDATE absent — Added column will be empty."
            fi
            if _bk_has_col "$_bk_cols" "ZDATEFINISHED"; then
                _lib_e_finisheddate="CASE WHEN ZDATEFINISHED IS NULL OR ZDATEFINISHED <= 0 THEN ''
                        ELSE datetime($(_sql_cd_to_unix ZDATEFINISHED), 'unixepoch', 'localtime') END"
            else
                _lib_e_finisheddate="''"
                log_info "Schema: ZBKLIBRARYASSET.ZDATEFINISHED absent — Finished Date column will be empty."
            fi
            local _lib_disc _lib_disc_q
            _lib_disc_q=$(sqlite3 -readonly "$_bk_snap" \
                "SELECT COUNT(*) FROM ZBKLIBRARYASSET;" 2>/dev/null)
            case "$_lib_disc_q" in
                ''|*[!0-9]*) _lib_disc="" ;;
                *)           _lib_disc="$_lib_disc_q" ;;
            esac
            local _lib_where="1=1"
            local _lib_order="Z_PK"
            _bk_has_col "$_bk_cols" "ZTITLE" && _lib_order="ZTITLE, Z_PK"
            local _lib_csv="$_books_root/Library.csv"
            local _lib_tmp
            _lib_tmp="$(mktemp "$_lib_csv.tmp.XXXXXX" 2>/dev/null)" || _lib_tmp="$_lib_csv.tmp.$$"
            track_output_path "$_lib_tmp"
            {
                printf 'Title,Author,Book ID,Content Type,Genre,Language,Progress,Rating,Finished,Added,Finished Date,Last Opened,Pages\r\n'
                sqlite3 -readonly "$_bk_snap" "
                    SELECT $_lib_e_title,
                           $_lib_e_author,
                           $_lib_e_assetid,
                           $_lib_e_ctype,
                           $_lib_e_genre,
                           $_lib_e_lang,
                           $_lib_e_progress,
                           $_lib_e_rating,
                           $_lib_e_finished,
                           $_lib_e_added,
                           $_lib_e_finisheddate,
                           $_lib_e_lastopen,
                           $_lib_e_pages
                    FROM ZBKLIBRARYASSET
                    WHERE $_lib_where
                    ORDER BY $_lib_order;
                " -separator $'\x1f' 2>/dev/null \
                  | while IFS=$'\x1f' read -r _lt _la _lid _lct _lg _llang _lp _lr _lf _ladd _lfd _lo _lpc; do
                    local _fin="No"
                    [ "$_lf" = "1" ] && _fin="Yes"
                    printf '%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s\r\n' \
                        "$(csv_field "$_lt")" "$(csv_field "$_la")" \
                        "$(csv_field "$_lid")" "$(csv_field "$_lct")" \
                        "$(csv_field "$_lg")" "$(csv_field "$_llang")" \
                        "$(csv_field "$_lp")" "$(csv_field "$_lr")" \
                        "$_fin" "$(csv_field "$_ladd")" "$(csv_field "$_lfd")" \
                        "$(csv_field "$_lo")" "${_lpc:-0}"
                done
            } > "$_lib_tmp"
            _atomic_commit_tmp $? "$_lib_tmp" "$_lib_csv"; local _lib_commit_ok=$?
            _untrack_output_path "$_lib_tmp"
            [ "$_lib_commit_ok" -eq 0 ] || note_incomplete "$_books_root" "Library.csv" \
                "the atomic CSV write failed (disk-full / read-only output volume / permission error) — the reading-library inventory was not exported"
            _lib_count=$(_count_csv_rows "$_lib_csv")
            [ "$_lib_commit_ok" -eq 0 ] && \
                validate_count_parity "$_lib_disc" "$_lib_count" "Books library entries" "$_books_root"
            if [ "$_lib_count" = "0" ]; then
                rm -f -- "$_lib_csv" 2>/dev/null
            else
                validate_csv_rfc4180 "$_lib_csv" || true
            fi
            local _coll_table _coll_join
            _coll_table=""
            if sqlite3 -readonly "$_bk_snap" \
               "SELECT 1 FROM sqlite_master WHERE type='table' AND name='ZBKCOLLECTION' LIMIT 1;" \
               2>/dev/null | grep -q '^1$'; then
                _coll_table="ZBKCOLLECTION"
            fi
            _coll_join="$(_bk_discover_z_join "$_bk_snap" "COLLECTIONS")"
            if [ -n "$_coll_table" ] && [ -z "$_coll_join" ]; then
                local _coll_rows
                _coll_rows="$(sqlite3 -readonly "$_bk_snap" \
                    "SELECT COUNT(*) FROM ZBKCOLLECTION;" 2>/dev/null)"
                case "$_coll_rows" in ''|*[!0-9]*) _coll_rows=0 ;; esac
                if [ "$_coll_rows" -gt 0 ]; then
                    log_warn "Books: $_coll_rows collection(s) exist but the membership join table could not be located — Collections.csv not written."
                    note_incomplete "$_books_root" "Books Collections.csv not written" \
                        "$_coll_rows collection(s) exist in Apple Books but the book<->collection join table (Z_<N>COLLECTIONS) could not be discovered, so Collections.csv (which book is in which shelf/collection) is not in this export. Your books and Library.csv are unaffected."
                fi
            fi
            if [ -n "$_coll_table" ] && [ -n "$_coll_join" ]; then
                local _coll_join_cols _coll_fk_asset _coll_fk_coll
                _coll_join_cols="$(_bk_table_cols "$_bk_snap" "$_coll_join")"
                local _coll_fk_count
                _coll_fk_count="$(printf '%s\n' "$_coll_join_cols" \
                    | grep -c -E '^Z_[0-9]')"
                case "$_coll_fk_count" in ''|*[!0-9]*) _coll_fk_count=0 ;; esac
                _coll_fk_coll="$(printf '%s\n' "$_coll_join_cols" \
                    | grep -m1 -E '^Z_[0-9]+COLLECTIONS$')"
                case "$_coll_fk_coll" in *[!A-Za-z0-9_]*) _coll_fk_coll="" ;; esac
                _coll_fk_asset=""
                if [ "$_coll_fk_count" -ne 2 ]; then
                    log_warn "Collections: join table $_coll_join has $_coll_fk_count Z_[0-9]* FK columns (expected 2) — cannot reliably identify the asset FK by exclusion; skipping Collections.csv."
                elif [ -n "$_coll_fk_coll" ]; then
                    _coll_fk_asset="$(printf '%s\n' "$_coll_join_cols" \
                        | grep -E '^Z_[0-9]' \
                        | grep -vx "$_coll_fk_coll" | head -n1)"
                fi
                case "$_coll_fk_asset" in *[!A-Za-z0-9_]*) _coll_fk_asset="" ;; esac
                local _coll_cols _coll_name_col
                _coll_cols="$(_bk_table_cols "$_bk_snap" "ZBKCOLLECTION")"
                _coll_name_col=""
                local _cnc
                for _cnc in ZTITLE ZCOLLECTIONNAME ZNAME; do
                    if _bk_has_col "$_coll_cols" "$_cnc"; then
                        _coll_name_col="$_cnc"; break
                    fi
                done
                if [ -n "$_coll_fk_asset" ] && [ -n "$_coll_fk_coll" ] \
                   && [ -z "$_coll_name_col" ]; then
                    log_warn "Books: ZBKCOLLECTION has no recognised name column (ZTITLE/ZCOLLECTIONNAME/ZNAME) — Collections.csv skipped."
                    note_incomplete "$_books_root" "Collections.csv" \
                        "the book-collection table exists but its name column was not recognised on this macOS version; collection membership was not exported"
                fi
                if [ -n "$_coll_fk_asset" ] && [ -n "$_coll_fk_coll" ] \
                   && [ -n "$_coll_name_col" ]; then
                    [ "$_coll_name_col" = "ZTITLE" ] || \
                        log_info "Schema: ZBKCOLLECTION name column = $_coll_name_col (legacy)"
                    local _coll_order="c.$_coll_name_col, c.Z_PK"
                    if _bk_has_col "$_bk_cols" "ZTITLE"; then
                        _coll_order="c.$_coll_name_col, c.Z_PK, b.ZTITLE, b.Z_PK"
                    fi
                    local _coll_csv="$_books_root/Collections.csv"
                    local _co_e_title _co_e_author _co_e_assetid
                    _co_e_title="$(_bk_col_or_empty "$_bk_cols" "ZTITLE" "$(_sql_tsv_safe "b.ZTITLE")")"
                    _co_e_author="$(_bk_col_or_empty "$_bk_cols" "ZAUTHOR" "$(_sql_tsv_safe "b.ZAUTHOR")")"
                    _co_e_assetid="$(_bk_col_or_empty "$_bk_cols" "ZASSETID" "COALESCE(b.ZASSETID, '')")"
                    local _bcoll_tmp
                    _bcoll_tmp="$(mktemp "$_coll_csv.tmp.XXXXXX" 2>/dev/null)" || _bcoll_tmp="$_coll_csv.tmp.$$"
                    track_output_path "$_bcoll_tmp"
                    local _bcoll_raw _bcoll_sel_ok=1
                    _bcoll_raw="$(mktemp "$SCRATCH_DIR/bcoll_raw.XXXXXX" 2>/dev/null)" \
                        || _bcoll_raw="$SCRATCH_DIR/bcoll_raw.$$"
                    sqlite3 -readonly "$_bk_snap" "
                        SELECT $_co_e_title,
                               $_co_e_author,
                               $_co_e_assetid,
                               $(_sql_tsv_safe "c.$_coll_name_col")
                        FROM $_coll_join j
                        JOIN ZBKLIBRARYASSET b ON j.$_coll_fk_asset = b.Z_PK
                        JOIN ZBKCOLLECTION c ON j.$_coll_fk_coll = c.Z_PK
                        ORDER BY $_coll_order;
                    " -separator $'\x1f' > "$_bcoll_raw" 2>/dev/null || _bcoll_sel_ok=0
                    {
                        printf 'Book Title,Book Author,Book ID,Collection\r\n'
                        while IFS=$'\x1f' read -r _ct _ca _cid _cn; do
                            printf '%s,%s,%s,%s\r\n' \
                                "$(csv_field "$_ct")" "$(csv_field "$_ca")" \
                                "$(csv_field "$_cid")" "$(csv_field "$_cn")"
                        done < "$_bcoll_raw"
                    } > "$_bcoll_tmp"
                    _atomic_commit_tmp $? "$_bcoll_tmp" "$_coll_csv"; local _coll_commit_ok=$?
                    rm -f -- "$_bcoll_raw" 2>/dev/null
                    _untrack_output_path "$_bcoll_tmp"
                    [ "$_bcoll_sel_ok" -eq 0 ] && note_incomplete "$_books_root" "Collections.csv" \
                        "the collection-membership query failed partway through (corrupt DB or unexpected schema) — Collections.csv may be missing rows"
                    [ "$_coll_commit_ok" -eq 0 ] || note_incomplete "$_books_root" "Collections.csv" \
                        "the atomic CSV write failed (disk-full / read-only output volume / permission error) — book-collection memberships (which shelf each book is in) were not exported"
                    local _coll_count
                    _coll_count=$(_count_csv_rows "$_coll_csv")
                    if [ "$_coll_count" = "0" ]; then
                        rm -f -- "$_coll_csv" 2>/dev/null
                    else
                        validate_csv_rfc4180 "$_coll_csv" || true
                        log_info "Wrote Collections.csv ($_coll_count book-collection $(_pluralize "$_coll_count" membership))"
                    fi
                fi
            fi
        elif [ -n "$_bk_snap" ]; then
            log_warn "Books: BKLibrary DB unreadable — Library.csv not exported."
            note_incomplete "$_books_root" "Library.csv (reading-library inventory)" \
                "the BKLibrary database was snapshotted but is not queryable (corrupt DB or unrecognised schema) — book files may still have exported"
        fi
    fi
    local _covers_src=""
    local _cov_candidate
    for _cov_candidate in \
        "$_books_db_dir/BKLibrary/Covers" \
        "$_books_db_dir/AssetThumbnails/Covers" \
        "$_books_db_dir/AssetThumbnails" \
        "$_books_db_dir/Thumbnails"; do
        if [ -d "$_cov_candidate" ]; then
            _covers_src="$_cov_candidate"
            break
        fi
    done
    local _cover_src_count=0 _cover_count=0 _cover_fails=0
    if [ -d "$_covers_src" ]; then
        _cover_src_count=$(find "$_covers_src" -type f \
            \( -iname '*.jpg' -o -iname '*.jpeg' -o -iname '*.png' \) \
            2>/dev/null | wc -l | tr -d ' ')
        if [ "$_cover_src_count" -gt 0 ]; then
            local _covers_dst="$_books_root/Covers"
            mkdir -p "$_covers_dst" 2>/dev/null || _covers_dst=""
            if [ -z "$_covers_dst" ]; then
                log_warn "Could not create Books/Covers/ — $_cover_src_count cover image(s) NOT copied (permission denied / disk full?)."
                note_incomplete "$_books_root" "Book cover images" \
                    "the Covers/ folder could not be created (permission denied or disk full), so $_cover_src_count cover image(s) were not exported"
            fi
            if [ -n "$_covers_dst" ] && [ -d "$_covers_dst" ]; then
                while IFS= read -r -d '' _src; do
                    local _cov_dst
                    _cov_dst="$(_unique_path "$_covers_dst/${_src##*/}")"
                    if ditto -- "$_src" "$_cov_dst" 2>/dev/null; then
                        _cover_count=$((_cover_count + 1))
                        local _covkey _covk
                        _var_key_into "${_src##*/}" _covkey
                        _covk="_covmap_$_covkey"
                        printf -v "$_covk" '%s' "${_cov_dst##*/}"
                    else
                        rm -f -- "$_cov_dst" 2>/dev/null   # reap a torn partial
                        _cover_fails=$((_cover_fails + 1))
                    fi
                done < <(find "$_covers_src" -type f \
                    \( -iname '*.jpg' -o -iname '*.jpeg' -o -iname '*.png' \) \
                    -print0 2>/dev/null)
            fi
            if [ "$_cover_fails" -gt 0 ]; then
                log_warn "Books: $_cover_fails cover image $(_pluralize "$_cover_fails" copy "copies") failed — $_cover_count of $_cover_src_count copied into Covers/"
                note_incomplete "$_books_root" "Book cover images ($_cover_fails of $_cover_src_count not copied)" \
                    "cover-image file copy failed — covers are derived thumbnails Apple regenerates, so this is not a loss of original book content"
            fi
            if [ -d "$_covers_dst" ] && [ -n "${_bk_snap:-}" ] && \
               sqlite3 -readonly "$_bk_snap" "SELECT Z_PK FROM ZBKLIBRARYASSET LIMIT 1;" >/dev/null 2>&1; then
                local _cm_cols _cm_url_col _cnc2
                _cm_cols="$(_bk_table_cols "$_bk_snap" "ZBKLIBRARYASSET")"
                _cm_url_col=""
                for _cnc2 in ZCOVERURL ZCOVERPATH ZASSETICONPATH; do
                    if _bk_has_col "$_cm_cols" "$_cnc2"; then
                        _cm_url_col="$_cnc2"; break
                    fi
                done
                if [ -n "$_cm_url_col" ]; then
                    [ "$_cm_url_col" = "ZCOVERURL" ] || \
                        log_info "Schema: ZBKLIBRARYASSET cover-path column = $_cm_url_col (legacy)"
                    local _cm_csv="$_covers_dst/_index.csv"
                    local _cm_e_title _cm_e_author _cm_e_assetid _cm_order
                    _cm_e_title="$(_bk_col_or_empty "$_cm_cols" "ZTITLE")"
                    _cm_e_author="$(_bk_col_or_empty "$_cm_cols" "ZAUTHOR")"
                    _cm_e_assetid="$(_bk_col_or_empty "$_cm_cols" "ZASSETID")"
                    _cm_order="Z_PK"
                    _bk_has_col "$_cm_cols" "ZTITLE" && _cm_order="ZTITLE, Z_PK"
                    local _cm_tmp
                    _cm_tmp="$(mktemp "$_cm_csv.tmp.XXXXXX" 2>/dev/null)" || _cm_tmp="$_cm_csv.tmp.$$"
                    track_output_path "$_cm_tmp"
                    local _cm_raw _cm_sel_ok=1
                    _cm_raw="$(mktemp "$SCRATCH_DIR/bcm_raw.XXXXXX" 2>/dev/null)" \
                        || _cm_raw="$SCRATCH_DIR/bcm_raw.$$"
                    sqlite3 -readonly "$_bk_snap" "
                        SELECT $(_sql_tsv_safe "$_cm_e_title"),
                               $(_sql_tsv_safe "$_cm_e_author"),
                               $_cm_e_assetid,
                               COALESCE($_cm_url_col, '')
                        FROM ZBKLIBRARYASSET
                        WHERE $_cm_url_col IS NOT NULL AND $_cm_url_col <> ''
                        ORDER BY $_cm_order;
                    " -separator $'\x1f' > "$_cm_raw" 2>/dev/null || _cm_sel_ok=0
                    {
                        printf 'Book Title,Book Author,Book ID,Cover Filename\r\n'
                        while IFS=$'\x1f' read -r _cmt _cma _cmid _cmurl; do
                            local _cmbn="${_cmurl##*/}"
                            [ -n "$_cmbn" ] || continue
                            local _covkey2
                            local _covk2 _cmdst
                            _var_key_into "$_cmbn" _covkey2
                            _covk2="_covmap_$_covkey2"
                            _cmdst="${!_covk2:-}"
                            [ -n "$_cmdst" ] || _cmdst="$_cmbn"
                            [ -e "$_covers_dst/$_cmdst" ] || continue
                            printf '%s,%s,%s,%s\r\n' \
                                "$(csv_field "$_cmt")" "$(csv_field "$_cma")" \
                                "$(csv_field "$_cmid")" "$(csv_field "$_cmdst")"
                        done < "$_cm_raw"
                    } > "$_cm_tmp"
                    _atomic_commit_tmp $? "$_cm_tmp" "$_cm_csv"; local _cm_commit_ok=$?
                    rm -f -- "$_cm_raw" 2>/dev/null
                    _untrack_output_path "$_cm_tmp"
                    [ "$_cm_sel_ok" -eq 0 ] && note_incomplete "$_books_root" "Covers/_index.csv" \
                        "the cover-manifest query failed partway through (corrupt DB or unexpected schema) — Covers/_index.csv may be missing rows"
                    [ "$_cm_commit_ok" -eq 0 ] || note_incomplete "$_books_root" "Covers/_index.csv" \
                        "the atomic CSV write failed (disk-full / read-only output volume / permission error) — the book-to-cover index was not written"
                    local _cm_count
                    _cm_count=$(_count_csv_rows "$_cm_csv")
                    if [ "$_cm_count" = "0" ]; then
                        rm -f -- "$_cm_csv" 2>/dev/null
                        if [ "$_cm_commit_ok" -eq 0 ] && [ "${_cover_count:-0}" -gt 0 ]; then
                            log_warn "Books: $_cover_count cover image(s) copied but none matched a database cover reference — Covers/_index.csv not written."
                            note_incomplete "$_books_root" "Covers/_index.csv" \
                                "cover images were copied but their filenames did not match any database cover reference on this macOS version, so the book-to-cover index could not be built"
                        fi
                    else
                        validate_csv_rfc4180 "$_cm_csv" || true
                        log_info "Wrote Covers/_index.csv ($_cm_count cover $(_pluralize "$_cm_count" mapping))"
                    fi
                fi
            fi
        fi
    fi
    local _parts=()
    [ "$_copied" -gt 0 ] && _parts+=("$_copied $(_pluralize "$_copied" book)")
    [ "$_ann_count" -gt 0 ] && _parts+=("$_ann_count $(_pluralize "$_ann_count" annotation)")
    [ "$_lib_count" -gt 0 ] && _parts+=("$_lib_count $(_pluralize "$_lib_count" "library entry" "library entries")")
    [ "${_coll_count:-0}" -gt 0 ] && _parts+=("$_coll_count collection $(_pluralize "$_coll_count" membership)")
    [ "$_cover_count" -gt 0 ] && _parts+=("$_cover_count $(_pluralize "$_cover_count" cover)")
    [ "$_evicted" -gt 0 ] && _parts+=("$_evicted in iCloud only")
    if [ "${#_parts[@]}" -gt 0 ]; then
        local _summary
        _summary="$(IFS=, ; printf '%s' "${_parts[*]}")"
        _summary="${_summary//,/, }"
        log_ok "Wrote Books/ ($_summary, $(_dir_size_human "$_books_root"))"
    elif report_have_incomplete "$_books_root"; then
        log_warn "Books: an earlier step could not complete$(_disclosure_pointer "Books/_incomplete.txt")."
    else
        rmdir "$_books_root" 2>/dev/null || true
        report_empty_source "books" "Books"
    fi
    return 0
}

books_main() {
    maybe_show_help "$@"
    _announce_step "Books export"
    check_dependencies
    local out_arg out_dir
    out_arg="$(_parse_output_folder_arg "$@")" || exit 1
    out_dir="$(resolve_output_dir "$out_arg")" || exit 1
    _announce_output_dir "Books"
    require_full_disk_access
    warn_if_app_running Books
    export_books "$out_dir"
    mark_success
    sweep_junk_files "$out_dir"
    print_summary
    if [ "$ERR_COUNT" -gt 0 ]; then exit 1; fi
    exit 0
}

_unescape_nl() {
    local s="$1"; s="${s//\\n/$'\n'}"; printf '%s' "$s"
}

_cal_ts_to_unix() { _cd_ts_to_unix_signed "$1"; }

_cal_ts_to_utc() {
    local u; u="$(_cal_ts_to_unix "$1")"; [ -z "$u" ] && return 0
    TZ=UTC date -r "$u" +%Y%m%dT%H%M%SZ 2>/dev/null
}

_cal_ts_to_utc_date() {
    local u; u="$(_cal_ts_to_unix "$1")"; [ -z "$u" ] && return 0
    TZ=UTC date -r "$u" +%Y%m%d 2>/dev/null
}

_cal_ts_to_local_in_tz() {
    local tz="$2"
    [ -z "$tz" ] && return 0
    local u; u="$(_cal_ts_to_unix "$1")"; [ -z "$u" ] && return 0
    TZ="$tz" date -r "$u" +%Y%m%dT%H%M%S 2>/dev/null
}

_tz_is_valid() {
    local tz="$1"
    case "$tz" in
        ''|UTC|*[!A-Za-z0-9_/+-]*) return 1 ;;
    esac
    local _key _ref
    _key="${tz//\//_}"
    _key="${_key//+/p}"
    _key="${_key//-/m}"
    _ref="_tz_cache_${_key}"
    case "${!_ref:-}" in
        ok)  return 0 ;;
        bad) return 1 ;;
    esac
    if TZ="$tz" date +%z >/dev/null 2>&1; then
        printf -v "$_ref" 'ok'
        return 0
    else
        printf -v "$_ref" 'bad'
        return 1
    fi
}

_unix_plus_days_to_date() {
    local unix="$1" days="$2"
    local out=$((unix + days * 86400))
    TZ=UTC date -r "$out" +%Y%m%d 2>/dev/null
}

_alarm_offset_to_duration() {
    local secs="$1"
    case "$secs" in
        ''|*[!0-9-]*) return 0 ;;
    esac
    local sign=""
    case "$secs" in
        -*) sign="-"; secs="${secs#-}" ;;
    esac
    case "$secs" in '') return 0 ;; *[!0-9]*) return 0 ;; esac
    if [ "$secs" -eq 0 ]; then
        printf '%sPT0S' "$sign"
        return 0
    fi
    if [ $((secs % 86400)) -eq 0 ]; then
        printf '%sP%dD' "$sign" $((secs / 86400))
        return 0
    fi
    local h=$((secs / 3600))
    local m=$(((secs % 3600) / 60))
    local s=$((secs % 60))
    local out="${sign}PT"
    [ "$h" -gt 0 ] && out="${out}${h}H"
    [ "$m" -gt 0 ] && out="${out}${m}M"
    [ "$s" -gt 0 ] && out="${out}${s}S"
    printf '%s' "$out"
}

_alarm_reloff_plausible() {
    local secs="$1"
    case "$secs" in
        ''|*[!0-9-]*) return 1 ;;
    esac
    case "$secs" in -*) secs="${secs#-}" ;; esac
    case "$secs" in '') return 1 ;; *[!0-9]*) return 1 ;; esac
    [ "$secs" -eq 0 ] && return 0
    [ "$secs" -ge 60 ] && [ "$secs" -le 63072000 ]
}

_apple_recurrence_to_rrule() {
    local freq="$1" interval="$2" count="$3" end_date="$4" specifier="$5"
    local allday="${6:-0}" first_dow="${7:-}" bymonthday="${8:-}"
    local rrule="RRULE:"
    case "$freq" in
        1) rrule+="FREQ=DAILY" ;;
        2) rrule+="FREQ=WEEKLY" ;;
        3) rrule+="FREQ=MONTHLY" ;;
        4) rrule+="FREQ=YEARLY" ;;
        *) return 1 ;;
    esac
    case "$interval" in ''|*[!0-9]*) interval=1 ;; esac
    case "$count"    in ''|*[!0-9]*) count=0    ;; esac
    if [ "$interval" != "1" ] && [ "$interval" != "0" ]; then
        rrule+=";INTERVAL=$interval"
    fi
    if [ -n "$specifier" ]; then
        local OLDIFS="$IFS"
        local had_f
        case $- in *f*) had_f=1 ;; *) had_f=0 ;; esac
        IFS=';'
        set -f
        local part
        for part in $specifier; do
            case "$part" in
                D=*)
                    local byday="${part#D=}"
                    byday="${byday#+}"
                    rrule+="$(_rrule_by_fragment BYDAY "$byday" 'A-Z0-9,+-' '[A-Z]')"
                    ;;
                O=*)
                    local bymonth="${part#O=}"
                    rrule+="$(_rrule_by_fragment BYMONTH "$bymonth" '0-9,' '[0-9]')"
                    ;;
            esac
        done
        [ "$had_f" -eq 0 ] && set +f
        IFS="$OLDIFS"
    fi
    if [ -n "$bymonthday" ]; then
        rrule+="$(_rrule_by_fragment BYMONTHDAY "$bymonthday" '0-9,-' '[0-9]')"
    fi
    if [ -n "$first_dow" ] && [ "$freq" = "2" ]; then
        local _wkst=""
        case "$first_dow" in
            0) _wkst=SU ;;
            1) _wkst=MO ;;
            2) _wkst=TU ;;
            3) _wkst=WE ;;
            4) _wkst=TH ;;
            5) _wkst=FR ;;
            6) _wkst=SA ;;
        esac
        [ -n "$_wkst" ] && [ "$_wkst" != "MO" ] && rrule+=";WKST=$_wkst"
    fi
    if [ "$count" != "0" ]; then
        rrule+=";COUNT=$count"
    elif [ -n "$end_date" ] && [ "$end_date" != "0" ]; then
        local until
        if [ "$allday" = "1" ]; then
            until="$(_cal_ts_to_utc_date "$end_date")"
        else
            until="$(_cal_ts_to_utc "$end_date")"
        fi
        [ -n "$until" ] && rrule+=";UNTIL=$until"
    fi
    printf '%s' "$rrule"
}

_discover_calendar_db() {
    local p
    for p in \
        "$HOME/Library/Group Containers/group.com.apple.calendar/Calendar.sqlitedb" \
        "$HOME/Library/Calendars/Calendar.sqlitedb"; do
        [ -f "$p" ] && { printf '%s' "$p"; return 0; }
    done
    return 1
}

_is_system_calendar() {
    local title="$1"
    case "$title" in
        Default \
        |DEFAULT_TASK_CALENDAR_NAME \
        |'Scheduled Reminders' \
        |'Found in Mail' \
        |'Found in Natural Language' \
        |'Facebook Birthdays' \
        |'Siri Suggestions' \
        |'US Holidays') return 0 ;;
    esac
    return 1
}

_is_caldav_system_endpoint() {
    case "$1" in
        */notification/*|*/inbox/*|*/outbox/*) return 0 ;;
    esac
    return 1
}

_friendly_calendar_title() {
    local raw="$1"
    case "$raw" in
        DEFAULT_CALENDAR_NAME) printf 'Calendar'; return ;;
    esac
    case "$raw" in
        *@*)
            local domain="${raw#*@}"
            domain="${domain%%.*}"
            local domain_lc
            domain_lc="$(printf '%s' "$domain" | tr 'A-Z' 'a-z')"
            local cap_first cap_rest
            cap_first="$(printf '%s' "${domain_lc:0:1}" | tr 'a-z' 'A-Z')"
            cap_rest="${domain_lc:1}"
            printf '%s%s Calendar' "$cap_first" "$cap_rest"
            return ;;
    esac
    printf '%s' "$raw"
}

calendars_main() {
    maybe_show_help "$@"
    _announce_step "Calendars export"
    check_dependencies
    local out_arg out_dir
    out_arg="$(_parse_output_folder_arg "$@")" || exit 1
    out_dir="$(resolve_output_dir "$out_arg")" || exit 1
    _announce_output_dir "Calendars"
    require_full_disk_access
    warn_if_app_running Calendar
    local cal_db
    cal_db="$(_discover_calendar_db)" || die "Calendar database not found.
  Open Calendar.app once to initialise the database, then re-run."
    log_info "Source: $cal_db"
    local out_root="$out_dir/Calendars"
    require_no_collision "$out_root"
    ensure_scratch
    log_info "Snapshotting Calendar database..."
    local snap
    snap="$(snapshot_db_or_die "$cal_db" "Calendar")" || exit 1
    log_info "Probing schema and dumping calendar/event tables..."
    local _cal_tables _cal_missing=""
    _cal_tables="$(sqlite3 -readonly "$snap" \
        "SELECT GROUP_CONCAT(name, ' ') FROM sqlite_master WHERE type='table';" 2>/dev/null)"
    local _required
    for _required in Calendar CalendarItem; do
        case " $_cal_tables " in
            *" $_required "*) ;;
            *) _cal_missing="${_cal_missing:+$_cal_missing, }$_required" ;;
        esac
    done
    [ -n "$_cal_missing" ] && die "Calendar schema unrecognised — missing tables: $_cal_missing"
    _cal_has() {
        case " $_cal_tables " in
            *" $1 "*) return 0 ;;
            *) return 1 ;;
        esac
    }
    _cal_colset() {
        local _t="$1" _cols
        _cal_has "$_t" || return 0
        _cols="$(sqlite3 -readonly "$snap" \
            "SELECT GROUP_CONCAT(name, ' ') FROM pragma_table_info('$_t');" \
            2>/dev/null)"
        printf ' %s ' "$_cols"
    }
    _cal_colhas() {
        case "$1" in
            *" $2 "*) return 0 ;;
            *) return 1 ;;
        esac
    }
    local _ci_cols
    _ci_cols="$(_cal_colset CalendarItem)"
    local _ci_status="" _ci_avail="" _ci_url="" _ci_hasrec=""
    _cal_colhas "$_ci_cols" status         && _ci_status=1
    _cal_colhas "$_ci_cols" availability   && _ci_avail=1
    _cal_colhas "$_ci_cols" url            && _ci_url=1
    _cal_colhas "$_ci_cols" has_recurrences && _ci_hasrec=1
    [ -z "$_ci_status" ] && log_info "Schema: CalendarItem.status absent — events exported without STATUS."
    [ -z "$_ci_avail" ]  && log_info "Schema: CalendarItem.availability absent — events exported without TRANSP."
    [ -z "$_ci_url" ]    && log_info "Schema: CalendarItem.url absent — events exported without URL."
    local _ci_origitem="" _ci_origdate_col=""
    _cal_colhas "$_ci_cols" orig_item_id && _ci_origitem=1
    if _cal_colhas "$_ci_cols" orig_date; then
        _ci_origdate_col="orig_date"
    fi
    local _override_ok=""
    if [ -n "$_ci_origitem" ] && [ -n "$_ci_origdate_col" ]; then
        _override_ok=1
    else
        log_info "Schema: detached-override columns unresolved — overridden recurrence occurrences excluded."
    fi
    local _rec_cols _rec_fdow="" _rec_monthday_col="" _rec_owner_col=""
    _rec_cols="$(_cal_colset Recurrence)"
    if _cal_colhas "$_rec_cols" owner_id; then
        _rec_owner_col="owner_id"
    elif _cal_colhas "$_rec_cols" calendaritem_owner_id; then
        _rec_owner_col="calendaritem_owner_id"
    elif _cal_colhas "$_rec_cols" calendaritem_owner; then
        _rec_owner_col="calendaritem_owner"
    fi
    if _cal_colhas "$_rec_cols" week_start; then
        _rec_fdow="week_start"
    elif _cal_colhas "$_rec_cols" first_day_of_the_week; then
        _rec_fdow="first_day_of_the_week"
    fi
    if _cal_colhas "$_rec_cols" day_of_the_month; then
        _rec_monthday_col="day_of_the_month"
    elif _cal_colhas "$_rec_cols" days_of_the_month; then
        _rec_monthday_col="days_of_the_month"
    fi
    if _cal_has Recurrence; then
        if [ -z "$_rec_fdow" ]; then
            log_info "Schema: Recurrence week-start column absent — RRULE emitted without WKST."
        elif [ "$_rec_fdow" != "week_start" ]; then
            log_info "Schema: Recurrence week-start column = $_rec_fdow (legacy)"
        fi
        if [ -n "$_rec_monthday_col" ] && [ "$_rec_monthday_col" != "day_of_the_month" ]; then
            log_info "Schema: Recurrence by-monthday column = $_rec_monthday_col (legacy)"
        fi
        if [ -z "$_rec_owner_col" ]; then
            log_warn "Schema: Recurrence owner column unresolved (Apple may have renamed it) — recurring events are exported WITHOUT their recurrence rules (RRULE); this is an INCOMPLETE export of recurrence data. Please report the schema change."
        elif [ "$_rec_owner_col" != "owner_id" ]; then
            log_info "Schema: Recurrence owner column = $_rec_owner_col (legacy)"
        fi
    fi
    local _exc_cols _exc_owner_col=""
    if _cal_has ExceptionDate; then
        _exc_cols="$(_cal_colset ExceptionDate)"
        if _cal_colhas "$_exc_cols" owner_id; then
            _exc_owner_col="owner_id"
        elif _cal_colhas "$_exc_cols" calendaritem_owner_id; then
            _exc_owner_col="calendaritem_owner_id"
        elif _cal_colhas "$_exc_cols" calendaritem_owner; then
            _exc_owner_col="calendaritem_owner"
        fi
        if [ -z "$_exc_owner_col" ]; then
            log_warn "Schema: ExceptionDate owner column unresolved (Apple may have renamed it) — recurring events are exported WITHOUT their exception dates (EXDATE); this is an INCOMPLETE export of recurrence data. Please report the schema change."
        elif [ "$_exc_owner_col" != "owner_id" ]; then
            log_info "Schema: ExceptionDate owner column = $_exc_owner_col (legacy)"
        fi
    fi
    local _alarm_ok="" _alarm_cols _alarm_fk="" _alarm_type="" \
          _alarm_absdate="" _alarm_reloff_col=""
    if _cal_has Alarm; then
        _alarm_cols="$(_cal_colset Alarm)"
        if _cal_colhas "$_alarm_cols" calendaritem_owner_id; then
            _alarm_fk="calendaritem_owner_id"
        elif _cal_colhas "$_alarm_cols" owner_id; then
            _alarm_fk="owner_id"
        elif _cal_colhas "$_alarm_cols" calendaritem_owner; then
            _alarm_fk="calendaritem_owner"
        fi
        _cal_colhas "$_alarm_cols" type && _alarm_type=1
        if _cal_colhas "$_alarm_cols" trigger_date; then
            _alarm_absdate="trigger_date"
        elif _cal_colhas "$_alarm_cols" fire_date; then
            _alarm_absdate="fire_date"
        fi
        if _cal_colhas "$_alarm_cols" trigger_interval; then
            _alarm_reloff_col="trigger_interval"
        elif _cal_colhas "$_alarm_cols" relative_offset; then
            _alarm_reloff_col="relative_offset"
        fi
        if [ -n "$_alarm_fk" ] && { [ -n "$_alarm_absdate" ] || [ -n "$_alarm_reloff_col" ]; }; then
            _alarm_ok=1
            [ "$_alarm_fk" != "calendaritem_owner_id" ] && \
                log_info "Schema: Alarm owner column = $_alarm_fk (legacy)"
            [ -n "$_alarm_absdate" ] && [ "$_alarm_absdate" != "trigger_date" ] && \
                log_info "Schema: Alarm absolute-trigger column = $_alarm_absdate (legacy)"
            [ -n "$_alarm_reloff_col" ] && [ "$_alarm_reloff_col" != "trigger_interval" ] && \
                log_info "Schema: Alarm relative-offset column = $_alarm_reloff_col (legacy)"
        else
            log_info "Schema: Alarm table columns unresolved — events exported without VALARM."
        fi
    else
        log_info "Calendar schema has no Alarm table — events exported without VALARM."
    fi
    local _cal_dump_ok=1
    sqlite3 -readonly -separator $'\x1f' "$snap" "
        SELECT ROWID,
               $(_sql_tsv_safe title),
               $(_sql_tsv_safe "COALESCE(external_id, '')")
          FROM Calendar
         ORDER BY ROWID;
    " > "$SCRATCH_DIR/calendars.tsv" 2>/dev/null || _cal_dump_ok=0
    if [ "$_cal_dump_ok" -ne 1 ]; then
        log_warn "Calendars source dump failed — the per-calendar emit step will produce no output for this run."
        note_incomplete "$out_root" "Calendars source dump" \
            "the per-calendar SELECT against the snapshot DB failed; the export may be missing every calendar even though the database itself appeared queryable"
    fi
    local _cal_disc_count _cal_disc_ok=1
    _cal_disc_count="$(sqlite3 -readonly "$snap" \
        "SELECT COUNT(*) FROM Calendar;" 2>/dev/null)" \
        || _cal_disc_ok=0
    case "$_cal_disc_count" in ''|*[!0-9]*) _cal_disc_ok=0 ;; esac
    local _sel_status="''" _sel_avail="''" _sel_url="''"
    [ -n "$_ci_status" ] && _sel_status="COALESCE(status,'')"
    [ -n "$_ci_avail" ]  && _sel_avail="COALESCE(availability,'')"
    [ -n "$_ci_url" ]    && _sel_url="$(_sql_tsv_bsafe "COALESCE(url,'')")"
    local _sel_hasrec="0"
    [ -n "$_ci_hasrec" ] && _sel_hasrec="CAST(COALESCE(has_recurrences, 0) AS INTEGER)"
    local _sel_isover="0" _sel_origparent="''" _sel_origdate="''" _ev_where
    if [ -n "$_override_ok" ]; then
        _sel_isover="CASE WHEN COALESCE(orig_item_id,0) != 0 THEN 1 ELSE 0 END"
        _sel_origparent="COALESCE(orig_item_id,'')"
        _sel_origdate="COALESCE($_ci_origdate_col,'')"
        _ev_where="entity_type IN (0, 2)"
    else
        _ev_where="entity_type IN (0, 2)
           AND (orig_item_id IS NULL OR orig_item_id = 0)"
    fi
    if [ -n "$_ci_status" ]; then
        _ev_where="$_ev_where
           AND (status IS NULL OR status != 3 OR COALESCE(orig_item_id, 0) != 0)"
    fi
    if [ -n "$_ci_status" ]; then
        local _cancelled_masters
        _cancelled_masters="$(sqlite3 -readonly "$snap" \
            "SELECT COUNT(*) FROM CalendarItem
              WHERE entity_type IN (0, 2)
                AND status = 3
                AND COALESCE(orig_item_id, 0) = 0;" 2>/dev/null)"
        case "${_cancelled_masters:-0}" in
            ''|*[!0-9]*) _cancelled_masters=0 ;;
        esac
        [ "$_cancelled_masters" -gt 0 ] && \
            _disclose_excluded "$_cancelled_masters cancelled $(_pluralize "$_cancelled_masters" event)" "explicitly-cancelled master events; re-importing one would resurrect it (cancelled occurrence-overrides are kept as STATUS:CANCELLED)"
    fi
    local _ev_disc_count _ev_disc_ok=1 _ev_dump_ok=1
    _ev_disc_count="$(sqlite3 -readonly "$snap" \
        "SELECT COUNT(*) FROM CalendarItem WHERE $_ev_where;" 2>/dev/null)" \
        || _ev_disc_ok=0
    case "$_ev_disc_count" in ''|*[!0-9]*) _ev_disc_ok=0 ;; esac
    sqlite3 -readonly -separator $'\x1f' "$snap" "
        SELECT calendar_id,
               ROWID,
               $(_sql_tsv_safe "COALESCE(NULLIF(UUID, ''), NULLIF(unique_identifier, ''), 'apple-event-' || calendar_id || '-' || ROWID)") AS uid,
               COALESCE(start_date,''),
               COALESCE(end_date,''),
               COALESCE(start_tz,''),
               COALESCE(end_tz,''),
               CAST(COALESCE(all_day,0) AS INTEGER),
               $(_sql_tsv_bsafe summary),
               $(_sql_tsv_bsafe description),
               $_sel_hasrec,
               $_sel_status,
               $_sel_avail,
               $_sel_url,
               $_sel_isover,
               $_sel_origparent,
               $_sel_origdate
          FROM CalendarItem
         WHERE $_ev_where
         ORDER BY calendar_id, start_date, ROWID;
    " > "$SCRATCH_DIR/events.tsv" || _ev_dump_ok=0
    local _ev_query_failed=""
    if [ "$_ev_dump_ok" -eq 0 ] || [ "$_ev_disc_ok" -eq 0 ]; then
        _ev_query_failed=1
    elif [ "$_ev_disc_count" -gt 0 ] && [ ! -s "$SCRATCH_DIR/events.tsv" ]; then
        _ev_query_failed=1
    fi
    if [ -n "$_ev_query_failed" ]; then
        log_warn "Calendars: could not read the list of events from the database — events may be missing from the export."
        note_incomplete "$out_root" "Calendars export" \
            "reading the list of events from the calendar database failed (it may be corrupt or have an unexpected layout on this macOS version); events could not be listed"
    fi
    local _cal_query_failed=""
    if [ "$_cal_disc_ok" -eq 1 ] && [ "$_cal_disc_count" -gt 0 ] \
        && [ ! -s "$SCRATCH_DIR/calendars.tsv" ]; then
        _cal_query_failed=1
        log_warn "Calendars: found $_cal_disc_count calendar(s) but could not read them out — calendars may be missing from the export."
        note_incomplete "$out_root" "Calendars export" \
            "reading the list of calendars from the database failed (it may be corrupt or have an unexpected layout on this macOS version); calendars could not be listed"
    fi
    : > "$SCRATCH_DIR/parent_uids.tsv"
    if [ -n "$_override_ok" ]; then
        sqlite3 -readonly -separator $'\x1f' "$snap" "
            SELECT ROWID,
                   $(_sql_tsv_safe "COALESCE(NULLIF(UUID, ''), NULLIF(unique_identifier, ''), 'apple-event-' || calendar_id || '-' || ROWID)") AS uid
              FROM CalendarItem
             WHERE entity_type IN (0, 2);
        " > "$SCRATCH_DIR/parent_uids.tsv" \
            || { log_warn "Calendars: parent-UID query failed — detached recurrence overrides may be dropped."
                 note_incomplete "$out_root" "Calendars export" \
                     "the CalendarItem parent-UID query failed; some detached recurrence overrides may be missing"
                 : > "$SCRATCH_DIR/parent_uids.tsv"; }
    fi
    : > "$SCRATCH_DIR/locations.tsv"
    if _cal_has Location; then
        sqlite3 -readonly -separator $'\x1f' "$snap" "
            SELECT ci.ROWID, $(_sql_tsv_bsafe "l.title")
              FROM CalendarItem ci
              LEFT JOIN Location l ON l.ROWID = ci.location_id
             WHERE l.title IS NOT NULL;
        " > "$SCRATCH_DIR/locations.tsv"
    else
        log_info "Calendar schema has no Location table — events exported without LOCATION."
    fi
    : > "$SCRATCH_DIR/recurrences.tsv"
    if _cal_has Recurrence && [ -n "$_rec_owner_col" ]; then
        local _rec_sel_fdow="''" _rec_sel_md="''"
        [ -n "$_rec_fdow" ] && _rec_sel_fdow="COALESCE($_rec_fdow,'')"
        [ -n "$_rec_monthday_col" ] && \
            _rec_sel_md="$(_sql_tsv_safe "COALESCE($_rec_monthday_col,'')")"
        sqlite3 -readonly -separator $'\x1f' "$snap" "
            SELECT $_rec_owner_col,
                   COALESCE(frequency,''),
                   COALESCE(interval,''),
                   COALESCE(count,''),
                   COALESCE(end_date,''),
                   $(_sql_tsv_safe "COALESCE(specifier,'')"),
                   $_rec_sel_fdow,
                   $_rec_sel_md
              FROM Recurrence
             ORDER BY $_rec_owner_col, ROWID;
        " > "$SCRATCH_DIR/recurrences.tsv" \
        || { log_warn "Calendars: Recurrence query failed — events may be exported without RRULE."
             note_incomplete "$out_root" "Calendars export" \
                 "reading repeat rules from the calendar database failed (it may be corrupt or have an unexpected layout); some repeating events may be missing their repeat rule"
             : > "$SCRATCH_DIR/recurrences.tsv"; }
    elif _cal_has Recurrence; then
        : # owner-FK unresolved — disclosure already emitted in the probe block
    else
        log_info "Calendar schema has no Recurrence table — events exported without RRULE."
    fi
    : > "$SCRATCH_DIR/exceptions.tsv"
    if _cal_has ExceptionDate && [ -n "$_exc_owner_col" ]; then
        sqlite3 -readonly -separator $'\x1f' "$snap" "
            SELECT $_exc_owner_col, date
              FROM ExceptionDate
             ORDER BY $_exc_owner_col, date, ROWID;
        " > "$SCRATCH_DIR/exceptions.tsv" \
        || { log_warn "Calendars: ExceptionDate query failed — events may be exported without EXDATE."
             note_incomplete "$out_root" "Calendars export" \
                 "reading recurrence exceptions from the calendar database failed (it may be corrupt or have an unexpected layout); some repeating events may be missing their skipped-date exceptions"
             : > "$SCRATCH_DIR/exceptions.tsv"; }
    elif _cal_has ExceptionDate; then
        : # owner-FK unresolved — disclosure already emitted in the probe block
    else
        log_info "Calendar schema has no ExceptionDate table — events exported without EXDATE."
    fi
    : > "$SCRATCH_DIR/alarms.tsv"
    if [ -n "$_alarm_ok" ]; then
        local _alm_sel_type="''" _alm_sel_abs="''" _alm_sel_rel="''"
        [ -n "$_alarm_type" ]      && _alm_sel_type="COALESCE(type,'')"
        [ -n "$_alarm_absdate" ]   && _alm_sel_abs="COALESCE($_alarm_absdate,'')"
        [ -n "$_alarm_reloff_col" ] && _alm_sel_rel="COALESCE($_alarm_reloff_col,'')"
        sqlite3 -readonly -separator $'\x1f' "$snap" "
            SELECT $_alarm_fk,
                   $_alm_sel_type,
                   $_alm_sel_abs,
                   $_alm_sel_rel
              FROM Alarm
             WHERE $_alarm_fk IS NOT NULL
             ORDER BY $_alarm_fk, ROWID;
        " > "$SCRATCH_DIR/alarms.tsv" \
            || { log_warn "Calendars: Alarm query failed — events may be exported without VALARM reminders."
                 note_incomplete "$out_root" "Calendars export" \
                     "the Alarm table query failed; some events' VALARM reminders may be missing"
                 : > "$SCRATCH_DIR/alarms.tsv"; }
    fi
    _create_output_dir "$out_root"
    if ! awk -F$'\x1f' '{c[$1]++} END{for(k in c) print k"\t"c[k]}' \
        "$SCRATCH_DIR/events.tsv" \
        | sort -n -t$'\t' -k1,1 > "$SCRATCH_DIR/event_counts.tsv"; then
        log_warn "Calendars: per-calendar event-count build failed — calendars may be misclassified as empty and omitted."
        note_incomplete "$out_root" "Calendars event classification" \
            "building the per-calendar event count (events.tsv → event_counts.tsv) failed; some calendars may have been misclassified as empty and omitted from the export. Re-run after confirming scratch space is available."
    fi
    local _evc_k _evc_v
    while IFS=$'\t' read -r _evc_k _evc_v; do
        case "$_evc_k" in
            ''|*[!0-9]*) continue ;;
        esac
        printf -v "_evc_$_evc_k" '%s' "$_evc_v"
    done < "$SCRATCH_DIR/event_counts.tsv"
    _ev_count_for() {
        local _ref="_evc_$1"
        printf '%s' "${!_ref:-0}"
    }
    mkdir -p "$SCRATCH_DIR/events_by_cal" \
        || die "Cannot create per-cal events slice dir"
    local _ev_slice_ok=1 _ev_sliced=0
    _ev_sliced="$(awk -F$'\x1f' -v outdir="$SCRATCH_DIR/events_by_cal" '
        $1 != "" {
            if ($1 != prev) {
                if (prev != "") close(outdir "/" prev ".tsv")
                prev = $1
            }
            print > (outdir "/" $1 ".tsv"); n++
        }
        END { if (prev != "") close(outdir "/" prev ".tsv"); print n+0 }
    ' "$SCRATCH_DIR/events.tsv")" || _ev_slice_ok=0
    case "$_ev_sliced" in ''|*[!0-9]*) _ev_slice_ok=0; _ev_sliced=0 ;; esac
    local _orphan_ev_count
    _orphan_ev_count="$(awk -F$'\x1f' '$1 == "" {n++} END{print n+0}' \
        "$SCRATCH_DIR/events.tsv")"
    if [ "${_orphan_ev_count:-0}" -gt 0 ]; then
        _disclose_excluded "$_orphan_ev_count $(_pluralize "$_orphan_ev_count" event) with no calendar" "orphan rows with no owning calendar"
        note_incomplete "$out_root" \
            "$_orphan_ev_count orphan $(_pluralize "$_orphan_ev_count" event)" \
            "$_orphan_ev_count event $(_pluralize "$_orphan_ev_count" "row was" "rows were") present in the source database but had no owning calendar to attach to (a calendar was deleted while events remained, or a CalDAV sync left stale rows); these events are not in any per-calendar .ics file in this export"
    fi
    if [ "$_ev_slice_ok" -eq 0 ]; then
        note_incomplete "$out_root" "Per-calendar event split failed" \
            "the events could not be split into per-calendar files (a scratch write error) — some calendars may be missing events in this export"
    elif [ "${_ev_disc_ok:-1}" -eq 1 ] && [ "${_ev_dump_ok:-1}" -eq 1 ]; then
        local _ev_expected_sliced=$((_ev_disc_count - ${_orphan_ev_count:-0}))
        if [ "$_ev_sliced" -ne "$_ev_expected_sliced" ]; then
            note_incomplete "$out_root" "Event count mismatch after split" \
                "expected $_ev_expected_sliced event(s) to be split into per-calendar files but only $_ev_sliced were written — some events may be missing from this export"
        fi
    fi
    log_info "Classifying calendars (system / empty / candidate)..."
    local -a skipped_names=() empty_names=() endpoint_names=()
    local total_cals=0 sys_count=0 empty_count=0 candidate_count=0 untitled_count=0 endpoint_count=0
    local cal_id cal_title cal_extid _ec
    while IFS=$'\x1f' read -r cal_id cal_title cal_extid; do
        [ -z "$cal_id" ] && continue
        total_cals=$((total_cals + 1))
        if _is_system_calendar "$cal_title"; then
            sys_count=$((sys_count + 1))
            [ -n "$cal_title" ] && skipped_names+=( "$cal_title" )
        elif _is_caldav_system_endpoint "$cal_extid"; then
            endpoint_count=$((endpoint_count + 1))
            [ -n "$cal_title" ] && endpoint_names+=( "$cal_title" )
        elif [ -z "$cal_title" ]; then
            untitled_count=$((untitled_count + 1))
        else
            _ec="$(_ev_count_for "$cal_id")"
            if [ -z "$_ec" ] || [ "$_ec" = "0" ]; then
                empty_count=$((empty_count + 1))
                empty_names+=( "$(_friendly_calendar_title "$cal_title")" )
            else
                candidate_count=$((candidate_count + 1))
            fi
        fi
    done < "$SCRATCH_DIR/calendars.tsv"
    local _cal_summary
    _cal_summary="Found $total_cals $(_pluralize "$total_cals" calendar): $candidate_count $(_pluralize "$candidate_count" candidate), $sys_count system $(_pluralize "$sys_count" list)"
    [ "$endpoint_count" -gt 0 ] && \
        _cal_summary="$_cal_summary, $endpoint_count protocol $(_pluralize "$endpoint_count" endpoint)"
    log_info "$_cal_summary, $empty_count empty"
    [ "$untitled_count" -gt 0 ] && \
        _disclose_excluded "$untitled_count untitled $(_pluralize "$untitled_count" calendar)"
    _emit_skipped_group() {
        local _label="$1" _arr="$2" _n
        eval "_n=\${#${_arr}[@]}"
        [ "$_n" -gt 0 ] || return 0
        local _uniq _uniq_n
        eval "_uniq=\"\$(printf '%s\\n' \"\${${_arr}[@]}\" | LC_ALL=C sort | LC_ALL=C uniq -c)\""
        _uniq_n=$(printf '%s\n' "$_uniq" | LC_ALL=C awk 'NF{n++} END{print n+0}')
        if [ "$_uniq_n" = "1" ]; then
            local _inline
            _inline="$(printf '%s\n' "$_uniq" | LC_ALL=C awk '{
                  c=$1; $1=""; sub(/^ /,"")
                  if (c > 1) printf "%s (×%d)", $0, c
                  else       printf "%s", $0
              }')"
            log_info "$_label: $_inline"
        else
            log_info "$_label:"
            printf '%s\n' "$_uniq" \
                | LC_ALL=C awk '{
                      c = $1
                      $1 = ""
                      sub(/^ /, "")
                      if (c > 1) printf "  • %s (×%d)\n", $0, c
                      else       printf "  • %s\n", $0
                  }' | while IFS= read -r _line; do log_info "$_line"; done
        fi
    }
    _emit_skipped_group "Skipped (system)" skipped_names
    _emit_skipped_group "Skipped (CalDAV protocol endpoints — scheduling inbox/outbox, not real calendars)" endpoint_names
    _emit_skipped_group "Skipped (empty)" empty_names
    local _cm_pk _cm_rest _cm_ref
    while IFS= read -r _cm_rest || [ -n "$_cm_rest" ]; do
        [ -z "$_cm_rest" ] && continue
        _cm_pk="${_cm_rest%%$'\x1f'*}"
        [ -z "$_cm_pk" ] && continue
        printf -v "_calmap_loc_$_cm_pk" '%s' "$_cm_rest"
    done < "$SCRATCH_DIR/locations.tsv"
    while IFS= read -r _cm_rest || [ -n "$_cm_rest" ]; do
        [ -z "$_cm_rest" ] && continue
        _cm_pk="${_cm_rest%%$'\x1f'*}"
        [ -z "$_cm_pk" ] && continue
        _cm_ref="_calmap_recseen_$_cm_pk"
        if [ -n "${!_cm_ref:-}" ]; then
            _cm_ref="_calmap_rec_$_cm_pk"
            printf -v "_calmap_rec_$_cm_pk" '%s' "${!_cm_ref}"$'\n'"$_cm_rest"
        else
            printf -v "_calmap_recseen_$_cm_pk" '%s' 1
            printf -v "_calmap_rec_$_cm_pk" '%s' "$_cm_rest"
        fi
    done < "$SCRATCH_DIR/recurrences.tsv"
    while IFS= read -r _cm_rest || [ -n "$_cm_rest" ]; do
        [ -z "$_cm_rest" ] && continue
        _cm_pk="${_cm_rest%%$'\x1f'*}"
        [ -z "$_cm_pk" ] && continue
        _cm_ref="_calmap_excseen_$_cm_pk"
        if [ -n "${!_cm_ref:-}" ]; then
            _cm_ref="_calmap_exc_$_cm_pk"
            printf -v "_calmap_exc_$_cm_pk" '%s' "${!_cm_ref}"$'\n'"$_cm_rest"
        else
            printf -v "_calmap_excseen_$_cm_pk" '%s' 1
            printf -v "_calmap_exc_$_cm_pk" '%s' "$_cm_rest"
        fi
    done < "$SCRATCH_DIR/exceptions.tsv"
    while IFS= read -r _cm_rest || [ -n "$_cm_rest" ]; do
        [ -z "$_cm_rest" ] && continue
        _cm_pk="${_cm_rest%%$'\x1f'*}"
        [ -z "$_cm_pk" ] && continue
        _cm_ref="_calmap_almseen_$_cm_pk"
        if [ -n "${!_cm_ref:-}" ]; then
            _cm_ref="_calmap_alm_$_cm_pk"
            printf -v "_calmap_alm_$_cm_pk" '%s' "${!_cm_ref}"$'\n'"$_cm_rest"
        else
            printf -v "_calmap_almseen_$_cm_pk" '%s' 1
            printf -v "_calmap_alm_$_cm_pk" '%s' "$_cm_rest"
        fi
    done < "$SCRATCH_DIR/alarms.tsv"
    while IFS=$'\x1f' read -r _cm_pk _cm_rest || [ -n "$_cm_pk" ]; do
        [ -z "$_cm_pk" ] && continue
        printf -v "_calmap_puid_$_cm_pk" '%s' "$_cm_rest"
    done < "$SCRATCH_DIR/parent_uids.tsv"
    log_info "Exporting per-calendar .ics files..."
    local exported=0 skipped=0 events_total=0
    _emit() { printf '%s\n' "$1"; }
    while IFS=$'\x1f' read -r cal_id cal_title cal_extid; do
        [ -z "$cal_id" ] && continue
        if _is_system_calendar "$cal_title" \
            || _is_caldav_system_endpoint "$cal_extid" \
            || [ -z "$cal_title" ]; then
            skipped=$((skipped + 1))
            continue
        fi
        _ec="$(_ev_count_for "$cal_id")"
        if [ -z "$_ec" ] || [ "$_ec" = "0" ]; then
            skipped=$((skipped + 1))
            continue
        fi
        local friendly fname
        friendly="$(_friendly_calendar_title "$cal_title")"
        fname="$(_sanitize_name "$friendly")"
        [ -z "$fname" ] && fname="Calendar-$cal_id"
        local out_file="$out_root/$fname.ics"
        if [ -e "$out_file" ] || [ -L "$out_file" ]; then
            local _new_out
            _new_out="$(_unique_path "$out_file")"
            log_info "Disambiguating duplicate calendar filename: $fname.ics → ${_new_out##*/}"
            out_file="$_new_out"
            fname="${out_file##*/}"
            fname="${fname%.ics}"
        fi
        local raw_stream="$SCRATCH_DIR/cal_${cal_id}.unfolded.ics"
        local events_stream="$SCRATCH_DIR/cal_${cal_id}.events"
        : > "$raw_stream"
        : > "$events_stream"
        local ev_count=0 _ev_dropped=0
        local ev_calid ev_id ev_uid ev_start ev_end ev_stz ev_etz ev_allday ev_sum ev_desc ev_hasrec
        local ev_status ev_avail ev_url ev_isover ev_origparent ev_origdate
        local _ev_slice="$SCRATCH_DIR/events_by_cal/$cal_id.tsv"
        {
        [ -s "$_ev_slice" ] && \
        while IFS=$'\x1f' read -r ev_calid ev_id ev_uid ev_start ev_end ev_stz ev_etz ev_allday ev_sum ev_desc ev_hasrec ev_status ev_avail ev_url ev_isover ev_origparent ev_origdate; do
            [ -z "$(_cal_ts_to_unix "$ev_start")" ] && { _ev_dropped=$((_ev_dropped + 1)); continue; }
            local _ev_uid_eff="$ev_uid" _ev_recid=""
            if [ "$ev_isover" = "1" ]; then
                local _puid_ref="_calmap_puid_$ev_origparent"
                if [ -z "$ev_origparent" ] || [ -z "${!_puid_ref:-}" ] \
                    || [ -z "$(_cal_ts_to_unix "$ev_origdate")" ]; then
                    _ev_dropped=$((_ev_dropped + 1))
                    continue
                fi
                _ev_uid_eff="${!_puid_ref}"
            fi
            _emit "BEGIN:VEVENT"
            _emit "UID:$(ics_escape "$_ev_uid_eff")"
            _emit "DTSTAMP:19700101T000000Z"
            if [ "$ev_allday" = "1" ]; then
                local sd
                sd="$(_cal_ts_to_utc_date "$ev_start")"
                [ -n "$sd" ] && _emit "DTSTART;VALUE=DATE:$sd"
                if [ -n "$ev_end" ]; then
                    local ed_unix
                    ed_unix="$(_cal_ts_to_unix "$ev_end")"
                    if [ -n "$ed_unix" ]; then
                        local end_date
                        end_date="$(_unix_plus_days_to_date "$ed_unix" 1)"
                        [ -n "$end_date" ] && _emit "DTEND;VALUE=DATE:$end_date"
                    fi
                fi
            else
                local sd ed sd_tz ed_tz
                sd_tz="$ev_stz"
                ed_tz="${ev_etz:-$ev_stz}"
                if _tz_is_valid "$sd_tz"; then
                    sd="$(_cal_ts_to_local_in_tz "$ev_start" "$sd_tz")"
                    if [ -n "$sd" ]; then
                        _emit "DTSTART;TZID=$sd_tz:$sd"
                    else
                        sd="$(_cal_ts_to_utc "$ev_start")"
                        [ -n "$sd" ] && _emit "DTSTART:$sd"
                    fi
                else
                    sd="$(_cal_ts_to_utc "$ev_start")"
                    [ -n "$sd" ] && _emit "DTSTART:$sd"
                fi
                if [ -n "$ev_end" ]; then
                    if _tz_is_valid "$ed_tz"; then
                        ed="$(_cal_ts_to_local_in_tz "$ev_end" "$ed_tz")"
                        if [ -n "$ed" ]; then
                            _emit "DTEND;TZID=$ed_tz:$ed"
                        fi
                    else
                        ed="$(_cal_ts_to_utc "$ev_end")"
                        [ -n "$ed" ] && _emit "DTEND:$ed"
                    fi
                fi
            fi
            if [ "$ev_isover" = "1" ]; then
                local _ridv
                if [ "$ev_allday" = "1" ]; then
                    _ridv="$(_cal_ts_to_utc_date "$ev_origdate")"
                    [ -n "$_ridv" ] && _emit "RECURRENCE-ID;VALUE=DATE:$_ridv"
                elif _tz_is_valid "$ev_stz"; then
                    _ridv="$(_cal_ts_to_local_in_tz "$ev_origdate" "$ev_stz")"
                    if [ -n "$_ridv" ]; then
                        _emit "RECURRENCE-ID;TZID=$ev_stz:$_ridv"
                    else
                        _ridv="$(_cal_ts_to_utc "$ev_origdate")"
                        [ -n "$_ridv" ] && _emit "RECURRENCE-ID:$_ridv"
                    fi
                else
                    _ridv="$(_cal_ts_to_utc "$ev_origdate")"
                    [ -n "$_ridv" ] && _emit "RECURRENCE-ID:$_ridv"
                fi
            fi
            [ -n "$ev_sum" ] && _emit "SUMMARY:$(ics_escape "$(_unescape_bsafe "$ev_sum")")"
            if [ -n "$ev_desc" ]; then
                _emit "DESCRIPTION:$(ics_escape "$(_unescape_bsafe "$ev_desc")")"
            fi
            local lid ltitle _cm_lref
            _cm_lref="_calmap_loc_$ev_id"
            if [ -n "${!_cm_lref:-}" ]; then
                IFS=$'\x1f' read -r lid ltitle <<< "${!_cm_lref}"
                [ -n "$ltitle" ] && _emit "LOCATION:$(ics_escape "$(_unescape_bsafe "$ltitle")")"
            fi
            if [ "$ev_hasrec" = "1" ] && [ "$ev_isover" != "1" ]; then
                local rid rfreq rint rcount rend rspec rfdow rmd rrule_line _cm_rref _cm_line
                _cm_rref="_calmap_rec_$ev_id"
                if [ -n "${!_cm_rref:-}" ]; then
                    while IFS= read -r _cm_line; do
                        IFS=$'\x1f' read -r rid rfreq rint rcount rend rspec rfdow rmd <<< "$_cm_line"
                        [ "$rid" = "$ev_id" ] || continue
                        rrule_line="$(_apple_recurrence_to_rrule \
                            "$rfreq" "$rint" "$rcount" "$rend" "$rspec" \
                            "$ev_allday" "$rfdow" "$rmd")"
                        [ -n "$rrule_line" ] && _emit "$rrule_line"
                    done <<< "${!_cm_rref}"
                fi
                local exid exdate exics _cm_eref
                _cm_eref="_calmap_exc_$ev_id"
                [ -n "${!_cm_eref:-}" ] && \
                while IFS= read -r _cm_line; do
                    IFS=$'\x1f' read -r exid exdate <<< "$_cm_line"
                    [ "$exid" = "$ev_id" ] || continue
                    [ -z "$exdate" ] && continue
                    if [ "$ev_allday" = "1" ]; then
                        exics="$(_cal_ts_to_utc_date "$exdate")"
                        [ -n "$exics" ] && _emit "EXDATE;VALUE=DATE:$exics"
                    elif _tz_is_valid "$ev_stz"; then
                        exics="$(_cal_ts_to_local_in_tz "$exdate" "$ev_stz")"
                        [ -n "$exics" ] && _emit "EXDATE;TZID=$ev_stz:$exics"
                    else
                        exics="$(_cal_ts_to_utc "$exdate")"
                        [ -n "$exics" ] && _emit "EXDATE:$exics"
                    fi
                done <<< "${!_cm_eref}"
            fi
            case "$ev_status" in
                1) _emit "STATUS:CONFIRMED" ;;
                2) _emit "STATUS:TENTATIVE" ;;
                3) _emit "STATUS:CANCELLED" ;;
            esac
            case "$ev_avail" in
                '') ;;
                1)  _emit "TRANSP:TRANSPARENT" ;;
                *)  _emit "TRANSP:OPAQUE" ;;
            esac
            [ -n "$ev_url" ] && _emit "URL:$(ics_escape "$(_unescape_bsafe "$ev_url")")"
            local _cm_aref="_calmap_alm_$ev_id"
            if [ -n "${!_cm_aref:-}" ]; then
                local _alm_line _alm_oid _alm_type _alm_abs _alm_rel _alm_trig
                while IFS= read -r _alm_line; do
                    IFS=$'\x1f' read -r _alm_oid _alm_type _alm_abs _alm_rel <<< "$_alm_line"
                    [ "$_alm_oid" = "$ev_id" ] || continue
                    _alm_trig=""
                    if [ -n "$_alm_rel" ] && _alarm_reloff_plausible "$_alm_rel"; then
                        local _dur
                        _dur="$(_alarm_offset_to_duration "$_alm_rel")"
                        [ -n "$_dur" ] && _alm_trig="TRIGGER:$_dur"
                    fi
                    if [ -z "$_alm_trig" ] && [ -n "$_alm_abs" ] \
                        && [ "$_alm_abs" != "0" ]; then
                        local _absv
                        _absv="$(_cal_ts_to_utc "$_alm_abs")"
                        [ -n "$_absv" ] && _alm_trig="TRIGGER;VALUE=DATE-TIME:$_absv"
                    fi
                    [ -z "$_alm_trig" ] && continue
                    _emit "BEGIN:VALARM"
                    _emit "ACTION:DISPLAY"
                    _emit "$_alm_trig"
                    if [ -n "$ev_sum" ]; then
                        _emit "DESCRIPTION:$(ics_escape "$(_unescape_bsafe "$ev_sum")")"
                    else
                        _emit "DESCRIPTION:Reminder"
                    fi
                    _emit "END:VALARM"
                done <<< "${!_cm_aref}"
            fi
            _emit "END:VEVENT"
            ev_count=$((ev_count + 1))
            events_total=$((events_total + 1))
        done < "$_ev_slice"
        } >> "$events_stream"
        if [ "$ev_count" -eq 0 ]; then
            log_warn "Calendar '$friendly' had event rows but none produced a usable event — not exported."
            note_incomplete "$out_root" "Calendar: $friendly" \
                "the calendar had event rows but every one was unusable (e.g. no parseable start date) — this calendar was not exported"
            skipped=$((skipped + 1))
            continue
        fi
        if [ "$_ev_dropped" -gt 0 ]; then
            log_warn "Calendar '$friendly': $_ev_dropped event(s) skipped (no parseable start date, or an unresolvable recurrence override) — not in the export; $ev_count exported."
            note_incomplete "$out_root" "Calendar: $friendly — $_ev_dropped event(s) not exported" \
                "$_ev_dropped event(s) in this calendar could not be exported (no parseable start date, or a detached recurrence-override whose parent series could not be resolved); $ev_count event(s) were exported"
        fi
        {
            printf 'BEGIN:VCALENDAR\n'
            printf 'VERSION:2.0\n'
            printf 'PRODID:-//Unknown//Unknown//EN\n'
            printf 'CALSCALE:GREGORIAN\n'
            printf 'X-WR-CALNAME:%s\n' "$(ics_escape "$(_unescape_nl "$friendly")")"
            cat "$events_stream"
            printf 'END:VCALENDAR\n'
        } > "$raw_stream"
        local tmp
        if ! tmp="$(mktemp "$out_file.tmp.XXXXXX" 2>/dev/null)"; then
            log_warn "Cannot create temp file for $friendly."
            note_incomplete "$out_root" "Calendar: $friendly" \
                "could not create a temp file to assemble the .ics — this calendar was not exported"
            skipped=$((skipped + 1))
            continue
        fi
        track_output_path "$tmp"
        if ! _fold_75_octets < "$raw_stream" > "$tmp"; then
            log_warn "Folding failed for $friendly."
            note_incomplete "$out_root" "Calendar: $friendly" \
                "the calendar file could not be formatted into valid .ics — this calendar's .ics was not written"
            rm -f -- "$tmp"
            skipped=$((skipped + 1))
            continue
        fi
        if ! grep -q 'BEGIN:VCALENDAR' "$tmp"; then
            log_warn "Output for $friendly missing VCALENDAR — refusing to publish."
            note_incomplete "$out_root" "Calendar: $friendly" \
                "the generated calendar file was malformed (it failed a basic .ics validity check) and was refused — this calendar was not exported"
            rm -f -- "$tmp"
            skipped=$((skipped + 1))
            continue
        fi
        if ! mv -f -- "$tmp" "$out_file"; then
            log_warn "Failed to write $out_file."
            note_incomplete "$out_root" "Calendar: $friendly" \
                "the final move into place failed (write error) — this calendar was not exported"
            rm -f -- "$tmp"
            skipped=$((skipped + 1))
            continue
        fi
        _untrack_output_path "$tmp"
        clean_ics_file "$out_file" || \
            log_warn "iCal post-clean pass failed for $fname.ics; output preserved"
        log_info "Wrote $fname.ics ($ev_count $(_pluralize "$ev_count" event))"
        exported=$((exported + 1))
    done < "$SCRATCH_DIR/calendars.tsv"
    log_info "Writing subscriptions list and finalising..."
    local _vcp_total="$total_cals"
    [ "${_cal_dump_ok:-1}" -eq 0 ] && _vcp_total=""
    { [ -n "${_cal_query_failed:-}" ] || [ -n "${_ev_query_failed:-}" ]; } && _vcp_total=""
    validate_count_parity "$_vcp_total" $((exported + skipped)) \
        "Calendar" "$out_root"
    local subs_csv="$out_root/CalendarSubscriptions.csv"
    require_no_collision "$subs_csv"
    local _subs_query_failed=""
    local _subs_rows
    _subs_rows="$(mktemp "$SCRATCH_DIR/cal_subs_rows.XXXXXX" 2>/dev/null)" \
        || _subs_rows="$SCRATCH_DIR/cal_subs_rows.$$"
    local _subs_tmp
    _subs_tmp="$(mktemp "$subs_csv.tmp.XXXXXX" 2>/dev/null)" \
        || _subs_tmp="$subs_csv.tmp.$$"
    track_output_path "$_subs_tmp"
    {
        printf 'Calendar,URL\r\n'
        if _cal_has Store; then
            sqlite3 -readonly -separator $'\x1f' "$snap" "
                SELECT $(_sql_tsv_safe "c.title"),
                       COALESCE(c.subcal_url, c.published_URL, '')
                  FROM Calendar c
                  JOIN Store s ON c.store_id = s.ROWID
                 WHERE c.title IS NOT NULL
                   AND LENGTH(c.title) > 0
                   AND (s.type = 4 OR c.subcal_url IS NOT NULL OR c.published_URL IS NOT NULL)
                   AND COALESCE(c.subcal_url, c.published_URL, '') != ''
                 ORDER BY c.title, c.ROWID;
            " > "$_subs_rows" 2>/dev/null \
                || _subs_query_failed=1
            while IFS=$'\x1f' read -r _scal_name _scal_url; do
                [ -z "$_scal_url" ] && continue
                printf '%s,%s\r\n' \
                    "$(csv_field "$(_friendly_calendar_title "$_scal_name")")" \
                    "$(csv_field "$_scal_url")"
            done < "$_subs_rows"
        fi
    } > "$_subs_tmp"
    if ! _atomic_commit_tmp $? "$_subs_tmp" "$subs_csv" \
        "CalendarSubscriptions.csv"; then
        note_incomplete "$out_root" "CalendarSubscriptions.csv" \
            "writing CalendarSubscriptions.csv failed (disk full / read-only volume) — subscribed-calendar URLs are not in the export"
    fi
    rm -f -- "$_subs_rows" 2>/dev/null
    _untrack_output_path "$_subs_tmp"
    if [ -n "$_subs_query_failed" ]; then
        log_warn "Calendars: subscriptions query failed — CalendarSubscriptions.csv may be incomplete."
        note_incomplete "$out_root" "CalendarSubscriptions.csv" \
            "reading calendar subscriptions from the database failed partway through (it may be corrupt or have an unexpected layout); subscription URLs may be missing from the export"
    fi
    if ! _cal_has Store; then
        log_info "Calendar schema has no Store table — CalendarSubscriptions.csv skipped."
    fi
    local sub_lines
    sub_lines="$(_count_csv_rows "$subs_csv")"
    [ "$sub_lines" -lt 0 ] && sub_lines=0
    if [ "$sub_lines" -le 0 ]; then
        rm -f -- "$subs_csv"
        sub_lines=0
    else
        validate_csv_rfc4180 "$subs_csv" || true
    fi
    if [ "$exported" -gt 0 ] || [ "$sub_lines" -gt 0 ]; then
        local _stat
        if [ "$exported" -eq 0 ] && [ "$sub_lines" -gt 0 ]; then
            _stat="$sub_lines subscription $(_pluralize "$sub_lines" URL) — no user calendars to export"
        else
            _stat="$exported $(_pluralize "$exported" calendar), $events_total $(_pluralize "$events_total" event)"
            [ "$sub_lines" -gt 0 ] && _stat="$_stat, $sub_lines subscription $(_pluralize "$sub_lines" URL)"
        fi
        _stat="$_stat, $(_dir_size_human "$out_root")"
        log_ok "Wrote Calendars/ ($_stat)"
    elif [ "$_cal_disc_ok" -eq 0 ] || [ -n "$_cal_query_failed" ] || [ -n "$_ev_query_failed" ]; then
        if [ "$_cal_disc_ok" -eq 0 ]; then
            log_warn "Calendars: could not read the list of calendars from the database — calendars may be missing from the export."
            note_incomplete "$out_root" "Calendars export" \
                "reading the list of calendars from the database failed (it may be corrupt or have an unexpected layout on this macOS version); calendars could not be listed"
        elif ! report_have_incomplete "$out_root"; then
            note_incomplete "$out_root" "Calendars export" \
                "a calendar or event query returned no rows despite a positive discovery count; the export may be missing calendars or events"
        fi
    elif report_have_incomplete "$out_root"; then
        log_warn "Calendars: an earlier step could not complete$(_disclosure_pointer "Calendars/_incomplete.txt")."
    else
        rmdir "$out_root" 2>/dev/null || true
        report_empty_source "calendars" "Calendar"
    fi
    mark_success
    sweep_junk_files "$out_root"
    print_summary
    if [ "$ERR_COUNT" -gt 0 ]; then exit 1; fi
    exit 0
}

_vcf_escape() {
    ics_escape "$1"
}

_vcf_label_to_type() {
    local lbl="$1" kind="$2"
    case "$lbl" in
        '_$!<'*'>!$_') lbl="${lbl#_\$!<}"; lbl="${lbl%>!\$_}" ;;
    esac
    if [ "$kind" = "email" ]; then
        local _u; _u="$(printf '%s' "$lbl" | LC_ALL=C tr 'a-z' 'A-Z')"
        case "$_u" in
            INTERNET|X-INTERNET|XINTERNET) return 0 ;;
        esac
    fi
    case "$lbl" in
        Home|home)               printf 'Home' ;;
        Work|work)               printf 'Work' ;;
        Other|other)             printf 'Other' ;;
        Mobile|mobile)
            if [ "$kind" = "tel" ]; then printf 'Cell'; else printf 'Other'; fi ;;
        iPhone)
            if [ "$kind" = "tel" ]; then printf 'Cell'; else printf 'Other'; fi ;;
        Main|main)               printf 'Voice' ;;
        Pager|pager)             printf 'Pager' ;;
        HomeFAX|HomeFax|homefax) printf 'Home,Fax' ;;
        WorkFAX|WorkFax|workfax) printf 'Work,Fax' ;;
        OtherFAX|OtherFax)       printf 'Fax' ;;
        '')                      printf '' ;;
        *)
            local s="$lbl"
            s="$(printf '%s' "$s" | LC_ALL=C tr -cd 'A-Za-z0-9')"
            [ -n "$s" ] && printf '%s' "$s"
            ;;
    esac
}

_vcf_normalize_tel() {
    local v="$1"
    local ext=""
    local _ext_n
    _ext_n=$(printf '%s' "$v" | LC_ALL=C sed -nE 's/.*[xX]([0-9]+)$/\1/p')
    if [ -n "$_ext_n" ]; then
        ext="$_ext_n"
        v="${v%[xX]*}"
    else
        _ext_n=$(printf '%s' "$v" | LC_ALL=C sed -nE 's/.*[eE][xX][tT][. ]*([0-9]+)$/\1/p')
        if [ -n "$_ext_n" ]; then
            ext="$_ext_n"
            v="$(printf '%s' "$v" | LC_ALL=C sed -E 's/[eE][xX][tT][. ]*[0-9]+$//')"
        fi
    fi
    v="${v%"${v##*[![:space:]]}"}"
    case "$v" in
        " "*\+*|\+*) printf '%s|%s' "$v" "$ext"; return ;;
    esac
    local digits
    digits="$(printf '%s' "$v" | LC_ALL=C tr -cd '0-9')"
    case "${#digits}" in
        11)
            if [ "${digits:0:1}" = "1" ]; then digits="${digits:1}"; fi
            ;;
    esac
    if [ "${#digits}" = "10" ]; then
        v="(${digits:0:3}) ${digits:3:3}-${digits:6:4}"
    fi
    printf '%s|%s' "$v" "$ext"
}

_cd_ts_to_vcard_date() {
    local _u; _u="$(_cd_ts_to_unix_signed "$1")"
    [ -n "$_u" ] || return 0
    TZ=UTC date -r "$_u" +%Y-%m-%d 2>/dev/null
}

_sniff_image_type() {
    local f="$1" head
    head="$(xxd -l 4 -p "$f" 2>/dev/null)"
    case "$head" in
        ffd8ff*)         printf 'JPEG' ;;
        89504e47)        printf 'PNG' ;;
        4749463[78]*)    printf 'GIF' ;;
        4d4d002a|49492a00) printf 'TIFF' ;;
    esac
}

_parse_external_uuid() {
    local f="$1" size first uuid
    size="$(stat -f %z "$f" 2>/dev/null)"
    [ "$size" = "38" ] || return 1
    first="$(head -c 1 "$f" 2>/dev/null | LC_ALL=C od -An -tx1 | LC_ALL=C tr -d ' \n')"
    [ "$first" = "02" ] || return 1
    uuid="$(LC_ALL=C tail -c +2 "$f" 2>/dev/null | LC_ALL=C head -c 36)"
    case "$uuid" in
        [0-9A-F][0-9A-F][0-9A-F][0-9A-F][0-9A-F][0-9A-F][0-9A-F][0-9A-F]-[0-9A-F][0-9A-F][0-9A-F][0-9A-F]-[0-9A-F][0-9A-F][0-9A-F][0-9A-F]-[0-9A-F][0-9A-F][0-9A-F][0-9A-F]-[0-9A-F][0-9A-F][0-9A-F][0-9A-F][0-9A-F][0-9A-F][0-9A-F][0-9A-F][0-9A-F][0-9A-F][0-9A-F][0-9A-F])
            printf '%s' "$uuid" ;;
        *) return 1 ;;
    esac
}

_vcf_relation_to_type() {
    local lbl="$1"
    case "$lbl" in
        '_$!<'*'>!$_') lbl="${lbl#_\$!<}"; lbl="${lbl%>!\$_}" ;;
    esac
    case "$lbl" in
        Spouse|spouse)                printf 'spouse' ;;
        Child|child)                  printf 'child' ;;
        Parent|parent|Mother|mother|Father|father)
                                      printf 'parent' ;;
        Brother|brother|Sister|sister|Sibling|sibling)
                                      printf 'sibling' ;;
        Friend|friend)                printf 'friend' ;;
        Assistant|assistant)          printf 'co-worker' ;;
        Manager|manager)              printf 'co-worker' ;;
        Partner|partner)              printf 'spouse' ;;
        *)                            printf '' ;;
    esac
}

_vcf_im_service() {
    local svc="$1"
    case "$svc" in
        '_$!<'*'>!$_') svc="${svc#_\$!<}"; svc="${svc%>!\$_}" ;;
    esac
    case "$svc" in
        com.apple.*) svc="${svc##*.}" ;;
    esac
    local scheme token="$svc"
    case "$svc" in
        AIM|aim)                       scheme="aim";       token="AIM" ;;
        Jabber|jabber|XMPP|xmpp)       scheme="xmpp";      token="Jabber" ;;
        MSN|msn)                       scheme="msnim";     token="MSN" ;;
        ICQ|icq)                       scheme="icq";       token="ICQ" ;;
        Yahoo|yahoo)                   scheme="ymsgr";     token="Yahoo" ;;
        GoogleTalk|"Google Talk"|googletalk)
                                       scheme="xmpp";      token="GoogleTalk" ;;
        Skype|skype)                   scheme="skype";     token="Skype" ;;
        QQ|qq)                         scheme="x-apple";   token="QQ" ;;
        Facebook|facebook)             scheme="xmpp";      token="Facebook" ;;
        GaduGadu|gadugadu)             scheme="x-apple";   token="GaduGadu" ;;
        '')                            scheme="x-apple";   token="" ;;
        *)
            scheme="$(printf '%s' "$svc" | LC_ALL=C tr 'A-Z' 'a-z' \
                      | LC_ALL=C tr -cd 'a-z0-9')"
            [ -z "$scheme" ] && scheme="x-apple"
            token="$svc"
            ;;
    esac
    printf '%s|%s' "$scheme" "$token"
}

AB_DIR="$HOME/Library/Application Support/AddressBook"
AB_DB="$AB_DIR/AddressBook-v22.abcddb"

contacts_main() {
    maybe_show_help "$@"
    _announce_step "Contacts export"
    check_dependencies
    local out_arg out_dir
    out_arg="$(_parse_output_folder_arg "$@")" || exit 1
    out_dir="$(resolve_output_dir "$out_arg")" || exit 1
    _announce_output_dir "Contacts"
    require_full_disk_access
    warn_if_app_running Contacts
    [ -d "$AB_DIR" ] || die "AddressBook directory not found at: $AB_DIR
  This is unusual; macOS creates it on first sign-in to Contacts.app.
  Open Contacts.app once and re-run."
    local out_root="$out_dir/Contacts"
    require_no_collision "$out_root"
    local out_file="$out_root/Contacts.vcf"
    ensure_scratch
    log_info "Snapshotting AddressBook database..."
    local -a ab_candidates=()
    local _src_db
    for _src_db in "$AB_DIR/Sources"/*/AddressBook-v22.abcddb; do
        [ -f "$_src_db" ] && ab_candidates+=( "$_src_db" )
    done
    [ -f "$AB_DB" ] && ab_candidates+=( "$AB_DB" )
    [ "${#ab_candidates[@]}" -eq 0 ] && die "No AddressBook database found under $AB_DIR.
  Open Contacts.app once to initialise the store, then re-run."
    if [ "${#ab_candidates[@]}" -gt 1 ]; then
        log_info "Scanning ${#ab_candidates[@]} AddressBook $(_pluralize "${#ab_candidates[@]}" candidate) (root + Sources/)..."
    fi
    local -a ab_db_paths=() ab_db_snaps=()
    local _cand _cand_snap _cand_ent _cand_count
    for _cand in "${ab_candidates[@]}"; do
        if ! _cand_snap="$(snapshot_db "$_cand")"; then
            log_warn "Contacts: could not snapshot $_cand for read-only querying — skipping; any contacts in this account database are NOT in the export."
            continue
        fi
        _cand_ent="$(sqlite3 -readonly "$_cand_snap" "
            SELECT Z_ENT FROM Z_PRIMARYKEY
             WHERE Z_NAME IN ('ABCDContact','ABCDRecord')
             ORDER BY CASE Z_NAME WHEN 'ABCDContact' THEN 0 ELSE 1 END
             LIMIT 1;" 2>/dev/null)"
        if [ -z "$_cand_ent" ]; then
            log_warn "Contacts: $_cand has no ABCDContact/ABCDRecord entity in Z_PRIMARYKEY (unrecognised schema) — skipping; any contacts in it are NOT in the export."
            continue
        fi
        case "$_cand_ent" in *[!0-9]*) log_warn "Contacts: $_cand returned a non-numeric contact entity number — skipping."; continue ;; esac
        _cand_count="$(sqlite3 -readonly "$_cand_snap" \
            "SELECT COUNT(*) FROM ZABCDRECORD WHERE Z_ENT=$_cand_ent;" 2>/dev/null)"
        case "$_cand_count" in ''|*[!0-9]*) log_warn "Contacts: the contact-count query failed against $_cand — skipping; any contacts in it are NOT in the export."; continue ;; esac
        [ "$_cand_count" -le 0 ] && continue
        ab_db_paths+=( "$_cand" )
        ab_db_snaps+=( "$_cand_snap" )
    done
    if [ "${#ab_db_paths[@]}" -ne "${#ab_db_snaps[@]}" ]; then
        die "Internal invariant violation: ab_db_paths (${#ab_db_paths[@]}) and ab_db_snaps (${#ab_db_snaps[@]}) array lengths disagree. This is a refactor bug; please report."
    fi
    [ "${#ab_db_paths[@]}" -eq 0 ] && die "No AddressBook database with contact rows found
  under $AB_DIR (root + Sources/). Open Contacts.app and re-run."
    if [ "${#ab_db_paths[@]}" -gt 1 ]; then
        log_info "Exporting ${#ab_db_paths[@]} AddressBook source $(_pluralize "${#ab_db_paths[@]}" database) (one per account)..."
    fi
    log_info "Probing schema (entities, photo storage)..."
    _create_output_dir "$out_root"
    local raw_stream="$SCRATCH_DIR/Contacts.unfolded.vcf"
    : > "$raw_stream"
    local groups_data="$SCRATCH_DIR/contact_groups_all.tsv"
    : > "$groups_data"
    local run_processed=0
    _export_contacts_db() {
    local snap="$1" db_path="$2" is_first_db="${3:-0}"
    _db_step() { [ "$is_first_db" = "1" ] && log_info "$@" || true; }
    local _srchash
    _srchash="$(printf '%s' "$db_path" | md5 2>/dev/null \
                | LC_ALL=C tr -cd 'a-f0-9' | cut -c1-8)"
    [ -z "$_srchash" ] && _srchash="src"
    local EXTERNAL_DATA_DIR=""
    local _ab_dir_picked
    _ab_dir_picked="$(dirname "$db_path")"
    if [ -d "$_ab_dir_picked/.AddressBook-v22_SUPPORT/_EXTERNAL_DATA" ]; then
        EXTERNAL_DATA_DIR="$_ab_dir_picked/.AddressBook-v22_SUPPORT/_EXTERNAL_DATA"
    elif [ -d "$AB_DIR/.AddressBook-v22_SUPPORT/_EXTERNAL_DATA" ]; then
        EXTERNAL_DATA_DIR="$AB_DIR/.AddressBook-v22_SUPPORT/_EXTERNAL_DATA"
    fi
    local contact_ent
    contact_ent="$(sqlite3 -readonly "$snap" "
        SELECT Z_ENT FROM Z_PRIMARYKEY
         WHERE Z_NAME IN ('ABCDContact','ABCDRecord')
         ORDER BY CASE Z_NAME WHEN 'ABCDContact' THEN 0 ELSE 1 END
         LIMIT 1;" 2>/dev/null)"
    if [ -z "$contact_ent" ]; then
        local _avail
        _avail="$(sqlite3 -readonly "$snap" \
            "SELECT GROUP_CONCAT(name, ', ') FROM sqlite_master \
              WHERE type='table' AND name LIKE 'ZABCD%';" 2>/dev/null)"
        die "Cannot resolve ABCDContact entity id (schema unrecognised; ZABCD tables: ${_avail:-none})"
    fi
    case "$contact_ent" in
        ''|*[!0-9]*) die "Resolved a non-numeric ABCDContact entity id ('$contact_ent') — schema unrecognised" ;;
    esac
    local group_ent="" grp_tbl="" grp_col_parent="" grp_col_contact=""
    group_ent="$(sqlite3 -readonly "$snap" "
        SELECT Z_ENT FROM Z_PRIMARYKEY
         WHERE Z_NAME IN ('ABCDAbstractGroup','ABCDGroup')
         ORDER BY CASE Z_NAME WHEN 'ABCDAbstractGroup' THEN 0 ELSE 1 END
         LIMIT 1;" 2>/dev/null)"
    case "$group_ent" in ''|*[!0-9]*) group_ent="" ;; esac
    if [ -n "$group_ent" ]; then
        grp_tbl="Z_${contact_ent}PARENTGROUPS"
        grp_col_parent="Z_${group_ent}PARENTGROUPS1"
        grp_col_contact="Z_${contact_ent}CONTACTS"
        if ! sqlite3 -readonly "$snap" "SELECT 1 FROM $grp_tbl LIMIT 1;" >/dev/null 2>&1; then
            local found
            found="$(sqlite3 -readonly "$snap" "
                SELECT name FROM sqlite_master
                 WHERE type='table' AND name LIKE 'Z_%PARENTGROUPS'
                 ORDER BY name DESC LIMIT 1;" 2>/dev/null)"
            if [ -n "$found" ]; then
                grp_tbl="$found"
                local _tbl_ent="${found#Z_}"
                _tbl_ent="${_tbl_ent%PARENTGROUPS}"
                case "$_tbl_ent" in
                    ''|*[!0-9]*) grp_tbl="" ;;
                    *) grp_col_contact="Z_${_tbl_ent}CONTACTS" ;;
                esac
            else
                grp_tbl=""
            fi
        fi
    fi
    if [ -n "$grp_tbl" ]; then
        local _gcol
        grp_col_contact=""; grp_col_parent=""
        local _grpcols_tmp="$SCRATCH_DIR/contact_groupcols.txt"
        sqlite3 -readonly "$snap" \
            "SELECT name FROM pragma_table_info('$grp_tbl');" \
            > "$_grpcols_tmp" 2>/dev/null
        while IFS= read -r _gcol; do
            case "$_gcol" in
                *CONTACTS*)     grp_col_contact="$_gcol" ;;
                *PARENTGROUPS*) grp_col_parent="$_gcol" ;;
            esac
        done < "$_grpcols_tmp"
        rm -f -- "$_grpcols_tmp"
        if [ -z "$grp_col_contact" ] || [ -z "$grp_col_parent" ]; then
            grp_tbl=""
        fi
    fi
    local total_count
    total_count="$(sqlite3 -readonly "$snap" "SELECT COUNT(*) FROM ZABCDRECORD WHERE Z_ENT=$contact_ent;" 2>/dev/null)"
    case "$total_count" in
        ''|*[!0-9]*) die "Could not count contacts — snapshot unreadable" ;;
    esac
    [ "$total_count" -le 0 ] && return 0
    log_info "Found $total_count $(_pluralize "$total_count" contact)"
    _sat_table_present() {
        sqlite3 -readonly "$snap" \
            "SELECT 1 FROM sqlite_master WHERE type='table' AND name='$1' LIMIT 1;" \
            2>/dev/null | grep -q '^1$'
    }
    _emit_satellite() {
        local _tbl="$1" _tsv="$2" _label="$3" _sql="$4"
        : > "$SCRATCH_DIR/$_tsv"
        if _sat_table_present "$_tbl"; then
            if ! sqlite3 -readonly -separator $'\x1f' "$snap" "$_sql" \
                    > "$SCRATCH_DIR/$_tsv" 2>/dev/null; then
                log_warn "Contacts: $_tbl present but query failed — $_label will be missing from the exported vCards."
                note_incomplete "$out_root" "Contact $_label" \
                    "the data source for $_label could not be read on this version of macOS (an unexpected Contacts database layout) — contacts still exported, but without their $_label"
            fi
        else
            log_warn "Contacts: $_tbl table absent — $_label will be missing from the exported vCards."
            note_incomplete "$out_root" "Contact $_label" \
                "the data source for $_label is missing from the Contacts database (it may be corrupt or only partly migrated) — contacts still exported, but without their $_label"
        fi
    }
    _emit_satellite_optional() {
        local _tbl="$1" _tsv="$2" _sql="$3"
        : > "$SCRATCH_DIR/$_tsv"
        if _sat_table_present "$_tbl"; then
            sqlite3 -readonly -separator $'\x1f' "$snap" "$_sql" \
                > "$SCRATCH_DIR/$_tsv" 2>/dev/null
            if [ $? -ne 0 ]; then
                log_warn "Contacts: $_tbl present but query failed (column rename?) — its data is missing from the exported vCards."
                note_incomplete "$out_root" "Optional Contacts data ($_tbl)" \
                    "an optional Contacts data source is present but could not be read on this version of macOS (an unexpected database layout); the extra fields it supplies are missing from every contact in this export"
            fi
        fi
    }
    _probe_isprimary() {
        local _t="$1"
        _sat_table_present "$_t" || { printf ', 0 AS _zisprimary_absent'; return 0; }
        if sqlite3 -readonly "$snap" \
            "SELECT name FROM pragma_table_info('$_t');" 2>/dev/null \
            | grep -qx 'ZISPRIMARY'; then
            printf ', COALESCE(ZISPRIMARY,0)'
        else
            printf ', 0 AS _zisprimary_absent'
        fi
    }
    local _phone_pref_col _email_pref_col
    _phone_pref_col="$(_probe_isprimary ZABCDPHONENUMBER)"
    _email_pref_col="$(_probe_isprimary ZABCDEMAILADDRESS)"
    _sat_col_expr() {
        local _picked="$1" _canon="$2" _enc="${3:-_sql_tsv_safe}"
        if [ -z "$_picked" ]; then
            printf "''"
            return 0
        fi
        printf '%s' "$("$_enc" "$_picked")" | LC_ALL=C tr -d '\n'
    }
    _sat_disclose_legacy() {
        local _picked="$1" _canon="$2" _label="${3:-$2}"
        [ -n "$_picked" ] || return 0
        [ "$_picked" = "$_canon" ] && return 0
        log_info "Schema: $_label = $_picked (legacy)"
    }
    _emit_satellite ZABCDPHONENUMBER phones.tsv "phone numbers" "
        SELECT ZOWNER, $(_sql_tsv_safe ZLABEL), $(_sql_tsv_safe ZFULLNUMBER)$_phone_pref_col
          FROM ZABCDPHONENUMBER ORDER BY ZOWNER, ZORDERINGINDEX, Z_PK;"
    _emit_satellite ZABCDEMAILADDRESS emails.tsv "email addresses" "
        SELECT ZOWNER, $(_sql_tsv_safe ZLABEL), $(_sql_tsv_safe ZADDRESS)$_email_pref_col
          FROM ZABCDEMAILADDRESS ORDER BY ZOWNER, ZORDERINGINDEX, Z_PK;"
    _emit_satellite ZABCDPOSTALADDRESS addresses.tsv "postal addresses" "
        SELECT ZOWNER, $(_sql_tsv_safe ZLABEL),
               $(_sql_tsv_bsafe ZSTREET), $(_sql_tsv_bsafe ZCITY), $(_sql_tsv_bsafe ZSTATE),
               $(_sql_tsv_bsafe ZZIPCODE), $(_sql_tsv_bsafe ZCOUNTRYNAME)
          FROM ZABCDPOSTALADDRESS ORDER BY ZOWNER, ZORDERINGINDEX, Z_PK;"
    _emit_satellite ZABCDURLADDRESS urls.tsv "URLs" "
        SELECT ZOWNER, $(_sql_tsv_safe ZLABEL), $(_sql_tsv_bsafe ZURL)
          FROM ZABCDURLADDRESS ORDER BY ZOWNER, ZORDERINGINDEX, Z_PK;"
    _emit_satellite ZABCDCONTACTDATE dates.tsv "dates (anniversaries)" "
        SELECT ZOWNER, $(_sql_tsv_safe ZLABEL), COALESCE(ZDATE,'')
          FROM ZABCDCONTACTDATE ORDER BY ZOWNER, ZORDERINGINDEX, Z_PK;"
    _emit_satellite ZABCDNOTE notes.tsv "notes" "
        SELECT ZCONTACT, $(_sql_tsv_bsafe ZTEXT)
          FROM ZABCDNOTE ORDER BY ZCONTACT, Z_PK;"
    local _im_svc_col
    _im_svc_col="$(_pick_first_col "$snap" ZABCDMESSAGINGADDRESS \
                       ZBUNDLEIDENTIFIERSSTRING ZSERVICENAME || true)"
    _emit_satellite_optional ZABCDMESSAGINGADDRESS im.tsv "
        SELECT ZOWNER,
               $(_sat_col_expr "$_im_svc_col" ZBUNDLEIDENTIFIERSSTRING),
               $(_sql_tsv_safe ZLABEL), $(_sql_tsv_bsafe ZADDRESS)
          FROM ZABCDMESSAGINGADDRESS ORDER BY ZOWNER, ZORDERINGINDEX, Z_PK;"
    _sat_disclose_legacy "$_im_svc_col" ZBUNDLEIDENTIFIERSSTRING \
        'ZABCDMESSAGINGADDRESS service column'
    local _social_url_col
    _social_url_col="$(_pick_first_col "$snap" ZABCDSOCIALPROFILE \
                           ZURLSTRING ZURL || true)"
    _emit_satellite_optional ZABCDSOCIALPROFILE social.tsv "
        SELECT ZOWNER, $(_sql_tsv_safe ZSERVICENAME), $(_sql_tsv_bsafe ZUSERNAME),
               $(_sat_col_expr "$_social_url_col" ZURLSTRING _sql_tsv_bsafe)
          FROM ZABCDSOCIALPROFILE ORDER BY ZOWNER, ZORDERINGINDEX, Z_PK;"
    _sat_disclose_legacy "$_social_url_col" ZURLSTRING \
        'ZABCDSOCIALPROFILE URL column'
    _emit_satellite_optional ZABCDRELATEDNAME related.tsv "
        SELECT ZOWNER, $(_sql_tsv_safe ZLABEL), $(_sql_tsv_bsafe ZNAME)
          FROM ZABCDRELATEDNAME ORDER BY ZOWNER, ZORDERINGINDEX, Z_PK;"
    local _ccols pcol_honorific="ZTITLE"
    _ccols="$(sqlite3 -readonly "$snap" "SELECT name FROM pragma_table_info('ZABCDRECORD');" 2>/dev/null)"
    if printf '%s\n' "$_ccols" | grep -qx 'ZPREFIX'; then
        pcol_honorific="ZPREFIX"
        log_info "Schema: honorific = ZPREFIX (legacy)"
    fi
    case "$pcol_honorific" in *[!A-Za-z0-9_]*) pcol_honorific="ZTITLE" ;; esac
    local kind_col="" kind_mode=""
    if printf '%s\n' "$_ccols" | grep -qx 'ZDISPLAYFLAGS'; then
        kind_col="ZDISPLAYFLAGS"; kind_mode="displayflags"
    elif printf '%s\n' "$_ccols" | grep -qx 'ZCONTACTKINDVALUE'; then
        kind_col="ZCONTACTKINDVALUE"; kind_mode="kindvalue"
        log_info "Schema: card-kind = ZCONTACTKINDVALUE (legacy)"
    elif printf '%s\n' "$_ccols" | grep -qx 'ZISPERSON'; then
        kind_col="ZISPERSON"; kind_mode="isperson"
        log_info "Schema: card-kind = ZISPERSON (legacy)"
    else
        log_info "Schema: no card-kind column found (probed: ZDISPLAYFLAGS / ZCONTACTKINDVALUE / ZISPERSON) — KIND:org will not be emitted on organization cards."
    fi
    case "$kind_col" in *[!A-Za-z0-9_]*) kind_col=""; kind_mode="" ;; esac
    local LIKENESS_OWNER_COL=""
    if sqlite3 -readonly "$snap" \
        "SELECT name FROM sqlite_master WHERE type='table' AND name='ZABCDLIKENESS' LIMIT 1;" \
        2>/dev/null | grep -qx 'ZABCDLIKENESS'; then
        local _lcols
        _lcols="$(sqlite3 -readonly "$snap" \
            "SELECT name FROM pragma_table_info('ZABCDLIKENESS');" 2>/dev/null)"
        if printf '%s\n' "$_lcols" | grep -qx 'ZOWNER'; then
            LIKENESS_OWNER_COL="ZOWNER"
        else
            LIKENESS_OWNER_COL="$(printf '%s\n' "$_lcols" \
                | grep -E '^Z[0-9]+_OWNER$' | head -1)"
        fi
        case "$LIKENESS_OWNER_COL" in
            *[!A-Za-z0-9_]*) LIKENESS_OWNER_COL="" ;;
        esac
    fi
    _db_step "Extracting photos and group memberships..."
    rm -rf -- "$SCRATCH_DIR/contact_photos"
    mkdir -p "$SCRATCH_DIR/contact_photos" || \
        die "Cannot create contact_photos scratch dir"
    local _photo_err _rc
    _photo_err="$(sqlite3 -readonly "$snap" "
        SELECT writefile('$SCRATCH_DIR/contact_photos/img_' || Z_PK || '.bin',
                         ZIMAGEDATA)
          FROM ZABCDRECORD
         WHERE ZIMAGEDATA IS NOT NULL
           AND length(ZIMAGEDATA) > 0
           AND Z_ENT=$contact_ent;
    " 2>&1 >/dev/null)"; _rc=$?
    if [ "$_rc" -ne 0 ] || [ -n "$_photo_err" ]; then
        log_warn "Bulk photo extract via SQLite writefile() failed${_photo_err:+: $_photo_err}; per-contact PHOTO emission may be incomplete"
        note_incomplete "$out_root" \
            "Contact photos (DB ${snap##*/})" \
            "bulk SQLite writefile() failed — some contacts may export without PHOTO blocks${_photo_err:+ (${_photo_err%%$'\n'*})}"
    fi
    if [ -n "$LIKENESS_OWNER_COL" ]; then
        _photo_err="$(sqlite3 -readonly "$snap" "
            SELECT writefile('$SCRATCH_DIR/contact_photos/like_' || c.Z_PK || '.bin',
                             (SELECT l.ZDATA
                                FROM ZABCDLIKENESS l
                               WHERE l.$LIKENESS_OWNER_COL = c.Z_PK
                                 AND l.ZDATA IS NOT NULL
                                 AND length(l.ZDATA) > 0
                               ORDER BY COALESCE(l.ZISPRIMARY, 0) DESC,
                                        COALESCE(l.ZORDERINGINDEX, 0) ASC,
                                        l.Z_PK ASC
                               LIMIT 1))
              FROM ZABCDRECORD c
             WHERE EXISTS (SELECT 1 FROM ZABCDLIKENESS l2
                            WHERE l2.$LIKENESS_OWNER_COL = c.Z_PK
                              AND l2.ZDATA IS NOT NULL);
        " 2>&1 >/dev/null)"; _rc=$?
        if [ "$_rc" -ne 0 ] || [ -n "$_photo_err" ]; then
            log_warn "Bulk likeness extract via SQLite writefile() failed${_photo_err:+: $_photo_err}; tier-3 likeness photos may be missing"
            note_incomplete "$out_root" \
                "Contact likenesses (DB ${snap##*/})" \
                "bulk SQLite writefile() failed — some contacts' modern likeness photos may be absent${_photo_err:+ (${_photo_err%%$'\n'*})}"
        fi
    fi
    local _kind_sel="''"
    [ -n "$kind_col" ] && _kind_sel="COALESCE($kind_col, '')"
    sqlite3 -readonly -separator $'\x1f' "$snap" "
        SELECT Z_PK, $(_sql_tsv_safe "COALESCE(NULLIF(ZUNIQUEID, ''), 'apple-contact-$_srchash-' || Z_PK)"),
               $(_sql_tsv_bsafe ZFIRSTNAME), $(_sql_tsv_bsafe ZMIDDLENAME), $(_sql_tsv_bsafe ZLASTNAME),
               $(_sql_tsv_bsafe ZSUFFIX), $(_sql_tsv_bsafe "$pcol_honorific"), $(_sql_tsv_bsafe ZNICKNAME),
               $(_sql_tsv_bsafe ZORGANIZATION), $(_sql_tsv_bsafe ZJOBTITLE), $(_sql_tsv_bsafe ZDEPARTMENT),
               COALESCE(ZBIRTHDAY, ''),
               $(_sql_tsv_bsafe ZMAIDENNAME), $_kind_sel
          FROM ZABCDRECORD WHERE Z_ENT=$contact_ent ORDER BY Z_PK;
    " > "$SCRATCH_DIR/contacts.tsv" || {
        log_warn "Contacts: the main per-contact query (SELECT against ZABCDRECORD) failed — contacts may be missing or partial in the export."
        note_incomplete "$out_root" "Contacts export" \
            "the main per-contact SELECT against the AddressBook snapshot failed (it may be corrupt or have an unexpected layout on this macOS version); some or all contacts could not be listed"
    }
    : > "$SCRATCH_DIR/contact_groups.tsv"
    if [ -n "$grp_tbl" ]; then
        if ! sqlite3 -readonly -separator $'\x1f' "$snap" "
            SELECT j.${grp_col_contact},
                   $(_sql_tsv_bsafe "COALESCE(g.ZFIRSTNAME, g.ZNAME, 'Unnamed')")
              FROM $grp_tbl j
              JOIN ZABCDRECORD g ON g.Z_PK = j.${grp_col_parent}
             ORDER BY j.${grp_col_contact}, g.ZFIRSTNAME, g.Z_PK, j.ROWID;
        " > "$SCRATCH_DIR/contact_groups.tsv" 2>/dev/null; then
            log_warn "Contact-groups query failed — per-contact CATEGORIES will be empty in the output vCards."
            note_incomplete "$out_root" "Contact group memberships (per-contact CATEGORIES and Contact Groups.csv)" \
                "the group-membership query failed against the AddressBook snapshot — every contact still exported, but without its group/category data"
            : > "$SCRATCH_DIR/contact_groups.tsv"
        fi
    fi
    local _stale_cg
    for _stale_cg in ${!_cg_@}; do unset "$_stale_cg"; done
    if [ -s "$SCRATCH_DIR/contact_groups.tsv" ]; then
        local _cg_pk _cg_cats
        while IFS=$'\t' read -r _cg_pk _cg_cats; do
            case "$_cg_pk" in ''|*[!0-9]*) continue ;; esac
            printf -v "_cg_${_cg_pk}" '%s' "$_cg_cats"
        done < <(LC_ALL=C awk -F$'\x1f' '
            {
                _g = $2
                if ($1 != prev) {
                    if (prev != "") printf "%s\t%s\n", prev, line
                    prev = $1
                    line = _g
                } else {
                    line = line "\037" _g
                }
            }
            END {
                if (prev != "") printf "%s\t%s\n", prev, line
            }
        ' "$SCRATCH_DIR/contact_groups.tsv")
    fi
    _load_satellite_map() {
        local _f="$SCRATCH_DIR/$1" _pfx="$2"
        [ -s "$_f" ] || return 0
        local _line _owner _ref
        while IFS= read -r _line || [ -n "$_line" ]; do
            _owner="${_line%%$'\x1f'*}"
            case "$_owner" in ''|*[!0-9]*) continue ;; esac
            _ref="${_pfx}${_owner}"
            if [ -n "${!_ref:-}" ]; then
                printf -v "$_ref" '%s\n%s' "${!_ref}" "$_line"
            else
                printf -v "$_ref" '%s' "$_line"
            fi
        done < "$_f"
    }
    local _stale _pfx
    for _pfx in _phones_ _emails_ _addresses_ _urls_ _dates_ _notes_ \
                _im_ _social_ _related_; do
        for _stale in $(eval "printf '%s\n' \${!$_pfx@}"); do
            unset "$_stale"
        done
    done
    _load_satellite_map phones.tsv    _phones_
    _load_satellite_map emails.tsv    _emails_
    _load_satellite_map addresses.tsv _addresses_
    _load_satellite_map urls.tsv      _urls_
    _load_satellite_map dates.tsv     _dates_
    _load_satellite_map notes.tsv     _notes_
    _load_satellite_map im.tsv        _im_
    _load_satellite_map social.tsv    _social_
    _load_satellite_map related.tsv   _related_
    _db_step "Emitting per-contact vCards..."
    _emit_unfolded() { printf '%s\n' "$1" >> "$raw_stream"; }
    local processed=0 skipped_untitled=0 no_name=0 custom_dates_dropped=0
    local _pt_last=0 _pt_inline=0
    local pk uid fn mn ln sfx ttl nck org jt dep bday maiden kindraw
    while IFS=$'\x1f' read -r pk uid fn mn ln sfx ttl nck org jt dep bday maiden kindraw; do
        case "${pk}" in
            ''|*[!0-9]*)
                skipped_untitled=$((skipped_untitled + 1))
                continue
                ;;
        esac
        local full=""
        [ -n "$ttl" ] && full="$ttl"
        [ -n "$fn" ] && full="${full:+$full }$fn"
        [ -n "$mn" ] && full="${full:+$full }$mn"
        [ -n "$ln" ] && full="${full:+$full }$ln"
        [ -n "$sfx" ] && full="${full:+$full }$sfx"
        local _nck_trim="$nck" _org_trim="$org"
        _nck_trim="${_nck_trim#"${_nck_trim%%[![:space:]]*}"}"
        _nck_trim="${_nck_trim%"${_nck_trim##*[![:space:]]}"}"
        _org_trim="${_org_trim#"${_org_trim%%[![:space:]]*}"}"
        _org_trim="${_org_trim%"${_org_trim##*[![:space:]]}"}"
        full="${full#"${full%%[![:space:]]*}"}"
        full="${full%"${full##*[![:space:]]}"}"
        [ -z "$full" ] && [ -n "$_nck_trim" ] && full="$_nck_trim"
        [ -z "$full" ] && [ -n "$_org_trim" ] && full="$_org_trim"
        if [ -z "$full" ]; then
            full="(No Name)"
            no_name=$((no_name + 1))
        fi
        _emit_unfolded "BEGIN:VCARD"
        _emit_unfolded "VERSION:3.0"
        _emit_unfolded "PRODID:-//Unknown//Unknown//EN"
        if [ -n "$uid" ]; then
            _emit_unfolded "UID:$(_vcf_escape "$uid")"
        fi
        _emit_unfolded "N:$(_vcf_escape "$(_unescape_bsafe "$ln")");$(_vcf_escape "$(_unescape_bsafe "$fn")");$(_vcf_escape "$(_unescape_bsafe "$mn")");$(_vcf_escape "$(_unescape_bsafe "$ttl")");$(_vcf_escape "$(_unescape_bsafe "$sfx")")"
        _emit_unfolded "FN:$(_vcf_escape "$(_unescape_bsafe "$full")")"
        if [ -n "$kind_mode" ] && [ -n "$kindraw" ]; then
            local _is_org=0
            case "$kind_mode" in
                kindvalue)
                    [ "$kindraw" = "2" ] && _is_org=1 ;;
                isperson)
                    [ "$kindraw" = "0" ] && _is_org=1 ;;
                displayflags)
                    case "$kindraw" in
                        *[!0-9]*) ;;
                        *) [ "$(( 10#$kindraw & 1 ))" -eq 1 ] && _is_org=1 ;;
                    esac ;;
            esac
            [ "$_is_org" -eq 1 ] && _emit_unfolded "KIND:org"
        fi
        [ -n "$_nck_trim" ] && _emit_unfolded "NICKNAME:$(_vcf_escape "$(_unescape_bsafe "$_nck_trim")")"
        [ -n "$maiden" ] && _emit_unfolded "X-MAIDEN-NAME:$(_vcf_escape "$(_unescape_bsafe "$maiden")")"
        if [ -n "$_org_trim" ] || [ -n "$dep" ]; then
            _emit_unfolded "ORG:$(_vcf_escape "$(_unescape_bsafe "$_org_trim")");$(_vcf_escape "$(_unescape_bsafe "$dep")")"
        fi
        [ -n "$jt" ] && _emit_unfolded "TITLE:$(_vcf_escape "$(_unescape_bsafe "$jt")")"
        if [ -n "$bday" ]; then
            local bday_str
            bday_str="$(_cd_ts_to_vcard_date "$bday")"
            [ -n "$bday_str" ] && _emit_unfolded "BDAY:$bday_str"
        fi
        local owner pl pn t _satref _satrows _prim
        _satref="_phones_$pk"; _satrows="${!_satref:-}"
        while IFS=$'\x1f' read -r owner pl pn _prim; do
            [ "$owner" = "$pk" ] || continue
            [ -z "$pn" ] && continue
            local pair val ext
            pair="$(_vcf_normalize_tel "$pn")"
            val="${pair%|*}"; ext="${pair#*|}"
            [ -n "$ext" ] && val="$val x$ext"
            t="$(_vcf_label_to_type "$pl" tel)"
            local prop="TEL" _types="$t"
            [ "$_prim" = "1" ] && _types="${_types:+$_types,}pref"
            [ -n "$_types" ] && prop="$prop;TYPE=$_types"
            _emit_unfolded "$prop:$(_vcf_escape "$val")"
        done <<< "$_satrows"
        _satref="_emails_$pk"; _satrows="${!_satref:-}"
        while IFS=$'\x1f' read -r owner pl pn _prim; do
            [ "$owner" = "$pk" ] || continue
            [ -z "$pn" ] && continue
            t="$(_vcf_label_to_type "$pl" email)"
            local _etypes="$t"
            [ "$_prim" = "1" ] && _etypes="${_etypes:+$_etypes,}pref"
            if [ -n "$_etypes" ]; then
                _emit_unfolded "EMAIL;TYPE=$_etypes:$(_vcf_escape "$pn")"
            else
                _emit_unfolded "EMAIL:$(_vcf_escape "$pn")"
            fi
        done <<< "$_satrows"
        local astreet acity astate azip acountry
        _satref="_addresses_$pk"; _satrows="${!_satref:-}"
        while IFS=$'\x1f' read -r owner pl astreet acity astate azip acountry; do
            [ "$owner" = "$pk" ] || continue
            [ -z "$astreet$acity$astate$azip$acountry" ] && continue
            t="$(_vcf_label_to_type "$pl" adr)"
            local adr_val=";;$(_vcf_escape "$(_unescape_bsafe "$astreet")");$(_vcf_escape "$(_unescape_bsafe "$acity")");$(_vcf_escape "$(_unescape_bsafe "$astate")");$(_vcf_escape "$(_unescape_bsafe "$azip")");$(_vcf_escape "$(_unescape_bsafe "$acountry")")"
            if [ -n "$t" ]; then
                _emit_unfolded "ADR;TYPE=$t:$adr_val"
            else
                _emit_unfolded "ADR:$adr_val"
            fi
        done <<< "$_satrows"
        _satref="_urls_$pk"; _satrows="${!_satref:-}"
        while IFS=$'\x1f' read -r owner pl pn; do
            [ "$owner" = "$pk" ] || continue
            [ -z "$pn" ] && continue
            t="$(_vcf_label_to_type "$pl" url)"
            pn="$(_unescape_bsafe "$pn")"
            if [ -n "$t" ]; then
                _emit_unfolded "URL;TYPE=$t:$(_vcf_escape "$pn")"
            else
                _emit_unfolded "URL:$(_vcf_escape "$pn")"
            fi
        done <<< "$_satrows"
        local ddate dval
        _satref="_dates_$pk"; _satrows="${!_satref:-}"
        while IFS=$'\x1f' read -r owner pl ddate; do
            [ "$owner" = "$pk" ] || continue
            [ -z "$ddate" ] && continue
            dval="$(_cd_ts_to_vcard_date "$ddate")"
            [ -z "$dval" ] && continue
            case "$pl" in
                '_$!<Anniversary>!$_'|Anniversary|anniversary)
                    _emit_unfolded "ANNIVERSARY:$dval" ;;
                *) custom_dates_dropped=$((custom_dates_dropped + 1)) ;;
            esac
        done <<< "$_satrows"
        local ntext real
        _satref="_notes_$pk"; _satrows="${!_satref:-}"
        while IFS=$'\x1f' read -r owner ntext; do
            [ "$owner" = "$pk" ] || continue
            [ -z "$ntext" ] && continue
            real="$(_unescape_bsafe "$ntext")"
            _emit_unfolded "NOTE:$(_vcf_escape "$real")"
        done <<< "$_satrows"
        local im_svc im_lbl im_addr im_pair im_scheme im_token
        _satref="_im_$pk"; _satrows="${!_satref:-}"
        while IFS=$'\x1f' read -r owner im_svc im_lbl im_addr; do
            [ "$owner" = "$pk" ] || continue
            [ -z "$im_addr" ] && continue
            im_pair="$(_vcf_im_service "$im_svc")"
            im_scheme="${im_pair%|*}"; im_token="${im_pair#*|}"
            local _impp="IMPP"
            [ -n "$im_token" ] && _impp="$_impp;X-SERVICE-TYPE=$(_vcf_escape "$im_token")"
            _emit_unfolded "$_impp:$im_scheme:$(_vcf_escape "$(_unescape_bsafe "$im_addr")")"
        done <<< "$_satrows"
        local sp_svc sp_user sp_url
        _satref="_social_$pk"; _satrows="${!_satref:-}"
        while IFS=$'\x1f' read -r owner sp_svc sp_user sp_url; do
            [ "$owner" = "$pk" ] || continue
            local _spurl="$sp_url"
            if [ -z "$_spurl" ] && [ -n "$sp_user" ]; then
                case "$sp_svc" in
                    '_$!<'*'>!$_') sp_svc="${sp_svc#_\$!<}"; sp_svc="${sp_svc%>!\$_}" ;;
                esac
                case "$sp_svc" in
                    Twitter|twitter)   _spurl="https://twitter.com/$sp_user" ;;
                    Facebook|facebook) _spurl="https://www.facebook.com/$sp_user" ;;
                    LinkedIn|linkedin) _spurl="https://www.linkedin.com/in/$sp_user" ;;
                    Flickr|flickr)     _spurl="https://www.flickr.com/people/$sp_user" ;;
                    *)                 _spurl="" ;;
                esac
            fi
            [ -z "$_spurl" ] && continue
            _emit_unfolded "URL:$(_vcf_escape "$(_unescape_bsafe "$_spurl")")"
        done <<< "$_satrows"
        local rl_lbl rl_name rl_type
        _satref="_related_$pk"; _satrows="${!_satref:-}"
        while IFS=$'\x1f' read -r owner rl_lbl rl_name; do
            [ "$owner" = "$pk" ] || continue
            [ -z "$rl_name" ] && continue
            rl_type="$(_vcf_relation_to_type "$rl_lbl")"
            rl_name="$(_unescape_bsafe "$rl_name")"
            if [ -n "$rl_type" ]; then
                _emit_unfolded "RELATED;TYPE=$rl_type:$(_vcf_escape "$rl_name")"
            else
                _emit_unfolded "RELATED:$(_vcf_escape "$rl_name")"
            fi
        done <<< "$_satrows"
        local pf="$SCRATCH_DIR/photo_$pk.bin"
        local _img_src="$SCRATCH_DIR/contact_photos/img_${pk}.bin"
        local _like_src="$SCRATCH_DIR/contact_photos/like_${pk}.bin"
        local itype="" b64
        : > "$pf"
        if [ -s "$_img_src" ]; then
            cp -p -- "$_img_src" "$pf" 2>/dev/null
            itype="$(_sniff_image_type "$pf")"
        fi
        if [ -z "$itype" ] && [ -s "$pf" ]; then
            local _tag
            _tag="$(head -c 1 "$pf" 2>/dev/null \
                    | LC_ALL=C od -An -tx1 | LC_ALL=C tr -d ' \n')"
            if [ "$_tag" = "01" ]; then
                local _stripped="$pf.stripped"
                tail -c +2 "$pf" > "$_stripped" 2>/dev/null
                itype="$(_sniff_image_type "$_stripped")"
                if [ -n "$itype" ]; then
                    mv -f -- "$_stripped" "$pf"
                else
                    rm -f -- "$_stripped"
                fi
            fi
        fi
        if [ -z "$itype" ] && [ -n "$EXTERNAL_DATA_DIR" ] && [ -s "$pf" ]; then
            local _ext_uuid
            _ext_uuid="$(_parse_external_uuid "$pf")"
            if [ -n "$_ext_uuid" ] && [ -f "$EXTERNAL_DATA_DIR/$_ext_uuid" ]; then
                if cp -p -- "$EXTERNAL_DATA_DIR/$_ext_uuid" "$pf" 2>/dev/null; then
                    itype="$(_sniff_image_type "$pf")"
                fi
            fi
        fi
        if [ -z "$itype" ] && [ -s "$_like_src" ]; then
            cp -p -- "$_like_src" "$pf" 2>/dev/null && \
                itype="$(_sniff_image_type "$pf")"
        fi
        if [ -n "$itype" ]; then
            if [ "$itype" = "TIFF" ]; then
                if _sips_to_jpeg "$pf" "$pf.jpg" ""; then
                    mv -f -- "$pf.jpg" "$pf"
                    itype="JPEG"
                else
                    rm -f -- "$pf.jpg" 2>/dev/null
                    note_incomplete "$out_root" "Contact \"$(printf '%s' "$full" | head -c 60)\" photo" \
                        "the source PHOTO is in TIFF format and sips couldn't convert it to JPEG (likely a corrupt TIFF blob); RFC 6350 importers silently drop PHOTO;TYPE=TIFF, so the contact in the export has its name + data but no photo"
                    itype=""
                fi
            fi
            if [ -n "$itype" ]; then
                b64="$(base64 < "$pf" 2>/dev/null | tr -d '\n')"
                [ -n "$b64" ] && _emit_unfolded "PHOTO;ENCODING=b;TYPE=$itype:$b64"
            fi
        fi
        rm -f -- "$pf"
        local _cg_ref="_cg_${pk}" _cats_raw _cats _cg_one _cg_rest
        _cats_raw="${!_cg_ref:-}"
        if [ -n "$_cats_raw" ]; then
            _cats=""
            _cg_rest="$_cats_raw"
            while [ -n "$_cg_rest" ]; do
                case "$_cg_rest" in
                    *$'\x1f'*) _cg_one="${_cg_rest%%$'\x1f'*}"; _cg_rest="${_cg_rest#*$'\x1f'}" ;;
                    *)         _cg_one="$_cg_rest";            _cg_rest="" ;;
                esac
                [ -z "$_cg_one" ] && continue
                _cg_one="$(_vcf_escape "$(_unescape_bsafe "$_cg_one")")"
                if [ -n "$_cats" ]; then _cats="$_cats,$_cg_one"; else _cats="$_cg_one"; fi
            done
            [ -n "$_cats" ] && _emit_unfolded "CATEGORIES:$_cats"
        fi
        _emit_unfolded "END:VCARD"
        processed=$((processed + 1))
        _progress_tick "$processed" "$total_count" "$(_pluralize "$total_count" contact) emitted"
    done < "$SCRATCH_DIR/contacts.tsv"
    _progress_end
    [ "$skipped_untitled" -gt 0 ] && \
        _disclose_excluded "$skipped_untitled untitled $(_pluralize "$skipped_untitled" contact)" "empty primary key"
    [ "$no_name" -gt 0 ] && \
        log_info "$no_name $(_pluralize "$no_name" contact) had no name or organisation (emitted as \"(No Name)\")"
    [ "$custom_dates_dropped" -gt 0 ] && \
        _disclose_excluded "$custom_dates_dropped custom-labelled $(_pluralize "$custom_dates_dropped" date)" "only Anniversary is emitted; vCard has no canonical property for arbitrary user-labelled dates"
    local _post_count
    _post_count="$(sqlite3 -readonly "$snap" "SELECT COUNT(*) FROM ZABCDRECORD WHERE Z_ENT=$contact_ent;" 2>/dev/null)"
    case "$_post_count" in
        ''|*[!0-9]*) _post_count="" ;;
    esac
    validate_count_parity "$_post_count" $((processed + skipped_untitled)) \
        "Contact" "$out_root"
    if [ -n "$grp_tbl" ]; then
        sqlite3 -readonly -separator $'\x1f' "$snap" "
            SELECT $(_sql_tsv_safe "COALESCE(g.ZFIRSTNAME, g.ZNAME, 'Unnamed')"),
                   $(_sql_tsv_safe "TRIM(COALESCE(c.ZFIRSTNAME, '') || ' ' || COALESCE(c.ZLASTNAME, ''))")
              FROM $grp_tbl j
              JOIN ZABCDRECORD g ON g.Z_PK = j.${grp_col_parent}
              JOIN ZABCDRECORD c ON c.Z_PK = j.${grp_col_contact}
             ORDER BY g.ZFIRSTNAME, g.Z_PK, c.Z_PK;
        " >> "$groups_data" 2>/dev/null \
            || log_warn "Contacts: group-membership accumulator query failed for ${db_path##*/} — its contact-group rows are missing from Contact Groups.csv."
    fi
    run_processed=$((run_processed + processed))
    } # end _export_contacts_db
    local _i _first_flag _src_age
    for _i in "${!ab_db_paths[@]}"; do
        _src_age="$(_fmt_relative_mtime "${ab_db_paths[$_i]}")"
        if [ -n "$_src_age" ]; then
            log_info "Source: ${ab_db_paths[$_i]} (last updated $_src_age)"
        else
            log_info "Source: ${ab_db_paths[$_i]}"
        fi
        if [ "$_i" -eq 0 ]; then _first_flag=1; else _first_flag=0; fi
        _export_contacts_db "${ab_db_snaps[$_i]}" "${ab_db_paths[$_i]}" "$_first_flag"
    done
    if [ "$run_processed" -eq 0 ]; then
        rm -f -- "$out_file" 2>/dev/null
        if report_have_incomplete "$out_root"; then
            log_warn "Contacts: discovered rows but emitted none$(_disclosure_pointer)."
            mark_success; print_summary; exit 0
        fi
        rmdir "$out_root" 2>/dev/null || true
        report_empty_source "contacts" "Contacts"
    fi
    if [ "${#ab_db_paths[@]}" -gt 1 ]; then
        log_info "Exported contacts from ${#ab_db_paths[@]} source $(_pluralize "${#ab_db_paths[@]}" database)"
    fi
    log_info "Folding vCard stream and writing companion files..."
    local tmp_out
    tmp_out="$(mktemp "$out_file.tmp.XXXXXX")" || die "Cannot create temp output file"
    track_output_path "$tmp_out"
    if ! _fold_75_octets < "$raw_stream" > "$tmp_out"; then
        die "Folding step failed; output not finalised"
    fi
    [ -s "$tmp_out" ] || die "Folded output is empty"
    grep -q 'BEGIN:VCARD' "$tmp_out" || die "Output missing BEGIN:VCARD; refusing to publish"
    mv -f -- "$tmp_out" "$out_file" || die "Cannot finalise $out_file"
    _untrack_output_path "$tmp_out"
    clean_vcf_file "$out_file" || \
        log_warn "vCard post-clean pass failed; output preserved but may contain Apple-proprietary metadata"
    local groups_csv="$out_root/Contact Groups.csv"
    local group_count=0
    if [ -s "$groups_data" ]; then
        local _gname _mname
        local _groups_tmp
        _groups_tmp="$(mktemp "$groups_csv.tmp.XXXXXX")" \
            || die "Cannot create temp file for Contact Groups.csv"
        track_output_path "$_groups_tmp"
        {
            printf 'Group,Member\r\n'
            while IFS=$'\x1f' read -r _gname _mname; do
                [ -z "$_gname" ] && [ -z "$_mname" ] && continue
                printf '%s,%s\r\n' "$(csv_field "$_gname")" "$(csv_field "$_mname")"
            done < "$groups_data"
        } > "$_groups_tmp"
        _atomic_commit_tmp $? "$_groups_tmp" "$groups_csv"
        _untrack_output_path "$_groups_tmp"
        if [ -f "$groups_csv" ]; then
            group_count="$(_count_csv_rows "$groups_csv")"
        else
            group_count=0
        fi
        if [ "$group_count" -le 0 ]; then
            rm -f -- "$groups_csv"
            group_count=0
        else
            validate_csv_rfc4180 "$groups_csv" || true
        fi
    fi
    local _stat="$run_processed $(_pluralize "$run_processed" contact)"
    [ "$group_count" -gt 0 ] && _stat="$_stat, $group_count group $(_pluralize "$group_count" membership)"
    _stat="$_stat, $(_dir_size_human "$out_root")"
    log_ok "Wrote Contacts/ ($_stat)"
    mark_success
    sweep_junk_files "$out_root"
    print_summary
    if [ "$ERR_COUNT" -gt 0 ]; then exit 1; fi
    exit 0
}

_CD_SOFFICE=""            # path to the fetched soffice once ready
_CD_LO_MNT=""             # DMG mountpoint while attached (for abort detach)
_CD_LO_DEV=""             # DMG /dev/diskN (force-detach fallback)
_CD_LO_PROFILE_URL=""     # file:// URL of the isolated UserInstallation
_CD_LO_HOME=""            # redirected HOME for soffice
_CD_LO_TMP=""             # redirected TMPDIR for soffice
_CD_SVP=0                 # 1 if the headless svp VCL plugin is bundled
_CD_START_MARK=""         # timestamp baseline for crash-report cleanup
_CD_LSREGISTER="/System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister"
_CD_SKIPVERIFY_SET=0      # 1 while we've overridden the DiskImages skip-verify pref
_CD_SKIPVERIFY_SAVED=""   # the pref's prior value, restored on the way out

_cd_set_skipverify() {
    [ "${_CD_SKIPVERIFY_SET:-0}" = "1" ] && return 0
    _CD_SKIPVERIFY_SAVED="$(defaults read com.apple.frameworks.diskimages skip-verify 2>/dev/null)"
    _CD_SKIPVERIFY_SET=1
    defaults write com.apple.frameworks.diskimages skip-verify -bool true 2>/dev/null || true
}

_cd_restore_skipverify() {
    [ "${_CD_SKIPVERIFY_SET:-0}" = "1" ] || return 0
    _CD_SKIPVERIFY_SET=0
    if [ -n "$_CD_SKIPVERIFY_SAVED" ]; then
        defaults write com.apple.frameworks.diskimages skip-verify -bool "$_CD_SKIPVERIFY_SAVED" 2>/dev/null || true
    else
        defaults delete com.apple.frameworks.diskimages skip-verify 2>/dev/null || true
    fi
    _CD_SKIPVERIFY_SAVED=""
}

_CD_QL_PREEXISTED=""      # 1 if LibreOffice QuickLook containers existed BEFORE
_CD_VCLPLUGIN=""          # per-conversion VCL plugin pin (svp for Keynote)
_CD_QL_BUNDLE_GLOB='org.libreoffice.'

_CD_LO_TRACE_DIRS=(
    "$HOME/Library/Containers"
    "$HOME/Library/Application Scripts"
    "$HOME/Library/HTTPStorages"
    "$HOME/Library/Saved Application State"
    "$HOME/Library/Preferences"
    "$HOME/Library/Application Support/com.apple.sharedfilelist/com.apple.LSSharedFileList.ApplicationRecentDocuments"
)
_CD_OK=0
_CD_FAILED=0
_CD_SKIPPED=0

_CD_INCOMPLETE=()

_cd_url_encode_path() {
    local _s="$1" _out="" _i=0 _ch _hex LC_ALL=C
    while [ "$_i" -lt "${#_s}" ]; do
        _ch="${_s:$_i:1}"
        case "$_ch" in
            [A-Za-z0-9/._~-]) _out="$_out$_ch" ;;
            *) printf -v _hex '%%%02X' "'$_ch"; _out="$_out$_hex" ;;
        esac
        _i=$((_i + 1))
    done
    printf '%s' "$_out"
}

_cd_run_soffice() {
    local _plug=()
    [ -n "${_CD_VCLPLUGIN:-}" ] && _plug=( "SAL_USE_VCLPLUGIN=$_CD_VCLPLUGIN" )
    env "${_plug[@]+"${_plug[@]}"}" \
        LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 SAL_DISABLE_FONTCONFIG=1 \
        HOME="$_CD_LO_HOME" TMPDIR="$_CD_LO_TMP" \
        UserInstallation="$_CD_LO_PROFILE_URL" \
        "$SCRATCH_DIR/LibreOffice.app/Contents/MacOS/soffice" "$@"
}

_cd_detach_dmg() {
    [ -n "${_CD_LO_MNT:-}" ] || return 0
    if hdiutil detach "$_CD_LO_MNT" -quiet 2>/dev/null \
       || hdiutil detach "$_CD_LO_MNT" -force -quiet 2>/dev/null; then
        _CD_LO_MNT=""; _CD_LO_DEV=""
        return 0
    fi
    return 1
}

_cd_fetch_libreoffice() {
    [ -n "$_CD_SOFFICE" ] && return 0
    if [ -z "$_CD_QL_PREEXISTED" ]; then
        _CD_QL_PREEXISTED=0
        local _qd
        for _qd in "${_CD_LO_TRACE_DIRS[@]}"; do
            [ -d "$_qd" ] || continue
            if [ -n "$(find "$_qd" -maxdepth 1 -iname "${_CD_QL_BUNDLE_GLOB:-org.libreoffice.}*" -print -quit 2>/dev/null)" ]; then
                _CD_QL_PREEXISTED=1; break
            fi
        done
    fi
    local _arch _apath _afile
    _arch="$(uname -m 2>/dev/null)"
    case "$_arch" in
        arm64|aarch64) _apath="aarch64"; _afile="aarch64" ;;
        x86_64)        _apath="x86_64";  _afile="x86-64"  ;;
        *) log_warn "LibreOffice: unsupported architecture '$_arch' — documents left unconverted."; return 1 ;;
    esac
    local _ver="${LO_VERSION:-}"
    if [ -z "$_ver" ]; then
        _ver="$(curl -fsSL --max-time 15 \
            'https://download.documentfoundation.org/libreoffice/stable/' 2>/dev/null \
            | grep -oE '"[0-9]+\.[0-9]+\.[0-9]+/"' | tr -d '"/' \
            | sort -t. -k1,1n -k2,2n -k3,3n | tail -1)"
        if [ -z "$_ver" ]; then _ver="25.2.5"; log_info "LibreOffice version discovery failed; using $_ver."; fi
    fi
    local _dmg="LibreOffice_${_ver}_MacOS_${_afile}.dmg"
    local _dmgpath="$SCRATCH_DIR/$_dmg"
    local _soffice="$SCRATCH_DIR/LibreOffice.app/Contents/MacOS/soffice"
    local _url="https://download.documentfoundation.org/libreoffice/stable/${_ver}/mac/${_apath}/${_dmg}"
    local _attempt _local=0 _hout _dlrc _why
    [ -n "${LOCAL_DMG:-}" ] && [ -e "${LOCAL_DMG:-}" ] && _local=1
    for _attempt in 1 2; do
        rm -rf -- "$SCRATCH_DIR/LibreOffice.app" 2>/dev/null || true
        if [ "$_local" = 1 ]; then
            cp -- "$LOCAL_DMG" "$_dmgpath" || { rm -f -- "$_dmgpath"; log_warn "LibreOffice: could not copy LOCAL_DMG — documents left unconverted."; return 1; }
        else
            _fetch_download "$_url" "$_dmgpath" "LibreOffice $_ver" 1800 350; _dlrc=$?
            if [ "$_dlrc" != 0 ]; then
                rm -f -- "$_dmgpath"
                _why="network?"
                [ "$_dlrc" = 23 ] && _why="could not write the download to scratch — disk full or \$TMPDIR removed?"
                if [ "$_attempt" -lt 2 ]; then log_warn "LibreOffice download failed ($_why) — retrying once..."; continue; fi
                log_warn "LibreOffice download failed ($_why) — documents left unconverted."
                return 1
            fi
        fi
        if [ "$_local" != 1 ]; then
            local _want_sha _got_sha
            _want_sha="$(curl -fsSL --max-time 30 "${_url}.sha256" 2>/dev/null | awk 'NR==1{print tolower($1)}')"
            case "$_want_sha" in *[!0-9a-f]*|'') _want_sha="" ;; esac
            if [ -n "$_want_sha" ] && [ "${#_want_sha}" -eq 64 ]; then
                _got_sha="$(shasum -a 256 -- "$_dmgpath" 2>/dev/null | awk '{print tolower($1)}')"
                if [ "$_got_sha" != "$_want_sha" ]; then
                    rm -f -- "$_dmgpath"
                    if [ "$_attempt" -lt 2 ]; then log_warn "LibreOffice DMG SHA-256 mismatch (corrupt download?) — retrying once..."; continue; fi
                    log_warn "LibreOffice DMG SHA-256 mismatch after retry — refusing to run it; documents left unconverted."
                    return 1
                fi
                log_info "LibreOffice DMG verified against published SHA-256."
            else
                log_warn "LibreOffice: could not retrieve the published SHA-256 — proceeding on HTTPS + smoke-test only (integrity not independently verified)."
            fi
        fi
        xattr -c "$_dmgpath" 2>/dev/null || true
        _CD_LO_MNT="$SCRATCH_DIR/lomnt"; mkdir -p "$_CD_LO_MNT"
        _cd_set_skipverify
        if ! _hout="$(hdiutil attach -nobrowse -noverify -noautoopen -quiet -readonly -mountpoint "$_CD_LO_MNT" "$_dmgpath" 2>&1)"; then
            _cd_restore_skipverify
            rmdir "$_CD_LO_MNT" 2>/dev/null || true; _CD_LO_MNT=""; rm -f -- "$_dmgpath"
            if [ "$_local" = 0 ] && [ "$_attempt" -lt 2 ]; then log_warn "LibreOffice: failed to mount DMG — retrying once..."; continue; fi
            log_warn "LibreOffice: failed to mount DMG — documents left unconverted."
            return 1
        fi
        _cd_restore_skipverify
        _CD_LO_DEV="$(printf '%s\n' "$_hout" | grep -oE '/dev/disk[0-9]+' | head -1)"
        if [ ! -d "$_CD_LO_MNT/LibreOffice.app" ]; then
            _cd_detach_dmg   # detach (force-fallback) + clear handles on success
            rm -f -- "$_dmgpath"
            log_warn "LibreOffice: the DMG contained no LibreOffice.app (unexpected asset) — documents left unconverted."
            return 1
        fi
        if ! ditto "$_CD_LO_MNT/LibreOffice.app" "$SCRATCH_DIR/LibreOffice.app" 2>/dev/null; then
            _cd_detach_dmg   # detach (force-fallback) + clear handles on success
            rm -f -- "$_dmgpath"
            log_warn "LibreOffice: failed to copy LibreOffice.app (scratch full?) — documents left unconverted."
            return 1
        fi
        local _mnt="$_CD_LO_MNT"
        if _cd_detach_dmg; then
            rmdir "$_mnt" 2>/dev/null || true
        fi
        rm -f -- "$_dmgpath"
        [ -x "$_soffice" ] && break
        rm -rf -- "$SCRATCH_DIR/LibreOffice.app" 2>/dev/null || true
        if [ "$_local" = 0 ] && [ "$_attempt" -lt 2 ]; then log_warn "LibreOffice: soffice missing after copy (incomplete extraction) — re-fetching once..."; continue; fi
        log_warn "LibreOffice: soffice missing from the fetched app — documents left unconverted."
        return 1
    done
    rm -rf -- "$SCRATCH_DIR/LibreOffice.app/Contents/Library/Spotlight" \
              "$SCRATCH_DIR/LibreOffice.app/Contents/PlugIns" 2>/dev/null || true
    xattr -cr "$SCRATCH_DIR/LibreOffice.app" 2>/dev/null || true
    _CD_LO_HOME="$SCRATCH_DIR/lo-home"
    _CD_LO_TMP="$SCRATCH_DIR/lo-tmp"
    mkdir -p "$SCRATCH_DIR/lo-profile" "$_CD_LO_HOME" "$_CD_LO_TMP"
    _CD_LO_PROFILE_URL="file://$(_cd_url_encode_path "$SCRATCH_DIR/lo-profile")"
    _CD_SVP=0
    local _f
    for _f in "$SCRATCH_DIR/LibreOffice.app/Contents/Frameworks/"libvclplug_svp*.dylib; do
        [ -e "$_f" ] && { _CD_SVP=1; break; }
    done
    if ! _run_with_timeout 60 _cd_run_soffice --version >/dev/null 2>&1; then
        log_warn "LibreOffice: soffice smoke-test failed or timed out (incompatible build?) — documents left unconverted."
        return 1
    fi
    _CD_SOFFICE="$_soffice"
    return 0
}

_cd_record_failure() {
    local _src="$1" _ext="$2" _out_dir="$3"
    _CD_FAILED=$((_CD_FAILED + 1))
    local _why="conversion failed — headless LibreOffice could not render it"
    case "$_ext" in
        odp)
            _why="conversion failed — .key/.keynote files can crash headless LibreOffice on macOS (a known LibreOffice/CoreText bug, not a fault of the file). Workaround: open it in Keynote and Export To > PowerPoint, then convert the .pptx; or run LibreOffice on Linux." ;;
    esac
    _incomplete_push _CD_INCOMPLETE "${_src#"$_out_dir"/}" "$_why"
    log_warn "  conversion failed: ${_src#"$_out_dir"/}"
}

_cd_convert_one() {
    local _src="$1" _dest_dir="$2" _ext="$3" _out_dir="$4"
    local _timeout="${CONVERT_DOC_TIMEOUT_SEC:-180}"
    case "$_timeout" in ''|*[!0-9]*|0) _timeout=60 ;; esac
    local _base="${_src##*/}"
    local _stem="${_base%.*}"
    [ -z "$_stem" ] && _stem="$_base"
    local _dest="$_dest_dir/$_stem.$_ext"
    if [ -e "$_dest" ]; then
        _CD_SKIPPED=$((_CD_SKIPPED + 1))
        log_info "  skip (exists): ${_dest#"$_out_dir"/}"
        return 0
    fi
    if ! mkdir -p -- "$_dest_dir" 2>/dev/null; then
        _CD_FAILED=$((_CD_FAILED + 1))
        _incomplete_push _CD_INCOMPLETE "${_dest_dir#"$_out_dir"/}" "could not create the output folder (permission denied or disk full)"
        log_warn "  cannot create ${_dest_dir#"$_out_dir"/}"
        return 1
    fi
    _CD_VCLPLUGIN=""
    case "$_ext" in odp) [ "$_CD_SVP" = "1" ] && _CD_VCLPLUGIN="svp" ;; esac
    local _cap="$SCRATCH_DIR/cd_conv.log"
    _run_with_timeout "$_timeout" \
        _cd_run_soffice --headless --norestore --nologo --nofirststartwizard \
        --convert-to "$_ext" --outdir "$_dest_dir" "$_src" >"$_cap" 2>&1
    local _crc=$?
    local _w=0
    while [ "$_crc" -le 128 ] && [ "$_crc" -ne 124 ] && [ ! -s "$_dest" ] && [ "$_w" -lt 15 ]; do
        sleep 1; _w=$((_w + 1))
    done
    if [ "$_crc" -ne 124 ] && [ "$_crc" -le 128 ] && [ -s "$_dest" ]; then
        _CD_OK=$((_CD_OK + 1))
        log_info "  ok: ${_src#"$_out_dir"/} → ${_dest#"$_out_dir"/}"
    else
        if [ "$_crc" -eq 124 ]; then
            log_warn "  conversion timed out (>${_timeout}s): ${_src#"$_out_dir"/}"
        fi
        rm -f -- "$_dest" 2>/dev/null
        _cd_record_failure "$_src" "$_ext" "$_out_dir"
    fi
    _CD_VCLPLUGIN=""
    rm -f -- "$_cap"
}

_cd_find_iwork() {
    find "$1" \
        \( -iname '*.pages' -o -iname '*.numbers' \
           -o \( -iname '*.key' -type d \) -o -iname '*.keynote' \) \
        ! -type l -prune -print0 2>/dev/null
}

_cd_convert_tree() {
    local _src_root="$1" _dest_root="$2" _out_dir="$3"
    local _src _rel _rel_dir _odf
    while IFS= read -r -d '' _src; do
        _rel="${_src#"$_src_root"/}"
        _rel_dir="$(dirname -- "$_rel")"
        case "$(printf '%s' "${_src##*.}" | LC_ALL=C tr '[:upper:]' '[:lower:]')" in
            pages)        _odf="odt" ;;
            numbers)      _odf="ods" ;;
            key|keynote)  _odf="odp" ;;
            *)            continue ;;
        esac
        local _dest_dir="$_dest_root"
        [ "$_rel_dir" != "." ] && _dest_dir="$_dest_root/$_rel_dir"
        _cd_convert_one "$_src" "$_dest_dir" "$_odf" "$_out_dir"
    done < <(_cd_find_iwork "$_src_root")
}

_cd_reap_lo_traces() {
    [ "${_CD_QL_PREEXISTED:-1}" = "0" ] || return 0
    local _qd
    for _qd in "${_CD_LO_TRACE_DIRS[@]}"; do
        [ -d "$_qd" ] || continue
        find "$_qd" -maxdepth 1 -iname "${_CD_QL_BUNDLE_GLOB:-org.libreoffice.}*" \
            -exec rm -rf -- {} + 2>/dev/null || true
    done
}

_cd_settle_reap_lo_traces() {
    [ "${_CD_QL_PREEXISTED:-1}" = "0" ] || return 0
    local _sfl="$HOME/Library/Application Support/com.apple.sharedfilelist/com.apple.LSSharedFileList.ApplicationRecentDocuments/org.libreoffice.script.sfl4"
    local _i=0
    while [ ! -e "$_sfl" ] && [ "$_i" -lt 5 ]; do sleep 1; _i=$((_i + 1)); done
    _cd_reap_lo_traces
    sleep 1; _cd_reap_lo_traces
}

converted_docs_leaf_cleanup_hook() {
    _cd_restore_skipverify
    _cd_detach_dmg || true   # mountpoint detach (force-fallback); clears handles on success
    if [ -n "${_CD_LO_DEV:-}" ]; then
        hdiutil detach "$_CD_LO_DEV" -force -quiet 2>/dev/null || true
    fi
    if [ -n "${SCRATCH_DIR:-}" ]; then
        pkill -f "$SCRATCH_DIR/LibreOffice.app" 2>/dev/null || true
    fi
    if [ -n "${SCRATCH_DIR:-}" ] && [ -d "$SCRATCH_DIR/LibreOffice.app" ] \
       && [ -x "$_CD_LSREGISTER" ]; then
        "$_CD_LSREGISTER" -u "$SCRATCH_DIR/LibreOffice.app" >/dev/null 2>&1 || true
    fi
    if [ -n "${_CD_START_MARK:-}" ] && [ -e "$_CD_START_MARK" ] \
       && [ -d "$HOME/Library/Logs/DiagnosticReports" ]; then
        find "$HOME/Library/Logs/DiagnosticReports" -maxdepth 1 \
            \( -iname 'soffice*.ips' -o -iname 'soffice*.crash' \) \
            -newer "$_CD_START_MARK" -delete 2>/dev/null || true
    fi
    _cd_reap_lo_traces
}

_cd_join_roots() {
    local _out="" _r
    for _r in "$@"; do
        if [ -z "$_out" ]; then _out="$_r"; else _out="$_out & $_r"; fi
    done
    printf '%s' "$_out"
}

converted_docs_main() {
    maybe_show_help "$@"
    _announce_step "Converted Docs export"
    : "${CONVERT_DOCS:=1}"
    local out_arg="" arg end_opts=0 out_dir
    for arg in "$@"; do
        if [ "$end_opts" -eq 0 ]; then
            case "$arg" in
                --) end_opts=1; continue ;;
                --disable-convert-docs|--no-convert-docs) CONVERT_DOCS=0; continue ;;
                -*) die "Unknown flag: $arg" ;;
            esac
        fi
        if [ -n "$out_arg" ]; then
            die "Too many positional arguments: '$arg' (already saw '$out_arg'). Pass at most one output folder."
        fi
        out_arg="$arg"
    done
    out_dir="$(resolve_output_dir "$out_arg")" || exit 1
    case "$CONVERT_DOCS" in
        n*|N*|0|f*|F*|of*|Of*|OF*|dis*|Dis*|DIS*)
            log_info "Document conversion disabled (CONVERT_DOCS=$CONVERT_DOCS)."
            mark_success; print_summary; exit 0
            ;;
    esac
    check_dependencies
    _announce_output_dir "Converted Docs"
    if [ "${_DOWNPOUR_TEST_HEADLESS:-0}" = "1" ]; then
        log_info "Document conversion skipped under the test harness (LibreOffice fetch suppressed)."
        mark_success; print_summary; exit 0
    fi
    local _roots=() _r
    for _r in "iCloud Drive" "Files" "Mail/Attachments" "Messages/Data/Attachments" "Notes" "Journal"; do
        [ -d "$out_dir/$_r" ] && _roots+=( "$_r" )
    done
    if [ "${#_roots[@]}" -eq 0 ]; then
        report_no_source "Converted Docs" "has no iCloud Drive / Files / Mail / Messages / Notes / Journal export to scan" "$out_dir"
    fi
    log_info "Source: exported $(_cd_join_roots "${_roots[@]+"${_roots[@]}"}")"
    local _total=0 _n
    for _r in "${_roots[@]+"${_roots[@]}"}"; do
        _n="$(_cd_find_iwork "$out_dir/$_r" | LC_ALL=C tr -cd '\0' | LC_ALL=C wc -c | tr -d ' ')"
        case "$_n" in ''|*[!0-9]*) _n=0 ;; esac
        _total=$((_total + _n))
    done
    if [ "$_total" -eq 0 ]; then
        log_info "No iWork documents (.pages / .numbers / .key / .keynote) in the export — nothing to convert."
        mark_success; print_summary; exit 0
    fi
    log_info "Found $_total iWork $(_pluralize "$_total" document) to convert."
    require_no_collision "$out_dir/Converted Docs"
    ensure_scratch
    _CD_START_MARK="$SCRATCH_DIR/.cd_start"; : > "$_CD_START_MARK"
    if ! _cd_fetch_libreoffice; then
        note_incomplete "$out_dir/Converted Docs" "iWork document conversion" \
            "LibreOffice could not be fetched / prepared (network, mount, or smoke-test failure), so $_total iWork document(s) were not converted. Re-run with network access."
        log_warn "$_total iWork $(_pluralize "$_total" document) NOT converted$(_disclosure_pointer)."
        mark_success; print_summary; exit 0
    fi
    log_info "Converting with LibreOffice (Pages→ODT, Numbers→ODS, Keynote→ODP)..."
    _create_output_dir "$out_dir/Converted Docs" "permission denied / disk full?"
    _CD_OK=0; _CD_FAILED=0; _CD_SKIPPED=0; _CD_INCOMPLETE=()
    for _r in "${_roots[@]+"${_roots[@]}"}"; do
        _cd_convert_tree "$out_dir/$_r" "$out_dir/Converted Docs/$_r" "$out_dir"
    done
    validate_count_parity "$_total" \
        "$((_CD_OK + _CD_FAILED + _CD_SKIPPED))" \
        "Converted Docs" "$out_dir/Converted Docs"
    if [ "$_CD_FAILED" -gt 0 ]; then
        _incomplete_drain "$out_dir/Converted Docs" "${_CD_INCOMPLETE[@]+"${_CD_INCOMPLETE[@]}"}"
    fi
    cleanup_empty_dirs "$out_dir/Converted Docs"
    local _stat="$_CD_OK $(_pluralize "$_CD_OK" document) converted"
    [ "$_CD_FAILED" -gt 0 ]  && _stat="$_stat, $_CD_FAILED failed"
    [ "$_CD_SKIPPED" -gt 0 ] && _stat="$_stat, $_CD_SKIPPED skipped"
    if [ -d "$out_dir/Converted Docs" ]; then
        _stat="$_stat, $(_dir_size_human "$out_dir/Converted Docs")"
        log_ok "Wrote Converted Docs/ ($_stat)"
    else
        log_warn "Converted Docs/ not written ($_stat)"
    fi
    mark_success
    _cd_settle_reap_lo_traces
    sweep_junk_files "$out_dir/Converted Docs"
    print_summary
    if [ "$ERR_COUNT" -gt 0 ]; then exit 1; fi
    exit 0
}

_FILES_STUBS_FILE=""
_FILES_MAT_FAIL_FILE=""

_files_section_included() {
    local _q="$1" _e
    for _e in "${FILES_INCLUSIONS[@]+"${FILES_INCLUSIONS[@]}"}"; do
        [ "$_e" = "$_q" ] && return 0
    done
    return 1
}

_files_target_in_scope() {
    local _p="$1" _pp _rel_pp
    if [ -z "${_FILES_SCOPE_HOME:-}" ]; then
        _FILES_SCOPE_HOME="$(readlink -f -- "$HOME" 2>/dev/null || realpath -- "$HOME" 2>/dev/null || printf '%s' "$HOME")"
    fi
    case "$_p/" in
        "$_FILES_SCOPE_HOME"/*) ;;
        *) return 1 ;;
    esac
    for _pp in "${SOURCE_PROTECTED_PREFIXES[@]+"${SOURCE_PROTECTED_PREFIXES[@]}"}"; do
        _rel_pp="${_pp#"$HOME"/}"
        case "$_p/" in
            "$_FILES_SCOPE_HOME/$_rel_pp"/*) return 1 ;;
        esac
    done
    return 0
}

_copy_files_tree() {
    local src="$1" dst="$2" exclude="${3:-}" tag="${4:-?}" pre_total="${5:-0}"
    local excludes="${6:-}"
    local copied=0 fails=0 _f _rel _tdir _orig _ftarget _reldir
    local _junk_skipped=0
    local _statout _src_size _src_flags _was_dataless
    local _ft_seen=0 _pt_last=0 _pt_inline=0
    local _files_scope_last_par="" _files_scope_par_real="" _files_scope_par_ok=1 _par
    local _files_scope_escape_root=""
    _COPY_TREE_N=0
    _COPY_TREE_ACCOUNTED=0
    [ -d "$src" ] || return 0
    mkdir -p "$dst" || { log_warn "Cannot create $dst"; return 1; }
    local _find_err=""
    if [ -n "${SCRATCH_DIR:-}" ] && [ -d "${SCRATCH_DIR:-}" ]; then
        _find_err="$SCRATCH_DIR/files_find_err.$$.$RANDOM"
        : > "$_find_err" 2>/dev/null || _find_err=""
    fi
    local -a find_args=( "$src" )
    if [ -n "$exclude" ]; then
        local _safe_exclude
        _safe_exclude="$(printf '%s' "$exclude" | sed 's/[][*?\\]/\\&/g')"
        find_args+=( -path "$_safe_exclude" -prune -o )
    fi
    if [ -n "$excludes" ]; then
        local _xn _xesc _x_ifs="$IFS"
        local -a _xarr=()
        IFS=$'\x1f' read -r -a _xarr <<< "$excludes"
        IFS="$_x_ifs"
        for _xn in "${_xarr[@]+"${_xarr[@]}"}"; do
            [ -n "$_xn" ] || continue
            _xesc="$(printf '%s' "$src/$_xn" | sed 's/[][*?\\]/\\&/g')"
            find_args+=( -path "$_xesc" -prune -o )
        done
    fi
    find_args+=( '(' -type f -o -type l ')' -print0 )
    while IFS= read -r -d '' _f; do
        _rel="${_f#"$src"/}"
        _is_prior_export_name "${_rel%%/*}" && continue
        _par="${_f%/*}"
        if [ "$_par" != "$_files_scope_last_par" ]; then
            _files_scope_last_par="$_par"
            _files_scope_par_real="$(readlink -f -- "$_par" 2>/dev/null || realpath -- "$_par" 2>/dev/null)"
            if [ -z "$_files_scope_par_real" ]; then
                _files_scope_par_ok=1
            elif _files_target_in_scope "$_files_scope_par_real"; then
                _files_scope_par_ok=1
            else
                _files_scope_par_ok=0
                local _files_link_new=1
                if [ -n "$_files_scope_escape_root" ]; then
                    case "$_files_scope_par_real/" in
                        "$_files_scope_escape_root"/*) _files_link_new=0 ;;
                    esac
                fi
                if [ "$_files_link_new" -eq 1 ]; then
                    _files_scope_escape_root="$_files_scope_par_real"
                    [ -n "${_nc_symlinks:-}" ] && printf '%s\x1f%s (reached through a symlinked folder whose target is outside the export scope — not copied)\n' \
                        "$(tsv_escape "$tag: ${_rel%/*}")" \
                        "$(tsv_escape "${_files_scope_par_real:-?}")" >> "$_nc_symlinks"
                fi
            fi
        fi
        [ "$_files_scope_par_ok" -eq 0 ] && continue
        if is_icloud_stub "$_f"; then
            _record_icloud_stub "$_FILES_STUBS_FILE" "$tag" "$_rel"
            continue
        fi
        if [ -L "$_f" ]; then
            if [ -f "$_f" ]; then
                local _real
                _real="$(readlink -f -- "$_f" 2>/dev/null || realpath -- "$_f" 2>/dev/null)"
                if [ -n "$_real" ] && [ -f "$_real" ]; then
                    if ! _files_target_in_scope "$_real"; then
                        [ -n "${_nc_symlinks:-}" ] && printf '%s\x1f%s (symlink target is outside the export scope — not copied)\n' \
                            "$(tsv_escape "$tag: $_rel")" \
                            "$(tsv_escape "$_real")" >> "$_nc_symlinks"
                        continue
                    fi
                    _f="$_real"
                    _FILES_SYMLINK_DEREF=$((${_FILES_SYMLINK_DEREF:-0} + 1))
                else
                    [ -n "${_nc_symlinks:-}" ] && printf '%s\x1f%s (unresolved)\n' \
                        "$(tsv_escape "$tag: $_rel")" \
                        "$(tsv_escape "$(readlink -- "$_f" 2>/dev/null || printf '?')")" >> "$_nc_symlinks"
                    continue
                fi
            else
                if [ -n "${_nc_symlinks:-}" ]; then
                    local _ltarget _swhy
                    _ltarget="$(readlink -- "$_f" 2>/dev/null)"
                    if [ -d "$_f" ]; then _swhy=" (directory link not followed — unreadable target or loop)"; else _swhy=" (broken / not a regular file)"; fi
                    printf '%s\x1f%s%s\n' \
                        "$(tsv_escape "$tag: $_rel")" \
                        "$(tsv_escape "${_ltarget:-?}")" "$_swhy" >> "$_nc_symlinks"
                fi
                continue
            fi
        fi
        if should_skip_copy "$_f" "$_rel"; then
            _junk_skipped=$((_junk_skipped + 1))
            continue
        fi
        _ftarget="$dst/$_rel"
        _tdir="${_ftarget%/*}"
        [ -d "$_tdir" ] || mkdir -p "$_tdir" 2>/dev/null
        _statout="$(stat -f '%z %f' -- "$_f" 2>/dev/null)"
        _src_size="${_statout%% *}"
        _src_flags="${_statout##* }"
        _was_dataless=0
        case "$_src_flags" in
            ''|*[!0-9]*) ;;
            *) [ "$(( 10#$_src_flags & 1073741824 ))" -ne 0 ] && _was_dataless=1 ;;
        esac
        local _err
        _err="$(_ditto_dl_retry "$_f" "$_ftarget" "$_was_dataless")"
        if [ $? -eq 0 ]; then
            if [ "$_was_dataless" = "1" ] && _materialized_copy_incomplete "$_src_size" "$_ftarget"; then
                rm -f -- "$_ftarget" 2>/dev/null
                if [ -n "$_FILES_MAT_FAIL_FILE" ]; then
                    printf 'incomplete\t%s\n' \
                        "$(tsv_escape "$tag/$_rel")" >> "$_FILES_MAT_FAIL_FILE"
                else
                    log_warn "iCloud download produced an incomplete copy: $tag/$_rel"
                    note_incomplete "${files_dir:-}" "$tag/$_rel" \
                        "the copy ran but the result was incomplete or still an iCloud placeholder rather than the real file — it was removed and is not in the export"
                fi
            else
                copied=$((copied + 1))
            fi
        else
            rm -f -- "$_ftarget" 2>/dev/null
            if [ "$_was_dataless" = "1" ]; then
                if [ -n "$_FILES_MAT_FAIL_FILE" ]; then
                    printf 'download-failed\t%s\n' \
                        "$(tsv_escape "$tag/$_rel")" >> "$_FILES_MAT_FAIL_FILE"
                else
                    log_warn "iCloud download failed for $_f — skip-tracking file not ready"
                    note_incomplete "${files_dir:-}" "$tag/$_rel" \
                        "iCloud download failed: $_f"
                fi
            else
                fails=$((fails + 1))
                local _reason="copy-failed"
                case "$_err" in
                    *"Permission denied"*|*"Operation not permitted"*) _reason="perm-denied" ;;
                esac
                if [ -n "$_FILES_MAT_FAIL_FILE" ]; then
                    printf '%s\t%s\n' "$_reason" \
                        "$(tsv_escape "$tag/$_rel")" >> "$_FILES_MAT_FAIL_FILE"
                fi
            fi
        fi
        _ft_seen=$((_ft_seen + 1))
        _progress_tick "$_ft_seen" "$pre_total" \
            "$tag $(_pluralize "$pre_total" file) copied" >&2
    done < <(find -L "${find_args[@]}" 2>"${_find_err:-/dev/null}")
    _progress_end >&2
    if [ -n "$_find_err" ] && [ -s "$_find_err" ]; then
        local _fe_line _fe_path
        while IFS= read -r _fe_line; do
            case "$_fe_line" in
                find:*': Permission denied'|find:*': Operation not permitted') ;;
                *) continue ;;
            esac
            _fe_path="${_fe_line#find: }"
            _fe_path="${_fe_path%: Permission denied}"
            _fe_path="${_fe_path%: Operation not permitted}"
            [ -n "$_fe_path" ] || continue
            note_incomplete "${files_dir:-}" "$_fe_path (unreadable folder)" \
                "macOS denied read access to this folder (POSIX permissions, not iCloud) — its files could not be enumerated and are not in the export"
        done < "$_find_err"
    fi
    [ -n "$_find_err" ] && rm -f -- "$_find_err" 2>/dev/null
    if [ "$fails" -gt 0 ]; then
        log_warn "$fails $(_pluralize "$fails" file) failed to copy from $src"
        note_incomplete "${files_dir:-}" "$fails $(_pluralize "$fails" file) from $src" \
            "the copy failed for these files (permissions, I/O error, or vanished mid-walk) — they are not in the export"
    fi
    [ "$_junk_skipped" -ge 10 ] && \
        printf '  Filtered %s junk path(s) in %s (.DS_Store / ._* / .localized / aliases)\n' \
            "$_junk_skipped" "$tag" >&2
    _COPY_TREE_N="$copied"
    _COPY_TREE_ACCOUNTED=$((copied + fails))
}

_files_section_excludes() {
    local _root="$1" _label="$2" _out="" _e _name _isk
    case "$_label" in
        Movies)
            while IFS= read -r -d '' _e; do
                _name="$(basename "$_e")"
                _out="${_out:+$_out$'\x1f'}$_name"
            done < <(find -L "$_root" -mindepth 1 -maxdepth 1 -type d \
                        -name '*.imovielibrary' -print0 2>/dev/null) ;;
        Music)
            [ -d "$_root/GarageBand" ] && _out="GarageBand" ;;
        Pictures)
            while IFS= read -r -d '' _e; do
                _name="$(basename "$_e")"
                _out="${_out:+$_out$'\x1f'}$_name"
            done < <(find "$_root" -mindepth 1 -maxdepth 1 -type d \
                        -name '*.photoslibrary' -print0 2>/dev/null)
            local _sympl_found=0 _sympl_e
            while IFS= read -r -d '' _sympl_e; do
                _name="$(basename "$_sympl_e")"
                _out="${_out:+$_out$'\x1f'}$_name"
                _sympl_found=$((_sympl_found + 1))
                if [ ! -e "$SCRATCH_DIR/.files-sympl-warned" ]; then
                    log_warn "Symlinked .photoslibrary detected at $_sympl_e — neither the Files nor the Photos category processes symlinked libraries; manually copy via the link's target if you need it backed up."
                    : > "$SCRATCH_DIR/.files-sympl-warned" 2>/dev/null
                fi
            done < <(find "$_root" -mindepth 1 -maxdepth 1 -type l \
                        -name '*.photoslibrary' -print0 2>/dev/null) ;;
    esac
    for _isk in "${FILES_EXCLUSIONS[@]+"${FILES_EXCLUSIONS[@]}"}"; do
        case "$_isk" in
            "$_label"/*) _out="${_out:+$_out$'\x1f'}${_isk#*/}" ;;
        esac
    done
    printf '%s' "$_out"
}

_is_prior_export_name() {
    case "$1" in
        downpour-[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]-[0-9][0-9][0-9][0-9][0-9][0-9]) return 0 ;;
        downpour-*-[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]-[0-9][0-9][0-9][0-9][0-9][0-9]) return 0 ;;
        cumulus-[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]-[0-9][0-9][0-9][0-9][0-9][0-9]) return 0 ;;
        cumulus-*-[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]-[0-9][0-9][0-9][0-9][0-9][0-9]) return 0 ;;
        export-[0-9]*-[0-9]*-[0-9]*-[0-9]*) return 0 ;;
    esac
    return 1
}

_is_other_home_dir() {
    case "$1" in
        Documents|Downloads|Desktop|Public|Movies|Music|Pictures|Library|Sites|Applications) return 1 ;;
        .*) return 1 ;;
    esac
    _files_section_included "$1" && return 1
    _is_prior_export_name "$1" && return 1
    return 0
}

_nc_measure() {
    local _p="$1" _c _h
    if [ -d "$_p" ]; then
        _c="$(find "$_p" -type f -print0 2>/dev/null | tr -dc '\0' | wc -c | tr -d ' ')"
    elif [ -e "$_p" ]; then
        _c=1
    else
        _c=0
    fi
    case "$_c" in ''|*[!0-9]*) _c=0 ;; esac
    _h="$(du -sh "$_p" 2>/dev/null | awk '{print $1}')"
    [ -n "$_h" ] || _h="?"
    case "$_h" in
        *.0[KMGTP]) _h="${_h%.0?}${_h#"${_h%?}"}" ;;
    esac
    case "$_h" in
        *K) _h="${_h%K} KB" ;;
        *M) _h="${_h%M} MB" ;;
        *G) _h="${_h%G} GB" ;;
        *T) _h="${_h%T} TB" ;;
        *P) _h="${_h%P} PB" ;;
        *B) _h="${_h%B} B" ;;
        *[0-9]) _h="$_h B" ;;
    esac
    printf '%s\x1f%s' "$_c" "$_h"
}

_write_not_copied_report() {
    local _fd="$1" _rep
    if [ ! -s "$_nc_partial" ] \
       && [ ! -s "$_nc_symlinks" ] \
       && [ ! -s "$_nc_intentional" ] \
       && [ ! -s "$_nc_dotfiles" ]; then
        return 0
    fi
    local _root _last_root _ent _cnt _sz _name _tgt _items=""
    if [ -s "$_nc_partial" ]; then
        _items="${_items:+$_items$'\n'}Partially copied folders:"
        _last_root=""
        while IFS=$'\x1f' read -r _root _ent _cnt _sz; do
            [ "$_root" != "$_last_root" ] && { _last_root="$_root"; _items="$_items"$'\n'"~/$_root"; }
            _items="$_items"$'\n'"    $_ent  ($_cnt $(_pluralize "$_cnt" file), $_sz)"
        done < "$_nc_partial"
    fi
    if [ -s "$_nc_symlinks" ]; then
        _items="${_items:+$_items$'\n'}Links not copied (broken, unresolvable, or pointing outside the export scope):"
        while IFS=$'\x1f' read -r _name _tgt; do
            _items="$_items"$'\n'"    $_name  ->  $_tgt"
        done < "$_nc_symlinks"
    fi
    if [ -s "$_nc_intentional" ]; then
        _items="${_items:+$_items$'\n'}System-managed items:"
        while IFS=$'\x1f' read -r _root _ent _cnt _sz; do
            _items="$_items"$'\n'"    ~/$_root/$_ent  ($_cnt $(_pluralize "$_cnt" file), $_sz)"
        done < "$_nc_intentional"
    fi
    if [ -s "$_nc_dotfiles" ]; then
        _items="${_items:+$_items$'\n'}Skipped at home root:"
        while IFS= read -r _name; do [ -n "$_name" ] && _items="$_items"$'\n'"    $_name"; done < "$_nc_dotfiles"
    fi
    report_review "$(_report_subject "$_fd")" "items outside the export scope" \
        "these weren't copied automatically — they're outside the Files export's defined scope (a neutral note, not an error). Copy any you need by hand." \
        "$_items"
    log_info "Reporting home-profile content that wasn't captured..."
}

_count_section() {
    local _r="$1"
    local _excludes="${2:-}"
    _COUNT_SECTION_N=0
    [ -d "$_r" ] || return 0
    local _e _c=0 _f _rel _real
    local _cs_last_par="" _cs_par_real="" _cs_par_ok=1 _par
    _e="$(printf '%s' "$_r" | sed 's/[][*?\\]/\\&/g')"
    local -a _cs_find=( "$_r"
            \( -type d \( -path "$_e/downpour-[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]-[0-9][0-9][0-9][0-9][0-9][0-9]" \
                          -o -path "$_e/downpour-*-[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]-[0-9][0-9][0-9][0-9][0-9][0-9]" \
                          -o -path "$_e/cumulus-[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]-[0-9][0-9][0-9][0-9][0-9][0-9]" \
                          -o -path "$_e/cumulus-*-[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]-[0-9][0-9][0-9][0-9][0-9][0-9]" \
                          -o -path "$_e/export-[0-9]*-[0-9]*-[0-9]*-[0-9]*" \) -prune \) )
    if [ -n "${files_dir:-}" ]; then
        local _cs_fd; _cs_fd="$(printf '%s' "$files_dir" | sed 's/[][*?\\]/\\&/g')"
        _cs_find+=( -o \( -path "$_cs_fd" -prune \) )
    fi
    if [ -n "$_excludes" ]; then
        local _cxn _cxesc _cx_ifs="$IFS"
        local -a _cxarr=()
        IFS=$'\x1f' read -r -a _cxarr <<< "$_excludes"
        IFS="$_cx_ifs"
        for _cxn in "${_cxarr[@]+"${_cxarr[@]}"}"; do
            [ -n "$_cxn" ] || continue
            _cxesc="$(printf '%s' "$_r/$_cxn" | sed 's/[][*?\\]/\\&/g')"
            _cs_find+=( -o \( -path "$_cxesc" -prune \) )
        done
    fi
    _cs_find+=( -o \( -type f -print0 \) )
    while IFS= read -r -d '' _f; do
        _rel="${_f#"$_r"/}"
        _par="${_f%/*}"
        if [ "$_par" != "$_cs_last_par" ]; then
            _cs_last_par="$_par"
            _cs_par_real="$(readlink -f -- "$_par" 2>/dev/null || realpath -- "$_par" 2>/dev/null)"
            if [ -z "$_cs_par_real" ]; then _cs_par_ok=1;
            elif _files_target_in_scope "$_cs_par_real"; then _cs_par_ok=1; else _cs_par_ok=0; fi
        fi
        [ "$_cs_par_ok" -eq 0 ] && continue
        is_icloud_stub "$_f" && continue
        if [ -L "$_f" ]; then
            _real="$(readlink -f -- "$_f" 2>/dev/null || realpath -- "$_f" 2>/dev/null)"
            if [ -n "$_real" ] && [ -f "$_real" ] && _files_target_in_scope "$_real"; then
                _c=$((_c + 1))
            fi
            continue
        fi
        should_skip_copy "$_f" "$_rel" && continue
        _c=$((_c + 1))
    done < <(find -L "${_cs_find[@]}" 2>/dev/null)
    case "$_c" in ''|*[!0-9]*) _c=0 ;; esac
    _COUNT_SECTION_N="$_c"
}

files_main() {
    maybe_show_help "$@"
    _announce_step "Files export"
    check_dependencies
    [ "${_INVOKED_BY_WRAPPER:-0}" = "1" ] || timemachine_suspend
    local out_arg out_dir
    out_arg="$(_parse_output_folder_arg "$@")" || exit 1
    out_dir="$(resolve_output_dir "$out_arg")" || exit 1
    _announce_output_dir "Files"
    log_info "Checking Full Disk Access and scanning \$HOME for symlinks..."
    require_full_disk_access
    local _src_kb=0 _avail_kb _need_kb _src_root _src_one
    for _src_root in "${FILES_INCLUSIONS[@]+"${FILES_INCLUSIONS[@]}"}"; do
        [ -d "$HOME/$_src_root" ] || continue
        _src_one="$(LC_ALL=C du -sk "$HOME/$_src_root" 2>/dev/null | awk '{print $1}')"
        case "$_src_one" in ''|*[!0-9]*) _src_one=0 ;; esac
        _src_kb=$((_src_kb + _src_one))
    done
    local _fe_sub _bundle_glob _phl
    if _files_section_included Pictures \
       && [ "$FILES_INCLUDE_PHOTOSLIBRARY_BUNDLES" != "1" ] \
       && [ -d "$HOME/Pictures" ]; then
        for _phl in "$HOME/Pictures"/*.photoslibrary; do
            [ -d "$_phl" ] || continue
            _fe_sub="$(LC_ALL=C du -sk "$_phl" 2>/dev/null | awk '{print $1}')"
            case "$_fe_sub" in ''|*[!0-9]*) _fe_sub=0 ;; esac
            _src_kb=$((_src_kb - _fe_sub))
        done
    fi
    if _files_section_included Movies \
       && [ "$FILES_INCLUDE_IMOVIE_BUNDLES" != "1" ] \
       && [ -d "$HOME/Movies" ]; then
        for _phl in "$HOME/Movies"/*.imovielibrary; do
            [ -d "$_phl" ] || continue
            _fe_sub="$(LC_ALL=C du -sk "$_phl" 2>/dev/null | awk '{print $1}')"
            case "$_fe_sub" in ''|*[!0-9]*) _fe_sub=0 ;; esac
            _src_kb=$((_src_kb - _fe_sub))
        done
    fi
    if _files_section_included Music \
       && [ "$FILES_INCLUDE_GARAGEBAND_BUNDLES" != "1" ] \
       && [ -d "$HOME/Music/GarageBand" ]; then
        _fe_sub="$(LC_ALL=C du -sk "$HOME/Music/GarageBand" 2>/dev/null | awk '{print $1}')"
        case "$_fe_sub" in ''|*[!0-9]*) _fe_sub=0 ;; esac
        _src_kb=$((_src_kb - _fe_sub))
    fi
    local _isk
    for _isk in "${FILES_EXCLUSIONS[@]+"${FILES_EXCLUSIONS[@]}"}"; do
        [ -e "$HOME/$_isk" ] || continue
        _fe_sub="$(LC_ALL=C du -sk "$HOME/$_isk" 2>/dev/null | awk '{print $1}')"
        case "$_fe_sub" in ''|*[!0-9]*) _fe_sub=0 ;; esac
        _src_kb=$((_src_kb - _fe_sub))
    done
    [ "$_src_kb" -lt 0 ] && _src_kb=0
    if [ "$FILES_INCLUDE_OTHER_HOME" = "1" ]; then
        local _oth_est _oth_est_size _oth_est_real
        while IFS= read -r -d '' _oth_est; do
            _is_other_home_dir "$(basename "$_oth_est")" || continue
            _oth_est_real="$(readlink -f -- "$_oth_est" 2>/dev/null || realpath -- "$_oth_est" 2>/dev/null)"
            { [ -n "$_oth_est_real" ] && _files_target_in_scope "$_oth_est_real"; } || continue
            _src_one="$(LC_ALL=C du -L -sk "$_oth_est" 2>/dev/null | awk '{print $1}')"
            case "$_src_one" in ''|*[!0-9]*) _src_one=0 ;; esac
            _src_kb=$((_src_kb + _src_one))
        done < <(find -L "$HOME" -mindepth 1 -maxdepth 1 -type d -print0 2>/dev/null)
        while IFS= read -r -d '' _oth_est; do
            case "$(basename "$_oth_est")" in .*) continue ;; esac
            [ -L "$_oth_est" ] && [ ! -f "$_oth_est" ] && continue
            if [ -L "$_oth_est" ]; then
                _oth_est_real="$(readlink -f -- "$_oth_est" 2>/dev/null || realpath -- "$_oth_est" 2>/dev/null)"
                { [ -n "$_oth_est_real" ] && [ -f "$_oth_est_real" ] && _files_target_in_scope "$_oth_est_real"; } || continue
            fi
            _oth_est_size="$(stat -L -f '%z' "$_oth_est" 2>/dev/null)"
            case "$_oth_est_size" in ''|*[!0-9]*) _oth_est_size=0 ;; esac
            _src_kb=$((_src_kb + (_oth_est_size + 1023) / 1024))
        done < <(find "$HOME" -maxdepth 1 \( -type f -o -type l \) -print0 2>/dev/null)
    fi
    _avail_kb="$(LC_ALL=C df -P -k "$out_dir" 2>/dev/null | awk 'END{print $4}')"
    _need_kb="$_src_kb"
    case "$_avail_kb" in
        ''|*[!0-9]*)
            _avail_kb=0
            [ "$_src_kb" -gt 0 ] && log_info "Could not determine output volume free space — sanity check skipped (df failed)." ;;
        0)
            [ "$_src_kb" -gt 0 ] && log_warn "Output volume reports 0 KB free — this Files export will likely fail (ENOSPC). Free up space or choose another output folder." ;;
        *)
            [ "$_src_kb" -gt 0 ] && [ "$_avail_kb" -lt "$_need_kb" ] && \
                log_warn "Output volume has $((_avail_kb/1024)) MB free; this Files export needs roughly $((_need_kb/1024)) MB across the user-content folders. The copy may fail partway — free up space or choose another output folder." ;;
    esac
    local files_dir="$out_dir/Files"
    require_no_collision "$files_dir"
    _create_output_dir "$files_dir"
    ensure_scratch
    _FILES_STUBS_FILE="$SCRATCH_DIR/files_stubs.tsv"
    : > "$_FILES_STUBS_FILE"
    _FILES_MAT_FAIL_FILE="$SCRATCH_DIR/files_mat_fail.tsv"
    : > "$_FILES_MAT_FAIL_FILE"
    local _nc_partial="$SCRATCH_DIR/nc_partial.tsv"
    local _nc_symlinks="$SCRATCH_DIR/nc_symlinks.tsv"
    local _nc_intentional="$SCRATCH_DIR/nc_intentional.tsv"
    local _nc_dotfiles="$SCRATCH_DIR/nc_dotfiles.txt"
    : > "$_nc_partial"
    : > "$_nc_symlinks"
    : > "$_nc_intentional"
    : > "$_nc_dotfiles"
    local _FILES_CANON=() _FILES_NOTES=() _note
    local _excl_pics _excl_mov _excl_mus
    _excl_pics="$(_files_section_excludes "$HOME/Pictures" Pictures)"
    _excl_mov="$(_files_section_excludes "$HOME/Movies" Movies)"
    _excl_mus="$(_files_section_excludes "$HOME/Music" Music)"
    local _n_doc _n_dl _n_desk _n_pub _n_pics _n_mov _n_mus _n_imv _n_gb
    _count_section "$HOME/Documents"; _n_doc="$_COUNT_SECTION_N"
    _count_section "$HOME/Downloads"; _n_dl="$_COUNT_SECTION_N"
    _count_section "$HOME/Desktop"; _n_desk="$_COUNT_SECTION_N"
    _count_section "$HOME/Public"; _n_pub="$_COUNT_SECTION_N"
    _count_section "$HOME/Pictures" "$_excl_pics"; _n_pics="$_COUNT_SECTION_N"
    _count_section "$HOME/Movies" "$_excl_mov"; _n_mov="$_COUNT_SECTION_N"
    _count_section "$HOME/Music" "$_excl_mus"; _n_mus="$_COUNT_SECTION_N"
    _n_imv=0
    if [ -d "$HOME/Movies" ]; then
        local _imv_lib
        while IFS= read -r -d '' _imv_lib; do
            local _imv_c
            _count_section "$_imv_lib"; _imv_c="$_COUNT_SECTION_N"
            _n_imv=$((_n_imv + _imv_c))
        done < <(find -L "$HOME/Movies" -mindepth 1 -maxdepth 1 \
                    -type d -name '*.imovielibrary' -print0 2>/dev/null)
    fi
    _count_section "$HOME/Music/GarageBand"; _n_gb="$_COUNT_SECTION_N"
    local _n_oth=0 _n_oth_entries=0 _oth_prev _oth_prev_name
    while IFS= read -r -d '' _oth_prev; do
        _is_other_home_dir "$(basename "$_oth_prev")" || continue
        _n_oth_entries=$((_n_oth_entries + 1))
        _count_section "$_oth_prev"; _n_oth=$((_n_oth + _COUNT_SECTION_N))
    done < <(find -L "$HOME" -mindepth 1 -maxdepth 1 -type d -print0 2>/dev/null)
    while IFS= read -r -d '' _oth_prev; do
        _oth_prev_name="$(basename "$_oth_prev")"
        case "$_oth_prev_name" in .*) continue ;; esac
        if [ -L "$_oth_prev" ]; then
            [ -f "$_oth_prev" ] || continue
            _oth_prev="$(readlink -f -- "$_oth_prev" 2>/dev/null || realpath -- "$_oth_prev" 2>/dev/null)"
            { [ -n "$_oth_prev" ] && [ -f "$_oth_prev" ] && _files_target_in_scope "$_oth_prev"; } || continue
        fi
        is_icloud_stub "$_oth_prev" && continue
        should_skip_copy "$_oth_prev" "$_oth_prev_name" && continue
        _n_oth_entries=$((_n_oth_entries + 1))
        _n_oth=$((_n_oth + 1))
    done < <(find "$HOME" -maxdepth 1 \( -type f -o -type l \) -print0 2>/dev/null)
    local _sl _sl_name _sl_target _sym_n=0
    while IFS= read -r -d '' _sl; do
        _sl_name="$(basename "$_sl")"
        case "$_sl_name" in
            .*) continue ;;
            Documents|Downloads|Desktop|Public|Pictures|Movies|Music) continue ;;
        esac
        if [ "$FILES_INCLUDE_OTHER_HOME" = "1" ] && [ -e "$_sl" ]; then
            continue
        fi
        _sym_n=$((_sym_n + 1))
        _sl_target="$(stat -f %Y "$_sl" 2>/dev/null)"
        [ -n "$_sl_target" ] || _sl_target="(broken — target missing)"
        printf '%s\x1f%s\n' "$(tsv_escape "$_sl_name")" \
            "$(tsv_escape "$_sl_target")" >> "$_nc_symlinks"
    done < <(find "$HOME" -mindepth 1 -maxdepth 1 -type l -print0 2>/dev/null)
    [ "$_sym_n" -gt 0 ] && \
        log_info "$_sym_n broken top-level \$HOME $(_pluralize "$_sym_n" symlink) (target missing)$(_disclosure_pointer)"
    log_info 'Copying to the "Files" output folder...'
    local total_copied=0 copied
    local section_name section_src section_dst _section_total _sec_excludes
    for section_name in "${FILES_INCLUSIONS[@]+"${FILES_INCLUSIONS[@]}"}"; do
        case "$section_name" in Pictures) continue ;; esac
        section_src="$HOME/$section_name"
        section_dst="$files_dir/$section_name"
        case "$section_name" in
            Documents) _section_total="$_n_doc";  _sec_excludes="" ;;
            Downloads) _section_total="$_n_dl";   _sec_excludes="" ;;
            Desktop)   _section_total="$_n_desk"; _sec_excludes="" ;;
            Public)    _section_total="$_n_pub";  _sec_excludes="" ;;
            Movies)    _section_total="$_n_mov";  _sec_excludes="$_excl_mov" ;;
            Music)     _section_total="$_n_mus";  _sec_excludes="$_excl_mus" ;;
            *)         # User-added entry in FILES_INCLUSIONS. Compute its
                       _sec_excludes="$(_files_section_excludes "$section_src" "$section_name")"
                       _count_section "$section_src" "$_sec_excludes"; _section_total="$_COUNT_SECTION_N" ;;
        esac
        local _sec_prune="$files_dir"
        case "$out_dir" in
            "$section_src"/?*) _sec_prune="$out_dir" ;;
        esac
        _copy_files_tree "$section_src" "$section_dst" "$_sec_prune" "$section_name" "$_section_total" "$_sec_excludes"; copied="$_COPY_TREE_N"
        total_copied=$((total_copied + copied))
        validate_count_parity "$_section_total" "${_COPY_TREE_ACCOUNTED:-0}" \
            "Files: $section_name" "$files_dir"
        local _canon_size _canon_line
        _canon_size="$(_dir_size_human "$section_dst")"
        [ -n "$_canon_size" ] || _canon_size="0K"
        _canon_line="  • Copied $section_name: $copied $(_pluralize "$copied" file), $_canon_size"
        case "$section_name" in
            Movies) _canon_line="$_canon_line (iMovie libraries copied separately)" ;;
            Music)  _canon_line="$_canon_line (GarageBand copied separately)" ;;
        esac
        _FILES_CANON+=( "$_canon_line" )
        local _prior_count=0 _ed
        while IFS= read -r -d '' _ed; do
            _is_prior_export_name "${_ed##*/}" && _prior_count=$((_prior_count + 1))
        done < <(find "$section_src" -mindepth 1 -maxdepth 1 -type d \
                    -print0 2>/dev/null)
        [ "$_prior_count" -gt 0 ] && \
            _FILES_NOTES+=( "Skipped $_prior_count prior export $(_pluralize "$_prior_count" folder) in $section_name" )
    done
    local pictures_src="$HOME/Pictures"
    local pictures_dst="$files_dir/Pictures"
    if _files_section_included Pictures; then
        copied=0
        if [ -d "$pictures_src" ] && [ "$_n_pics" -gt 0 ]; then
            _copy_files_tree "$pictures_src" "$pictures_dst" "$files_dir" "Pictures" "$_n_pics" "$_excl_pics"; copied="$_COPY_TREE_N"
            total_copied=$((total_copied + copied))
        fi
        local _pics_size
        _pics_size="$(_dir_size_human "$pictures_dst")"
        [ -n "$_pics_size" ] || _pics_size="0K"
        _FILES_CANON+=( "  • Copied Pictures: $copied $(_pluralize "$copied" file), $_pics_size (loose files only; Photos libraries copied separately)" )
    fi
    if [ "${#_FILES_CANON[@]}" -gt 0 ]; then
        local _canon_out
        while IFS= read -r _canon_out; do
            [ -n "$_canon_out" ] && log_info "$_canon_out"
        done < <(printf '%s\n' "${_FILES_CANON[@]}" | LC_ALL=C sort)
    fi
    log_info "Copying bundles to their own subfolders..."
    if _files_section_included Pictures \
       && [ "$FILES_INCLUDE_PHOTOSLIBRARY_BUNDLES" != "1" ] \
       && [ -d "$pictures_src" ]; then
        local _ppl _ppl_name _ppl_n=0
        while IFS= read -r -d '' _ppl; do
            _ppl_name="$(basename "$_ppl")"
            _ppl_n=$((_ppl_n + 1))
            printf 'Pictures\x1f%s/\x1f%s\n' "$(tsv_escape "$_ppl_name")" "$(_nc_measure "$_ppl")" >> "$_nc_partial"
        done < <(find -L "$pictures_src" -mindepth 1 -maxdepth 1 \
                    -type d -name '*.photoslibrary' -print0 2>/dev/null)
        [ "$_ppl_n" -gt 0 ] && \
            log_info "  • Note: $_ppl_n Photos $(_pluralize "$_ppl_n" library libraries) not copied here (captured by the Photos category)"
    fi
    if [ "$FILES_INCLUDE_IMOVIE_BUNDLES" != "1" ]; then
        if [ -d "$HOME/Movies" ]; then
            local _iml _iml_name _iml_n=0
            while IFS= read -r -d '' _iml; do
                _iml_name="$(basename "$_iml")"
                _iml_n=$((_iml_n + 1))
                printf 'Movies\x1f%s/\x1f%s\n' "$(tsv_escape "$_iml_name")" "$(_nc_measure "$_iml")" >> "$_nc_partial"
            done < <(find -L "$HOME/Movies" -mindepth 1 -maxdepth 1 \
                        -type d -name '*.imovielibrary' -print0 2>/dev/null)
            [ "$_iml_n" -gt 0 ] && \
                log_info "  • iMovie projects NOT copied ($_iml_n $(_pluralize "$_iml_n" library libraries), FILES_INCLUDE_IMOVIE_BUNDLES=0)"
        fi
    else
    local imovie_src="$HOME/Movies"
    local imovie_dst="$files_dir/iMovie"
    local imovie_count=0 imovie_files=0
    local _lib _libname _lib_total
    if [ -d "$imovie_src" ]; then
        while IFS= read -r -d '' _lib; do
            _libname="$(basename "$_lib")"
            _count_section "$_lib"; _lib_total="$_COUNT_SECTION_N"
            log_info "  Copying iMovie library \"$_libname\" ($_lib_total $(_pluralize "$_lib_total" file))..."
            _copy_files_tree "$_lib" "$imovie_dst/$_libname" "$files_dir" "iMovie/$_libname" "$_lib_total"; copied="$_COPY_TREE_N"
            imovie_files=$((imovie_files + copied))
            [ "$copied" -gt 0 ] && imovie_count=$((imovie_count + 1))
        done < <(find -L "$imovie_src" -mindepth 1 -maxdepth 1 \
                    -type d -name '*.imovielibrary' -print0 2>/dev/null)
        [ "$imovie_files" -gt 0 ] && total_copied=$((total_copied + imovie_files))
    fi
    local _imv_size
    _imv_size="$(_dir_size_human "$imovie_dst")"
    [ -n "$_imv_size" ] || _imv_size="0K"
    log_info "  • Copied iMovie projects: $imovie_count $(_pluralize "$imovie_count" library libraries), $imovie_files $(_pluralize "$imovie_files" file), $_imv_size"
    fi  # close FILES_INCLUDE_IMOVIE_BUNDLES gate
    if [ "$FILES_INCLUDE_PHOTOSLIBRARY_BUNDLES" = "1" ]; then
        local photos_src="$HOME/Pictures"
        local photos_dst="$files_dir/Photos"
        local photos_count=0 photos_files=0
        local _phl_lib _phl_libname _phl_lib_total
        if [ -d "$photos_src" ]; then
            while IFS= read -r -d '' _phl_lib; do
                _phl_libname="$(basename "$_phl_lib")"
                _count_section "$_phl_lib"; _phl_lib_total="$_COUNT_SECTION_N"
                log_info "  Copying Photos library \"$_phl_libname\" ($_phl_lib_total $(_pluralize "$_phl_lib_total" file))..."
                _copy_files_tree "$_phl_lib" "$photos_dst/$_phl_libname" "$files_dir" "Photos/$_phl_libname" "$_phl_lib_total"; copied="$_COPY_TREE_N"
                photos_files=$((photos_files + copied))
                [ "$copied" -gt 0 ] && photos_count=$((photos_count + 1))
            done < <(find -L "$photos_src" -mindepth 1 -maxdepth 1 \
                        -type d -name '*.photoslibrary' -print0 2>/dev/null)
            [ "$photos_files" -gt 0 ] && total_copied=$((total_copied + photos_files))
        fi
        local _photos_size
        _photos_size="$(_dir_size_human "$photos_dst")"
        [ -n "$_photos_size" ] || _photos_size="0K"
        log_info "  • Copied Photos libraries: $photos_count $(_pluralize "$photos_count" library libraries), $photos_files $(_pluralize "$photos_files" file), $_photos_size"
    fi
    if [ "$FILES_INCLUDE_GARAGEBAND_BUNDLES" != "1" ]; then
        if [ -d "$HOME/Music/GarageBand" ]; then
            printf 'Music\x1fGarageBand/\x1f%s\n' "$(_nc_measure "$HOME/Music/GarageBand")" >> "$_nc_partial"
            log_info "  • GarageBand NOT copied (FILES_INCLUDE_GARAGEBAND_BUNDLES=0)"
        fi
    else
    local gb_src="$HOME/Music/GarageBand"
    local gb_dst="$files_dir/GarageBand"
    copied=0
    if [ -d "$gb_src" ] && [ "$_n_gb" -gt 0 ]; then
        _copy_files_tree "$gb_src" "$gb_dst" "$files_dir" "GarageBand" "$_n_gb"; copied="$_COPY_TREE_N"
        total_copied=$((total_copied + copied))
    fi
    local _gb_size
    _gb_size="$(_dir_size_human "$gb_dst")"
    [ -n "$_gb_size" ] || _gb_size="0K"
    log_info "  • Copied GarageBand projects: $copied $(_pluralize "$copied" file), $_gb_size"
    fi  # close FILES_INCLUDE_GARAGEBAND_BUNDLES gate
    if [ "$FILES_INCLUDE_OTHER_HOME" != "1" ]; then
        :  # Files/Other/ disabled by CONFIG; nothing to do
    else
    log_info "Copying non-standard folders/files in the home profile..."
    local _oth _oth_name _oth_total _oth_copied _oth_entries=0
    local _dotdir_count=0
    while IFS= read -r -d '' _oth; do
        _oth_name="$(basename "$_oth")"
        if ! _is_other_home_dir "$_oth_name"; then
            case "$_oth_name" in
                .*) _dotdir_count=$((_dotdir_count + 1)) ;;
            esac
            continue
        fi
        _oth_entries=$((_oth_entries + 1))
        if [ -L "$_oth" ] && [ -d "$_oth" ]; then
            local _oth_real
            _oth_real="$(readlink -f -- "$_oth" 2>/dev/null || realpath -- "$_oth" 2>/dev/null)"
            if [ -n "$_oth_real" ] && ! _files_target_in_scope "$_oth_real"; then
                [ -n "${_nc_symlinks:-}" ] && printf '%s\x1f%s (symlink target is outside the export scope — not copied)\n' \
                    "$(tsv_escape "Other: $_oth_name")" \
                    "$(tsv_escape "$_oth_real")" >> "$_nc_symlinks"
                continue
            fi
            _FILES_SYMLINK_DEREF_DIR=$((${_FILES_SYMLINK_DEREF_DIR:-0} + 1))
        fi
        _count_section "$_oth"; _oth_total="$_COUNT_SECTION_N"
        log_info "  Copying ~/$_oth_name ($_oth_total $(_pluralize "$_oth_total" file))..."
        _copy_files_tree "$_oth" "$files_dir/Other/$_oth_name" "$files_dir" "Other/$_oth_name" "$_oth_total"; _oth_copied="$_COPY_TREE_N"
        total_copied=$((total_copied + _oth_copied))
        local _oth_size
        _oth_size="$(_dir_size_human "$files_dir/Other/$_oth_name")"
        [ -n "$_oth_size" ] || _oth_size="0K"
        log_info "  • Copied ~/$_oth_name: $_oth_copied $(_pluralize "$_oth_copied" file), $_oth_size"
    done < <(find -L "$HOME" -mindepth 1 -maxdepth 1 -type d -print0 2>/dev/null)
    local _lf_copied=0 _lf_fails=0 _lf_size _lf_was_dataless _dotfile_count=0
    while IFS= read -r -d '' _oth; do
        _oth_name="$(basename "$_oth")"
        if is_icloud_stub "$_oth"; then
            if [ -n "$_FILES_STUBS_FILE" ]; then
                printf '%s\t%s\n' "$(tsv_escape "Other")" \
                    "$(tsv_escape "$(_strip_icloud_stub_name "$_oth_name")")" \
                    >> "$_FILES_STUBS_FILE"
            fi
            continue
        fi
        case "$_oth_name" in
            .*)
                _dotfile_count=$((_dotfile_count + 1))
                continue
                ;;
        esac
        if [ -L "$_oth" ]; then
            if [ -f "$_oth" ]; then
                local _oth_real
                _oth_real="$(readlink -f -- "$_oth" 2>/dev/null || realpath -- "$_oth" 2>/dev/null)"
                if [ -n "$_oth_real" ] && [ -f "$_oth_real" ] && _files_target_in_scope "$_oth_real"; then
                    _oth="$_oth_real"
                    _FILES_SYMLINK_DEREF=$((${_FILES_SYMLINK_DEREF:-0} + 1))
                elif [ -n "$_oth_real" ] && [ -f "$_oth_real" ]; then
                    [ -n "${_nc_symlinks:-}" ] && printf '%s\x1f%s (symlink target is outside the export scope — not copied)\n' \
                        "$(tsv_escape "Other: $_oth_name")" \
                        "$(tsv_escape "$_oth_real")" >> "$_nc_symlinks"
                    continue
                else
                    continue
                fi
            else
                continue
            fi
        fi
        should_skip_copy "$_oth" "$_oth_name" && continue
        _oth_entries=$((_oth_entries + 1))
        _lf_was_dataless=0
        local _lf_src_size=""
        if is_dataless "$_oth"; then
            _lf_was_dataless=1
            _lf_src_size="$(stat -f '%z' -- "$_oth" 2>/dev/null)"
        fi
        mkdir -p -- "$files_dir/Other" 2>/dev/null
        local _lf_err
        _lf_err="$(_ditto_dl_retry "$_oth" "$files_dir/Other/$_oth_name" "$_lf_was_dataless")"
        if [ $? -eq 0 ]; then
            local _lf_integrity_ok=1
            if [ "$_lf_was_dataless" = "1" ] \
               && _materialized_copy_incomplete "$_lf_src_size" "$files_dir/Other/$_oth_name"; then
                rm -f -- "$files_dir/Other/$_oth_name" 2>/dev/null
                log_warn "Failed to download from iCloud: loose ~/$_oth_name (the copy ran but the downloaded file came out incomplete)"
                note_incomplete "${files_dir:-}" "Other/$_oth_name" \
                    "the iCloud-only file ~/$_oth_name appeared to copy but the result was incomplete or zero bytes (it did not match the original) — the iCloud download did not finish"
                _lf_fails=$((_lf_fails + 1))
                _lf_integrity_ok=0
            fi
            if [ "$_lf_integrity_ok" -eq 1 ]; then
                _lf_size="$(stat -f '%z' "$files_dir/Other/$_oth_name" 2>/dev/null)"
                case "${_lf_size:-0}" in
                    ''|*[!0-9]*) _lf_size="0 B" ;;
                    *) _lf_size="$(_bytes_human "$_lf_size")" ;;
                esac
                log_info "  • Copied ~/$_oth_name: 1 file, $_lf_size"
                total_copied=$((total_copied + 1))
                _lf_copied=$((_lf_copied + 1))
            fi
        else
            rm -f -- "$files_dir/Other/$_oth_name" 2>/dev/null
            if [ "$_lf_was_dataless" = "1" ]; then
                log_warn "Failed to download from iCloud: loose ~/$_oth_name (the file is iCloud-only and could not be downloaded)"
                note_incomplete "${files_dir:-}" "Other/$_oth_name" \
                    "the iCloud-only file ~/$_oth_name failed to download (it stayed a cloud placeholder — network unreachable, iCloud throttling, or stuck in an offloaded state)"
            else
                case "$_lf_err" in
                    *"Permission denied"*|*"Operation not permitted"*)
                        log_warn "Failed to copy loose ~/$_oth_name into Files/Other/ (permission denied — Full Disk Access may be needed)"
                        note_incomplete "${files_dir:-}" "Other/$_oth_name" \
                            "the loose file at ~/$_oth_name failed to copy (permission denied — grant Full Disk Access and re-run)" ;;
                    *)
                        log_warn "Failed to copy loose ~/$_oth_name into Files/Other/"
                        note_incomplete "${files_dir:-}" "Other/$_oth_name" \
                            "the loose file at ~/$_oth_name failed to copy (I/O error, or vanished mid-walk)" ;;
                esac
            fi
            _lf_fails=$((_lf_fails + 1))
        fi
    done < <(find "$HOME" -maxdepth 1 \( -type f -o -type l \) -print0 2>/dev/null)
    [ "$_oth_entries" -eq 0 ] && \
        log_info "  • No non-standard home-profile content found"
    if [ "$_dotdir_count" -gt 0 ] || [ "$_dotfile_count" -gt 0 ]; then
        local _dot_total=$((_dotdir_count + _dotfile_count))
        local _dot_what
        if [ "$_dotdir_count" -gt 0 ] && [ "$_dotfile_count" -gt 0 ]; then
            _dot_what="$_dot_total $(_pluralize "$_dot_total" "dotfile/dot-directory" "dotfiles/dot-directories") at ~ (~/.ssh, ~/.gnupg, etc.)"
        elif [ "$_dotdir_count" -gt 0 ]; then
            _dot_what="$_dotdir_count dot-$(_pluralize "$_dotdir_count" directory directories) at ~ (~/.ssh, ~/.gnupg, etc.)"
        else
            _dot_what="$_dotfile_count $(_pluralize "$_dotfile_count" dotfile) at ~ (~/.bashrc, ~/.zshrc, etc.)"
        fi
        _FILES_NOTES+=( "Skipped $_dot_what" )
        printf '  %s\n' "$_dot_what" >> "$_nc_dotfiles"
    fi
    fi  # close FILES_INCLUDE_OTHER_HOME gate
    local _isk_root _isk_ent _isk_n=0
    local _nc_paths=() _nc_std _nc_p _nc_joined=""
    for _isk in "${FILES_EXCLUSIONS[@]+"${FILES_EXCLUSIONS[@]}"}"; do
        [ -e "$HOME/$_isk" ] || continue
        _isk_root="${_isk%%/*}"
        _isk_ent="${_isk#*/}"
        [ -d "$HOME/$_isk" ] && _isk_ent="$_isk_ent/"
        _isk_n=$((_isk_n + 1))
        printf '%s\x1f%s\x1f%s\n' "$_isk_root" "$_isk_ent" \
            "$(_nc_measure "$HOME/$_isk")" >> "$_nc_intentional"
        _nc_paths+=( "~/$_isk" )
    done
    for _nc_std in Library Sites Applications; do
        [ -d "$HOME/$_nc_std" ] || continue
        _isk_n=$((_isk_n + 1))
        printf '%s\x1f%s\x1f%s\n' "$_nc_std" "" \
            "$(_nc_measure "$HOME/$_nc_std")" >> "$_nc_intentional"
        _nc_paths+=( "~/$_nc_std" )
    done
    if [ "$_isk_n" -gt 0 ]; then
        while IFS= read -r _nc_p; do
            [ -n "$_nc_p" ] || continue
            _nc_joined="${_nc_joined:+$_nc_joined, }$_nc_p"
        done < <(printf '%s\n' "${_nc_paths[@]}" | LC_ALL=C sort)
        _FILES_NOTES+=( "$_isk_n paths outside this category's scope (not captured here or by the GarageBand / iMovie / Photos categories): $_nc_joined" )
    fi
    if [ "${#_FILES_NOTES[@]}" -gt 0 ]; then
        log_info "Notes:"
        for _note in "${_FILES_NOTES[@]}"; do
            log_info "  • $_note"
        done
    fi
    log_info "Finalising Files/ output..."
    _write_not_copied_report "$files_dir"
    find "$files_dir" -mindepth 1 -type d -empty -delete 2>/dev/null || true
    local _files_stat
    _files_stat="$total_copied $(_pluralize "$total_copied" file)"
    if [ -s "$_FILES_STUBS_FILE" ]; then
        local _stub_summary
        _stub_summary="$(_count_lines "$_FILES_STUBS_FILE")"
        [ "$_stub_summary" -gt 0 ] && \
            _files_stat="$_files_stat, $_stub_summary cloud-only$(_disclosure_pointer)"
    fi
    _files_stat="$_files_stat, $(_dir_size_human "$files_dir")"
    if [ "$total_copied" -eq 0 ]; then
        _flag_no_content
        log_info "Files: no in-scope files to copy$(_disclosure_pointer)."
        rmdir "$files_dir" 2>/dev/null || true
    else
        log_ok "Wrote Files/ ($_files_stat)"
    fi
    if [ "${_FILES_SYMLINK_DEREF:-0}" -gt 0 ] || [ "${_FILES_SYMLINK_DEREF_DIR:-0}" -gt 0 ]; then
        local _sd_parts=""
        [ "${_FILES_SYMLINK_DEREF:-0}" -gt 0 ] && \
            _sd_parts="${_FILES_SYMLINK_DEREF} file $(_pluralize "${_FILES_SYMLINK_DEREF}" symlink) dereferenced (target content copied)"
        if [ "${_FILES_SYMLINK_DEREF_DIR:-0}" -gt 0 ]; then
            [ -n "$_sd_parts" ] && _sd_parts="$_sd_parts; "
            _sd_parts="${_sd_parts}${_FILES_SYMLINK_DEREF_DIR} top-level directory $(_pluralize "${_FILES_SYMLINK_DEREF_DIR}" symlink) followed"
        fi
        log_info "Symlinks: $_sd_parts — no symlink objects are written to the export."
    fi
    if [ -s "$_FILES_STUBS_FILE" ] || [ -s "$_FILES_MAT_FAIL_FILE" ]; then
        local _stub_count _mat_fail_count
        _stub_count="$(_count_lines "$_FILES_STUBS_FILE")"
        _mat_fail_count="$(LC_ALL=C sort -u "$_FILES_MAT_FAIL_FILE" | wc -l | tr -d ' ')"
        {
            if [ -s "$_FILES_STUBS_FILE" ]; then
                LC_ALL=C sort -u "$_FILES_STUBS_FILE" | LC_ALL=C awk -F'\t' '{
                    if ($1 != prev) { if (prev != "") print ""; print "[" $1 "]"; prev = $1 }
                    print $2
                }'
            fi
            if [ -s "$_FILES_MAT_FAIL_FILE" ]; then
                [ -s "$_FILES_STUBS_FILE" ] && printf '\n'
                printf '[Failed to download from iCloud]\n'
                LC_ALL=C awk -F'\t' '{
                    if ($1 == "incomplete")        r = "incomplete copy, removed"
                    else if ($1 == "perm-denied")  r = "permission denied (TCC-protected source, or sandboxed app folder)"
                    else if ($1 == "copy-failed")  r = "copy failed (I/O error or destination full)"
                    else                            r = "download failed"
                    print $2 "  (" r ")"
                }' "$_FILES_MAT_FAIL_FILE" | LC_ALL=C sort -u
            fi
        } | _write_skipped_report "$files_dir" "Files"
        [ "$_mat_fail_count" -gt 0 ] && \
            log_warn "$_mat_fail_count $(_pluralize "$_mat_fail_count" file) could not be copied — NOT in this export (iCloud download, copy, or permission failures; see the per-file reasons)$(_disclosure_pointer)"
        if [ "$_stub_count" -gt 0 ]; then
            _disclose_optimize_storage "Documents / Desktop / Downloads" \
                "$_stub_count" "" \
                "System Settings > Apple ID > iCloud > iCloud Drive > Sync this Mac > Optimize Mac Storage (off), and ensure 'Desktop & Documents Folders' is fully downloaded"
        fi
    fi
    mark_success
    sweep_junk_files "$files_dir"
    print_summary
    if [ "$ERR_COUNT" -gt 0 ]; then exit 1; fi
    exit 0
}

_FREEFORM_LAUNCHED_BY_US=0
case "$FREEFORM_GUI_WAIT_SEC" in
    ''|*[!0-9]*)        FREEFORM_GUI_WAIT_SEC=20 ;;
    *)
        FREEFORM_GUI_WAIT_SEC=$((10#$FREEFORM_GUI_WAIT_SEC))
        [ "$FREEFORM_GUI_WAIT_SEC" -lt 1 ] && FREEFORM_GUI_WAIT_SEC=1
        [ "$FREEFORM_GUI_WAIT_SEC" -gt 3600 ] && FREEFORM_GUI_WAIT_SEC=20
        ;;
esac

_FREEFORM_PREF_HAD_VALUE=0
_FREEFORM_PREF_ORIGINAL=""
_FREEFORM_PREF_WRITTEN=0
_FREEFORM_PREF_SKIP=0

_restore_freeform_pref() {
    [ -n "${SCRATCH_DIR:-}" ] && [ -f "$SCRATCH_DIR/freeform_pref_written" ] && _FREEFORM_PREF_WRITTEN=1
    _restore_defaults_pref _FREEFORM com.apple.freeform NSNavLastRootDirectory
}

freeform_leaf_cleanup_hook() {
    quit_app_iff_we_launched_it Freeform _FREEFORM_LAUNCHED_BY_US
    _restore_freeform_pref
}

_ff_count_board_rows() {
    local _n
    _n=$(awk -F'\t' '$1!=""{n++} END{print n+0}' "$1" 2>/dev/null | tr -d ' ')
    case "$_n" in ''|*[!0-9]*) _n=0 ;; esac
    printf '%s' "$_n"
}

_ff_has_content() {
    local _d="$1"
    [ -d "$_d" ] || return 1
    local _real
    _real=$(find "$_d" -type f \
        -not -name '.DS_Store' -not -name '.localized' -not -name '._*' \
        -not -name '.com.apple.containermanagerd.metadata.plist' \
        -not -path '*/Library/Preferences/*' \
        2>/dev/null | head -1)
    [ -n "$_real" ]
}

export_freeform() {
    local out_root="$1"
    local _ff_root="$out_root/Freeform"
    local _ff_container="$HOME/Library/Containers/com.apple.freeform/Data"
    local _ff_group="$HOME/Library/Group Containers/group.com.apple.freeform"
    local _has_container=0 _has_group=0
    _ff_has_content "$_ff_container" && _has_container=1
    _ff_has_content "$_ff_group" && _has_group=1
    if [ "$_has_container" = "0" ] && [ "$_has_group" = "0" ]; then
        report_no_source "Freeform" "not configured" \
            "~/Library/Containers/com.apple.freeform/Data and ~/Library/Group Containers/group.com.apple.freeform" \
            "Freeform"
    fi
    require_no_collision "$_ff_root"
    _create_output_dir "$_ff_root" "permission denied / disk full?"
    local _ff_sources=""
    if [ "$_has_container" = "1" ] && [ "$_has_group" = "1" ]; then
        _ff_sources="$_ff_container and $_ff_group"
    elif [ "$_has_container" = "1" ]; then
        _ff_sources="$_ff_container"
    else
        _ff_sources="$_ff_group"
    fi
    log_info "Source: $_ff_sources"
    _freeform_export_pdfs "$_ff_root"
    local _snap="$HOME/Library/Group Containers/group.com.apple.freeform/Snapshot.plist"
    local _have_pdfs=0
    if [ -d "$_ff_root" ]; then
        local _ff_first_pdf
        if IFS= read -r -d '' _ff_first_pdf < <(find "$_ff_root" -maxdepth 1 -name '*.pdf' -type f -print0 -quit 2>/dev/null); then
            _have_pdfs=1
        fi
    fi
    ensure_scratch
    local _boards_tsv="$SCRATCH_DIR/ff-boards.tsv"
    if [ ! -s "$_boards_tsv" ]; then
        local _snap_xml=""
        if [ -f "$_snap" ]; then
            _snap_xml="$SCRATCH_DIR/ff-inventory-snapshot.xml"
            plutil -convert xml1 -o "$_snap_xml" "$_snap" 2>/dev/null || _snap_xml=""
        fi
        _ff_enumerate_boards "$_snap_xml" "$_boards_tsv" || : > "$_boards_tsv"
    fi
    local _ff_board_rows=0
    if [ -s "$_boards_tsv" ]; then
        _ff_board_rows="$(_ff_count_board_rows "$_boards_tsv")"
    fi
    [ "${_FF_TOMBSTONED_N:-0}" -gt 0 ] && \
        log_info "$_FF_TOMBSTONED_N $(_pluralize "$_FF_TOMBSTONED_N" board) in Freeform's Recently Deleted $(_pluralize "$_FF_TOMBSTONED_N" was were) not exported (deleted boards can't be rendered to PDF; recover them in Freeform within ~30 days)."
    local _ff_have_date=0 _ff_have_flags=0
    if [ -s "$_boards_tsv" ]; then
        awk -F'\t' '$3!=""{exit 0} END{exit 1}' "$_boards_tsv" 2>/dev/null && _ff_have_date=1
        awk -F'\t' '$4!=""{exit 0} END{exit 1}' "$_boards_tsv" 2>/dev/null && _ff_have_flags=1
    fi
    local _ff_pdf_map="$SCRATCH_DIR/ff-pdf-map.tsv"
    local _ff_map_keys=()
    local _ffmu _ffma _ffms _ffmkey _ff_safekey
    if [ -f "$_ff_pdf_map" ]; then
        while IFS=$'\t' read -r _ffmu _ffma _ffms; do
            [ -n "$_ffmu" ] || continue
            _ff_safekey="${_ffmu//-/_}"
            _ff_safekey="${_ff_safekey//[^A-Za-z0-9_]/_}"
            [ -n "$_ff_safekey" ] || continue
            _ffmkey="_ff_map_${_ff_safekey}"
            printf -v "$_ffmkey" '%s\x1f%s' "$_ffms" "$_ffma"
            _ff_map_keys+=( "$_ffmkey" )
        done < "$_ff_pdf_map"
    fi
    local _ff_unsupported=0
    [ -f "$SCRATCH_DIR/ff-unsupported-device" ] && _ff_unsupported=1
    local _ff_needs_attention=0
    if [ -s "$_boards_tsv" ]; then
        local _scan_uuid _scan_rest _scan_key _scan_rec _scan_actual _scan_status
        while IFS=$'\t' read -r _scan_uuid _scan_rest; do
            [ -n "$_scan_uuid" ] || continue
            _scan_key="${_scan_uuid//-/_}"
            _scan_key="${_scan_key//[^A-Za-z0-9_]/_}"
            _scan_key="_ff_map_${_scan_key}"
            _scan_rec="${!_scan_key:-}"
            if [ -z "$_scan_rec" ]; then
                _ff_needs_attention=1; break
            fi
            _scan_status="${_scan_rec%%$'\x1f'*}"
            _scan_actual="${_scan_rec#*$'\x1f'}"
            if [ "$_scan_status" != "exported" ]; then
                _ff_needs_attention=1; break
            fi
            if [ -z "$_scan_actual" ] || [ ! -f "$_ff_root/$_scan_actual" ]; then
                _ff_needs_attention=1; break
            fi
        done < "$_boards_tsv"
    fi
    if [ "$_ff_needs_attention" = "1" ]; then
        {
            if [ "$_ff_unsupported" = "1" ]; then
                _doc_header "Freeform boards" \
                    "Note" "macOS flags this Mac as possibly unsupported for Freeform export"
            else
                _doc_header "Freeform boards"
            fi
            if [ -s "$_boards_tsv" ]; then
                local _inv_idx=0
                local _uuid _title _bdate _bflags _pdf_actual _pdf_status _ffmrec
                while IFS=$'\t' read -r _uuid _title _bdate _bflags; do
                    [ -n "$_uuid" ] || continue
                    _inv_idx=$((_inv_idx + 1))
                    [ -n "$_title" ] || _title="Board $_inv_idx"
                    _pdf_actual=""; _pdf_status=""
                    local _ff_lookup_key="${_uuid//-/_}"
                    _ff_lookup_key="${_ff_lookup_key//[^A-Za-z0-9_]/_}"
                    _ffmkey="_ff_map_${_ff_lookup_key}"
                    _ffmrec="${!_ffmkey:-}"
                    if [ -n "$_ffmrec" ]; then
                        _pdf_status="${_ffmrec%%$'\x1f'*}"
                        _pdf_actual="${_ffmrec#*$'\x1f'}"
                    fi
                    if [ "$_pdf_status" = "exported" ]; then
                        if [ -z "$_pdf_actual" ] || [ ! -f "$_ff_root/$_pdf_actual" ]; then
                            _pdf_status="export-failed"
                        fi
                    elif [ -z "$_pdf_status" ]; then
                        _pdf_status="not-attempted"
                    fi
                    printf '  • %s\n' "$_title"
                    printf '      uuid:   %s\n' "$_uuid"
                    [ "$_ff_have_date"  = "1" ] && [ -n "$_bdate"  ] && \
                        printf '      date:   %s\n' "$_bdate"
                    [ "$_ff_have_flags" = "1" ] && [ -n "$_bflags" ] && \
                        printf '      flags:  %s\n' "$_bflags"
                    printf '      status: %s' "$_pdf_status"
                    if [ "$_pdf_status" = "exported" ] && [ "$_have_pdfs" = "1" ]; then
                        printf '   (%s)' "$_pdf_actual"
                    fi
                    printf '\n'
                done < "$_boards_tsv"
            fi
        } > "$SCRATCH_DIR/ff_inventory.txt" 2>/dev/null \
          || log_warn "Could not build the Freeform board inventory."
    fi
    local _pdf_count=0
    if [ "$_have_pdfs" = "1" ]; then
        _pdf_count=$(find "$_ff_root" -maxdepth 1 -name '*.pdf' -type f -print0 2>/dev/null | tr -dc '\0' | wc -c | tr -d ' ')
        case "$_pdf_count" in ''|*[!0-9]*) _pdf_count=0 ;; esac
    fi
    local _ff_drift_loss=$(( _ff_board_rows - _pdf_count - ${_FF_MIGRATION_LOSS_COUNT:-0} ))
    if [ "$_ff_board_rows" -gt 0 ] && [ "$_ff_drift_loss" -gt 0 ]; then
        report_incomplete "$(_report_subject "$_ff_root")" \
            "$_ff_drift_loss of $_ff_board_rows board PDF(s) did not export" \
            "The per-board PDF export did not cover every board — see the run-log warning(s) for the cause, then re-run. The full board list with per-board status:" \
            "$(cat "$SCRATCH_DIR/ff_inventory.txt" 2>/dev/null)"
    fi
    if [ "$_pdf_count" -gt 0 ]; then
        log_ok "Wrote Freeform/ ($_pdf_count $(_pluralize "$_pdf_count" "board PDF" "board PDFs"), $(_dir_size_human "$_ff_root"))"
    elif [ "$_ff_board_rows" -eq 0 ]; then
        if [ -s "$SCRATCH_DIR/ff_inventory.txt" ]; then
            log_warn "Freeform: no board PDFs produced$(_disclosure_pointer)."
        elif [ "${_FF_ENUM_DEGRADED:-0}" = "1" ]; then
            log_warn "Freeform: could not read the board database (boards.db unreadable or schema-changed) — unable to confirm whether boards exist; none were exported."
            note_incomplete "$_ff_root" "Freeform boards — could not enumerate" \
                "the Freeform board database (boards.db) could not be read (a snapshot failure or a macOS/Freeform schema change) and the fallback carries no board list, so downpour.sh could not determine whether you have boards to export and exported none. If you use Freeform, re-run after a macOS/Freeform update, or report this so the schema probe can be fixed."
        else
            log_info "No Freeform boards found — nothing to export."
            find "$_ff_root" -type d -empty -delete 2>/dev/null || true
        fi
    else
        log_warn "Freeform: no PDFs were produced; Freeform/ left empty"
    fi
    if [ "${#_ff_map_keys[@]}" -gt 0 ]; then
        unset "${_ff_map_keys[@]}"
    fi
    return 0
}

_ff_check_supported_device() {
    local _state_xml="$1"
    grep -q '<key>isSupportedDevice</key>' "$_state_xml" 2>/dev/null || return 0
    if awk '/<key>isSupportedDevice<\/key>/{
                if ($0 ~ /<false *\/>/) exit 0
                if ($0 ~ /<true *\/>/)  exit 1
                getline
                if ($0 ~ /<false *\/>/) exit 0
                exit 1
            }' "$_state_xml" 2>/dev/null
    then
        return 1
    fi
    return 0
}

_ff_enumerate_boards() {
    local _state_xml="$1" _tsv="$2"
    _FF_ENUM_DEGRADED=0
    _FF_TOMBSTONED_N=0
    ensure_scratch
    local _ff_db="$HOME/Library/Group Containers/group.com.apple.freeform/Boards/boards.db"
    if [ -f "$_ff_db" ] && { : < "$_ff_db"; } 2>/dev/null; then
        local _ff_snap
        if _ff_snap="$(snapshot_db "$_ff_db")" && [ -n "$_ff_snap" ]; then
            local _ff_rows _ff_qrc
            _ff_rows="$(sqlite3 -readonly "$_ff_snap" \
                "SELECT lower(hex(board_identifier))
                   FROM boards
                  WHERE COALESCE(tombstoned, 0) = 0
                  ORDER BY last_activity_time DESC, board_identifier;" \
                2>/dev/null)"
            _ff_qrc=$?
            if [ "$_ff_qrc" -eq 0 ]; then
                local _ff_tomb
                _ff_tomb="$(sqlite3 -readonly "$_ff_snap" \
                    "SELECT COUNT(*) FROM boards
                      WHERE COALESCE(tombstoned, 0) != 0;" 2>/dev/null)"
                case "${_ff_tomb:-0}" in
                    ''|*[!0-9]*) : ;;
                    *) _FF_TOMBSTONED_N="$_ff_tomb" ;;
                esac
                printf '%s\n' "$_ff_rows" | awk '
                    {
                        h = $0
                        if (length(h) != 32) next   # not a 16-byte UUID
                        if (h ~ /[^0-9a-f]/) next   # not pure hex
                        uuid = substr(h,1,8) "-" substr(h,9,4) "-" \
                               substr(h,13,4) "-" substr(h,17,4) "-" \
                               substr(h,21,12)
                        print uuid "\t\t\t"
                    }
                ' > "$_tsv" 2>/dev/null
                if [ -s "$_tsv" ]; then
                    return 0
                fi
                : > "$_tsv"
                return 1
            fi
        fi
        _FF_ENUM_DEGRADED=1
    fi
    [ -n "$_state_xml" ] && [ -f "$_state_xml" ] || { : > "$_tsv"; return 1; }
    awk '
        function emit_pending(    f, n, i, sep) {
            if (cur_uuid == "") return
            if (cur_uuid !~ /^[0-9A-Fa-f-]+$/) {
                cur_uuid=""; cur_title=""; cur_date=""; return
            }
            f = ""
            n = split(mem_order, parts, ",")
            for (i = 1; i <= n; i++) {
                if (parts[i] == "") continue
                if (mem[cur_uuid SUBSEP parts[i]]) {
                    f = (f == "") ? parts[i] : f "," parts[i]
                }
            }
            print cur_uuid "\t" cur_title "\t" cur_date "\t" f
            cur_uuid=""; cur_title=""; cur_date=""
        }
        BEGIN {
            mem_order="allBoards,favorites,recents"
            cur_container=""
        }
        /<key>allBoards<\/key>/ { cur_container="allBoards"; next }
        /<key>favorites<\/key>/ { cur_container="favorites"; next }
        /<key>recents<\/key>/   { cur_container="recents";   next }
        /<key>boardUUID<\/key>/ { want_uuid=1; next }
        want_uuid && /<string>/ {
            line=$0
            sub(/.*<string>/, "", line)
            sub(/<\/string>.*/, "", line)
            emit_pending()
            cur_uuid=line
            cur_title=""; cur_date=""
            if (cur_container != "")
                mem[cur_uuid SUBSEP cur_container]=1
            want_uuid=0
            next
        }
        /<key>title<\/key>/ { want_title=1; next }
        want_title && /<string>/ {
            line=$0
            sub(/.*<string>/, "", line)
            sub(/<\/string>.*/, "", line)
            gsub(/[\t\r\n]/, " ", line)
            if (cur_uuid != "" && cur_title == "") cur_title=line
            want_title=0
            next
        }
        /<key>modificationDate<\/key>/ { want_date=1; next }
        /<key>creationDate<\/key>/     { want_date=1; next }
        /<key>lastViewedDate<\/key>/   { want_date=1; next }
        want_date && /<date>/ {
            line=$0
            sub(/.*<date>/, "", line)
            sub(/<\/date>.*/, "", line)
            if (cur_uuid != "" && cur_date == "") cur_date=line
            want_date=0
            next
        }
        want_date { want_date=0 }
        END { emit_pending() }
    ' "$_state_xml" 2>/dev/null \
        | awk -F'\t' '
            {
                u=$1
                if (!(u in seen)) { order[++n]=u; seen[u]=1 }
                if (title[u]=="" && $2!="") title[u]=$2
                if (date[u]=="" && $3!="")  date[u]=$3
                if ($4!="") {
                    k=split($4, fp, ",")
                    for (i=1;i<=k;i++) {
                        if (fp[i]=="") continue
                        if (index(SUBSEP flags[u] SUBSEP, SUBSEP fp[i] SUBSEP)==0)
                            flags[u]=(flags[u]=="")?fp[i]:flags[u]","fp[i]
                    }
                }
            }
            END {
                for (i=1;i<=n;i++) {
                    u=order[i]
                    print u "\t" title[u] "\t" date[u] "\t" flags[u]
                }
            }
        ' > "$_tsv"
    [ -s "$_tsv" ]
}

_ff_smoke_probe() {
    local _probe_uuid="$1"
    open -a Freeform 2>/dev/null
    local _waited=0
    while [ "$_waited" -lt 15 ]; do
        local _wc
        _wc=$(osascript \
            -e 'with timeout of 3 seconds' \
            -e 'tell application "System Events" to tell process "Freeform" to count of windows' \
            -e 'end timeout' 2>/dev/null)
        case "$_wc" in
            ''|*[!0-9]*) : ;;
            *) [ "$_wc" -gt 0 ] && break ;;
        esac
        sleep 1
        _waited=$((_waited + 1))
    done
    open "freeform://board?id=$_probe_uuid" 2>/dev/null
    sleep 3
    local _probe_out _probe_err _probe_rc
    ensure_scratch
    _probe_err="$(mktemp "$SCRATCH_DIR/ff-probe-err.XXXXXX" 2>/dev/null)" || _probe_err=""
    _probe_out=$(FREEFORM_GUI_WAIT_SEC="$FREEFORM_GUI_WAIT_SEC" osascript 2>"${_probe_err:-/dev/null}" <<'APPLESCRIPT'
tell application "Freeform" to activate
delay 0.5
set ffWaitSec to 20
try
    set ffWaitSec to (system attribute "FREEFORM_GUI_WAIT_SEC") as integer
end try
with timeout of ffWaitSec seconds
tell application "System Events"
    tell process "Freeform"
        set winList to {}
        try
            repeat with w in (every window)
                try
                    set end of winList to (name of w)
                end try
            end repeat
        end try
        set winSummary to "windows=" & (count of winList) & ":"
        repeat with wn in winList
            set winSummary to winSummary & " [" & (wn as text) & "]"
        end repeat
        set hasExport to "missing"
        try
            set fileMenu to menu "File" of menu bar 1
            repeat with mi in (every menu item of fileMenu)
                try
                    set _nm to (name of mi) as string
                    if (_nm starts with "Export Board" ¬
                            or _nm starts with "Export" ¬
                            or _nm starts with "Esporta" ¬
                            or _nm starts with "Exporter" ¬
                            or _nm starts with "Exportar" ¬
                            or _nm starts with "Exportieren" ¬
                            or _nm starts with "Exporteren" ¬
                            or _nm starts with "Exportera" ¬
                            or _nm starts with "Eksport" ¬
                            or _nm starts with "Экспорт" ¬
                            or _nm starts with "导出" ¬
                            or _nm starts with "匯出" ¬
                            or _nm starts with "내보내기" ¬
                            or _nm starts with "書き出") then
                        if (enabled of mi) is true then
                            set hasExport to "enabled"
                        else
                            set hasExport to "disabled"
                        end if
                        exit repeat
                    end if
                end try
            end repeat
        end try
        return winSummary & " | export=" & hasExport
    end tell
end tell
end timeout
APPLESCRIPT
)
    _probe_rc=$?
    printf '%s\n' "$_probe_out"
    case "$_probe_out" in
        *"export=enabled"*)  rm -f -- "$_probe_err" 2>/dev/null; return 0 ;;
        *"export=disabled"*) rm -f -- "$_probe_err" 2>/dev/null; return 1 ;;
        *"export=missing"*)  rm -f -- "$_probe_err" 2>/dev/null; return 2 ;;
        *)
            if [ -n "$_probe_err" ] && [ -s "$_probe_err" ]; then
                log_info "Freeform smoke probe stderr: $(head -3 "$_probe_err" 2>/dev/null | tr '\n' ' ')" >&2
            fi
            if [ "$_probe_rc" -ne 0 ]; then
                log_info "Freeform smoke probe osascript exited rc=$_probe_rc" >&2
            fi
            rm -f -- "$_probe_err" 2>/dev/null
            return 3 ;;
    esac
}

_ff_export_one_board() {
    local _uuid="$1" _safe_title="$2" _pdf_staging="$3" _ff_dbg="$4"
    : > "$_ff_dbg" 2>/dev/null || true
    ensure_scratch
    local _board_dir="$_pdf_staging/.board_$_uuid"
    rm -rf -- "$_board_dir" 2>/dev/null
    if ! mkdir -p "$_board_dir" 2>/dev/null; then
        printf 'mkdir failed: %s\n' "$_board_dir" >>"$_ff_dbg" 2>/dev/null
        return 1
    fi
    if [ "${_FREEFORM_PREF_SKIP:-0}" != "1" ]; then
        defaults write com.apple.freeform NSNavLastRootDirectory \
            -string "$_board_dir" 2>/dev/null || true
        _FREEFORM_PREF_WRITTEN=1
        [ -n "${SCRATCH_DIR:-}" ] && : > "$SCRATCH_DIR/freeform_pref_written" 2>/dev/null || true
    fi
    open "freeform://board?id=$_uuid" 2>/dev/null
    sleep 0.3
    local _ff_outer=$(( FREEFORM_GUI_WAIT_SEC + 10 ))
    [ "$_ff_outer" -lt 30 ] && _ff_outer=30
    FREEFORM_TITLE="$_safe_title" \
         FREEFORM_GUI_WAIT_SEC="$FREEFORM_GUI_WAIT_SEC" \
         FREEFORM_OUTER_TIMEOUT="$_ff_outer" \
         osascript >"$_ff_dbg" 2>&1 <<'APPLESCRIPT' &
set fn to system attribute "FREEFORM_TITLE"
if fn is "" then set fn to "Board"

set waitSec to 20
try
    set waitSec to (system attribute "FREEFORM_GUI_WAIT_SEC") as integer
end try
set frontmostSec to waitSec
set menuSec to waitSec
set savePanelSec to waitSec
set dismissSec to waitSec
set outerSec to 120
try
    set outerSec to (system attribute "FREEFORM_OUTER_TIMEOUT") as integer
end try

on freeformRunning()
    tell application "System Events"
        try
            return exists application process "Freeform"
        on error
            return false
        end try
    end tell
end freeformRunning

on findFreeformExportButton(_root)
    tell application "System Events"
        try
            if (class of _root) is button then
                try
                    if (subrole of _root) is "AXDefaultButton" then return _root
                end try
                try
                    set _bn to (name of _root) as string
                    if _bn is "Export" or _bn is "Save" then return _root
                end try
            end if
        end try
        try
            set _kids to UI elements of _root
        on error
            set _kids to {}
        end try
        repeat with _kid in _kids
            set _found to my findFreeformExportButton(_kid)
            if _found is not missing value then return _found
        end repeat
    end tell
    return missing value
end findFreeformExportButton

tell application "Freeform" to activate
delay 0.3

with timeout of outerSec seconds
tell application "System Events"
    tell process "Freeform"
        set _ffmAbsentStreak to 0
        repeat (frontmostSec * 5) times
            if frontmost then exit repeat
            if my freeformRunning() then
                set _ffmAbsentStreak to 0
            else
                set _ffmAbsentStreak to _ffmAbsentStreak + 1
                if _ffmAbsentStreak ≥ 15 then
                    error "Freeform.app is no longer running — was it quit during board navigation?"
                end if
            end if
            delay 0.2
        end repeat

        set exportItem to missing value
        set _ffmenuAbsentStreak to 0
        repeat (menuSec * 4) times
            if my freeformRunning() then
                set _ffmenuAbsentStreak to 0
            else
                set _ffmenuAbsentStreak to _ffmenuAbsentStreak + 1
                if _ffmenuAbsentStreak ≥ 12 then
                    error "Freeform.app is no longer running — was it quit before the Export menu became available?"
                end if
            end if
            try
                set fileMenu to menu "File" of menu bar 1
                repeat with mi in (every menu item of fileMenu)
                    try
                        set _nm to (name of mi) as string
                        if (_nm starts with "Export Board" ¬
                                or _nm starts with "Export" ¬
                                or _nm starts with "Esporta" ¬
                                or _nm starts with "Exporter" ¬
                                or _nm starts with "Exportar" ¬
                                or _nm starts with "Exportieren" ¬
                                or _nm starts with "Exporteren" ¬
                                or _nm starts with "Exportera" ¬
                                or _nm starts with "Eksport" ¬
                                or _nm starts with "Экспорт" ¬
                                or _nm starts with "导出" ¬
                                or _nm starts with "匯出" ¬
                                or _nm starts with "내보내기" ¬
                                or _nm starts with "書き出") then
                            if (enabled of mi) is true then
                                set exportItem to mi
                                exit repeat
                            end if
                        end if
                    end try
                end repeat
            end try
            if exportItem is not missing value then exit repeat
            delay 0.25
        end repeat
        if exportItem is missing value then
            error "Export Board as PDF menu item not enabled within " & menuSec & " s"
        end if

        click exportItem

        set savePanel to missing value
        set saveDescription to ""
        set _ffspAbsentStreak to 0
        repeat (savePanelSec * 5) times
            if my freeformRunning() then
                set _ffspAbsentStreak to 0
            else
                set _ffspAbsentStreak to _ffspAbsentStreak + 1
                if _ffspAbsentStreak ≥ 15 then
                    error "Freeform.app is no longer running — was it quit before the Save panel appeared?"
                end if
            end if
            try
                set wincount to count of windows
                repeat with i from 1 to wincount
                    try
                        set _wname to (name of window i) as text
                        if _wname is "Export as PDF" then
                            set savePanel to window i
                            set saveDescription to "window " & i & " name=\"" & _wname & "\""
                            exit repeat
                        end if
                    end try
                    if savePanel is not missing value then exit repeat
                end repeat
            end try
            if savePanel is not missing value then exit repeat
            try
                if exists sheet 1 of window 1 then
                    set savePanel to sheet 1 of window 1
                    set saveDescription to "sheet 1 of window 1"
                    exit repeat
                end if
            end try
            try
                set wincount to count of windows
                repeat with i from 1 to wincount
                    try
                        if exists sheet 1 of window i then
                            set savePanel to sheet 1 of window i
                            set saveDescription to "sheet 1 of window " & i
                            exit repeat
                        end if
                    end try
                    if savePanel is not missing value then exit repeat
                end repeat
            end try
            if savePanel is not missing value then exit repeat
            try
                set wincount to count of windows
                repeat with i from 1 to wincount
                    try
                        set w to window i
                        set _subrole to ""
                        try
                            set _subrole to (subrole of w) as text
                        end try
                        if _subrole is "AXDialog" or _subrole is "AXSystemDialog" then
                            set savePanel to w
                            set saveDescription to "window " & i & " (subrole=" & _subrole & ")"
                            exit repeat
                        end if
                    end try
                    if savePanel is not missing value then exit repeat
                end repeat
            end try
            if savePanel is not missing value then exit repeat
            delay 0.2
        end repeat
        if savePanel is missing value then
            set ffDiag to ""
            try
                set wincount to count of windows
                repeat with i from 1 to wincount
                    try
                        set _wname to ""
                        set _wsub to ""
                        try
                            set _wname to (name of window i) as text
                        end try
                        try
                            set _wsub to (subrole of window i) as text
                        end try
                        if ffDiag is not "" then set ffDiag to ffDiag & ", "
                        set ffDiag to ffDiag & "[" & i & "] " & _wname & "(" & _wsub & ")"
                    end try
                end repeat
            end try
            if ffDiag is "" then set ffDiag to "(no windows visible in Freeform process)"
            error "Save sheet did not appear within " & savePanelSec & " s. Freeform windows: " & ffDiag
        end if
        log "Save panel found at: " & saveDescription

        try
            set value of text field 1 of savePanel to fn
        end try
        delay 0.3

        set _ffSubmitDone to false
        set _ffWin to "none"
        try
            tell application "Freeform" to activate
        end try
        try
            perform action "AXRaise" of savePanel
        end try
        try
            set _ffBtn to my findFreeformExportButton(savePanel)
            if _ffBtn is not missing value then
                perform action "AXPress" of _ffBtn
                set _ffWin to "ax-press"
            end if
        end try
        if _ffWin is "ax-press" then
            repeat 30 times
                delay 0.1
                set _stillPanel to false
                try
                    repeat with _w in windows
                        if (name of _w) as text is "Export as PDF" then
                            set _stillPanel to true
                            exit repeat
                        end if
                    end repeat
                end try
                if not _stillPanel then
                    set _ffSubmitDone to true
                    exit repeat
                end if
            end repeat
        end if
        repeat with _si from 1 to 5
            if _ffSubmitDone then exit repeat
            try
                if _si is 1 then
                    try
                        set focused of savePanel to true
                    end try
                    delay 0.2
                    key code 36
                else if _si is 2 then
                    key code 76
                else if _si is 3 then
                    keystroke return
                else if _si is 4 then
                    key code 36
                else
                    set _pPos to position of savePanel
                    set _pSize to size of savePanel
                    click at {(item 1 of _pPos) + (item 1 of _pSize) - 55, (item 2 of _pPos) + (item 2 of _pSize) - 28}
                end if
            end try
            set _ffSubmitDone to false
            repeat 15 times
                delay 0.1
                set _stillPanel to false
                try
                    repeat with _w in windows
                        if (name of _w) as text is "Export as PDF" then
                            set _stillPanel to true
                            exit repeat
                        end if
                    end repeat
                end try
                if not _stillPanel then
                    set _ffSubmitDone to true
                    if _ffWin is "none" then set _ffWin to ("kbd-strategy-" & _si)
                    exit repeat
                end if
            end repeat
        end repeat
        try
            log "Freeform export submit: winner=" & _ffWin
        end try
        set _stillUp to false
        try
            repeat with _w in windows
                if (name of _w) as text is "Export as PDF" then
                    set _stillUp to true
                    exit repeat
                end if
            end repeat
        end try
        if _stillUp then
            set elemDump to ""
            set _elemCount to 0
            try
                repeat with e in (entire contents of savePanel)
                    try
                        set _eRole to ""
                        set _eName to ""
                        set _eDesc to ""
                        try
                            set _eRole to (role of e) as text
                        end try
                        try
                            set _eName to (name of e) as text
                        end try
                        try
                            set _eDesc to (description of e) as text
                        end try
                        if elemDump is not "" then set elemDump to elemDump & "; "
                        set elemDump to elemDump & _eRole & " name=\"" & _eName & "\" desc=\"" & _eDesc & "\""
                        set _elemCount to _elemCount + 1
                        if _elemCount > 30 then
                            set elemDump to elemDump & " ... (truncated)"
                            exit repeat
                        end if
                    end try
                end repeat
            end try
            if elemDump is "" then set elemDump to "(entire contents of savePanel returned no elements)"
            error "Return key didn't dismiss the Save panel. Panel contents: " & elemDump
        end if

        set _ffdmAbsentStreak to 0
        repeat (dismissSec * 5) times
            if my freeformRunning() then
                set _ffdmAbsentStreak to 0
            else
                set _ffdmAbsentStreak to _ffdmAbsentStreak + 1
                if _ffdmAbsentStreak ≥ 15 then
                    error "Freeform.app is no longer running — was it quit during the file save?"
                end if
            end if
            try
                set _stillThere to false
                set wincount to count of windows
                repeat with i from 1 to wincount
                    try
                        if exists sheet 1 of window i then
                            set _stillThere to true
                            exit repeat
                        end if
                    end try
                end repeat
                if not _stillThere then
                    repeat with i from 1 to wincount
                        try
                            if (name of window i) as text is "Export as PDF" then
                                set _stillThere to true
                                exit repeat
                            end if
                        end try
                    end repeat
                end if
                if not _stillThere then exit repeat
            end try
            delay 0.2
        end repeat
    end tell
end tell
end timeout
APPLESCRIPT
    local _ff_pid=$!
    CHILD_PIDS+=( "$_ff_pid" )
    local _ff_cap=$(( _ff_outer + 5 ))
    ( _ff_e=0
      while kill -0 "$_ff_pid" 2>/dev/null; do
          if [ "$_ff_e" -ge "$_ff_cap" ]; then
              kill -KILL "$_ff_pid" 2>/dev/null
              break
          fi
          sleep 1
          _ff_e=$(( _ff_e + 1 ))
      done ) &
    local _ff_wd=$!
    wait "$_ff_pid" 2>/dev/null; local _ff_rc=$?
    wait "$_ff_wd" 2>/dev/null
    local _cp _ff_newcp=()
    for _cp in "${CHILD_PIDS[@]+"${CHILD_PIDS[@]}"}"; do
        [ "$_cp" = "$_ff_pid" ] || _ff_newcp+=( "$_cp" )
    done
    CHILD_PIDS=( "${_ff_newcp[@]+"${_ff_newcp[@]}"}" )
    if [ "$_ff_rc" -ne 0 ]; then
        rm -rf -- "$_board_dir" 2>/dev/null
        return 1
    fi
    local _src_pdf
    if ! IFS= read -r -d '' _src_pdf < <(find "$_board_dir" -maxdepth 1 -name '*.pdf' -type f -print0 -quit 2>/dev/null); then
        _src_pdf=""
    fi
    if [ -z "$_src_pdf" ] || [ ! -f "$_src_pdf" ]; then
        rmdir "$_board_dir" 2>/dev/null || rm -rf -- "$_board_dir" 2>/dev/null
        return 2
    fi
    local _new_pdf _target
    _target="$_pdf_staging/${_safe_title}.pdf"
    _target="$(_unique_path "$_target" 2>/dev/null || printf '%s' "$_target")"
    if ! mv -f -- "$_src_pdf" "$_target" 2>/dev/null; then
        printf 'mv failed: %s -> %s\n' "$_src_pdf" "$_target" >>"$_ff_dbg" 2>/dev/null
        rm -rf -- "$_board_dir" 2>/dev/null
        return 1
    fi
    _new_pdf="${_target##*/}"
    rmdir "$_board_dir" 2>/dev/null || rm -rf -- "$_board_dir" 2>/dev/null
    printf '%s\n' "$_new_pdf"
    return 0
}

_ff_set_pdf_status() {
    local _map="$1" _uuid="$2" _pdf="$3" _status="$4"
    printf '%s\t%s\t%s\n' "$_uuid" "$_pdf" "$_status" >> "$_map" 2>/dev/null
}

_ff_finalize_pdf_status() {
    local _map="$1"
    [ -f "$_map" ] || return 0
    local _tmp="${_map}.final.tmp"
    awk -F'\t' '
        { last[$1] = $0; if (!($1 in order)) order[++n] = $1 }
        END { for (i = 1; i <= n; i++) print last[order[i]] }
    ' "$_map" > "$_tmp" 2>/dev/null && mv -f -- "$_tmp" "$_map" 2>/dev/null
}

_ff_osascript_watchdog() {
    local _wd_cap="${1:-8}"
    ensure_scratch
    local _wd_out="$SCRATCH_DIR/ff-wd-osascript.$$.out"
    : > "$_wd_out" 2>/dev/null || true
    osascript >"$_wd_out" 2>/dev/null &
    local _wd_pid=$!
    ( _wd_e=0
      while kill -0 "$_wd_pid" 2>/dev/null; do
          if [ "$_wd_e" -ge "$_wd_cap" ]; then
              kill -KILL "$_wd_pid" 2>/dev/null
              break
          fi
          sleep 1
          _wd_e=$(( _wd_e + 1 ))
      done ) &
    local _wd_wd=$!
    wait "$_wd_pid" 2>/dev/null
    wait "$_wd_wd" 2>/dev/null
    cat "$_wd_out" 2>/dev/null
    rm -f "$_wd_out" 2>/dev/null || true
}

_freeform_export_pdfs() {
    local _ff_root="$1"
    _FF_MIGRATION_LOSS_COUNT=0
    local _snap="$HOME/Library/Group Containers/group.com.apple.freeform/Snapshot.plist"
    local _ff_db="$HOME/Library/Group Containers/group.com.apple.freeform/Boards/boards.db"
    if [ ! -f "$_ff_db" ] && [ ! -f "$_snap" ]; then
        return 0
    fi
    require_accessibility || {
        _untrack_output_path "$_ff_root"
        ensure_scratch
        note_incomplete "$_ff_root" "Freeform" \
            "Accessibility permission was not granted — the per-board PDF export drives Freeform.app via System Events; grant it in System Settings > Privacy & Security > Accessibility, then re-run"
        mark_success
        print_summary
        exit 0
    }
    if [ "${FREEFORM_FORCE_DRIVE:-0}" = "1" ]; then
        log_info "FREEFORM_FORCE_DRIVE=1 — driving Freeform regardless of window-count probe."
        if pgrep -x Freeform >/dev/null 2>&1; then
            log_info "  Freeform.app was already running — leaving it open on cleanup (won't quit a session we didn't launch)."
            _FREEFORM_LAUNCHED_BY_US=0
        else
            _FREEFORM_LAUNCHED_BY_US=1
        fi
    elif pgrep -x Freeform >/dev/null 2>&1; then
        local _ff_win_count
        _ff_win_count=$(_ff_osascript_watchdog 8 <<'APPLESCRIPT'
with timeout of 5 seconds
    tell application "System Events"
        if (exists process "Freeform") then
            return (count of windows of process "Freeform")
        else
            return -2
        end if
    end tell
end timeout
APPLESCRIPT
)
        case "$_ff_win_count" in
            -2) : ;;
            ''|*[!0-9]*) _ff_win_count="?" ;;
        esac
        if [ "$_ff_win_count" = "0" ]; then
            log_info "Freeform.app process is running with no visible windows — proceeding (will quit on cleanup)"
            _FREEFORM_LAUNCHED_BY_US=1
        elif [ "$_ff_win_count" = "-2" ]; then
            log_info "Freeform.app is no longer running (process exited between the pgrep and window-count checks) — proceeding."
            _FREEFORM_LAUNCHED_BY_US=1
        elif [ "$_ff_win_count" = "?" ]; then
            log_warn "Freeform.app is running and the window-count probe failed — skipping PDF export."
            log_info "  If Freeform.app is NOT actually open on your screen:"
            log_info "  • run \`pgrep -lx Freeform\` to identify the lingering process"
            log_info "  • set \`FREEFORM_FORCE_DRIVE=1\` and re-run to override this guard"
            return 0
        else
            log_warn "Freeform.app has $_ff_win_count visible window(s) — skipping PDF export to preserve your session."
            log_info "  Quit Freeform.app (Cmd+Q) and re-run if you want per-board PDFs in this export"
            return 0
        fi
    else
        _FREEFORM_LAUNCHED_BY_US=1
    fi
    ensure_scratch
    local _snap_xml=""
    if [ -f "$_snap" ]; then
        _snap_xml="$SCRATCH_DIR/ff-snapshot.xml"
        plutil -convert xml1 -o "$_snap_xml" "$_snap" 2>/dev/null || _snap_xml=""
    fi
    if [ -n "$_snap_xml" ] && ! _ff_check_supported_device "$_snap_xml"; then
        log_info "Freeform marks this Mac as isSupportedDevice=false in Snapshot.plist — trying the export anyway."
        log_info "  This is an advisory flag from Apple, not a functional check"
        log_info "  Freeform may still render boards on this machine; the smoke probe below is the real test"
        : > "$SCRATCH_DIR/ff-unsupported-device" 2>/dev/null || true
    fi
    local _boards_tsv="$SCRATCH_DIR/ff-boards.tsv"
    if ! _ff_enumerate_boards "$_snap_xml" "$_boards_tsv"; then
        log_info "Freeform PDF export: no boards found in boards.db — nothing to render."
        return 0
    fi
    local _board_total
    _board_total="$(_ff_count_board_rows "$_boards_tsv")"
    local _pdf_staging="$SCRATCH_DIR/freeform-pdfs"
    mkdir -p "$_pdf_staging" || {
        log_warn "Cannot create PDF staging dir — skipping PDF export."
        return 0
    }
    _save_defaults_pref _FREEFORM com.apple.freeform NSNavLastRootDirectory "$_pdf_staging"
    _ax_os_check "Freeform PDF export"
    log_info "Freeform: exporting $_board_total $(_pluralize "$_board_total" board) to PDF via Freeform.app (app window may appear briefly; up to ~30 s per board worst case)..."
    local _ff_dbg="${SCRATCH_DIR}/ff-osascript.out"
    local _ff_pdf_map="$SCRATCH_DIR/ff-pdf-map.tsv"
    awk -F'\t' '$1!="" {print $1 "\t\tnot-attempted"}' "$_boards_tsv" > "$_ff_pdf_map" 2>/dev/null || : > "$_ff_pdf_map"
    local _probe_uuid _probe_out _probe_rc
    _probe_uuid=$(awk -F'\t' '$1 != "" {print $1; exit}' "$_boards_tsv")
    if [ -z "$_probe_uuid" ]; then
        log_warn "Freeform PDF export aborted — could not read a valid list of boards"
        _restore_freeform_pref
        return 0
    fi
    _probe_out=$(_ff_smoke_probe "$_probe_uuid")
    _probe_rc=$?
    [ -n "${DEBUG_APPLESCRIPT:-}${DOWNPOUR_DEBUG_FREEFORM:-}${DOWNPOUR_PROBE_UI:-}" ] && log_info "Freeform probe: $_probe_out"
    case "$_probe_rc" in
        0) ;;  # enabled — proceed with the loop
        1)
            log_warn "Freeform PDF export aborted — Export Board as PDF is disabled (URL scheme opened the app but didn't load a board)"
            log_warn "  Probable cause: board(s) not yet synced from iCloud, or Freeform's first-run welcome panel is blocking"
            log_info "  Quit Freeform, open it manually once (dismissing any onboarding/welcome screens), then re-run"
            quit_app_iff_we_launched_it Freeform _FREEFORM_LAUNCHED_BY_US
            _restore_freeform_pref
            return 0
            ;;
        2)
            local _ff_ver
            _ff_ver=$(mdls -name kMDItemVersion /System/Applications/Freeform.app 2>/dev/null | awk -F'= ' '{print $2}')
            _ff_ver="${_ff_ver%\"}"; _ff_ver="${_ff_ver#\"}"
            case "$_ff_ver" in ''|'(null)') _ff_ver="(unknown)" ;; esac
            log_warn "Freeform PDF export aborted — Export Board as PDF menu item not found."
            log_warn "  Probable cause: Freeform.app version $_ff_ver uses a menu label not covered by this probe (the app may have renamed or newly localized the export command)"
            log_info "  Probe result: $_probe_out"
            quit_app_iff_we_launched_it Freeform _FREEFORM_LAUNCHED_BY_US
            _restore_freeform_pref
            return 0
            ;;
        *)
            log_warn "Freeform PDF export aborted — unrecognised smoke probe output."
            log_warn "  Probe output: $_probe_out"
            quit_app_iff_we_launched_it Freeform _FREEFORM_LAUNCHED_BY_US
            _restore_freeform_pref
            return 0
            ;;
    esac
    local _success_count=0 _fail_count=0
    local _uuid _title _safe_title _new_pdf _idx=0 _rc
    local _ut_n _ff_extra _ffseen_keys=()
    while IFS=$'\t' read -r _uuid _title _ff_extra; do
        [ -n "$_uuid" ] || continue
        _idx=$((_idx + 1))
        [ -n "$_title" ] || _title="Board $_idx"
        _safe_title=$(_sanitize_name "$_title" 2>/dev/null || printf 'Board')
        [ -n "$_safe_title" ] || _safe_title="Board"
        local _ff_key _ff_seen
        _var_key_into "$_safe_title" _ff_key
        _ff_seen="_ffseen_$_ff_key"
        if [ -n "${!_ff_seen:-}" ]; then
            _ut_n=2
            local _capped=0 _ff_probe
            _var_key_into "$_safe_title $_ut_n" _ff_key
            _ff_probe="_ffseen_$_ff_key"
            while [ -n "${!_ff_probe:-}" ]; do
                _ut_n=$((_ut_n + 1))
                if [ "$_ut_n" -gt 9999 ]; then
                    _capped=1
                    break
                fi
                _var_key_into "$_safe_title $_ut_n" _ff_key
                _ff_probe="_ffseen_$_ff_key"
            done
            if [ "$_capped" -eq 1 ]; then
                _safe_title="$_safe_title ${_idx}-$(printf '%s' "$_uuid" | head -c 8)"
                log_warn "Freeform title-collision counter exceeded 9999 for '$_safe_title'; falling back to index+UUID suffix."
            else
                _safe_title="$_safe_title $_ut_n"
            fi
        fi
        _var_key_into "$_safe_title" _ff_key
        local _ff_seen_final="_ffseen_$_ff_key"
        printf -v "$_ff_seen_final" '%s' 1
        _ffseen_keys+=( "$_ff_seen_final" )
        log_info "Freeform PDF $_idx/$_board_total: $_title"
        _new_pdf=$(_ff_export_one_board "$_uuid" "$_safe_title" "$_pdf_staging" "$_ff_dbg")
        _rc=$?
        if [ "$_rc" != "0" ] && pgrep -x Freeform >/dev/null 2>&1; then
            log_info "Freeform PDF $_idx/$_board_total: retrying \"$_title\" (first attempt rc=$_rc — transient GUI failure, e.g. focus lost)"
            osascript -e 'with timeout of 5 seconds' \
                      -e 'tell application "Freeform" to activate' \
                      -e 'end timeout' >/dev/null 2>&1 || true
            _new_pdf=$(_ff_export_one_board "$_uuid" "$_safe_title" "$_pdf_staging" "$_ff_dbg")
            _rc=$?
        fi
        if [ "$_rc" = "0" ]; then
            _success_count=$((_success_count + 1))
            local _ff_stage_pdf _ff_final_pdf
            _ff_stage_pdf="$_pdf_staging/$_new_pdf"
            _ff_final_pdf="$(_unique_path "$_ff_root/$_new_pdf")"
            if [ -f "$_ff_stage_pdf" ] && mv -n -- "$_ff_stage_pdf" "$_ff_final_pdf" 2>/dev/null; then
                _ff_set_pdf_status "$_ff_pdf_map" "$_uuid" "${_ff_final_pdf##*/}" "exported"
            else
                _ff_set_pdf_status "$_ff_pdf_map" "$_uuid" "$_new_pdf" "exported"
            fi
            [ -n "${DOWNPOUR_DEBUG_FREEFORM:-}${DOWNPOUR_PROBE_UI:-}" ] && [ -s "$_ff_dbg" ] && \
                log_info "  [debug] osascript: $(tr '\n' '|' < "$_ff_dbg" 2>/dev/null)"
        elif [ "$_rc" = "2" ]; then
            _fail_count=$((_fail_count + 1))
            _ff_set_pdf_status "$_ff_pdf_map" "$_uuid" "" "export-failed"
            log_warn "Freeform: board \"$_title\" — Save click succeeded but no new PDF in staging."
            [ -s "$_ff_dbg" ] && log_warn "  osascript said: $(head -3 "$_ff_dbg" 2>/dev/null | tr '\n' ' ')"
        else
            _fail_count=$((_fail_count + 1))
            _ff_set_pdf_status "$_ff_pdf_map" "$_uuid" "" "export-failed"
            log_warn "Freeform: board \"$_title\" — AppleScript export failed (rc=$_rc)"
            if [ -s "$_ff_dbg" ]; then
                local _err_line
                while IFS= read -r _err_line; do
                    [ -n "$_err_line" ] && log_warn "  $_err_line"
                done < <(head -5 "$_ff_dbg" 2>/dev/null)
            fi
        fi
        local _cmdw_safe
        _cmdw_safe=$(_ff_osascript_watchdog 8 <<'APPLESCRIPT'
with timeout of 5 seconds
    tell application "System Events"
        tell process "Freeform"
            try
                if (count of windows) = 0 then return "no"
                if exists sheet 1 of window 1 then return "no"
                set wname to name of window 1
                if wname is "Freeform" or wname is "" then return "no"
                return "yes"
            end try
            return "no"
        end tell
    end tell
end timeout
APPLESCRIPT
)
        [ "$_cmdw_safe" = "yes" ] || _cmdw_safe="no"
        if ! pgrep -x Freeform >/dev/null 2>&1; then
            log_warn "Freeform.app is no longer running — stopping the per-board loop early. $((_board_total - _idx)) board(s) not attempted."
            break
        fi
        if [ "$_cmdw_safe" = "yes" ]; then
            osascript \
                -e 'with timeout of 3 seconds' \
                -e 'tell application "Freeform" to activate' \
                -e 'delay 0.05' \
                -e 'tell application "System Events"' \
                -e '  tell process "Freeform"' \
                -e '    if frontmost then keystroke "w" using {command down}' \
                -e '  end tell' \
                -e 'end tell' \
                -e 'end timeout' >/dev/null 2>&1 || true
        fi
        sleep 0.4
    done < "$_boards_tsv"
    _ff_finalize_pdf_status "$_ff_pdf_map"
    if [ "$_success_count" -gt 0 ]; then
        local _mv_fails=0 _mv_renamed=0 _pdf _stage_base
        while IFS= read -r -d '' _pdf; do
            _stage_base="$(basename "$_pdf")"
            if [ -f "$_ff_root/$_stage_base" ]; then
                local _alt_dst _alt_base _muuid
                _alt_dst="$(_unique_path "$_ff_root/$_stage_base")"
                _alt_base="$(basename "$_alt_dst")"
                if ! mv -n -- "$_pdf" "$_alt_dst" 2>/dev/null; then
                    _mv_fails=$((_mv_fails + 1))
                    log_warn "Failed to move Freeform PDF $_stage_base (destination collision unresolved)."
                else
                    _mv_renamed=$((_mv_renamed + 1))
                    log_info "Freeform PDF renamed on migration: $_stage_base → $_alt_base"
                    _muuid="$(awk -F'\t' -v s="$_stage_base" '$2==s && $3=="exported" {print $1; exit}' "$_ff_pdf_map" 2>/dev/null)"
                    if [ -n "$_muuid" ]; then
                        _ff_set_pdf_status "$_ff_pdf_map" "$_muuid" "$_alt_base" "exported"
                    fi
                fi
            elif ! mv -n -- "$_pdf" "$_ff_root/" 2>/dev/null; then
                _mv_fails=$((_mv_fails + 1))
                log_warn "Failed to move Freeform PDF $_stage_base to $_ff_root/ (destination volume full or permission denied)."
            fi
        done < <(find "$_pdf_staging" -maxdepth 1 -name '*.pdf' -type f -print0 2>/dev/null)
        [ "$_mv_renamed" -gt 0 ] && _ff_finalize_pdf_status "$_ff_pdf_map"
        if [ "$_mv_renamed" -gt 0 ]; then
            log_info "Freeform PDF migration: $_mv_renamed $(_pluralize "$_mv_renamed" file) renamed at destination to avoid collision."
        fi
        if [ "$_mv_fails" -gt 0 ]; then
            note_incomplete "$_ff_root" "Freeform PDF migration" \
                "$_mv_fails Freeform PDF(s) were generated successfully but could not be moved from scratch into the export — the destination volume may be full, or permissions may have changed mid-run; the affected boards are missing from the export"
            _FF_MIGRATION_LOSS_COUNT=$_mv_fails
            _success_count=$((_success_count - _mv_fails))
            [ "$_success_count" -lt 0 ] && _success_count=0
            _fail_count=$((_fail_count + _mv_fails))
        fi
    fi
    if [ "$_success_count" -eq "$_board_total" ] && [ "$_board_total" -gt 0 ]; then
        log_info "Freeform PDFs: $_success_count of $_board_total $(_pluralize "$_board_total" board) exported"
    elif [ "$_success_count" -gt 0 ] && [ "$_fail_count" -gt 0 ]; then
        log_warn "Freeform PDFs: $_success_count of $_board_total $(_pluralize "$_board_total" board) exported; $_fail_count failed (uncovered boards have no fallback representation — re-run after fixing the cause)"
    elif [ "$_success_count" -gt 0 ] && [ "$_success_count" -lt "$_board_total" ] && [ "$_fail_count" -eq 0 ]; then
        log_warn "Freeform PDFs: $_success_count of $_board_total $(_pluralize "$_board_total" board) exported; $((_board_total - _success_count)) uncovered (enumeration produced unprocessable rows — those boards have no representation in the export)"
    elif [ "$_success_count" -eq 0 ] && [ "$_board_total" -gt 0 ]; then
        log_warn "Freeform PDFs: 0 of $_board_total $(_pluralize "$_board_total" board) exported — no PDF output produced."
    fi
    if [ "${#_ffseen_keys[@]}" -gt 0 ]; then
        unset "${_ffseen_keys[@]}"
    fi
    return 0
}

freeform_main() {
    maybe_show_help "$@"
    _announce_step "Freeform export"
    check_dependencies
    local out_arg out_dir
    out_arg="$(_parse_output_folder_arg "$@")" || exit 1
    out_dir="$(resolve_output_dir "$out_arg")" || exit 1
    _announce_output_dir "Freeform"
    require_full_disk_access
    export_freeform "$out_dir"
    mark_success
    sweep_junk_files "$out_dir"
    quit_app_iff_we_launched_it Freeform _FREEFORM_LAUNCHED_BY_US
    print_summary
    if [ "$ERR_COUNT" -gt 0 ]; then exit 1; fi
    exit 0
}

ICLOUD_ROOT="$HOME/Library/Mobile Documents"

_icloud_friendly() {
    local basename="$1" friendly=""
    case "$basename" in
        [A-Z0-9][A-Z0-9][A-Z0-9][A-Z0-9][A-Z0-9][A-Z0-9][A-Z0-9][A-Z0-9][A-Z0-9][A-Z0-9]~*)
            basename="${basename#*~}" ;;
    esac
    local _ver_suffix=""
    case "$basename" in
        *~[0-9]|*~[0-9][0-9]|*~[0-9][0-9][0-9])
            _ver_suffix="${basename##*~}"
            basename="${basename%~*}" ;;
    esac
    case "$basename" in
        com~apple~*)        friendly="${basename#com~apple~}" ;;
        ~com~apple~*)       friendly="${basename#~com~apple~}" ;;
        iCloud~*~*)         friendly="${basename##*~}" ;;
        iCloud~*)           friendly="${basename#iCloud~}" ;;
        com~*~*)            friendly="${basename##*~}" ;;
        ~com~*~*)           friendly="${basename##*~}" ;;
        *~*~*~*)            friendly="${basename##*~}" ;;
    esac
    case "$friendly" in
        *~Documents)      friendly="${friendly%~Documents}" ;;
        *~Library)        friendly="${friendly%~Library}" ;;
        *~Data)           friendly="${friendly%~Data}" ;;
        *~CloudDocuments) friendly="${friendly%~CloudDocuments}" ;;
        *~Shared)         friendly="${friendly%~Shared}" ;;
    esac
    if [ -z "$friendly" ] || [ "$friendly" = "$basename" ]; then
        return 1
    fi
    [ -n "$_ver_suffix" ] && friendly="${friendly}_${_ver_suffix}"
    printf '%s' "$friendly"
}

_is_clouddocs_container() {
    case "$1" in
        com~apple~CloudDocs|~com~apple~CloudDocs|iCloud~com~apple~CloudDocs)
            return 0 ;;
    esac
    return 1
}

_DRIVE_STUBS_FILE=""
_DRIVE_PERM_DENIED_FILE=""
_DRIVE_MAT_FAIL_FILE=""
_DRIVE_SYMLINK_FILE=""
_ICD_DEREF_PATH=""
_ICD_ALLOW_DOTFILES=0

_icd_target_in_scope() {
    local _p="$1"
    if [ -z "${_ICD_SCOPE_ROOT:-}" ]; then
        _ICD_SCOPE_ROOT="$(readlink -f -- "$ICLOUD_ROOT" 2>/dev/null \
            || realpath -- "$ICLOUD_ROOT" 2>/dev/null || printf '%s' "$ICLOUD_ROOT")"
    fi
    case "$_p/" in
        "$_ICD_SCOPE_ROOT"/*) return 0 ;;
    esac
    return 1
}

_icd_should_skip_copy() {
    local _f="$1" _rel="${2:-$1}" _friendly="${3:-?}"
    _ICD_DEREF_PATH=""
    if [ -L "$_f" ]; then
        if [ -f "$_f" ]; then
            local _real
            _real="$(readlink -f -- "$_f" 2>/dev/null || realpath -- "$_f" 2>/dev/null)"
            if [ -n "$_real" ] && [ -f "$_real" ]; then
                if ! _icd_target_in_scope "$_real"; then
                    if [ -n "$_DRIVE_SYMLINK_FILE" ]; then
                        printf '%s\t%s\n' "$(tsv_escape "$_friendly")" \
                            "$(tsv_escape "$_rel  ->  $_real (target outside iCloud Drive — not copied)")" \
                            >> "$_DRIVE_SYMLINK_FILE"
                    fi
                    return 0
                fi
                _ICD_DEREF_PATH="$_real"
                _DRIVE_SYMLINK_DEREF=$((${_DRIVE_SYMLINK_DEREF:-0} + 1))
                return 1
            fi
        fi
        if [ -n "$_DRIVE_SYMLINK_FILE" ]; then
            printf '%s\t%s\n' "$(tsv_escape "$_friendly")" \
                "$(tsv_escape "$_rel")" >> "$_DRIVE_SYMLINK_FILE"
        fi
        return 0
    fi
    should_skip_copy "$_f" "$_rel"
}

_copy_tree_skip_placeholders() {
    local src="$1" dst="$2" friendly="${3:-}"
    local placeholder_count=0 copied=0
    local _enum_n=0 _fail_n=0 _other_n=0
    _DRIVE_COPY_N=0
    if [ -z "${SCRATCH_DIR:-}" ]; then
        log_warn "_copy_tree_skip_placeholders called before SCRATCH_DIR was initialized — skipped-items accounting (stubs, perm-denied, dataless) will be lost. This is a refactor bug; please report."
    fi
    mkdir -p "$dst" || { log_warn "Cannot create $dst"; return 1; }
    local _find_err=""
    if [ -n "${SCRATCH_DIR:-}" ]; then
        _find_err="$SCRATCH_DIR/icloud_find_err.$$.$RANDOM"
        : > "$_find_err" 2>/dev/null || _find_err=""
    fi
    local _pt_last=0 _pt_inline=0
    local f rel target tdir _err _orig _cp_rc
    local _statout _src_size _src_flags _was_dataless
    local _icd_scope_last_par="" _icd_scope_par_real="" _icd_scope_par_ok=1 _icd_par
    local _icd_scope_escape_root=""
    while IFS= read -r -d '' f; do
        _enum_n=$((_enum_n + 1))
        rel="${f#"$src"/}"
        _icd_par="${f%/*}"
        if [ "$_icd_par" != "$_icd_scope_last_par" ]; then
            _icd_scope_last_par="$_icd_par"
            _icd_scope_par_real="$(readlink -f -- "$_icd_par" 2>/dev/null || realpath -- "$_icd_par" 2>/dev/null)"
            if [ -z "$_icd_scope_par_real" ]; then
                _icd_scope_par_ok=1
            elif _icd_target_in_scope "$_icd_scope_par_real"; then
                _icd_scope_par_ok=1
            else
                _icd_scope_par_ok=0
                local _icd_link_new=1
                if [ -n "$_icd_scope_escape_root" ]; then
                    case "$_icd_scope_par_real/" in
                        "$_icd_scope_escape_root"/*) _icd_link_new=0 ;;
                    esac
                fi
                if [ "$_icd_link_new" -eq 1 ]; then
                    _icd_scope_escape_root="$_icd_scope_par_real"
                    if [ -n "$_DRIVE_SYMLINK_FILE" ]; then
                        printf '%s\t%s\n' "$(tsv_escape "${friendly:-?}")" \
                            "$(tsv_escape "${rel%/*}  ->  $_icd_scope_par_real (reached through a symlinked folder whose target is outside iCloud Drive — not copied)")" \
                            >> "$_DRIVE_SYMLINK_FILE"
                    fi
                fi
            fi
        fi
        [ "$_icd_scope_par_ok" -eq 0 ] && { _other_n=$((_other_n + 1)); continue; }
        if is_icloud_stub "$f"; then
            placeholder_count=$((placeholder_count + 1))
            _record_icloud_stub "$_DRIVE_STUBS_FILE" "${friendly:-?}" "$rel"
            continue
        fi
        if [ "$_ICD_ALLOW_DOTFILES" != "1" ]; then
            case "$rel" in
                .*|*/.*) _other_n=$((_other_n + 1)); continue ;;
            esac
        fi
        _icd_should_skip_copy "$f" "$rel" "${friendly:-?}" && \
            { _other_n=$((_other_n + 1)); continue; }
        [ -n "$_ICD_DEREF_PATH" ] && f="$_ICD_DEREF_PATH"
        target="$dst/$rel"
        case "$rel" in
            */*) tdir="${dst}/${rel%/*}" ;;
            *)   tdir="$dst" ;;
        esac
        [ -d "$tdir" ] || mkdir -p "$tdir" 2>/dev/null
        _statout="$(stat -f '%z %f' -- "$f" 2>/dev/null)"
        _src_size="${_statout%% *}"
        _src_flags="${_statout##* }"
        _was_dataless=0
        case "$_src_flags" in
            ''|*[!0-9]*) ;;
            *) [ "$(( 10#$_src_flags & 1073741824 ))" -ne 0 ] && _was_dataless=1 ;;
        esac
        _err="$(_ditto_dl_retry "$f" "$target" "$_was_dataless")"; _cp_rc=$?
        if [ "$_cp_rc" -ne 0 ]; then
            _fail_n=$((_fail_n + 1))
            rm -f -- "$target" 2>/dev/null
            case "$_err" in
                *"Permission denied"*|*"Operation not permitted"*)
                    [ -n "$_DRIVE_PERM_DENIED_FILE" ] && \
                        printf '%s\n' "$src/$rel" >> "$_DRIVE_PERM_DENIED_FILE" ;;
                *)
                    if [ "$_was_dataless" = "1" ]; then
                        if [ -n "$_DRIVE_MAT_FAIL_FILE" ]; then
                            printf 'download-failed\t%s\n' \
                                "$(tsv_escape "${friendly:+$friendly/}$rel")" \
                                >> "$_DRIVE_MAT_FAIL_FILE"
                        else
                            log_warn "iCloud download failed: $rel"
                            note_incomplete "${root_out:-}" "$rel" \
                                "this iCloud Drive file could not be downloaded from iCloud (no network, iCloud throttling, or the download did not finish) — it is not in the export"
                        fi
                    else
                        log_warn "Copy failed: $rel."
                        note_incomplete "${root_out:-}" "$rel" \
                            "the copy of this iCloud Drive file failed (disk full, I/O error, or permissions) — it is not in the export"
                    fi ;;
            esac
        else
            if [ "$_was_dataless" = "1" ] && _materialized_copy_incomplete "$_src_size" "$target"; then
                _fail_n=$((_fail_n + 1))
                rm -f -- "$target" 2>/dev/null
                if [ -n "$_DRIVE_MAT_FAIL_FILE" ]; then
                    printf 'incomplete\t%s\n' \
                        "$(tsv_escape "${friendly:+$friendly/}$rel")" \
                        >> "$_DRIVE_MAT_FAIL_FILE"
                else
                    log_warn "iCloud download produced an incomplete copy: ${friendly:+$friendly/}$rel"
                    note_incomplete "${root_out:-}" "${friendly:+$friendly/}$rel" \
                        "the copy ran but the result was incomplete or still an iCloud placeholder rather than the real file — it was removed and is not in the export"
                fi
            else
                copied=$((copied + 1))
            fi
        fi
        _progress_tick "$copied" 0 "items copied from ${friendly:-?}" >&2
    done < <(find -L "$src" \( -type f -o -type l \) -print0 2>"${_find_err:-/dev/null}")
    _progress_end >&2
    if [ -n "$_find_err" ] && [ -s "$_find_err" ]; then
        if LC_ALL=C grep -qE 'Permission denied|Operation not permitted' "$_find_err" 2>/dev/null; then
            log_warn "Container unreadable (macOS keeps this app's storage locked): $src."
            [ -n "$_DRIVE_PERM_DENIED_FILE" ] && \
                printf '%s\n' "$src" >> "$_DRIVE_PERM_DENIED_FILE"
        fi
        rm -f -- "$_find_err" 2>/dev/null || true
    fi
    [ "$placeholder_count" -gt 0 ] && \
        log_warn "$placeholder_count $(_pluralize "$placeholder_count" file) not yet downloaded from iCloud (skipped)"
    validate_count_parity "$_enum_n" \
        "$((copied + placeholder_count + _fail_n + _other_n))" \
        "iCloud Drive: ${friendly:-container}" "${root_out:-}"
    _DRIVE_COPY_N="$copied"
}

_drive_account_copy() {
    local _s="$1" _d="$2" _disp="$3" _rc="$4" _serr="$5" _was_dataless="${6:-0}"
    if [ "$_rc" -ne 0 ]; then
        rm -f -- "$_d" 2>/dev/null
        case "$_serr" in
            *"Permission denied"*|*"Operation not permitted"*)
                [ -n "$_DRIVE_PERM_DENIED_FILE" ] && \
                    printf '%s\n' "$_s" >> "$_DRIVE_PERM_DENIED_FILE"
                printf 0; return ;;
        esac
        if [ "$_was_dataless" = "1" ]; then
            if [ -n "$_DRIVE_MAT_FAIL_FILE" ]; then
                printf 'download-failed\t%s\n' "$(tsv_escape "$_disp")" \
                    >> "$_DRIVE_MAT_FAIL_FILE"
            else
                log_warn "iCloud download failed: $_disp"
                note_incomplete "${root_out:-}" "$_disp" \
                    "this iCloud Drive file could not be downloaded from iCloud (no network, iCloud throttling, or the download did not finish) — it is not in the export"
            fi
        else
            log_warn "Copy failed: $_disp."
            note_incomplete "${root_out:-}" "$_disp" \
                "the copy of this iCloud Drive file failed (disk full, I/O error, or permissions) — it is not in the export"
            if [ -n "$_DRIVE_MAT_FAIL_FILE" ]; then
                printf 'copy-failed\t%s\n' "$(tsv_escape "$_disp")" \
                    >> "$_DRIVE_MAT_FAIL_FILE"
            fi
        fi
        printf 0; return
    fi
    if [ "$_was_dataless" -eq 1 ]; then
        local _ss
        _ss="$(stat -f '%z' -- "$_s" 2>/dev/null)"
        if _materialized_copy_incomplete "$_ss" "$_d"; then
            rm -f -- "$_d" 2>/dev/null
            [ -n "$_DRIVE_MAT_FAIL_FILE" ] && \
                printf 'incomplete\t%s\n' "$(tsv_escape "$_disp")" \
                    >> "$_DRIVE_MAT_FAIL_FILE"
            printf 0; return
        fi
    fi
    printf 1
}

_is_apple_internal_container() {
    case "$2" in *com~apple~*) ;; *) return 1 ;; esac
    local _f="$1" _suf="${1##*_}"
    case "$1" in *_*) case "$_suf" in ''|*[!0-9]*) ;; *) _f="${1%_*}" ;; esac ;; esac
    case "$_f" in
        mail|shoebox|AccountSD|mobilephone|sbd3|suggestions|Safari|\
        TextInput|donotdisturbd|videoservices|GameCenter|ScreenTimeAgent)
            return 0 ;;
    esac
    return 1
}

icloud_drive_main() {
    maybe_show_help "$@"
    _announce_step "iCloud Drive export"
    check_dependencies
    [ "${_INVOKED_BY_WRAPPER:-0}" = "1" ] || timemachine_suspend
    local _LABEL_CLOUDDOCS_ROOT="iCloud Drive root"
    local _LABEL_RECENTLY_DELETED="iCloud Drive Recently Deleted"
    local out_arg out_dir
    out_arg="$(_parse_output_folder_arg "$@")" || exit 1
    out_dir="$(resolve_output_dir "$out_arg")" || exit 1
    _announce_output_dir "iCloud Drive"
    if [ ! -d "$ICLOUD_ROOT" ]; then
        report_no_source "iCloud Drive" "not enabled" "$ICLOUD_ROOT"
    fi
    log_info "Source: $ICLOUD_ROOT"
    local _src_kb _avail_kb _need_kb _dataless_kb
    _src_kb="$(LC_ALL=C du -sk "$ICLOUD_ROOT" 2>/dev/null | awk '{print $1}')"
    case "$_src_kb" in ''|*[!0-9]*) _src_kb=0 ;; esac
    ensure_scratch
    _dataless_kb=0
    local _idl_f_pid _idl_w_pid _idl_p _idl_np=()
    ( find "$ICLOUD_ROOT" -flags +dataless -print0 2>/dev/null \
        | xargs -0 stat -f '%z' 2>/dev/null \
        | awk 'BEGIN{s=0} {s+=$1+0} END{printf "%d\n", s/1024}' \
        > "$SCRATCH_DIR/_idrive_dataless.out" 2>/dev/null ) &
    _idl_f_pid=$!
    CHILD_PIDS+=( "$_idl_f_pid" )
    ( sleep 30; kill -0 "$_idl_f_pid" 2>/dev/null || exit 0; pkill -P "$_idl_f_pid" 2>/dev/null; kill -9 "$_idl_f_pid" 2>/dev/null ) >/dev/null 2>&1 &
    _idl_w_pid=$!
    CHILD_PIDS+=( "$_idl_w_pid" )
    wait "$_idl_f_pid" 2>/dev/null
    pkill -P "$_idl_w_pid" 2>/dev/null || true
    kill -9 "$_idl_w_pid" 2>/dev/null
    wait "$_idl_w_pid" 2>/dev/null
    for _idl_p in "${CHILD_PIDS[@]+"${CHILD_PIDS[@]}"}"; do
        [ "$_idl_p" = "$_idl_f_pid" ] || [ "$_idl_p" = "$_idl_w_pid" ] || _idl_np+=( "$_idl_p" )
    done
    if [ "${#_idl_np[@]}" -gt 0 ]; then CHILD_PIDS=( "${_idl_np[@]}" ); else CHILD_PIDS=(); fi
    _dataless_kb="$(awk 'END{print}' "$SCRATCH_DIR/_idrive_dataless.out" 2>/dev/null)"
    case "$_dataless_kb" in ''|*[!0-9]*) _dataless_kb=0 ;; esac
    rm -f -- "$SCRATCH_DIR/_idrive_dataless.out" 2>/dev/null
    _avail_kb="$(LC_ALL=C df -P -k "$out_dir" 2>/dev/null | awk 'END{print $4}')"
    case "$_avail_kb" in
        ''|*[!0-9]*)
            _avail_kb=0
            [ "$_src_kb" -gt 0 ] && log_info "Could not determine output volume free space — sanity check skipped (df failed)." ;;
        0)
            [ "$_src_kb" -gt 0 ] && log_warn "Output volume reports 0 KB free — the copy will likely fail (ENOSPC)." ;;
    esac
    _need_kb=$(( _src_kb + _dataless_kb + 5 * 1024 * 1024 ))
    if [ "$_avail_kb" -gt 0 ] && [ "$_avail_kb" -lt "$_need_kb" ]; then
        if [ "$_dataless_kb" -gt 0 ]; then
            log_warn "Output volume has $((_avail_kb/1024)) MB free; this iCloud Drive export needs roughly $((_need_kb/1024)) MB on disk ($((_src_kb/1024)) MB already on disk + $((_dataless_kb/1024)) MB iCloud-only, downloaded on access + 5 GB headroom). The copy may fail partway — free up space or choose another output folder."
        else
            log_warn "Output volume has $((_avail_kb/1024)) MB free; this iCloud Drive export needs roughly $((_need_kb/1024)) MB on disk ($((_src_kb/1024)) MB + 5 GB headroom). The copy may fail partway — free up space or choose another output folder."
        fi
    fi
    log_info "Scanning for alternate-account iCloud caches..."
    local _alt_acct _alt_acct_count=0
    for _alt_acct in "$HOME/Library/Mobile Documents."*; do
        [ -d "$_alt_acct" ] || continue
        _alt_acct_count=$((_alt_acct_count + 1))
        log_warn "Alternate-account iCloud cache present: $_alt_acct."
        log_info "This is leftover from a previous Apple ID sign-out and is not"
        log_info "exported. To recover its contents: sign back into the previous"
        log_info "Apple ID temporarily, let iCloud Drive populate the canonical"
        log_info "$ICLOUD_ROOT, then re-run."
    done
    local root_out="$out_dir/iCloud Drive"
    require_no_collision "$root_out"
    log_info "Enumerating Mobile Documents containers..."
    local clouddocs=""
    local -a app_containers=() app_friendly=() app_unmapped=()
    local _apple_internal_skipped=0
    local entry name f
    while IFS= read -r -d '' entry; do
        name="$(basename "$entry")"
        case "$name" in .*) continue ;; esac
        if _is_clouddocs_container "$name"; then
            if [ -n "$clouddocs" ]; then
                log_err "Multiple CloudDocs containers found."
                log_info "  • Existing:    $clouddocs"
                log_info "  • Conflicting: $name"
                log_info "Investigate ~/Library/Mobile Documents/ manually before re-running."
                exit 1
            fi
            clouddocs="$name"
            continue
        fi
        local _was_unmapped=0
        if ! f="$(_icloud_friendly "$name")"; then
            f="$name"
            _was_unmapped=1
        fi
        if _is_apple_internal_container "$f" "$name"; then
            _apple_internal_skipped=$((_apple_internal_skipped + 1))
            continue
        fi
        f="$(_sanitize_name "$f")"
        app_containers+=( "$name" )
        app_friendly+=( "$f" )
        app_unmapped+=( "$_was_unmapped" )
    done < <(find "$ICLOUD_ROOT" -mindepth 1 -maxdepth 1 -type d -print0 2>/dev/null)
    if [ -z "$clouddocs" ] && [ "${#app_containers[@]}" -eq 0 ]; then
        if [ "$_apple_internal_skipped" -gt 0 ]; then
            report_empty_source "iCloud Drive documents"
        fi
        die "No iCloud Drive containers found under $ICLOUD_ROOT"
    fi
    log_info "Mapping friendly names + resolving collisions..."
    if [ "$_apple_internal_skipped" -gt 0 ]; then
        _disclose_excluded "$_apple_internal_skipped Apple-internal $(_pluralize "$_apple_internal_skipped" container)" "system state, not user data"
    fi
    local i j _dupes
    local -a app_friendly_orig=()
    for (( i=0; i<${#app_friendly[@]}; i++ )); do
        app_friendly_orig+=( "${app_friendly[$i]}" )
    done
    for (( i=0; i<${#app_friendly[@]}; i++ )); do
        _dupes=0
        for (( j=0; j<i; j++ )); do
            [ "${app_friendly_orig[$j]}" = "${app_friendly_orig[$i]}" ] && _dupes=$((_dupes + 1))
        done
        if [ "$_dupes" -gt 0 ]; then
            local _n=$(( _dupes + 1 )) _cand _collide=1 _guard=0
            _cand="${app_friendly_orig[$i]} ($_n)"
            while [ "$_collide" = 1 ] && [ "$_guard" -lt 1000 ]; do
                _collide=0; _guard=$(( _guard + 1 ))
                for (( j=0; j<${#app_friendly[@]}; j++ )); do
                    [ "$j" = "$i" ] && continue
                    if [ "${app_friendly[$j]}" = "$_cand" ] || \
                       [ "${app_friendly_orig[$j]}" = "$_cand" ]; then
                        _collide=1; _n=$(( _n + 1 ))
                        _cand="${app_friendly_orig[$i]} ($_n)"; break
                    fi
                done
            done
            app_friendly[$i]="$_cand"
            log_info "Auto-resolved duplicate app-library name (kept both): ${app_containers[$i]} → ${app_friendly[$i]}"
        fi
    done
    local -a cd_entries=() cd_renamed=()
    local cd_src=""
    if [ -n "$clouddocs" ]; then
        cd_src="$ICLOUD_ROOT/$clouddocs"
        [ -d "$cd_src/Documents" ] && cd_src="$cd_src/Documents"
        local ent_path ent_name
        while IFS= read -r -d '' ent_path; do
            ent_name="$(basename "$ent_path")"
            case "$ent_name" in
                .Trash) continue ;;
            esac
            is_macos_junk_path "$ent_name" && continue
            cd_entries+=( "$ent_name" )
        done < <(find "$cd_src" -mindepth 1 -maxdepth 1 -print0 2>/dev/null)
        local -a cd_will_be_renamed=()
        local cd_name app
        for cd_name in "${cd_entries[@]+"${cd_entries[@]}"}"; do
            local _flag=0
            for app in "${app_friendly[@]+"${app_friendly[@]}"}"; do
                if [ "$cd_name" = "$app" ]; then
                    _flag=1
                    break
                fi
            done
            cd_will_be_renamed+=( "$_flag" )
        done
        local -a renames_for_log=()
        local i j dst_name n taken
        for (( i=0; i<${#cd_entries[@]}; i++ )); do
            cd_name="${cd_entries[$i]}"
            if [ "${cd_will_be_renamed[$i]}" = "0" ]; then
                cd_renamed+=( "$cd_name" )
                continue
            fi
            cd_name="$(_sanitize_name "$cd_name")"
            dst_name="$cd_name (iCloud Drive)"
            n=2
            local _attempts=0
            while true; do
                _attempts=$((_attempts + 1))
                if [ "$_attempts" -gt 1000 ]; then
                    local _rand_suffix _rand_try _rand_taken
                    for _rand_try in $(seq 1 50); do
                        _rand_suffix="$(LC_ALL=C tr -dc 'a-z0-9' < /dev/urandom 2>/dev/null | head -c 6)"
                        [ -z "$_rand_suffix" ] && _rand_suffix="$$$RANDOM"
                        dst_name="$cd_name (iCloud Drive ${_rand_suffix})"
                        _rand_taken=0
                        for app in "${app_friendly[@]+"${app_friendly[@]}"}"; do
                            if [ "$dst_name" = "$app" ]; then _rand_taken=1; break; fi
                        done
                        if [ "$_rand_taken" = "0" ]; then
                            for (( j=0; j<${#cd_entries[@]}; j++ )); do
                                if [ "${cd_will_be_renamed[$j]}" = "0" ]; then
                                    [ "$dst_name" = "${cd_entries[$j]}" ] && { _rand_taken=1; break; }
                                elif [ "$j" -lt "$i" ]; then
                                    [ "$dst_name" = "${cd_renamed[$j]}" ] && { _rand_taken=1; break; }
                                fi
                            done
                        fi
                        [ "$_rand_taken" = "0" ] && break
                    done
                    log_warn "Collision-resolution: '$cd_name' has 1000+ sibling renames already in use; falling back to random-suffix name '$dst_name' rather than aborting the export."
                    break
                fi
                taken=0
                for app in "${app_friendly[@]+"${app_friendly[@]}"}"; do
                    if [ "$dst_name" = "$app" ]; then
                        taken=1
                        break
                    fi
                done
                if [ "$taken" = "0" ]; then
                    for (( j=0; j<${#cd_entries[@]}; j++ )); do
                        if [ "${cd_will_be_renamed[$j]}" = "0" ]; then
                            if [ "$dst_name" = "${cd_entries[$j]}" ]; then
                                taken=1
                                break
                            fi
                        elif [ "$j" -lt "$i" ]; then
                            if [ "$dst_name" = "${cd_renamed[$j]}" ]; then
                                taken=1
                                break
                            fi
                        fi
                    done
                fi
                [ "$taken" = "0" ] && break
                dst_name="$cd_name (iCloud Drive $n)"
                n=$((n + 1))
            done
            cd_renamed+=( "$dst_name" )
            renames_for_log+=( "$cd_name → $dst_name" )
        done
        if [ "${#renames_for_log[@]}" -gt 0 ]; then
            log_info "Auto-resolved name collisions (app library wins):"
            local r
            for r in "${renames_for_log[@]}"; do
                log_info "  • $r"
            done
        fi
    fi
    _create_output_dir "$root_out"
    local n_containers=0 _has_cd=0
    [ -n "$clouddocs" ] && { n_containers=$((n_containers + 1)); _has_cd=1; }
    n_containers=$((n_containers + ${#app_containers[@]}))
    if [ "$_has_cd" -eq 1 ]; then
        log_info "Found $n_containers $(_pluralize "$n_containers" container) at $ICLOUD_ROOT: 1 CloudDocs root + ${#app_containers[@]} app-library $(_pluralize "${#app_containers[@]}" container)"
    else
        log_info "Found $n_containers $(_pluralize "$n_containers" container) at $ICLOUD_ROOT (no CloudDocs root present)"
    fi
    ensure_scratch
    _DRIVE_STUBS_FILE="$SCRATCH_DIR/icloud_stubs.tsv"
    : > "$_DRIVE_STUBS_FILE"
    _DRIVE_PERM_DENIED_FILE="$SCRATCH_DIR/icloud_perm_denied.txt"
    : > "$_DRIVE_PERM_DENIED_FILE"
    _DRIVE_MAT_FAIL_FILE="$SCRATCH_DIR/icloud_mat_fail.tsv"
    : > "$_DRIVE_MAT_FAIL_FILE"
    _DRIVE_SYMLINK_FILE="$SCRATCH_DIR/icloud_symlinks.tsv"
    : > "$_DRIVE_SYMLINK_FILE"
    local _DRIVE_CONTAINER_SKIP_FILE="$SCRATCH_DIR/icloud_container_skip.tsv"
    : > "$_DRIVE_CONTAINER_SKIP_FILE"
    local total_copied=0 copied
    local n_with_data=0
    local -a unmapped_with_data=()
    log_info "Copying CloudDocs (iCloud Drive root)..."
    if [ -n "$clouddocs" ]; then
        local cd_total=0 sub_copied i ent_path ent_dst _name _err _orig _icd_dl_real
        _ICD_ALLOW_DOTFILES=1
        for (( i=0; i<${#cd_entries[@]}; i++ )); do
            ent_path="$cd_src/${cd_entries[$i]}"
            ent_dst="$root_out/${cd_renamed[$i]}"
            _name="${cd_entries[$i]}"
            if [ -d "$ent_path" ]; then
                if [ -L "$ent_path" ]; then
                    _icd_dl_real="$(readlink -f -- "$ent_path" 2>/dev/null || realpath -- "$ent_path" 2>/dev/null)"
                    if [ -n "$_icd_dl_real" ] && ! _icd_target_in_scope "$_icd_dl_real"; then
                        [ -n "$_DRIVE_SYMLINK_FILE" ] && \
                            printf '%s\t%s\n' "$(tsv_escape "$_LABEL_CLOUDDOCS_ROOT")" \
                                "$(tsv_escape "$_name  ->  $_icd_dl_real (target outside iCloud Drive — not copied)")" \
                                >> "$_DRIVE_SYMLINK_FILE"
                        continue
                    fi
                    _DRIVE_SYMLINK_DEREF_DIR=$((${_DRIVE_SYMLINK_DEREF_DIR:-0} + 1))
                fi
                _copy_tree_skip_placeholders \
                    "$ent_path" "$ent_dst" "$_LABEL_CLOUDDOCS_ROOT"
                sub_copied="$_DRIVE_COPY_N"
                cd_total=$((cd_total + sub_copied))
                continue
            fi
            if _icd_should_skip_copy "$ent_path" "$_name" "$_LABEL_CLOUDDOCS_ROOT"; then
                continue
            fi
            [ -n "$_ICD_DEREF_PATH" ] && ent_path="$_ICD_DEREF_PATH"
            if [ -f "$ent_path" ]; then
                if is_icloud_stub "$ent_path"; then
                    if [ -n "$_DRIVE_STUBS_FILE" ]; then
                        _orig="$(tsv_escape "$(_strip_icloud_stub_name "$_name")")"
                        printf '%s\t%s\n' "$_LABEL_CLOUDDOCS_ROOT" "$_orig" \
                            >> "$_DRIVE_STUBS_FILE"
                    fi
                    continue
                fi
                local _cd_rc _cd_was_dl=0
                is_dataless "$ent_path" && _cd_was_dl=1
                _err="$(_ditto_dl_retry "$ent_path" "$ent_dst" "$_cd_was_dl")"; _cd_rc=$?
                cd_total=$((cd_total + $(_drive_account_copy "$ent_path" \
                    "$ent_dst" "$_name" "$_cd_rc" "$_err" "$_cd_was_dl")))
            fi
        done
        local _cd_container="$ICLOUD_ROOT/$clouddocs"
        if [ "$cd_src" != "$_cd_container" ]; then
            local _re _rname _rdst _rerr _rrc _rdl
            while IFS= read -r -d '' _re; do
                _rname="${_re##*/}"
                [ "$_rname" = "Documents" ] && continue
                case "$_rname" in
                    .*) continue ;;
                esac
                _rdst="$(_unique_path "$root_out/$_rname")"
                if [ -d "$_re" ]; then
                    if [ -L "$_re" ]; then
                        _icd_dl_real="$(readlink -f -- "$_re" 2>/dev/null || realpath -- "$_re" 2>/dev/null)"
                        if [ -n "$_icd_dl_real" ] && ! _icd_target_in_scope "$_icd_dl_real"; then
                            [ -n "$_DRIVE_SYMLINK_FILE" ] && \
                                printf '%s\t%s\n' "$(tsv_escape "$_LABEL_CLOUDDOCS_ROOT")" \
                                    "$(tsv_escape "$_rname  ->  $_icd_dl_real (target outside iCloud Drive — not copied)")" \
                                    >> "$_DRIVE_SYMLINK_FILE"
                            continue
                        fi
                        _DRIVE_SYMLINK_DEREF_DIR=$((${_DRIVE_SYMLINK_DEREF_DIR:-0} + 1))
                    fi
                    _copy_tree_skip_placeholders "$_re" "$_rdst" "$_LABEL_CLOUDDOCS_ROOT"
                    cd_total=$((cd_total + _DRIVE_COPY_N))
                elif _icd_should_skip_copy "$_re" "$_rname" "$_LABEL_CLOUDDOCS_ROOT"; then
                    :
                else
                    [ -n "$_ICD_DEREF_PATH" ] && _re="$_ICD_DEREF_PATH"
                    if [ -f "$_re" ]; then
                        if is_icloud_stub "$_re"; then
                            [ -n "$_DRIVE_STUBS_FILE" ] && \
                                printf '%s\t%s\n' "$_LABEL_CLOUDDOCS_ROOT" \
                                    "$(tsv_escape "$(_strip_icloud_stub_name "$_rname")")" \
                                    >> "$_DRIVE_STUBS_FILE"
                        else
                            _rdl=0; is_dataless "$_re" && _rdl=1
                            _rerr="$(_ditto_dl_retry "$_re" "$_rdst" "$_rdl")"; _rrc=$?
                            cd_total=$((cd_total + $(_drive_account_copy \
                                "$_re" "$_rdst" "$_rname" "$_rrc" "$_rerr" "$_rdl")))
                        fi
                    fi
                fi
            done < <(find "$_cd_container" -mindepth 1 -maxdepth 1 -print0 2>/dev/null)
        fi
        _ICD_ALLOW_DOTFILES=0
        total_copied=$((total_copied + cd_total))
        if [ "$cd_total" -gt 0 ]; then
            log_info "Copied iCloud Drive root: $cd_total $(_pluralize "$cd_total" file), $(_dir_size_human "$root_out")"
            n_with_data=$((n_with_data + 1))
        fi
    else
        log_info "No CloudDocs container present (no Finder-visible iCloud Drive root)"
    fi
    log_info "Copying app-library containers (${#app_containers[@]} $(_pluralize "${#app_containers[@]}" container))..."
    for (( i=0; i<${#app_containers[@]}; i++ )); do
        local cname="${app_containers[$i]}" fname="${app_friendly[$i]}"
        local src="$ICLOUD_ROOT/$cname"
        local dst="$root_out/$fname"
        local container_copied=0 _entry _ename _edst _icd_dl_real
        if [ -d "$src/Documents" ]; then
            _copy_tree_skip_placeholders "$src/Documents" "$dst" "$fname"
            copied="$_DRIVE_COPY_N"
            container_copied=$((container_copied + copied))
            mkdir -p "$dst" 2>/dev/null || true
            while IFS= read -r -d '' _entry; do
                _ename="$(basename "$_entry")"
                case "$_ename" in
                    Documents|.*) continue ;;
                    Library|Caches|tmp)
                        local _drive_first_skipped_entry
                        if [ -d "$_entry" ] && \
                           IFS= read -r -d '' _drive_first_skipped_entry < <(find "$_entry" -mindepth 1 -print0 -quit 2>/dev/null); then
                            printf '%s\t%s\n' \
                                "$(tsv_escape "$fname")" "$(tsv_escape "$_ename")" \
                                >> "$_DRIVE_CONTAINER_SKIP_FILE"
                        fi
                        continue ;;
                esac
                _edst="$dst/$_ename"
                if [ -d "$_entry" ]; then
                    if [ -L "$_entry" ]; then
                        _icd_dl_real="$(readlink -f -- "$_entry" 2>/dev/null || realpath -- "$_entry" 2>/dev/null)"
                        if [ -n "$_icd_dl_real" ] && ! _icd_target_in_scope "$_icd_dl_real"; then
                            [ -n "$_DRIVE_SYMLINK_FILE" ] && \
                                printf '%s\t%s\n' "$(tsv_escape "$fname")" \
                                    "$(tsv_escape "$_ename  ->  $_icd_dl_real (target outside iCloud Drive — not copied)")" \
                                    >> "$_DRIVE_SYMLINK_FILE"
                            continue
                        fi
                        _DRIVE_SYMLINK_DEREF_DIR=$((${_DRIVE_SYMLINK_DEREF_DIR:-0} + 1))
                    fi
                    _copy_tree_skip_placeholders "$_entry" "$_edst" "$fname"
                    copied="$_DRIVE_COPY_N"
                    container_copied=$((container_copied + copied))
                elif ! _icd_should_skip_copy "$_entry" "$_ename" "$fname"; then
                    [ -n "$_ICD_DEREF_PATH" ] && _entry="$_ICD_DEREF_PATH"
                    local _cp_err _cp_err_rc _cp_was_dl=0
                    is_dataless "$_entry" && _cp_was_dl=1
                    _cp_err="$(_ditto_dl_retry "$_entry" "$_edst" "$_cp_was_dl")"; _cp_err_rc=$?
                    container_copied=$((container_copied + $(_drive_account_copy \
                        "$_entry" "$_edst" "$fname/$_ename" \
                        "$_cp_err_rc" "$_cp_err" "$_cp_was_dl")))
                fi
            done < <(find "$src" -mindepth 1 -maxdepth 1 -print0 2>/dev/null)
        else
            mkdir -p "$dst" 2>/dev/null || true
            while IFS= read -r -d '' _entry; do
                _ename="$(basename "$_entry")"
                case "$_ename" in
                    Documents|.*) continue ;;
                    Library|Caches|tmp)
                        local _drive_first_skipped_entry
                        if [ -d "$_entry" ] && \
                           IFS= read -r -d '' _drive_first_skipped_entry < <(find "$_entry" -mindepth 1 -print0 -quit 2>/dev/null); then
                            printf '%s\t%s\n' \
                                "$(tsv_escape "$fname")" "$(tsv_escape "$_ename")" \
                                >> "$_DRIVE_CONTAINER_SKIP_FILE"
                        fi
                        continue ;;
                esac
                _edst="$dst/$_ename"
                if [ -d "$_entry" ]; then
                    if [ -L "$_entry" ]; then
                        _icd_dl_real="$(readlink -f -- "$_entry" 2>/dev/null || realpath -- "$_entry" 2>/dev/null)"
                        if [ -n "$_icd_dl_real" ] && ! _icd_target_in_scope "$_icd_dl_real"; then
                            [ -n "$_DRIVE_SYMLINK_FILE" ] && \
                                printf '%s\t%s\n' "$(tsv_escape "$fname")" \
                                    "$(tsv_escape "$_ename  ->  $_icd_dl_real (target outside iCloud Drive — not copied)")" \
                                    >> "$_DRIVE_SYMLINK_FILE"
                            continue
                        fi
                        _DRIVE_SYMLINK_DEREF_DIR=$((${_DRIVE_SYMLINK_DEREF_DIR:-0} + 1))
                    fi
                    _copy_tree_skip_placeholders "$_entry" "$_edst" "$fname"
                    copied="$_DRIVE_COPY_N"
                    container_copied=$((container_copied + copied))
                elif ! _icd_should_skip_copy "$_entry" "$_ename" "$fname"; then
                    [ -n "$_ICD_DEREF_PATH" ] && _entry="$_ICD_DEREF_PATH"
                    local _cp_err2 _cp_err2_rc _cp_was_dl2=0
                    is_dataless "$_entry" && _cp_was_dl2=1
                    _cp_err2="$(_ditto_dl_retry "$_entry" "$_edst" "$_cp_was_dl2")"; _cp_err2_rc=$?
                    container_copied=$((container_copied + $(_drive_account_copy \
                        "$_entry" "$_edst" "$fname/$_ename" \
                        "$_cp_err2_rc" "$_cp_err2" "$_cp_was_dl2")))
                fi
            done < <(find "$src" -mindepth 1 -maxdepth 1 -print0 2>/dev/null)
        fi
        total_copied=$((total_copied + container_copied))
        if [ "$container_copied" -gt 0 ]; then
            log_info "Copied $fname: $container_copied $(_pluralize "$container_copied" file), $(_dir_size_human "$dst")"
            n_with_data=$((n_with_data + 1))
            if [ "${app_unmapped[$i]}" = "1" ]; then
                local _cname_safe
                _cname_safe="$(printf '%s' "$cname" | LC_ALL=C tr -d '[:cntrl:]')"
                unmapped_with_data+=( "$_cname_safe" )
            fi
        fi
        find "$dst" -mindepth 0 -type d -empty -delete 2>/dev/null || true
    done
    if [ "${#unmapped_with_data[@]}" -gt 0 ]; then
        log_info "Container(s) with data but no friendly-name rule:"
        local _u
        for _u in "${unmapped_with_data[@]}"; do
            log_info "  • $_u"
        done
        log_info "(Add patterns to _icloud_friendly() in export_icloud_drive to map these.)"
    fi
    log_info "Recovering Recently Deleted + scanning for conflicts/shared folders..."
    local _conflicts_tmp="$SCRATCH_DIR/icloud_conflicts.tsv"
    : > "$_conflicts_tmp"
    if [ -d "$root_out" ]; then
        local _cf _crel
        while IFS= read -r -d '' _cf; do
            _crel="$_cf"
            case "$_crel" in "$root_out"/*) _crel="${_crel#"$root_out"/}" ;; esac
            printf '%s\n' "$(tsv_escape "$_crel")" >> "$_conflicts_tmp"
        done < <(find "$root_out" -type f -iname "*conflicted copy*" -print0 2>/dev/null)
    fi
    local _share_tmp="$SCRATCH_DIR/icloud_shared.tsv"
    : > "$_share_tmp"
    local _share_scan="$ICLOUD_ROOT/$clouddocs"
    if [ -n "$clouddocs" ] && [ -d "$_share_scan" ]; then
        local _sf _srel
        while IFS= read -r -d '' _sf; do
            _srel="$_sf"
            case "$_srel" in "$ICLOUD_ROOT"/*) _srel="${_srel#"$ICLOUD_ROOT"/}" ;; esac
            _srel="${_srel%/*}"
            printf '%s\n' "$(tsv_escape "$_srel")" >> "$_share_tmp"
        done < <(find "$_share_scan" -type f -name '.*.icloud-share' -print0 2>/dev/null)
    fi
    local _RD_DIRNAME="Recently Deleted"
    [ -e "$root_out/$_RD_DIRNAME" ] && _RD_DIRNAME="_recently-deleted"
    local _drive_recovered_n=0
    local _trash_src=""
    local _trash_src_legacy=""
    if [ -n "$clouddocs" ]; then
        if [ -d "$ICLOUD_ROOT/$clouddocs/Documents/.Trash" ]; then
            _trash_src="$ICLOUD_ROOT/$clouddocs/Documents/.Trash"
        fi
        if [ -d "$ICLOUD_ROOT/$clouddocs/.Trash" ]; then
            if [ -z "$_trash_src" ]; then
                _trash_src="$ICLOUD_ROOT/$clouddocs/.Trash"
            else
                _trash_src_legacy="$ICLOUD_ROOT/$clouddocs/.Trash"
                log_warn "Both <CloudDocs>/Documents/.Trash AND <CloudDocs>/.Trash exist — recovering content from both (legacy path → $_RD_DIRNAME/legacy/)."
            fi
        fi
    fi
    if [ -n "$_trash_src" ]; then
        local _trash_dst="$root_out/$_RD_DIRNAME"
        local _trash_n
        _ICD_ALLOW_DOTFILES=1
        _copy_tree_skip_placeholders "$_trash_src" "$_trash_dst" "$_LABEL_RECENTLY_DELETED"
        _trash_n="$_DRIVE_COPY_N"
        local _trash_src_rel="${_trash_src#"$ICLOUD_ROOT"/}"
        case "$_trash_n" in ''|*[!0-9]*) _trash_n=0 ;; esac
        if [ "$_trash_n" -gt 0 ]; then
            _drive_recovered_n=$((_drive_recovered_n + _trash_n))
            log_info "Recovered $_trash_n $(_pluralize "$_trash_n" file) from $_trash_src_rel → $_RD_DIRNAME/ ($(_dir_size_human "$_trash_dst"))"
        else
            rmdir "$_trash_dst" 2>/dev/null || true
        fi
        if [ -n "$_trash_src_legacy" ]; then
            local _trash_legacy_dst="$root_out/$_RD_DIRNAME/legacy"
            local _trash_legacy_n
            _copy_tree_skip_placeholders "$_trash_src_legacy" "$_trash_legacy_dst" "$_LABEL_RECENTLY_DELETED (legacy)"
            _trash_legacy_n="$_DRIVE_COPY_N"
            case "$_trash_legacy_n" in ''|*[!0-9]*) _trash_legacy_n=0 ;; esac
            if [ "$_trash_legacy_n" -gt 0 ]; then
                _drive_recovered_n=$((_drive_recovered_n + _trash_legacy_n))
                log_info "Recovered $_trash_legacy_n $(_pluralize "$_trash_legacy_n" file) from ${_trash_src_legacy#"$ICLOUD_ROOT"/} → $_RD_DIRNAME/legacy/ ($(_dir_size_human "$_trash_legacy_dst"))"
            else
                rmdir "$_trash_legacy_dst" 2>/dev/null || true
            fi
        fi
        _ICD_ALLOW_DOTFILES=0
    fi
    log_info "Writing companion files + cleanup..."
    local stubs_count=0 conflicts_count=0 shared_count=0 mat_fail_count=0
    local symlink_count=0 container_skip_count=0
    if [ -s "$_DRIVE_STUBS_FILE" ] || [ -s "$_conflicts_tmp" ] \
       || [ -s "$_share_tmp" ] || [ -s "$_DRIVE_MAT_FAIL_FILE" ] \
       || [ -s "$_DRIVE_SYMLINK_FILE" ] || [ -s "$_DRIVE_CONTAINER_SKIP_FILE" ]; then
        [ -s "$_DRIVE_STUBS_FILE" ] && \
            stubs_count="$(LC_ALL=C sort -u "$_DRIVE_STUBS_FILE" | wc -l | tr -d ' ')"
        [ -s "$_conflicts_tmp" ] && \
            conflicts_count="$(LC_ALL=C sort -u "$_conflicts_tmp" | wc -l | tr -d ' ')"
        [ -s "$_share_tmp" ] && \
            shared_count="$(LC_ALL=C sort -u "$_share_tmp" | wc -l | tr -d ' ')"
        [ -s "$_DRIVE_MAT_FAIL_FILE" ] && \
            mat_fail_count="$(LC_ALL=C sort -u "$_DRIVE_MAT_FAIL_FILE" | wc -l | tr -d ' ')"
        [ -s "$_DRIVE_SYMLINK_FILE" ] && \
            symlink_count="$(LC_ALL=C sort -u "$_DRIVE_SYMLINK_FILE" | wc -l | tr -d ' ')"
        [ -s "$_DRIVE_CONTAINER_SKIP_FILE" ] && \
            container_skip_count="$(LC_ALL=C sort -u "$_DRIVE_CONTAINER_SKIP_FILE" | wc -l | tr -d ' ')"
        {
            if [ -s "$_DRIVE_STUBS_FILE" ]; then
                LC_ALL=C sort -u "$_DRIVE_STUBS_FILE" | LC_ALL=C awk -F'\t' '{
                    if ($1 != prev) { if (prev != "") print ""; print "[" $1 "]"; prev = $1 }
                    print $2
                }'
            fi
            if [ -s "$_DRIVE_MAT_FAIL_FILE" ]; then
                [ -s "$_DRIVE_STUBS_FILE" ] && printf '\n'
                printf '[Failed to download from iCloud]\n'
                LC_ALL=C awk -F'\t' '{
                    if ($1 == "incomplete")        r = "incomplete copy, removed"
                    else if ($1 == "copy-failed")  r = "copy failed (I/O error or permission denied)"
                    else                            r = "download failed"
                    print $2 "  (" r ")"
                }' "$_DRIVE_MAT_FAIL_FILE" | LC_ALL=C sort -u
            fi
            if [ -s "$_conflicts_tmp" ]; then
                { [ -s "$_DRIVE_STUBS_FILE" ] || [ -s "$_DRIVE_MAT_FAIL_FILE" ]; } \
                    && printf '\n'
                printf '[Conflicts]\n'
                LC_ALL=C sort -u "$_conflicts_tmp"
            fi
            if [ -s "$_share_tmp" ]; then
                if [ -s "$_DRIVE_STUBS_FILE" ] || [ -s "$_DRIVE_MAT_FAIL_FILE" ] \
                   || [ -s "$_conflicts_tmp" ]; then
                    printf '\n'
                fi
                printf '[Shared folders]\n'
                LC_ALL=C sort -u "$_share_tmp"
            fi
            if [ -s "$_DRIVE_SYMLINK_FILE" ]; then
                if [ -s "$_DRIVE_STUBS_FILE" ] || [ -s "$_DRIVE_MAT_FAIL_FILE" ] \
                   || [ -s "$_conflicts_tmp" ] || [ -s "$_share_tmp" ]; then
                    printf '\n'
                fi
                printf '[Broken / unfollowable symlinks (file & directory symlinks are dereferenced)]\n'
                LC_ALL=C sort -u "$_DRIVE_SYMLINK_FILE" | LC_ALL=C awk -F'\t' '{
                    print $1 ": " $2
                }'
            fi
            if [ -s "$_DRIVE_CONTAINER_SKIP_FILE" ]; then
                if [ -s "$_DRIVE_STUBS_FILE" ] || [ -s "$_DRIVE_MAT_FAIL_FILE" ] \
                   || [ -s "$_conflicts_tmp" ] || [ -s "$_share_tmp" ] \
                   || [ -s "$_DRIVE_SYMLINK_FILE" ]; then
                    printf '\n'
                fi
                printf '[Skipped app-container folders (not copied — app state)]\n'
                LC_ALL=C sort -u "$_DRIVE_CONTAINER_SKIP_FILE" | LC_ALL=C awk -F'\t' '{
                    print $1 ": " $2
                }'
            fi
        } | _write_skipped_report "$root_out" "iCloud Drive files"
        [ "$mat_fail_count" -gt 0 ] && \
            log_warn "$mat_fail_count $(_pluralize "$mat_fail_count" file) could not be copied — NOT in this export (iCloud download or copy failures; see the per-file reasons)$(_disclosure_pointer)"
        if [ "$stubs_count" -gt 0 ]; then
            _disclose_optimize_storage "iCloud Drive" "$stubs_count" "" \
                "System Settings > Apple ID > iCloud > iCloud Drive > Sync this Mac > Optimize Mac Storage (off)"
        fi
        [ "$symlink_count" -gt 0 ] && \
            log_warn "$symlink_count $(_pluralize "$symlink_count" symlink) skipped (not copied)$(_disclosure_pointer)"
        [ "$container_skip_count" -gt 0 ] && \
            log_warn "$container_skip_count app-container $(_pluralize "$container_skip_count" folder) skipped (app state in a no-Documents container)$(_disclosure_pointer)"
        if [ "$stubs_count" -eq 0 ] && [ "$mat_fail_count" -eq 0 ] \
           && [ "$symlink_count" -eq 0 ] && [ "$container_skip_count" -eq 0 ] \
           && [ "$((conflicts_count + shared_count))" -gt 0 ]; then
            log_warn "$((conflicts_count + shared_count)) entry(ies) flagged$(_disclosure_pointer)"
        fi
    fi
    local _perm_denied=0
    if [ -s "$_DRIVE_PERM_DENIED_FILE" ]; then
        _perm_denied="$(_count_lines "$_DRIVE_PERM_DENIED_FILE")"
        log_warn "$_perm_denied $(_pluralize "$_perm_denied" path) could not be read (macOS keeps some app storage locked)"
        if [ -d "$root_out" ]; then
            report_blocked "$(_report_subject "$root_out")" "files macOS blocked" \
                "macOS blocked access to these paths even with Full Disk Access on — a few apps keep their storage locked. The originals are untouched; nothing was changed or removed." \
                "$(LC_ALL=C sort -u "$_DRIVE_PERM_DENIED_FILE")"
        fi
    fi
    find "$root_out" -mindepth 1 -type d -empty -delete 2>/dev/null || true
    if [ "$total_copied" -eq 0 ]; then
        local _has_content=0
        if [ -s "$_DRIVE_PERM_DENIED_FILE" ]; then
            _has_content=1
        fi
        if [ "$_has_content" = "0" ]; then
            if [ -s "$_DRIVE_STUBS_FILE" ] || [ -s "$_conflicts_tmp" ] \
               || [ -s "$_share_tmp" ] || [ -s "$_DRIVE_MAT_FAIL_FILE" ] \
               || [ -s "$_DRIVE_SYMLINK_FILE" ] \
               || [ -s "$_DRIVE_CONTAINER_SKIP_FILE" ]; then
                _has_content=1
            fi
        fi
        if [ "$_has_content" = "0" ] \
           && [ -d "$root_out/$_RD_DIRNAME" ]; then
            local _drive_recent_deleted_first
            if IFS= read -r -d '' _drive_recent_deleted_first < <(find "$root_out/$_RD_DIRNAME" -mindepth 1 -print0 -quit 2>/dev/null); then
                _has_content=1
            fi
        fi
        if [ "$_has_content" = "1" ]; then
            :
        else
            rmdir "$root_out" 2>/dev/null || true
            report_empty_source "iCloud Drive items"
        fi
    fi
    local _ic_stats
    if [ "$total_copied" -eq 0 ] && [ "$_drive_recovered_n" -gt 0 ]; then
        _ic_stats="$_drive_recovered_n $(_pluralize "$_drive_recovered_n" file) recovered from Recently Deleted, $(_dir_size_human "$root_out")"
    else
        _ic_stats="$total_copied $(_pluralize "$total_copied" file) across "
        if [ "$n_with_data" -lt "$n_containers" ]; then
            _ic_stats="$_ic_stats$n_with_data of $n_containers $(_pluralize "$n_containers" container)"
        else
            _ic_stats="$_ic_stats$n_containers $(_pluralize "$n_containers" container)"
        fi
        _ic_stats="$_ic_stats, $(_dir_size_human "$root_out")"
    fi
    local _ic_side=""
    [ "$stubs_count" -gt 0 ] && _ic_side="$stubs_count cloud-only"
    if [ "$mat_fail_count" -gt 0 ]; then
        [ -n "$_ic_side" ] && _ic_side="$_ic_side + "
        _ic_side="$_ic_side$mat_fail_count download-failed"
    fi
    if [ "$symlink_count" -gt 0 ]; then
        [ -n "$_ic_side" ] && _ic_side="$_ic_side + "
        _ic_side="$_ic_side$symlink_count $(_pluralize "$symlink_count" symlink)"
    fi
    if [ "$_perm_denied" -gt 0 ]; then
        [ -n "$_ic_side" ] && _ic_side="$_ic_side + "
        _ic_side="$_ic_side$_perm_denied perm-denied"
    fi
    if [ -n "$_ic_side" ]; then
        local _ic_sources=""
        if [ "${_INVOKED_BY_WRAPPER:-0}" != "1" ]; then
            _ic_sources=" — see _downpour_report.txt"
        fi
        _ic_stats="$_ic_stats, $_ic_side$_ic_sources"
    fi
    if [ "$total_copied" -eq 0 ] && [ "$_drive_recovered_n" -eq 0 ]; then
        rmdir "$root_out" 2>/dev/null || true
        _flag_no_content
        log_info "iCloud Drive: no in-scope files to copy$(_disclosure_pointer)."
    else
        log_ok "Wrote iCloud Drive/ ($_ic_stats)"
    fi
    if [ "${_DRIVE_SYMLINK_DEREF:-0}" -gt 0 ] || [ "${_DRIVE_SYMLINK_DEREF_DIR:-0}" -gt 0 ]; then
        local _ds_parts=""
        [ "${_DRIVE_SYMLINK_DEREF:-0}" -gt 0 ] && \
            _ds_parts="${_DRIVE_SYMLINK_DEREF} file $(_pluralize "${_DRIVE_SYMLINK_DEREF}" symlink) dereferenced (target content copied)"
        if [ "${_DRIVE_SYMLINK_DEREF_DIR:-0}" -gt 0 ]; then
            [ -n "$_ds_parts" ] && _ds_parts="$_ds_parts; "
            _ds_parts="${_ds_parts}${_DRIVE_SYMLINK_DEREF_DIR} top-level directory $(_pluralize "${_DRIVE_SYMLINK_DEREF_DIR}" symlink) followed"
        fi
        log_info "Symlinks: $_ds_parts — no symlink objects are written to the export."
    fi
    mark_success
    sweep_junk_files "$root_out"
    print_summary
    if [ "$ERR_COUNT" -gt 0 ]; then exit 1; fi
    exit 0
}

_render_body_html() {
    local text="$1"
    LC_ALL=C awk '
        function html_esc(s, r) {
            r = s
            gsub(/&/, "\\&amp;", r); gsub(/</, "\\&lt;", r); gsub(/>/, "\\&gt;", r)
            gsub(/"/, "\\&quot;", r); gsub(/'\''/, "\\&#39;", r)
            return r
        }
        BEGIN { in_para = 0 }
        /^[[:space:]]*$/ {
            if (in_para) { print "</p>"; in_para = 0 }
            next
        }
        {
            if (in_para == 0) { printf "<p>"; in_para = 1 }
            else printf "<br>"
            printf "%s", html_esc($0)
        }
        END { if (in_para) print "</p>" }
    ' <<< "$text"
}

_render_body_rich_html() {
    local rtf_file="$1"
    [ -s "$rtf_file" ] || return 1
    local html
    html="$(textutil -convert html -stdout -- "$rtf_file" 2>/dev/null)"
    [ -z "$html" ] && return 1
    case "$html" in
        *"<body"*) : ;;
        *) return 1 ;;
    esac
    html="${html#*<body}"; html="${html#*>}"
    html="${html%%</body>*}"
    [ -z "$html" ] && return 1
    printf '%s' "$html" \
        | LC_ALL=C sed -E \
                       -e 's/ class="[^"]*"//g' \
                       -e 's/ style="[^"]*"//g' \
                       -e 's/ lang="[^"]*"//g' \
                       -e 's/ href="(https?|mailto|tel|sms|ftp|applenotes):/ HREF_OK_="\1:/gI' \
                       -e 's/ href="[A-Za-z][A-Za-z0-9+.-]*:[^"]*"/ href="#"/gI' \
                       -e 's/ HREF_OK_="/ href="/g'
}

_make_jpg_sibling_if_heic() { _maybe_sips_heic_sibling "$1"; }

_attachment_tag() {
    local rel="$1" basename
    basename="${rel##*/}"   # param-expansion, fork-free; $rel is already a relative path
    local ext="${basename##*.}"
    local _ul="ABCDEFGHIJKLMNOPQRSTUVWXYZ" _ll="abcdefghijklmnopqrstuvwxyz"
    local _lc="" _i _c _pre
    for (( _i=0; _i<${#ext}; _i++ )); do
        _c="${ext:_i:1}"
        _pre="${_ul%%"$_c"*}"
        [ "$_pre" != "$_ul" ] && _c="${_ll:${#_pre}:1}"
        _lc="$_lc$_c"
    done
    ext="$_lc"
    local en er
    en="$(html_escape "$basename")"
    er="$(_url_encode_path "$rel")"
    case "$ext" in
        heic|heif)
            local jpg_rel ej
            jpg_rel="${rel%.*}.jpg"
            ej="$(_url_encode_path "$jpg_rel")"
            printf '<a href="%s"><img src="%s" alt="%s"></a>' "$er" "$ej" "$en"
            ;;
        jpg|jpeg|png|gif|webp|tiff|tif|bmp)
            printf '<img src="%s" alt="%s">' "$er" "$en"
            ;;
        mov|mp4|m4v|webm)
            printf '<video controls src="%s">%s</video>' "$er" "$en"
            ;;
        m4a|mp3|wav|aac)
            printf '<audio controls src="%s">%s</audio>' "$er" "$en"
            ;;
        *)
            printf '<a href="%s">%s</a>' "$er" "$en"
            ;;
    esac
}

JOURNAL_DIR="$HOME/Library/Group Containers/group.com.apple.moments"
MOMENTS_DB="$JOURNAL_DIR/Library/moments.sqlite"
ATTACHMENTS_BASE="$JOURNAL_DIR/Library/Attachments"

_journal_idx_rows() {
    local _rel _date _title _jrnl _e1 _e2 _e3
    LC_ALL=C sort -t "$(printf '\x1f')" -k2,2 "$_mf" | \
        while IFS="$(printf '\x1f')" read -r _rel _date _title; do
        printf '<tr>'
        html_escape "$_date" _e1
        printf '<td class="d">%s</td>' "$_e1"
        html_escape "${_title:-(untitled)}" _e2
        printf '<td><a href="%s">%s</a></td>' "$(_url_encode_path "$_rel")" "$_e2"
        if [ "$_multi" = "yes" ]; then
            case "$_rel" in */*) _jrnl="${_rel%%/*}" ;; *) _jrnl="" ;; esac
            html_escape "${_jrnl:-—}" _e3
            printf '<td>%s</td>' "$_e3"
        fi
        printf '</tr>\n'
    done
}

_journal_emit_index() {
    local _mf="$1" _nc="$2" _root="$3" _multi="$4"
    local _idx_title _idx_h1 _idx_extra_css _idx_thead _idx_rows_fn
    _idx_title="Journal ($_nc)"
    _idx_h1="Journal — $_nc $(_pluralize "$_nc" entry entries)"
    _idx_extra_css='td.d{white-space:nowrap;color:#555;}'
    _idx_thead="<tr><th>Date</th><th>Entry</th>$([ "$_multi" = "yes" ] && printf '<th>Journal</th>')</tr>"
    _idx_rows_fn=_journal_idx_rows
    _emit_html_index "$_root/index.html" "Journal/index.html"
}

journal_main() {
    maybe_show_help "$@"
    _announce_step "Journal export"
    check_dependencies
    local out_arg out_dir
    out_arg="$(_parse_output_folder_arg "$@")" || exit 1
    out_dir="$(resolve_output_dir "$out_arg")" || exit 1
    _announce_output_dir "Journal"
    require_full_disk_access
    warn_if_app_running Journal
    if [ ! -f "$MOMENTS_DB" ]; then
        report_no_source "Journal" "not configured" "$MOMENTS_DB" "Journal"
    fi
    local out_root="$out_dir/Journal"
    require_no_collision "$out_root"
    ensure_scratch
    log_info "Snapshotting moments.sqlite..."
    log_info "Source: $MOMENTS_DB"
    local snap
    snap="$(snapshot_db_or_die "$MOMENTS_DB" "Journal")" || exit 1
    if ! sqlite3 -readonly "$snap" "SELECT 1 FROM ZJOURNALENTRYMO LIMIT 1;" >/dev/null 2>&1; then
        local _avail
        _avail="$(sqlite3 -readonly "$snap" \
            "SELECT GROUP_CONCAT(name, ', ') FROM sqlite_master \
              WHERE type='table' AND name LIKE 'Z%';" 2>/dev/null)"
        die "Journal schema not recognised — ZJOURNALENTRYMO not queryable
  (Available tables: ${_avail:-none})"
    fi
    local _att_base_present=0
    if [ ! -d "$ATTACHMENTS_BASE" ]; then
        log_info "Attachments dir not present — skipping attachment recovery."
        log_info "(Looked for: $ATTACHMENTS_BASE)"
    else
        _att_base_present=1
    fi
    log_info "Probing schema (columns, asset tables)..."
    local _cols _c
    local _jrc
    _cols="$(sqlite3 -readonly "$snap" \
        "SELECT name FROM pragma_table_info('ZJOURNALENTRYMO');" 2>/dev/null)"
    _jrc=$?
    [ "$_jrc" -ne 0 ] && _probe_miss error ZJOURNALENTRYMO '*'
    local jcol_date jcol_title jcol_text jcol_richtext
    local jcol_flagged jcol_type
    local jcol_deleted jcol_removed jcol_textlen
    local jcol_weather jcol_temp jcol_lat jcol_lon jcol_location jcol_timezone jcol_mood
    local jcol_moddate jcol_placename
    local jcol_weather_high jcol_weather_low jcol_weather_humidity jcol_weather_code
    jcol_date="$(printf '%s\n' "$_cols" | grep -m1 '^ZENTRYDATE$')"
    jcol_title="$(printf '%s\n' "$_cols" | grep -m1 '^ZTITLE$')"
    jcol_text="$(printf '%s\n' "$_cols" | grep -m1 '^ZTEXT$')"
    jcol_richtext="$(printf '%s\n' "$_cols" | grep -m1 '^ZRICHTEXTDATA$')"
    [ -n "$jcol_richtext" ] && jcol_text="$jcol_richtext"
    jcol_flagged="$(printf '%s\n' "$_cols" | grep -m1 '^ZFLAGGED$')"
    jcol_type="$(printf '%s\n' "$_cols" | grep -m1 '^ZENTRYTYPE$')"
    jcol_deleted="$(printf '%s\n' "$_cols" | grep -m1 '^ZRECENTLYDELETED$')"
    jcol_removed="$(printf '%s\n' "$_cols" | grep -m1 '^ZISFULLYREMOVED$')"
    jcol_textlen="$(printf '%s\n' "$_cols" | grep -m1 '^ZTEXTLENGTH$')"
    jcol_weather="$(printf '%s\n' "$_cols" | grep -m1 '^ZWEATHERCONDITION$')"
    jcol_temp="$(printf '%s\n' "$_cols" | grep -m1 '^ZWEATHERTEMPERATURE$')"
    jcol_lat="$(printf '%s\n' "$_cols" | grep -m1 '^ZLATITUDE$')"
    jcol_lon="$(printf '%s\n' "$_cols" | grep -m1 '^ZLONGITUDE$')"
    jcol_location="$(printf '%s\n' "$_cols" | grep -m1 '^ZLOCATION$')"
    jcol_timezone="$(_pick_first_col "$snap" ZJOURNALENTRYMO \
                        ZTIMEZONE ZTIMEZONENAME)"
    jcol_mood="$(_pick_first_col "$snap" ZJOURNALENTRYMO \
                    ZSTATEOFMIND ZMOODVALENCE ZMENTALSTATE ZEMOTION)"
    jcol_moddate="$(_pick_first_col "$snap" ZJOURNALENTRYMO \
                       ZUPDATEDDATE ZENTRYDATAUPDATEDATE \
                       ZMODIFICATIONDATE ZLASTMODIFIEDDATE)"
    jcol_placename="$(_pick_first_col "$snap" ZJOURNALENTRYMO \
                         ZPLACENAME ZLOCATIONNAME ZADDRESS ZPLACE)"
    jcol_weather_high="$(_pick_first_col "$snap" ZJOURNALENTRYMO \
                            ZWEATHERHIGHTEMPERATURE ZWEATHERTEMPERATUREHIGH ZWEATHERHIGHTEMP)"
    jcol_weather_low="$(_pick_first_col "$snap" ZJOURNALENTRYMO \
                           ZWEATHERLOWTEMPERATURE ZWEATHERTEMPERATURELOW ZWEATHERLOWTEMP)"
    jcol_weather_humidity="$(_pick_first_col "$snap" ZJOURNALENTRYMO \
                                ZWEATHERHUMIDITY ZWEATHERRELATIVEHUMIDITY)"
    jcol_weather_code="$(_pick_first_col "$snap" ZJOURNALENTRYMO \
                            ZWEATHERCONDITIONCODE ZWEATHERCODE)"
    [ -z "$jcol_date" ] && jcol_date="ZENTRYDATE"
    [ -z "$jcol_title" ] && jcol_title="ZTITLE"
    [ -z "$jcol_text" ] && jcol_text="ZTEXT"
    [ -z "$jcol_deleted" ] && jcol_deleted="ZRECENTLYDELETED"
    [ -z "$jcol_removed" ] && jcol_removed="ZISFULLYREMOVED"
    for _c in "$jcol_date" "$jcol_title" "$jcol_text" "$jcol_flagged" \
              "$jcol_type" "$jcol_deleted" \
              "$jcol_removed" "$jcol_textlen" "$jcol_weather" \
              "$jcol_temp" "$jcol_lat" "$jcol_lon" "$jcol_location" \
              "$jcol_timezone" "$jcol_mood" "$jcol_moddate" \
              "$jcol_placename" "$jcol_weather_high" "$jcol_weather_low" \
              "$jcol_weather_humidity" "$jcol_weather_code"; do
        [ -z "$_c" ] && continue
        case "$_c" in *[!A-Za-z0-9_]*) die "Journal: unsafe column name '$_c'" ;; esac
    done
    [ -n "$jcol_timezone" ] && [ "$jcol_timezone" != "ZTIMEZONE" ] && \
        log_info "Schema: timezone = $jcol_timezone (legacy)"
    [ -n "$jcol_mood" ] && [ "$jcol_mood" != "ZSTATEOFMIND" ] && \
        log_info "Schema: mood = $jcol_mood (legacy)"
    [ -n "$jcol_moddate" ] && [ "$jcol_moddate" != "ZUPDATEDDATE" ] && \
        log_info "Schema: modification-date = $jcol_moddate (legacy)"
    [ -n "$jcol_placename" ] && [ "$jcol_placename" != "ZPLACENAME" ] && \
        log_info "Schema: place-name = $jcol_placename (legacy)"
    local _J_HAS_CONTENT="(COALESCE(ZJOURNALENTRYMO.$jcol_textlen, 0) > 0
           OR COALESCE(length(ZJOURNALENTRYMO.$jcol_text), 0) > 0)"
    if [ -z "$jcol_textlen" ]; then
        _J_HAS_CONTENT="(COALESCE(length(ZJOURNALENTRYMO.$jcol_text), 0) > 0)"
    fi
    local _J_LIVE_FILTER="(
             (COALESCE(ZJOURNALENTRYMO.$jcol_deleted, 0) = 0
              AND COALESCE(ZJOURNALENTRYMO.$jcol_removed, 0) = 0)
             OR $_J_HAS_CONTENT
           )"
    local _tables has_asset_table="no" has_file_att_table="no"
    local _jt_rc
    _tables="$(sqlite3 -readonly "$snap" "SELECT name FROM sqlite_master WHERE type='table';" 2>/dev/null)"
    _jt_rc=$?
    [ "$_jt_rc" -ne 0 ] && _probe_miss error sqlite_master '*'
    if _col_in_list "$_tables" 'ZJOURNALENTRYASSETMO'; then
        has_asset_table="yes"
    fi
    if _col_in_list "$_tables" 'ZJOURNALENTRYASSETFILEATTACHMENTMO'; then
        has_file_att_table="yes"
        local _fa_cols _fa_need _fa_missing="" _fa_rc
        _fa_cols="$(sqlite3 -readonly "$snap" \
            "SELECT name FROM pragma_table_info('ZJOURNALENTRYASSETFILEATTACHMENTMO');" \
            2>/dev/null)"
        _fa_rc=$?
        [ "$_fa_rc" -ne 0 ] && _probe_miss error ZJOURNALENTRYASSETFILEATTACHMENTMO '*'
        for _fa_need in ZFILEPATH ZNAME ZASSET ZINDEX; do
            _col_in_list "$_fa_cols" "$_fa_need" \
                || _fa_missing="$_fa_missing $_fa_need"
        done
        if [ -n "$_fa_missing" ]; then
            log_warn "Journal: ZJOURNALENTRYASSETFILEATTACHMENTMO is missing required column(s):$_fa_missing — falling back to legacy ZJOURNALENTRYASSETMO lookup for attachments"
            if [ "${_fa_rc:-0}" -eq 0 ]; then
                for _fa_need in $_fa_missing; do
                    _probe_miss absent ZJOURNALENTRYASSETFILEATTACHMENTMO "$_fa_need"
                done
            fi
            has_file_att_table="no"
        fi
    fi
    local _has_multi_journal=0
    local _journal_join_table="" _journal_entries_col="" _journal_journals_col=""
    local _journal_count=0
    if [ "${JOURNAL_MULTI_FOLDER:-1}" = "1" ] && \
       _col_in_list "$_tables" 'ZJOURNALMO'; then
        local _journal_join_candidates _jj_rc
        _journal_join_table="$(_discover_z_join "$snap" JOURNALS)"; _jj_rc=$?
        if [ "$_jj_rc" -eq 2 ]; then
            _journal_join_candidates="$(sqlite3 -readonly "$snap" \
                "SELECT name FROM sqlite_master
                  WHERE type='table' AND name GLOB 'Z_[0-9]*JOURNALS'
                  ORDER BY name;" 2>/dev/null)"
            log_info "Schema: multiple Z_<N>JOURNALS join tables present ($_journal_join_candidates) — picking the one with the most rows"
            local _jjc _best_count=-1 _best_name=""
            while IFS= read -r _jjc; do
                [ -z "$_jjc" ] && continue
                case "$_jjc" in
                    *[!A-Za-z0-9_]*) continue ;;
                esac
                local _jjc_count
                _jjc_count="$(sqlite3 -readonly "$snap" "SELECT COUNT(*) FROM $_jjc;" 2>/dev/null)"
                case "${_jjc_count:-0}" in ''|*[!0-9]*) _jjc_count=0 ;; esac
                if [ "$_jjc_count" -gt "$_best_count" ]; then
                    _best_count="$_jjc_count"
                    _best_name="$_jjc"
                fi
            done <<< "$_journal_join_candidates"
            _journal_join_table="$_best_name"
        fi
        case "$_journal_join_table" in
            Z_*JOURNALS) : ;;
            *) _journal_join_table="" ;;
        esac
        case "$_journal_join_table" in
            *[!A-Za-z0-9_]*) _journal_join_table="" ;;
        esac
        if [ -n "$_journal_join_table" ]; then
            _journal_entries_col="$(sqlite3 -readonly "$snap" \
                "SELECT name FROM pragma_table_info('$_journal_join_table')
                  WHERE name GLOB 'Z_[0-9]*ENTRIES' LIMIT 1;" 2>/dev/null)"
            _journal_journals_col="$(sqlite3 -readonly "$snap" \
                "SELECT name FROM pragma_table_info('$_journal_join_table')
                  WHERE name GLOB 'Z_[0-9]*JOURNALS' LIMIT 1;" 2>/dev/null)"
            case "$_journal_entries_col" in *[!A-Za-z0-9_]*) _journal_entries_col="" ;; esac
            case "$_journal_journals_col" in *[!A-Za-z0-9_]*) _journal_journals_col="" ;; esac
        fi
        if [ -n "$_journal_join_table" ] && [ -n "$_journal_entries_col" ] \
           && [ -n "$_journal_journals_col" ]; then
            _journal_count="$(sqlite3 -readonly "$snap" \
                "SELECT COUNT(*) FROM ZJOURNALMO
                  WHERE COALESCE(ZUSERDELETED, 0) = 0;" 2>/dev/null)"
            case "${_journal_count:-0}" in ''|*[!0-9]*) _journal_count=0 ;; esac
        fi
        if [ "$_journal_count" -gt 1 ]; then
            _has_multi_journal=1
            local _jpk _jidx=0
            while IFS= read -r _jpk; do
                [ -z "$_jpk" ] && continue
                case "$_jpk" in *[!0-9]*) continue ;; esac
                _jidx=$((_jidx + 1))
                printf -v "_jl_$_jpk" '%s' "Journal $_jidx"
            done < <(sqlite3 -readonly "$snap" \
                "SELECT Z_PK FROM ZJOURNALMO
                  WHERE COALESCE(ZUSERDELETED, 0) = 0
                  ORDER BY Z_PK ASC;" 2>/dev/null)
            log_info "Multi-journal: $_journal_count journals — entries will land in 'Journal N' subfolders (set JOURNAL_MULTI_FOLDER=0 to force flat output)"
        fi
    fi
    _journal_label_for() {
        case "$1" in ''|*[!0-9]*) return 0 ;; esac
        local _ref="_jl_$1"
        printf '%s' "${!_ref:-}"
    }
    local _acol_entry _acol_atitle
    if [ "$has_asset_table" = "yes" ]; then
        _acol_entry="$(_pick_first_col "$snap" ZJOURNALENTRYASSETMO ZENTRY ZENTRY1 ZENTRY2)"
        _acol_atitle="$(_pick_first_col "$snap" ZJOURNALENTRYASSETMO ZTITLE ZTITLE1 ZTITLE2)"
        [ -z "$_acol_entry" ] && _acol_entry="ZENTRY"
        [ -z "$_acol_atitle" ] && _acol_atitle="ZTITLE"
        case "$_acol_entry" in *[!A-Za-z0-9_]*) die "Journal: unsafe asset entry column '$_acol_entry'" ;; esac
        case "$_acol_atitle" in *[!A-Za-z0-9_]*) die "Journal: unsafe asset title column '$_acol_atitle'" ;; esac
    fi
    local _J_ATTACH_EXISTS=""
    if [ "$has_asset_table" = "yes" ]; then
        _J_ATTACH_EXISTS="EXISTS (SELECT 1 FROM ZJOURNALENTRYASSETMO a
                       WHERE a.$_acol_entry = ZJOURNALENTRYMO.Z_PK)"
        _J_HAS_CONTENT="($_J_HAS_CONTENT
           OR $_J_ATTACH_EXISTS)"
        _J_LIVE_FILTER="(
             (COALESCE(ZJOURNALENTRYMO.$jcol_deleted, 0) = 0
              AND COALESCE(ZJOURNALENTRYMO.$jcol_removed, 0) = 0)
             OR $_J_HAS_CONTENT
           )"
    fi
    local _entry_type_filter=""
    if [ -n "$jcol_type" ] && [ "${JOURNAL_INCLUDE_ALL_TYPES:-0}" != "1" ]; then
        local _et_dist
        _et_dist="$(sqlite3 -readonly -separator $'\t' "$snap" "
            SELECT COALESCE($jcol_type, 'NULL') AS t, COUNT(*)
              FROM ZJOURNALENTRYMO
             WHERE $_J_LIVE_FILTER
             GROUP BY t ORDER BY t;" 2>/dev/null)"
        local _et_storage
        _et_storage="$(sqlite3 -readonly "$snap" "
            SELECT typeof($jcol_type) FROM ZJOURNALENTRYMO
             WHERE $jcol_type IS NOT NULL
             LIMIT 1;" 2>/dev/null)"
        local _et_kind="numeric"
        case "$_et_storage" in
            text) _et_kind="string" ;;
        esac
        if [ "$_et_kind" = "string" ]; then
            local _et_text_guard="COALESCE(ZJOURNALENTRYMO.$jcol_textlen, 0) > 0
                          OR (ZJOURNALENTRYMO.$jcol_text IS NOT NULL
                              AND length(ZJOURNALENTRYMO.$jcol_text) > 0)"
            if [ -z "$jcol_textlen" ]; then
                _et_text_guard="ZJOURNALENTRYMO.$jcol_text IS NOT NULL
                              AND length(ZJOURNALENTRYMO.$jcol_text) > 0"
            fi
            [ -n "$_J_ATTACH_EXISTS" ] && _et_text_guard="$_et_text_guard
                          OR $_J_ATTACH_EXISTS"
            _entry_type_filter="AND (ZJOURNALENTRYMO.$jcol_type = 'blankEntry'
               OR ZJOURNALENTRYMO.$jcol_type IS NULL
               OR ($_et_text_guard))"
        else
            local _et_text_guard_num="ZJOURNALENTRYMO.$jcol_text IS NOT NULL
                              AND length(ZJOURNALENTRYMO.$jcol_text) > 0"
            [ -n "$jcol_textlen" ] && \
                _et_text_guard_num="COALESCE(ZJOURNALENTRYMO.$jcol_textlen, 0) > 0
                              OR $_et_text_guard_num"
            [ -n "$_J_ATTACH_EXISTS" ] && _et_text_guard_num="$_et_text_guard_num
                          OR $_J_ATTACH_EXISTS"
            _entry_type_filter="AND (COALESCE(ZJOURNALENTRYMO.$jcol_type, 0) = 0
               OR ($_et_text_guard_num))"
        fi
        if printf '%s\n' "$_et_dist" | LC_ALL=C awk -F'\t' 'END{exit !(NR>1)}'; then
            log_info "ZENTRYTYPE distribution: $(printf '%s' "$_et_dist" | LC_ALL=C tr '\t' '=' | LC_ALL=C tr '\n' ' ')"
            if [ "$_et_kind" = "string" ]; then
                log_info "Filtering to user-authored entries (ZENTRYTYPE='blankEntry'/NULL or any entry with text). Set JOURNAL_INCLUDE_ALL_TYPES=1 to export everything."
            else
                log_info "Filtering to ZENTRYTYPE=0 (user-authored). Set JOURNAL_INCLUDE_ALL_TYPES=1 to export everything."
            fi
        fi
    fi
    local _rd_skipped_tombstones=0
    local _n_tombstone
    _n_tombstone="$(sqlite3 -readonly "$snap" "
        SELECT COUNT(*) FROM ZJOURNALENTRYMO
         WHERE (COALESCE($jcol_deleted, 0) = 1
                OR COALESCE($jcol_removed, 0) = 1)
           AND NOT $_J_HAS_CONTENT;" 2>/dev/null)"
    case "${_n_tombstone:-0}" in
        ''|*[!0-9]*) : ;;
        *) _rd_skipped_tombstones=$_n_tombstone ;;
    esac
    local n_entries n_entries_discovery_ok=1
    n_entries="$(sqlite3 -readonly "$snap" "
        SELECT COUNT(*) FROM ZJOURNALENTRYMO
         WHERE $_J_LIVE_FILTER
           $_entry_type_filter;" 2>/dev/null)"
    case "$n_entries" in
        ''|*[!0-9]*) n_entries_discovery_ok=0 ;;
    esac
    if [ "$n_entries_discovery_ok" = "0" ]; then
        log_warn "Journal entry-count query failed — proceeding without a discovery baseline; the drift check will surface this as a verification gap."
        n_entries=0
    fi
    if [ "$n_entries" = "0" ] && [ "$n_entries_discovery_ok" = "1" ]; then
        report_empty_source "journal entries" "Journal"
    fi
    if [ "$n_entries_discovery_ok" = "1" ]; then
        log_info "Found $n_entries $(_pluralize "$n_entries" entry entries)"
    else
        log_info "Entry count could not be determined — proceeding with per-entry SELECT (may be partial)"
    fi
    _create_output_dir "$out_root"
    local sel_weather="''" sel_temp="''" sel_lat="''" sel_lon="''" sel_loc="''" sel_tz="''" sel_mood="''"
    local sel_moddate="''" sel_placename="''"
    local sel_flagged="0"
    [ -n "$jcol_flagged" ] && sel_flagged="COALESCE(ZJOURNALENTRYMO.$jcol_flagged, 0)"
    local sel_weather_high="''" sel_weather_low="''"
    local sel_weather_humidity="''" sel_weather_code="''"
    [ -n "$jcol_weather" ] && sel_weather="$(_sql_tsv_safe "COALESCE(ZJOURNALENTRYMO.$jcol_weather, '')")"
    [ -n "$jcol_temp" ]    && sel_temp="$(_sql_tsv_safe "COALESCE(ZJOURNALENTRYMO.$jcol_temp, '')")"
    [ -n "$jcol_lat" ]     && sel_lat="$(_sql_tsv_safe "COALESCE(ZJOURNALENTRYMO.$jcol_lat, '')")"
    [ -n "$jcol_lon" ]     && sel_lon="$(_sql_tsv_safe "COALESCE(ZJOURNALENTRYMO.$jcol_lon, '')")"
    [ -n "$jcol_location" ] && sel_loc="$(_sql_tsv_safe "COALESCE(ZJOURNALENTRYMO.$jcol_location, '')")"
    [ -n "$jcol_timezone" ] && sel_tz="$(_sql_tsv_safe "COALESCE(ZJOURNALENTRYMO.$jcol_timezone, '')")"
    [ -n "$jcol_mood" ]    && sel_mood="$(_sql_tsv_safe "COALESCE(ZJOURNALENTRYMO.$jcol_mood, '')")"
    [ -n "$jcol_moddate" ] && sel_moddate="$(_sql_tsv_safe "COALESCE(ZJOURNALENTRYMO.$jcol_moddate, '')")"
    [ -n "$jcol_weather_high" ]     && sel_weather_high="$(_sql_tsv_safe "COALESCE(ZJOURNALENTRYMO.$jcol_weather_high, '')")"
    [ -n "$jcol_weather_low" ]      && sel_weather_low="$(_sql_tsv_safe "COALESCE(ZJOURNALENTRYMO.$jcol_weather_low, '')")"
    [ -n "$jcol_weather_humidity" ] && sel_weather_humidity="$(_sql_tsv_safe "COALESCE(ZJOURNALENTRYMO.$jcol_weather_humidity, '')")"
    [ -n "$jcol_weather_code" ]     && sel_weather_code="$(_sql_tsv_safe "COALESCE(ZJOURNALENTRYMO.$jcol_weather_code, '')")"
    if [ -n "$jcol_placename" ]; then
        sel_placename="$(_sql_tsv_safe "COALESCE(ZJOURNALENTRYMO.$jcol_placename, '')")"
    fi
    local exported=0 empty_count=0 total_attachments=0 stub_count=0 _attachments_missing=0 _entry_write_failed=0 _rd_exported=0
    local _attachments_copyfail=0
    ensure_scratch
    local _journal_stubs_tsv="$SCRATCH_DIR/journal_stubs.tsv"
    : > "$_journal_stubs_tsv"
    local _journal_join_sql="" _journal_pk_sel=", 0 AS journal_pk"
    local _journal_group_sql=""
    if [ "$_has_multi_journal" = "1" ]; then
        _journal_join_sql="
        LEFT JOIN $_journal_join_table jt
                  ON jt.$_journal_entries_col = ZJOURNALENTRYMO.Z_PK
        LEFT JOIN ZJOURNALMO j
                  ON j.Z_PK = jt.$_journal_journals_col
                  AND COALESCE(j.ZUSERDELETED, 0) = 0"
        _journal_pk_sel=", COALESCE(MIN(j.Z_PK), 0) AS journal_pk"
        _journal_group_sql="
         GROUP BY ZJOURNALENTRYMO.Z_PK"
    fi
    log_info "Bulk-extracting title and body RTF for $n_entries $(_pluralize "$n_entries" entry entries)..."
    if ! sqlite3 -readonly "$snap" "
        SELECT writefile('$SCRATCH_DIR/jentry_title_' || Z_PK || '.rtf', $jcol_title)
          FROM ZJOURNALENTRYMO
         WHERE $_J_LIVE_FILTER
           $_entry_type_filter
           AND $jcol_title IS NOT NULL
           AND length($jcol_title) > 0;
    " >/dev/null 2>&1; then
        log_warn "Bulk-extract of entry titles failed; per-entry titles may be missing."
        note_incomplete "$out_root" "Journal entry titles" \
            "the bulk extraction of entry titles from the database failed — per-entry .html files may render as \"(untitled)\" / friendly-name fallback even though the entries themselves were emitted with full body content"
    fi
    if ! sqlite3 -readonly "$snap" "
        SELECT writefile('$SCRATCH_DIR/jentry_body_' || Z_PK || '.rtf', $jcol_text)
          FROM ZJOURNALENTRYMO
         WHERE $_J_LIVE_FILTER
           $_entry_type_filter
           AND $jcol_text IS NOT NULL
           AND length($jcol_text) > 0;
    " >/dev/null 2>&1; then
        log_warn "Bulk-extract of entry bodies failed; per-entry bodies may be missing."
        note_incomplete "$out_root" "Journal entry body text" \
            "the bulk extraction of entry bodies from the database failed — the per-entry .html files may have empty or missing body content even though the entries themselves were emitted"
    fi
    local _legacy_att_index="" _legacy_att_root="" _legacy_att_index_built=0
    _ensure_legacy_att_index() {
        [ "$_legacy_att_index_built" = "1" ] && return 0
        _legacy_att_index_built=1
        if [ -d "$JOURNAL_DIR/Library/Attachments" ]; then
            _legacy_att_root="$JOURNAL_DIR/Library/Attachments"
        elif [ -d "$JOURNAL_DIR/Library" ]; then
            _legacy_att_root="$JOURNAL_DIR/Library"
        fi
        [ -n "$_legacy_att_root" ] || return 0
        _legacy_att_index="$SCRATCH_DIR/journal_legacy_att_index"
        find "$_legacy_att_root" -type f ! -type l 2>/dev/null \
            | LC_ALL=C awk '
                { n = $0; sub(/.*\//, "", n);
                  if (!(n in seen)) { seen[n] = 1; print } }' \
            > "$_legacy_att_index" 2>/dev/null || _legacy_att_index=""
        [ -s "$_legacy_att_index" ] || _legacy_att_index=""
    }
    log_info "Emitting per-entry HTML..."
    local _pt_last=0 _pt_inline=0
    local _html_validated=0
    local _journal_index="$SCRATCH_DIR/journal_index.tsv"
    : > "$_journal_index" 2>/dev/null || true
    local pk entry_date_raw flagged j_weather j_temp j_lat j_lon j_loc j_tz j_mood
    local j_moddate j_placename j_weather_high j_weather_low j_weather_humidity j_weather_code is_deleted journal_pk
    while IFS=$'\x1f' read -r pk entry_date_raw flagged \
            j_weather j_temp j_lat j_lon j_loc j_tz j_mood \
            j_moddate j_placename j_weather_high j_weather_low \
            j_weather_humidity j_weather_code is_deleted journal_pk; do
        [ -z "$pk" ] && continue
        case "$pk" in *[!0-9]*) continue ;; esac
        local _target_dir="$out_root"
        if [ "$_has_multi_journal" = "1" ] && [ -n "$journal_pk" ] \
           && [ "$journal_pk" != "0" ]; then
            case "$journal_pk" in *[!0-9]*) : ;; *)
                local _jlabel
                _jlabel="$(_journal_label_for "$journal_pk")"
                if [ -n "$_jlabel" ]; then
                    _target_dir="$out_root/$_jlabel"
                    if [ ! -d "$_target_dir" ]; then
                        if mkdir -p "$_target_dir" 2>/dev/null; then
                            track_output_path "$_target_dir"
                        else
                            log_warn "Cannot create journal subfolder $_target_dir; emitting this entry flat under $out_root."
                            _target_dir="$out_root"
                        fi
                    fi
                fi
            ;; esac
        fi
        if [ "${is_deleted:-0}" = "1" ]; then
            _target_dir="$out_root/Recently Deleted"
            if [ ! -d "$_target_dir" ]; then
                if mkdir -p "$_target_dir" 2>/dev/null; then
                    track_output_path "$_target_dir"
                else
                    log_warn "Cannot create Recently Deleted subfolder $_target_dir; emitting this entry flat under $out_root."
                    _target_dir="$out_root"
                fi
            fi
        fi
        local _epoch_int="" iso_date="" file_date="undated" entry_date_fmt="(unknown)"
        _epoch_int="$(_cd_ts_to_unix "$entry_date_raw")"
        local _entry_tz=""
        if [ -n "$j_tz" ]; then
            case "$j_tz" in
                *[!A-Za-z0-9/_+-]*) ;;
                *) _entry_tz="$j_tz" ;;
            esac
        fi
        if [ -n "$_epoch_int" ]; then
            if [ -n "$_entry_tz" ]; then
                iso_date="$(TZ="$_entry_tz" date -r "$_epoch_int" +%Y-%m-%dT%H:%M:%S%z 2>/dev/null)"
                file_date="$(TZ="$_entry_tz" date -r "$_epoch_int" +%Y-%m-%d 2>/dev/null)"
                entry_date_fmt="$(TZ="$_entry_tz" date -r "$_epoch_int" +'%Y-%m-%d %H:%M:%S %Z' 2>/dev/null)"
            else
                _epoch_to_utc_iso_into "$_epoch_int" iso_date
                file_date="$(date -r "$_epoch_int" +%Y-%m-%d 2>/dev/null)"
                entry_date_fmt="$(date -r "$_epoch_int" +'%Y-%m-%d %H:%M:%S' 2>/dev/null)"
            fi
        fi
        [ -z "$file_date" ] && file_date="undated"
        [ -z "$entry_date_fmt" ] && entry_date_fmt="(unknown)"
        local _mod_iso=""
        if [ -n "${j_moddate:-}" ] && [ "$j_moddate" != "0" ]; then
            local _mod_epoch=""
            _mod_epoch="$(_cd_ts_to_unix "$j_moddate")"
            if [ -n "$_mod_epoch" ]; then
                if [ -n "$_entry_tz" ]; then
                    _mod_iso="$(TZ="$_entry_tz" date -r "$_mod_epoch" +%Y-%m-%dT%H:%M:%S%z 2>/dev/null)"
                else
                    _epoch_to_utc_iso_into "$_mod_epoch" _mod_iso
                fi
            fi
        fi
        local title_text="" rtf_title="$SCRATCH_DIR/jentry_title_$pk.rtf"
        if [ -s "$rtf_title" ]; then
            title_text="$(textutil -convert txt -stdout -- "$rtf_title" 2>/dev/null)"
            while [ -n "$title_text" ] && \
                  { [ "${title_text: -1}" = $'\n' ] || \
                    [ "${title_text: -1}" = $'\r' ]; }; do
                title_text="${title_text%?}"
            done
            rm -f -- "$rtf_title" 2>/dev/null
        fi
        [ -z "$title_text" ] && title_text="(untitled)"
        local safe_title base_name target
        safe_title="$(_sanitize_name "$title_text")"
        base_name="${file_date}_${safe_title}_${pk}"
        target="$(_unique_path "$_target_dir/$base_name.html")"
        local body_text="" body_html_rich="" rtf_body="$SCRATCH_DIR/jentry_body_$pk.rtf"
        if [ -s "$rtf_body" ]; then
            body_html_rich="$(_render_body_rich_html "$rtf_body")"
            body_text="$(textutil -convert txt -stdout -- "$rtf_body" 2>/dev/null)"
            rm -f -- "$rtf_body" 2>/dev/null
        fi
        local _att_stem="${target##*/}"; _att_stem="${_att_stem%.html}"
        local att_dir="$_target_dir/$_att_stem.attachments"
        local att_count=0 att_html_inline=""
        local _src _dst _basename
        local _modern_saw_row=0
        if [ "$has_file_att_table" = "yes" ] && [ "$has_asset_table" = "yes" ]; then
            local _fpath _fname
            while IFS=$'\x1f' read -r _fpath _fname; do
                [ -z "$_fpath" ] && continue
                _modern_saw_row=1
                _src=""
                if [ -n "$ATTACHMENTS_BASE" ] && [ -f "$ATTACHMENTS_BASE/$_fpath" ]; then
                    _src="$ATTACHMENTS_BASE/$_fpath"
                fi
                if [ -z "$_src" ] && [ -n "$ATTACHMENTS_BASE" ]; then
                    if _icloud_stub_sibling_for "$ATTACHMENTS_BASE/$_fpath" >/dev/null; then
                        stub_count=$((stub_count + 1))
                        printf '%s\x1f%s\n' "$base_name" "${_fpath##*/}" \
                            >> "$_journal_stubs_tsv"
                        continue
                    fi
                fi
                if [ -z "$_src" ]; then
                    [ "$_att_base_present" = "1" ] && \
                        _attachments_missing=$((_attachments_missing + 1))
                    continue
                fi
                if is_icloud_stub "$_src"; then
                    stub_count=$((stub_count + 1))
                    printf '%s\x1f%s\n' "$base_name" \
                        "$(_strip_icloud_stub_name "${_src##*/}")" \
                        >> "$_journal_stubs_tsv"
                    continue
                fi
                _basename="${_fpath##*/}"
                if [ "$att_count" -eq 0 ]; then
                    if ! mkdir -p "$att_dir" 2>/dev/null; then
                        log_warn "Failed to create attachment dir for entry $base_name — remaining attachments discarded."
                        note_incomplete "$out_root" \
                            "Journal entry $base_name attachments" \
                            "could not create $att_dir; remaining attachment rows for this entry were dropped"
                        break
                    fi
                fi
                _dst="$(_unique_path "$att_dir/$_basename")"
                if _ditto_verified "$_src" "$_dst"; then
                    att_count=$((att_count + 1))
                    _make_jpg_sibling_if_heic "$_dst"
                    att_html_inline="$att_html_inline$(_attachment_tag "$_att_stem.attachments/${_dst##*/}")"$'\n'
                else
                    _attachments_copyfail=$((_attachments_copyfail + 1))
                    log_warn "Failed to copy attachment '$_basename' for entry $base_name."
                fi
            done < <(sqlite3 -readonly -separator $'\x1f' "$snap" "
                SELECT COALESCE(f.ZFILEPATH, ''),
                       COALESCE(f.ZNAME, '')
                  FROM ZJOURNALENTRYASSETFILEATTACHMENTMO f
                  JOIN ZJOURNALENTRYASSETMO a ON f.ZASSET = a.Z_PK
                 WHERE a.$_acol_entry = $pk
                 ORDER BY COALESCE(f.ZINDEX, 0), f.Z_PK ASC;" 2>/dev/null)
        fi
        local -a _seen_legacy_src=()
        if [ "$att_count" -eq 0 ] && [ "$_modern_saw_row" = "0" ] \
           && [ "$has_asset_table" = "yes" ]; then
            _ensure_legacy_att_index
            local _a_pk _a_title
            while IFS=$'\x1f' read -r _a_pk _a_title; do
                [ -z "$_a_pk" ] && continue
                _src=""
                if [ -n "$_a_title" ]; then
                    local _wanted
                    _wanted="${_a_title##*/}"
                    if [ -n "$_legacy_att_index" ]; then
                        _src="$(_wanted="$_wanted" LC_ALL=C awk '
                            BEGIN { want = ENVIRON["_wanted"] }
                            { n = $0; sub(/.*\//, "", n); if (n == want) { print; exit } }' \
                            "$_legacy_att_index" 2>/dev/null)"
                    fi
                fi
                [ -z "$_src" ] && continue
                local _already=0 _ss
                for _ss in "${_seen_legacy_src[@]+"${_seen_legacy_src[@]}"}"; do
                    [ "$_ss" = "$_src" ] && { _already=1; break; }
                done
                [ "$_already" = "1" ] && continue
                _seen_legacy_src+=( "$_src" )
                if is_icloud_stub "$_src"; then
                    stub_count=$((stub_count + 1))
                    printf '%s\x1f%s\n' "$base_name" \
                        "$(_strip_icloud_stub_name "${_src##*/}")" \
                        >> "$_journal_stubs_tsv"
                    continue
                fi
                _basename="${_src##*/}"
                if [ "$att_count" -eq 0 ]; then
                    if ! mkdir -p "$att_dir" 2>/dev/null; then
                        log_warn "Failed to create attachment dir for entry $base_name (legacy path) — remaining attachments discarded."
                        note_incomplete "$out_root" \
                            "Journal entry $base_name attachments (legacy path)" \
                            "could not create $att_dir; remaining attachment rows for this entry were dropped"
                        break
                    fi
                fi
                _dst="$(_unique_path "$att_dir/$_basename")"
                if _ditto_verified "$_src" "$_dst"; then
                    att_count=$((att_count + 1))
                    _make_jpg_sibling_if_heic "$_dst"
                    att_html_inline="$att_html_inline$(_attachment_tag "$_att_stem.attachments/${_dst##*/}")"$'\n'
                else
                    _attachments_copyfail=$((_attachments_copyfail + 1))
                    log_warn "Failed to copy attachment '$_basename' for entry $base_name."
                fi
            done < <(sqlite3 -readonly -separator $'\x1f' "$snap" "
                SELECT a.Z_PK, COALESCE(a.$_acol_atitle, '')
                  FROM ZJOURNALENTRYASSETMO a
                 WHERE a.$_acol_entry = $pk
                 ORDER BY a.Z_PK ASC;" 2>/dev/null)
        fi
        total_attachments=$((total_attachments + att_count))
        if [ "$att_count" -eq 0 ] && [ -d "$att_dir" ]; then
            rmdir "$att_dir" 2>/dev/null || true
        fi
        local body_html=""
        if [ -n "$body_html_rich" ]; then
            body_html="$body_html_rich"
        elif [ -n "$body_text" ]; then
            body_html="$(_render_body_html "$body_text")"
        fi
        if [ -z "$body_html" ] && [ "$att_count" -eq 0 ]; then
            empty_count=$((empty_count + 1))
            body_html="<p><em>(empty entry)</em></p>"
        fi
        local meta_block=""
        if [ "${flagged:-0}" = "1" ]; then
            meta_block="$meta_block        <li>Flagged</li>
"
        fi
        if [ -n "$j_weather" ] && [ "$j_weather" != "0" ]; then
            local weather_text="$j_weather"
            [ -n "$j_temp" ] && [ "$j_temp" != "0" ] && weather_text="$weather_text, $j_temp"
            [ -n "${j_weather_high:-}" ] && [ "$j_weather_high" != "0" ] && \
                weather_text="$weather_text, high $j_weather_high"
            [ -n "${j_weather_low:-}" ] && [ "$j_weather_low" != "0" ] && \
                weather_text="$weather_text, low $j_weather_low"
            [ -n "${j_weather_humidity:-}" ] && [ "$j_weather_humidity" != "0" ] && \
                weather_text="$weather_text, humidity $j_weather_humidity"
            [ -n "${j_weather_code:-}" ] && [ "$j_weather_code" != "0" ] && \
                weather_text="$weather_text, code $j_weather_code"
            meta_block="$meta_block        <li>Weather: $(html_escape "$weather_text")</li>
"
        fi
        if [ -n "${j_placename:-}" ]; then
            meta_block="$meta_block        <li>Location: $(html_escape "$j_placename")</li>
"
        elif [ -n "$j_loc" ]; then
            meta_block="$meta_block        <li>Location: $(html_escape "$j_loc")</li>
"
        elif [ -n "$j_lat" ] && [ -n "$j_lon" ] && [ "$j_lat" != "0" ] && [ "$j_lon" != "0" ]; then
            meta_block="$meta_block        <li>Location: $(html_escape "$j_lat, $j_lon")</li>
"
        fi
        local tmp
        if ! tmp="$(mktemp "$target.tmp.XXXXXX" 2>/dev/null)"; then
            log_warn "Cannot create temp file for $base_name.html."
            _entry_write_failed=$((_entry_write_failed + 1))
            note_incomplete "$out_root" "$base_name.html" \
                "could not write per-entry HTML — mktemp failed in the export folder (disk full or permission denied)"
            [ -d "$att_dir" ] && rm -rf -- "$att_dir"
            continue
        fi
        track_output_path "$tmp"
        {
            printf '<!DOCTYPE html>\n<html>\n<head>\n<meta charset="UTF-8">\n'
            printf '<title>%s</title>\n' "$(html_escape "$title_text")"
            [ -n "$iso_date" ] && printf '<meta name="entry-date" content="%s">\n' "$iso_date"
            [ -n "$_mod_iso" ] && printf '<meta name="modified" content="%s">\n' "$_mod_iso"
            [ "${flagged:-0}" = "1" ] && printf '<meta name="flagged" content="true">\n'
            [ -n "${j_mood:-}" ] && [ "$j_mood" != "0" ] && \
                printf '<meta name="mood" content="%s">\n' "$(html_escape "$j_mood")"
            printf '</head>\n<body>\n'
            printf '<h1>%s</h1>\n' "$(html_escape "$title_text")"
            printf '<p class="entry-date"><em>%s</em></p>\n' "$(html_escape "$entry_date_fmt")"
            if [ -n "$meta_block" ]; then
                printf '<ul class="entry-meta">\n'
                printf '%s' "$meta_block"
                printf '</ul>\n'
            fi
            printf '%s\n' "$body_html"
            if [ -n "$att_html_inline" ]; then
                printf '<div class="entry-attachments">\n'
                printf '%s' "$att_html_inline"
                printf '</div>\n'
            fi
            printf '</body>\n</html>\n'
        } > "$tmp"
        if ! mv -f -- "$tmp" "$target"; then
            log_warn "Failed to write $target"
            rm -f -- "$tmp"
            _entry_write_failed=$((_entry_write_failed + 1))
            note_incomplete "$out_root" "$base_name.html" \
                "could not write per-entry HTML — atomic mv into export folder failed (volume ejected, disk full, or permission denied)"
            [ -d "$att_dir" ] && rm -rf -- "$att_dir"
            continue
        fi
        _untrack_output_path "$tmp"
        if [ "$_html_validated" != "1" ]; then
            validate_html_structure "$target"
            _html_validated=1
        fi
        if [ -n "$_epoch_int" ]; then
            _apply_touch_t "$(_format_touch_t "$_epoch_int")" "$target"
        fi
        exported=$((exported + 1))
        [ "${is_deleted:-0}" = "1" ] && _rd_exported=$((_rd_exported + 1))
        printf '%s\x1f%s\x1f%s\n' \
            "${target#"$out_root/"}" "$entry_date_fmt" "$(tsv_escape "$title_text")" \
            >> "$_journal_index" 2>/dev/null || true
        _progress_tick "$exported" "$n_entries" "entries exported"
    done < <(sqlite3 -readonly -separator $'\x1f' "$snap" "
        SELECT ZJOURNALENTRYMO.Z_PK,
               ZJOURNALENTRYMO.$jcol_date,
               $sel_flagged,
               $sel_weather,
               $sel_temp,
               $sel_lat,
               $sel_lon,
               $sel_loc,
               $sel_tz,
               $sel_mood,
               $sel_moddate,
               $sel_placename,
               $sel_weather_high,
               $sel_weather_low,
               $sel_weather_humidity,
               $sel_weather_code,
               CASE WHEN COALESCE(ZJOURNALENTRYMO.$jcol_deleted, 0) = 1
                      OR COALESCE(ZJOURNALENTRYMO.$jcol_removed, 0) = 1
                    THEN 1 ELSE 0 END
               $_journal_pk_sel
          FROM ZJOURNALENTRYMO $_journal_join_sql
         WHERE $_J_LIVE_FILTER
           $_entry_type_filter
         $_journal_group_sql
         ORDER BY ZJOURNALENTRYMO.$jcol_date ASC, ZJOURNALENTRYMO.Z_PK ASC;" 2>/dev/null)
    _progress_end
    [ "$empty_count" -gt 0 ] && log_info "$empty_count empty / unextractable entries"
    [ "$_rd_exported" -gt 0 ] && \
        log_info "Exported $_rd_exported recently-deleted journal $(_pluralize "$_rd_exported" entry entries) to Recently Deleted/ — review and discard if not needed."
    [ "$_rd_skipped_tombstones" -gt 0 ] && \
        _disclose_excluded "$_rd_skipped_tombstones fully-removed $(_pluralize "$_rd_skipped_tombstones" tombstone tombstones)" "deletion records with no remaining content"
    log_info "Recovering attachments + writing evicted-attachments list..."
    if [ "$stub_count" -gt 0 ]; then
        {
            printf '# Sections below group by entry filename (attachment filenames within).\n\n'
            LC_ALL=C sort -u "$_journal_stubs_tsv" \
                | LC_ALL=C awk -F$'\x1f' '
                    $1 != prev { if (prev != "") printf "\n"; printf "[%s]\n", $1; prev=$1 }
                    { print $2 }
                  '
        } | _write_skipped_report "$out_root" "Journal attachments" \
                "$stub_count" "" \
                "disable Optimize Mac Storage system-wide, open Journal.app once to trigger sync"
    fi
    if [ "$_attachments_missing" -gt 0 ]; then
        log_warn "$_attachments_missing journal $(_pluralize "$_attachments_missing" attachment) had DB pointers but were missing on disk"
        note_incomplete "$out_root" "$_attachments_missing journal $(_pluralize "$_attachments_missing" attachment)" \
            "the database referenced these attachments but the files were not on disk (not iCloud-evicted stubs) — they are not in the export"
    fi
    if [ "$_attachments_copyfail" -gt 0 ]; then
        log_warn "$_attachments_copyfail journal $(_pluralize "$_attachments_copyfail" attachment) failed to copy"
        note_incomplete "$out_root" "$_attachments_copyfail journal $(_pluralize "$_attachments_copyfail" attachment)" \
            "the attachment file(s) were on disk but cp failed — the photo / video content was not exported"
    fi
    log_info "Sanity checks and finalising..."
    local _vcp_discovered="$n_entries"
    [ "$n_entries_discovery_ok" = "0" ] && _vcp_discovered=""
    local _vcp_accounted=$((exported + _entry_write_failed))
    validate_count_parity "$_vcp_discovered" "$_vcp_accounted" \
        "Journal entry" "$out_root"
    if [ "$_entry_write_failed" -gt 0 ]; then
        log_warn "$_entry_write_failed $(_pluralize "$_entry_write_failed" entry entries) could not be written$(_disclosure_pointer "Journal/_incomplete.txt")"
    fi
    local _journal_have_index=0
    if [ "$exported" -gt 0 ] && [ -s "$_journal_index" ]; then
        local _ji_multi="no"
        [ "$_has_multi_journal" = "1" ] && _ji_multi="yes"
        _journal_emit_index "$_journal_index" "$exported" "$out_root" "$_ji_multi"
        validate_html_structure "$out_root/index.html"
        [ -s "$out_root/index.html" ] && _journal_have_index=1
    fi
    local _stat="$exported $(_pluralize "$exported" entry entries)"
    [ "$_journal_have_index" -eq 1 ] && _stat="$_stat + index.html"
    [ "$total_attachments" -gt 0 ] && _stat="$_stat, $total_attachments $(_pluralize "$total_attachments" attachment) copied"
    [ "$stub_count" -gt 0 ] && _stat="$_stat, $stub_count cloud-only$(_disclosure_pointer "Journal/_skipped.txt")"
    _stat="$_stat, $(_dir_size_human "$out_root")"
    log_ok "Wrote Journal/ ($_stat)"
    mark_success
    sweep_junk_files "$out_root"
    print_summary
    if [ "$ERR_COUNT" -gt 0 ]; then exit 1; fi
    exit 0
}

MAIL_DIR="$HOME/Library/Mail"

_parse_emlx_plist() {
    local emlx_file="$1" plist_offset="$2"
    _emlx_date_recv=""
    _emlx_flags=""
    tail -c +"$plist_offset" "$emlx_file" > "$_MAIL_PLIST_TMP" 2>/dev/null
    [ -s "$_MAIL_PLIST_TMP" ] || return 0
    local json
    json="$(plutil -convert json -o - "$_MAIL_PLIST_TMP" 2>/dev/null)" || return 0
    [ -n "$json" ] || return 0
    _emlx_date_recv="$(printf '%s' "$json" \
        | sed -n 's/.*"date-received"[[:space:]]*:[[:space:]]*\([0-9.]*\).*/\1/p' | head -1)"
    [ -z "$_emlx_date_recv" ] && _emlx_date_recv="$(printf '%s' "$json" \
        | sed -n 's/.*"date-received"[[:space:]]*:[[:space:]]*"\([0-9.]*\)".*/\1/p' | head -1)"
    _emlx_flags="$(printf '%s' "$json" \
        | sed -n 's/.*"flags"[[:space:]]*:[[:space:]]*\([0-9]*\).*/\1/p' | head -1)"
    [ -z "$_emlx_flags" ] && _emlx_flags="$(printf '%s' "$json" \
        | sed -n 's/.*"flags"[[:space:]]*:[[:space:]]*"\([0-9]*\)".*/\1/p' | head -1)"
}

_emlx_flags_to_mozilla() {
    local _f
    _f=$((10#${1:-0}))
    local _s=0 _s2=0
    [ "$((_f & 1))"  -ne 0 ] && _s=$((_s | 1))    # read     (Apple bit 0)
    [ "$((_f & 4))"  -ne 0 ] && _s=$((_s | 2))    # replied  (Apple bit 2)
    [ "$((_f & 16))" -ne 0 ] && _s=$((_s | 4))    # flagged  (Apple bit 4)
    _moz_status="$(printf '%04x' "$_s")"
    _moz_status2="$(printf '%08x' "$_s2")"
}

_emlx_header_parse() {
    local _f="$1"
    [ -f "$_f" ] || return 1
    local _line1
    _line1="$(head -1 -- "$_f" 2>/dev/null; printf x)"
    _line1="${_line1%x}"
    _emlx_byte_count="$(printf '%s' "$_line1" | LC_ALL=C tr -d '[:space:]')"
    case "$_emlx_byte_count" in
        ''|*[!0-9]*) return 1 ;;
    esac
    [ "$_emlx_byte_count" -eq 0 ] && return 1
    _emlx_first_line_bytes="$(printf '%s' "$_line1" | LC_ALL=C wc -c | LC_ALL=C tr -d '[:space:]')"
    return 0
}

_emlx_to_mbox() {
    local emlx_file="$1" mbox_file="$2"
    [ -f "$emlx_file" ] || return 1
    local _emlx_is_partial=0
    case "${emlx_file##*/}" in
        *.partial.emlx) _emlx_is_partial=1 ;;
    esac
    local _emlx_body_truncated=0
    local byte_count first_line_bytes file_size avail
    local _emlx_byte_count _emlx_first_line_bytes
    _emlx_header_parse "$emlx_file" || return 1
    byte_count="$((10#$_emlx_byte_count))"
    first_line_bytes="$_emlx_first_line_bytes"
    file_size="$(stat -f %z "$emlx_file" 2>/dev/null)"
    case "$file_size" in ''|*[!0-9]*) file_size=0 ;; esac
    avail=$((file_size - first_line_bytes))
    local _emlx_orig_byte_count="$((10#$_emlx_byte_count))"
    if [ "$avail" -gt 0 ] && [ "$byte_count" -gt "$avail" ]; then
        log_warn "Partial emlx body clamped: $emlx_file (declared $byte_count bytes, only $avail on disk)"
        byte_count="$avail"
        _emlx_body_truncated=1
    elif [ "$avail" -le 0 ]; then
        local _avail_disp
        if [ "$avail" -lt 0 ]; then _avail_disp=0; else _avail_disp="$avail"; fi
        log_warn "Catastrophic emlx truncation: $emlx_file (declared $byte_count bytes; file has ${_avail_disp} body bytes available — first_line_bytes=$first_line_bytes file_size=$file_size)"
        return 1
    fi
    local _actual_size _plist_offset
    _actual_size="$file_size"
    _plist_offset=$((first_line_bytes + byte_count + 1))
    local _emlx_date_recv="" _emlx_flags="" _emlx_no_plist=0
    if [ "$_emlx_body_truncated" -eq 1 ]; then
        local _emlx_orig_plist_offset
        _emlx_orig_plist_offset=$((first_line_bytes + _emlx_orig_byte_count + 1))
        if [ "$_actual_size" -gt 0 ] && [ "$_emlx_orig_plist_offset" -le "$_actual_size" ]; then
            _parse_emlx_plist "$emlx_file" "$_emlx_orig_plist_offset"
        fi
    elif [ "$_actual_size" -gt 0 ] && [ "$_plist_offset" -le "$_actual_size" ]; then
        _parse_emlx_plist "$emlx_file" "$_plist_offset"
    elif [ "$_actual_size" -gt 0 ] && [ "$_plist_offset" -eq "$((_actual_size + 1))" ]; then
        _emlx_no_plist=1
    else
        log_warn "Truncated emlx: $emlx_file (plist offset $_plist_offset > size $_actual_size)"
    fi
    _emlx_flags=$((10#${_emlx_flags:-0}))
    if [ "$((_emlx_flags & 2))" -ne 0 ]; then
        return 2
    fi
    tail -c +"$((first_line_bytes + 1))" "$emlx_file" \
        | head -c "$byte_count" > "$_MAIL_MSG_TMP" 2>/dev/null
    [ -s "$_MAIL_MSG_TMP" ] || return 1
    local from_addr="" from_date="" line="" _in_from=0 _in_date=0
    while IFS= read -r line; do
        line="${line%$'\r'}"
        [ -z "$line" ] && break
        case "$line" in
            ' '*|$'\t'*)
                if [ "$_in_from" -eq 1 ] && [ -z "$from_addr" ]; then
                    local _angle_c
                    _angle_c="$(printf '%s' "$line" | LC_ALL=C grep -oE '<[^<>]*>' | tail -1)"
                    if [ -n "$_angle_c" ]; then
                        _angle_c="${_angle_c#<}"; _angle_c="${_angle_c%>}"
                        from_addr="$(printf '%s' "$_angle_c" \
                            | LC_ALL=C grep -oE '[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}' | head -1)"
                    fi
                    if [ -z "$from_addr" ]; then
                        from_addr="$(printf '%s' "$line" \
                            | LC_ALL=C grep -oE '[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}' | head -1)"
                    fi
                elif [ "$_in_date" -eq 1 ] && [ -z "$from_date" ]; then
                    from_date="${line#"${line%%[![:space:]]*}"}"
                fi
                continue ;;
            [Ff][Rr][Oo][Mm]:*)
                _in_from=1; _in_date=0
                if [ -z "$from_addr" ]; then
                    local _angle
                    _angle="$(printf '%s' "$line" \
                        | LC_ALL=C grep -oE '<[^<>]*>' | tail -1)"
                    if [ -n "$_angle" ]; then
                        _angle="${_angle#<}"; _angle="${_angle%>}"
                        from_addr="$(printf '%s' "$_angle" \
                            | LC_ALL=C grep -oE '[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}' | head -1)"
                    fi
                    if [ -z "$from_addr" ]; then
                        from_addr="$(printf '%s' "$line" \
                            | LC_ALL=C grep -oE '[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}' | head -1)"
                    fi
                fi ;;
            [Dd][Aa][Tt][Ee]:*)
                _in_date=1; _in_from=0
                if [ -z "$from_date" ]; then
                    from_date="${line#*:}"
                    from_date="${from_date#"${from_date%%[![:space:]]*}"}"
                fi ;;
            *)
                _in_from=0; _in_date=0 ;;
        esac
    done < "$_MAIL_MSG_TMP"
    [ -n "$from_addr" ] || from_addr='unknown@unknown'
    local mbox_date=""
    if [ -n "$_emlx_date_recv" ]; then
        mbox_date="$(date -r "${_emlx_date_recv%%.*}" '+%a %b %e %H:%M:%S %Y' 2>/dev/null)"
    fi
    if [ -z "$mbox_date" ] && [ -n "$from_date" ]; then
        local cleaned
        cleaned="$(printf '%s' "$from_date" | LC_ALL=C sed 's/([^)]*)//g; s/[[:space:]]*$//')"
        mbox_date="$(date -j -f '%a, %d %b %Y %H:%M:%S %z' "$cleaned" '+%a %b %e %H:%M:%S %Y' 2>/dev/null \
            || date -j -f '%d %b %Y %H:%M:%S %z'      "$cleaned" '+%a %b %e %H:%M:%S %Y' 2>/dev/null \
            || date -j -f '%a, %d %b %Y %H:%M:%S'     "$cleaned" '+%a %b %e %H:%M:%S %Y' 2>/dev/null)"
    fi
    if [ -z "$mbox_date" ]; then
        if [ -n "$_emlx_date_recv" ] || [ -n "$from_date" ]; then
            _emlx_datefail=$(( ${_emlx_datefail:-0} + 1 ))
            if [ "$_emlx_datefail" -le "${_MAIL_DATE_WARN_LIMIT:-3}" ]; then
                log_warn "Date header unparseable for emlx (plist='$_emlx_date_recv', from='$from_date'); using epoch fallback — message will sort as Jan 2000 in import."
            fi
        fi
        mbox_date='Thu Jan  1 00:00:00 2000'
    fi
    local _moz_status="0000" _moz_status2="00000000"
    _emlx_flags_to_mozilla "$_emlx_flags"
    {
        printf 'From %s %s\n' "$from_addr" "$mbox_date"
        printf 'X-Mozilla-Status: %s\n' "$_moz_status"
        printf 'X-Mozilla-Status2: %s\n' "$_moz_status2"
        [ "$_emlx_is_partial" -eq 1 ] && printf 'X-Downpour-Partial: true\n'
        [ "$_emlx_body_truncated" -eq 1 ] && printf 'X-Downpour-Partial-Body: true\n'
        [ "$_emlx_no_plist" -eq 1 ] && printf 'X-Downpour-No-Plist: true\n'
        LC_ALL=C sed 's/^\(>*\)From /\1>From /' "$_MAIL_MSG_TMP"
        local _last_byte
        _last_byte="$(LC_ALL=C tail -c1 "$_MAIL_MSG_TMP" 2>/dev/null | LC_ALL=C od -An -tu1 | LC_ALL=C tr -d '[:space:]')"
        [ -n "$_last_byte" ] && [ "$_last_byte" != 10 ] && printf '\n'
        printf '\n'
    } >> "$mbox_file"
}

_mbox_logical_name() {
    local mbox_dir="$1" base_root="$2" rel="" name="" part=""
    rel="${mbox_dir#"$base_root"}"
    rel="${rel#/}"
    [ -n "$rel" ] || rel="${mbox_dir##*/}"
    while [ -n "$rel" ]; do
        case "$rel" in
            */*) part="${rel%%/*}"; rel="${rel#*/}" ;;
            *)   part="$rel";       rel="" ;;
        esac
        case "$part" in
            *.mbox) part="${part%.mbox}" ;;
            *)      continue ;;
        esac
        [ -n "$part" ] || continue
        if [ -n "$name" ]; then
            name="${name}-${part}"
        else
            name="$part"
        fi
    done
    [ -n "$name" ] || name='mailbox'
    printf '%s' "$name"
}

_emlx_in_mbox() {
    find "$1" \
        \( -mindepth 1 -type d -name '*.mbox' -prune \) \
        -o \( -type f -name '*.emlx' -print0 \) 2>/dev/null
}

_extract_mime_attachments_from_emlx() {
    local emlx="$1"
    [ -f "$emlx" ] || return 1
    local byte_count first_line_bytes
    local _emlx_byte_count _emlx_first_line_bytes
    _emlx_header_parse "$emlx" || return 1
    byte_count="$((10#$_emlx_byte_count))"
    first_line_bytes="$_emlx_first_line_bytes"
    local _email="$SCRATCH_DIR/_mime_email_$$.eml"
    tail -c +"$((first_line_bytes + 1))" "$emlx" 2>/dev/null \
        | head -c "$byte_count" > "$_email" 2>/dev/null
    [ -s "$_email" ] || { rm -f -- "$_email" 2>/dev/null; return 1; }
    local _stream="$SCRATCH_DIR/_mime_parts_$$.txt"
    LC_ALL=C awk '
    function get_param(hdr, pname,   lc, plc, vv, rs, rl) {
        lc = tolower(hdr); plc = tolower(pname)
        if (match(lc, "(^|[ \t;])" plc "=\"[^\"]*\"")) {
            rs = RSTART; rl = RLENGTH
            vv = substr(hdr, rs, rl)
            sub(/^[^"]*"/, "", vv); sub(/"$/, "", vv)
            return vv
        }
        if (match(lc, "(^|[ \t;])" plc "=[^ \t;\r\n]+")) {
            rs = RSTART; rl = RLENGTH
            vv = substr(hdr, rs, rl)
            sub(/^[^=]*=/, "", vv)
            return vv
        }
        return ""
    }
    function rfc2231_pct_decode(raw,   decoded, i, c, h1, h2) {
        decoded = ""
        i = 1
        while (i <= length(raw)) {
            c = substr(raw, i, 1)
            if (c == "%" && i + 2 <= length(raw)) {
                h1 = substr(raw, i+1, 1); h2 = substr(raw, i+2, 1)
                if ((h1 in hex2) && (h2 in hex2)) {
                    decoded = decoded sprintf("%c", hex2[h1] * 16 + hex2[h2])
                    i += 3
                    continue
                }
            }
            decoded = decoded c
            i++
        }
        return decoded
    }
    function rfc2231_raw_value(hdr, lc, tok,   rs, rl, vv) {
        _r2231_found = 0
        if (match(lc, "(^|[ \t;])" tok "=\"[^\"]*\"")) {
            rs = RSTART; rl = RLENGTH
            vv = substr(hdr, rs, rl)
            sub(/^[^"]*"/, "", vv); sub(/"$/, "", vv)
            _r2231_found = 1
            return vv
        }
        if (match(lc, "(^|[ \t;])" tok "=[^ \t;\r\n]+")) {
            rs = RSTART; rl = RLENGTH
            vv = substr(hdr, rs, rl)
            sub(/^[^=]*=/, "", vv)
            _r2231_found = 1
            return vv
        }
        return ""
    }
    function get_rfc2231_param(hdr, pname,   lc, plc, vv, n, parts, charset, raw, i, seg, segraw, charset_done, found_any, esc_seg, esc_seg_star) {
        lc = tolower(hdr); plc = tolower(pname)
        raw = ""
        charset = ""
        charset_done = 0
        found_any = 0
        i = 0
        while (1) {
            esc_seg_star = plc "\\*" i "\\*"
            esc_seg      = plc "\\*" i
            segraw = rfc2231_raw_value(hdr, lc, esc_seg_star)
            if (_r2231_found) {
                if (i == 0) {
                    n = split(segraw, parts, "'\''")
                    if (n >= 3) {
                        charset = tolower(parts[1])
                        seg = parts[3]
                        for (vv = 4; vv <= n; vv++) seg = seg "'\''" parts[vv]
                        charset_done = 1
                    } else {
                        seg = ""
                    }
                } else {
                    seg = segraw
                }
                raw = raw seg
                found_any = 1
                i++
                continue
            }
            segraw = rfc2231_raw_value(hdr, lc, esc_seg)
            if (_r2231_found) {
                raw = raw segraw
                found_any = 1
                i++
                continue
            }
            break
        }
        if (found_any) {
            if (charset_done) {
                if (charset != "utf-8" && charset != "us-ascii" && charset != "") return ""
            }
            return rfc2231_pct_decode(raw)
        }
        vv = rfc2231_raw_value(hdr, lc, plc "\\*")
        if (!_r2231_found) return ""
        n = split(vv, parts, "'\''")
        if (n < 3) return ""
        charset = tolower(parts[1])
        if (charset != "utf-8" && charset != "us-ascii" && charset != "") return ""
        raw = parts[3]
        for (i = 4; i <= n; i++) raw = raw "'\''" parts[i]
        return rfc2231_pct_decode(raw)
    }
    function reset_block() {
        cur_ct = "text/plain"; cur_boundary = ""
        cur_encoding = "7bit"; cur_filename = ""; cur_disp = ""
        cur_cid = ""
    }
    function image_subtype_ext(ct,   st) {
        st = ct
        gsub(/[ \t]/, "", st)
        st = tolower(st)
        gsub(/;.*$/, "", st)
        gsub(/^image\//, "", st)
        gsub(/^x-/, "", st)
        if (st == "jpeg" || st == "jpg") return "jpg"
        if (st == "png")  return "png"
        if (st == "gif")  return "gif"
        if (st == "tiff" || st == "tif") return "tiff"
        if (st == "bmp")  return "bmp"
        if (st == "webp") return "webp"
        if (st == "heic") return "heic"
        if (st == "heif") return "heif"
        if (st == "svg+xml" || st == "svg") return "svg"
        return "img"
    }
    function process_header(line,   lc, val, _fn) {
        sub(/[\r]+$/, "", line)
        lc = tolower(line)
        if (lc ~ /^content-type:/) {
            val = substr(line, index(line, ":") + 1)
            sub(/^[ \t]+/, "", val); sub(/[ \t]+$/, "", val)
            cur_ct = val
            if (tolower(val) ~ /^multipart\//) cur_boundary = get_param(val, "boundary")
            if (cur_filename == "") {
                _fn = get_rfc2231_param(val, "name")
                if (_fn == "") _fn = get_param(val, "name")
                cur_filename = _fn
            }
        } else if (lc ~ /^content-transfer-encoding:/) {
            val = substr(line, index(line, ":") + 1)
            sub(/^[ \t]+/, "", val); sub(/[ \t]+$/, "", val)
            cur_encoding = tolower(val)
        } else if (lc ~ /^content-id:/) {
            val = substr(line, index(line, ":") + 1)
            sub(/^[ \t]+/, "", val); sub(/[ \t]+$/, "", val)
            gsub(/^</, "", val); gsub(/>$/, "", val)
            cur_cid = val
        } else if (lc ~ /^content-disposition:/) {
            val = substr(line, index(line, ":") + 1)
            sub(/^[ \t]+/, "", val); sub(/[ \t]+$/, "", val)
            cur_disp = val
            if (val ~ /[Ff][Ii][Ll][Ee][Nn][Aa][Mm][Ee](\*[0-9]+)?\*?=/) {
                _fn = get_rfc2231_param(val, "filename")
                if (_fn == "") _fn = get_param(val, "filename")
                cur_filename = _fn
            }
        }
    }
    function end_headers_block(   lct, ldisp, is_att, is_inline_image, _ext) {
        if (accum != "") { process_header(accum); accum = "" }
        lct = tolower(cur_ct)
        ldisp = tolower(cur_disp)
        if (cur_boundary != "") {
            depth++; b_stack[depth] = cur_boundary
            state = "scan"
            reset_block()
            return
        }
        if (lct ~ /^application\/(x-)?pkcs7-signature/) {
            capturing = 0
            return
        }
        is_att = (ldisp ~ /^attachment/ ||
                  (cur_filename != "" && lct !~ /^(text\/plain|text\/html|multipart\/|message\/)/))
        is_inline_image = (cur_filename == "" && lct ~ /^image\// &&
                           (ldisp ~ /^inline/ || cur_cid != ""))
        if (is_att || is_inline_image) {
            if (cur_filename == "" && is_inline_image) {
                _ext = image_subtype_ext(cur_ct)
                if (cur_cid != "") {
                    cur_filename = cur_cid
                    if (cur_filename !~ /\.[A-Za-z0-9]+$/)
                        cur_filename = cur_filename "." _ext
                } else {
                    inline_seq++
                    cur_filename = sprintf("inline-%03d.%s", inline_seq, _ext)
                }
            }
            gsub(/[\t\r\n]/, "_", cur_filename)
            sub(/^[ \t]+/, "", cur_filename); sub(/[ \t]+$/, "", cur_filename)
            if (cur_filename == "") cur_filename = "attachment"
            print "H\t" cur_filename "\t" cur_encoding
            capturing = 1
        } else {
            capturing = 0
        }
    }
    BEGIN {
        state = "headers"; depth = 0; capturing = 0; accum = ""
        inline_seq = 0
        for (_hi = 0; _hi < 16; _hi++) {
            hex2[substr("0123456789ABCDEF", _hi+1, 1)] = _hi
            hex2[substr("0123456789abcdef", _hi+1, 1)] = _hi
        }
        reset_block()
    }
    state == "headers" {
        if ($0 ~ /^\r?$/) {
            end_headers_block()
            if (state == "headers") state = "body"
            next
        }
        if (depth > 0) {
            boundary_cand = $0
            sub(/[ \t\r]+$/, "", boundary_cand)
            for (b_idx = depth; b_idx >= 1; b_idx--) {
                if (boundary_cand == "--" b_stack[b_idx] ||
                    boundary_cand == "--" b_stack[b_idx] "--") {
                    end_headers_block()
                    if (state == "headers") state = "body"
                    break
                }
            }
        }
        if (state == "headers") {
            if ($0 ~ /^[ \t]/ && accum != "") {
                accum = accum " " $0
                next
            }
            if (accum != "") { process_header(accum) }
            accum = $0
            next
        }
    }
    state == "scan" || state == "body" {
        if (depth > 0) {
            boundary_cand = $0
            sub(/[ \t\r]+$/, "", boundary_cand)
            if (depth < 0) {
                depth = 0
            }
            for (i = depth; i >= 1; i--) {
                if (boundary_cand == "--" b_stack[i]) {
                    if (capturing) { print "E"; capturing = 0 }
                    depth = i
                    state = "headers"; accum = ""
                    reset_block()
                    next
                }
                if (boundary_cand == "--" b_stack[i] "--") {
                    if (capturing) { print "E"; capturing = 0 }
                    depth = i - 1
                    state = (depth > 0) ? "body" : "ended"
                    next
                }
            }
        }
        if (capturing) print "B\t" $0
    }
    END { if (capturing) print "E" }
    ' "$_email" > "$_stream" 2>/dev/null
    rm -f -- "$_email" 2>/dev/null
    [ -s "$_stream" ] || { rm -f -- "$_stream" 2>/dev/null; return 0; }
    local _cur_enc="" _cur_fn="" _cur_body="$SCRATCH_DIR/_mime_body_$$"
    local _line _rest _decoded _final _amd5
    local _tab=$'\t'
    : > "$_cur_body"
    while IFS= read -r _line; do
        case "$_line" in
            "H$_tab"*)
                _rest="${_line#H$_tab}"
                _cur_fn="${_rest%%$_tab*}"
                _cur_enc="${_rest#*$_tab}"
                _cur_fn="${_cur_fn##*/}"
                _cur_fn="${_cur_fn%$'\r'}"
                _cur_fn="$(_sanitize_name "$_cur_fn")"
                [ -z "$_cur_fn" ] && _cur_fn="attachment"
                : > "$_cur_body"
                ;;
            "B$_tab"*)
                printf '%s\n' "${_line#B$_tab}" >> "$_cur_body"
                ;;
            E)
                _decoded="$SCRATCH_DIR/_mime_decoded_$$.bin"
                local _decode_rc=0
                case "$_cur_enc" in
                    base64)
                        LC_ALL=C tr -d ' \t\r' < "$_cur_body" \
                            | base64 -D > "$_decoded" 2>/dev/null
                        _decode_rc="${PIPESTATUS[1]}"
                        ;;
                    quoted-printable)
                        LC_ALL=C awk '
                        BEGIN {
                            for (i = 0; i < 16; i++) {
                                hex2[substr("0123456789ABCDEF", i+1, 1)] = i
                                hex2[substr("0123456789abcdef", i+1, 1)] = i
                            }
                            cont = ""
                        }
                        {
                            line = $0
                            sub(/\r$/, "", line)
                            out = ""
                            L = length(line)
                            i = 1
                            softbreak = 0
                            while (i <= L) {
                                c = substr(line, i, 1)
                                if (c == "=" && i + 2 <= L) {
                                    h1 = substr(line, i+1, 1); h2 = substr(line, i+2, 1)
                                    if ((h1 in hex2) && (h2 in hex2)) {
                                        v = hex2[h1] * 16 + hex2[h2]
                                        out = out sprintf("%c", v)
                                        i += 3
                                        continue
                                    }
                                }
                                if (c == "=" && i == L) {
                                    softbreak = 1
                                    break
                                }
                                out = out c
                                i++
                            }
                            out = cont out
                            cont = ""
                            if (softbreak) { cont = out } else { printf "%s\n", out }
                        }
                        END { if (cont != "") printf "%s", cont }
                        ' "$_cur_body" > "$_decoded" 2>/dev/null
                        _decode_rc="$?"
                        ;;
                    7bit|8bit|binary|"")
                        cp -- "$_cur_body" "$_decoded" 2>/dev/null
                        _decode_rc="$?"
                        ;;
                    *)
                        cp -- "$_cur_body" "$_decoded" 2>/dev/null
                        _decode_rc="$?"
                        ;;
                esac
                if [ "$_decode_rc" -ne 0 ]; then
                    rm -f -- "$_decoded" 2>/dev/null
                    att_failed=$((att_failed + 1))
                    note_incomplete "$mail_dir" \
                        "Attachment ${_cur_fn:-attachment} (decode error)" \
                        "the MIME decoder (base64 or quoted-printable) reported an error — partial body discarded"
                elif [ -s "$_decoded" ]; then
                    _amd5="$(_md5_hex "$_decoded")"
                    if [ -n "$_amd5" ] && _mail_seen_md5_check "$_amd5"; then
                        att_dupes=$((att_dupes + 1))
                        rm -f -- "$_decoded" 2>/dev/null
                    else
                        _final="$(_unique_path "$att_dir/$_cur_fn")"
                        if mv -- "$_decoded" "$_final"; then
                            att_count=$((att_count + 1))
                            _mail_seen_md5_mark "$_amd5"
                        else
                            att_failed=$((att_failed + 1))
                            rm -f -- "$_final" 2>/dev/null
                            rm -f -- "$_decoded" 2>/dev/null
                        fi
                    fi
                else
                    rm -f -- "$_decoded" 2>/dev/null
                fi
                _cur_fn=""; _cur_enc=""
                : > "$_cur_body"
                ;;
        esac
    done < "$_stream"
    rm -f -- "$_stream" "$_cur_body" 2>/dev/null
    return 0
}

mail_main() {
    maybe_show_help "$@"
    _announce_step "Mail export"
    check_dependencies
    [ "${_INVOKED_BY_WRAPPER:-0}" = "1" ] || timemachine_suspend
    local out_arg out_dir
    out_arg="$(_parse_output_folder_arg "$@")" || exit 1
    out_dir="$(resolve_output_dir "$out_arg")" || exit 1
    _announce_output_dir "Mail"
    log_info "Checking Full Disk Access and discovering mailboxes..."
    require_full_disk_access
    warn_if_app_running Mail
    if [ ! -d "$MAIL_DIR" ]; then
        report_no_source "Mail" "not configured" "$MAIL_DIR"
    fi
    log_info "Source: $MAIL_DIR"
    if [ -d "$MAIL_DIR" ]; then
        local _src_kb _avail_kb _need_kb
        _src_kb="$(LC_ALL=C du -sk "$MAIL_DIR" 2>/dev/null | awk '{print $1}')"
        case "$_src_kb" in ''|*[!0-9]*) _src_kb=0 ;; esac
        _avail_kb="$(LC_ALL=C df -P -k "$out_dir" 2>/dev/null | awk 'END{print $4}')"
        case "$_avail_kb" in ''|*[!0-9]*) _avail_kb=0 ;; esac
        _need_kb=$((_src_kb * 2))
        if [ "$_src_kb" -gt 0 ] && [ "$_avail_kb" -gt 0 ] && [ "$_avail_kb" -lt "$_need_kb" ]; then
            log_warn "Output volume has $((_avail_kb/1024)) MB free; this Mail export needs roughly $((_need_kb/1024)) MB for the verbatim copy + Thunderbird conversion. The copy may fail partway — free up space or choose another output folder."
        fi
    fi
    local mail_dir="$out_dir/Mail"
    mkdir -p "$mail_dir" || die "Cannot create $mail_dir"
    track_output_path "$mail_dir"
    local out_root="$mail_dir/Apple Mail"
    require_no_collision "$out_root"
    _create_output_dir "$out_root"
    log_info "Copying Apple Mail (verbatim)..."
    local total_mboxes=0 nonempty_mboxes=0 empty_mboxes=0
    local total_files=0 copy_failures=0
    local mbox rel dst f rel_in_mbox dst_in_mbox
    local _MAIL_COPY_FAIL_WARN_LIMIT=3
    local _mail_copy_first_err=""
    while IFS= read -r -d '' mbox; do
        total_mboxes=$((total_mboxes + 1))
        mark_activity
        if find "$mbox" -mindepth 1 -type d -name '*.mbox' -prune -o -name '*.emlx' -print -quit 2>/dev/null | grep -q .; then
            nonempty_mboxes=$((nonempty_mboxes + 1))
        else
            empty_mboxes=$((empty_mboxes + 1))
            continue
        fi
        rel="${mbox#"$MAIL_DIR"/}"
        dst="$out_root/$rel"
        if ! mkdir -p "$dst"; then
            log_warn "Cannot create $dst — skipping mailbox."
            note_incomplete "$mail_dir" "Mailbox: $rel" \
                "could not create its destination folder under Mail/Apple Mail/ — this mailbox was not mirrored"
            continue
        fi
        while IFS= read -r -d '' f; do
            rel_in_mbox="${f#"$mbox"/}"
            should_skip_copy "$f" "$rel_in_mbox" && continue
            dst_in_mbox="$dst/$rel_in_mbox"
            local _tdir="${dst_in_mbox%/*}"
            [ -d "$_tdir" ] || mkdir -p "$_tdir" 2>/dev/null
            local _copy_err _copy_err_rc
            _copy_err="$(ditto -- "$f" "$dst_in_mbox" 2>&1 >/dev/null)"; _copy_err_rc=$?
            if [ "$_copy_err_rc" -eq 0 ] && [ -f "$dst_in_mbox" ]; then
                total_files=$((total_files + 1))
            else
                copy_failures=$((copy_failures + 1))
                rm -f -- "$dst_in_mbox" 2>/dev/null || true
                local _err_msg="${_copy_err##*: }"
                [ -z "$_err_msg" ] && _err_msg="(no error message)"
                if [ "$copy_failures" -le "$_MAIL_COPY_FAIL_WARN_LIMIT" ]; then
                    log_warn "Copy failed: $rel/$rel_in_mbox: $_err_msg."
                fi
                [ -z "$_mail_copy_first_err" ] && _mail_copy_first_err="$_err_msg"
            fi
        done < <(find "$mbox" -mindepth 1 -type d -name '*.mbox' -prune -o -type f -print0 2>/dev/null)
    done < <(find "$MAIL_DIR" -type d -name '*.mbox' -print0 2>/dev/null)
    find "$out_root" -mindepth 1 -type d -empty -delete 2>/dev/null || true
    if [ "$total_mboxes" -eq 0 ]; then
        rmdir "$out_root" 2>/dev/null || true
        rmdir "$mail_dir" 2>/dev/null || true
        report_no_source "Mail" "has no mailboxes" "$MAIL_DIR"
    fi
    log_info "Found $total_mboxes $(_pluralize "$total_mboxes" mailbox mailboxes) ($nonempty_mboxes with messages, $empty_mboxes empty)"
    if [ "$copy_failures" -gt 0 ]; then
        local _suffix=""
        [ -n "$_mail_copy_first_err" ] && _suffix=" — first error: $_mail_copy_first_err"
        if [ "$copy_failures" -gt "$_MAIL_COPY_FAIL_WARN_LIMIT" ]; then
            local _hidden=$((copy_failures - _MAIL_COPY_FAIL_WARN_LIMIT))
            log_warn "$copy_failures $(_pluralize "$copy_failures" file) failed to copy ($_hidden similar warns suppressed)$_suffix"
        else
            log_warn "$copy_failures $(_pluralize "$copy_failures" file) failed to copy$_suffix"
        fi
        log_info "  Common causes: Mail.app actively running and locking message files; iCloud-Mail \"optimized storage\" placeholder files; macOS sandbox / data-vault protection on the mailbox. Quitting Mail.app and re-running usually clears the locked-file class of failures."
        note_incomplete "$mail_dir" "$copy_failures message file(s) across the Apple Mail mirror" \
            "individual file copies failed (commonly: Mail.app running and locking files, iCloud optimized-storage placeholders, or sandbox protection) — those messages are missing from Mail/Apple Mail/. Quit Mail.app and re-run."
    fi
    if [ "$nonempty_mboxes" -eq 0 ]; then
        log_warn "All mailboxes empty — nothing to export."
        rm -rf -- "$out_root" 2>/dev/null
        rmdir "$mail_dir" 2>/dev/null || true
        _flag_no_content
        mark_success
        print_summary
        exit 0
    fi
    if [ "$total_files" -eq 0 ]; then
        rmdir "$out_root" 2>/dev/null || true
        rmdir "$mail_dir" 2>/dev/null || true
        log_warn "All file copies failed — Mail/Apple Mail/ left empty."
        note_incomplete "$mail_dir" "The entire Apple Mail mirror" \
            "every message-file copy failed — Mail/Apple Mail/ is empty. Quit Mail.app (it locks message files while running) and re-run."
    else
        log_ok "Wrote Mail/Apple Mail/ ($nonempty_mboxes $(_pluralize "$nonempty_mboxes" mailbox mailboxes), $total_files $(_pluralize "$total_files" file), $(_dir_size_human "$out_root"))"
    fi
    ensure_scratch
    local _MAIL_PLIST_TMP="$SCRATCH_DIR/a2t_plist"
    local _MAIL_MSG_TMP="$SCRATCH_DIR/a2t_msg"
    local _MAIL_DATE_WARN_LIMIT=3
    local _emlx_datefail=0
    local tb_dir="$mail_dir/Thunderbird"
    _create_output_dir "$tb_dir"
    log_info "Converting to Thunderbird format..."
    local _tb_total
    _tb_total="$(find "$out_root" -type d -name '*.mbox' -print0 2>/dev/null | tr -dc '\0' | wc -c | tr -d ' ')"
    case "$_tb_total" in ''|*[!0-9]*) _tb_total=0 ;; esac
    local tb_mailboxes=0 tb_messages=0 tb_deleted=0 tb_errors=0
    local mbox_dir base out_file emlx_file converted deleted errors
    local _tb_processed=0
    local _pt_last=0 _pt_inline=0
    while IFS= read -r -d '' mbox_dir; do
        base="$(_mbox_logical_name "$mbox_dir" "$out_root")"
        out_file="$(_unique_path "$tb_dir/${base}.mbox")"
        : > "$out_file" 2>/dev/null || { log_warn "Cannot create $out_file"; continue; }
        converted=0
        deleted=0
        errors=0
        while IFS= read -r -d '' emlx_file; do
            _emlx_to_mbox "$emlx_file" "$out_file"
            case $? in
                0) converted=$((converted + 1)) ;;
                2) deleted=$((deleted + 1)) ;;
                *) errors=$((errors + 1)) ;;
            esac
        done < <(_emlx_in_mbox "$mbox_dir" | sort -z)
        if [ "$converted" -gt 0 ]; then
            tb_mailboxes=$((tb_mailboxes + 1))
            tb_messages=$((tb_messages + converted))
        else
            rm -f -- "$out_file" 2>/dev/null
        fi
        tb_deleted=$((tb_deleted + deleted))
        tb_errors=$((tb_errors + errors))
        _tb_processed=$((_tb_processed + 1))
        _progress_tick "$_tb_processed" "$_tb_total" "mailboxes converted"
        mark_activity
    done < <(find "$out_root" -type d -name '*.mbox' -print0 2>/dev/null | sort -z)
    _progress_end
    if [ "$_emlx_datefail" -gt "$_MAIL_DATE_WARN_LIMIT" ]; then
        local _date_hidden=$((_emlx_datefail - _MAIL_DATE_WARN_LIMIT))
        log_warn "$_emlx_datefail $(_pluralize "$_emlx_datefail" message) had an unparseable Date: header and were given the epoch fallback ($_date_hidden further warning(s) suppressed)"
    fi
    if [ "$tb_messages" -gt 0 ]; then
        local _tb_stat
        _tb_stat="$tb_messages $(_pluralize "$tb_messages" msg) across $tb_mailboxes $(_pluralize "$tb_mailboxes" mailbox mailboxes)"
        [ "$tb_deleted" -gt 0 ] && _tb_stat="$_tb_stat, $tb_deleted deleted skipped"
        [ "$tb_errors" -gt 0 ] && _tb_stat="$_tb_stat, $tb_errors $(_pluralize "$tb_errors" error)"
        log_ok "Wrote Mail/Thunderbird/ ($_tb_stat)"
        local _from_count
        _from_count=$(LC_ALL=C grep -rh '^From ' "$tb_dir" 2>/dev/null | wc -l | tr -d '[:space:]')
        case "$_from_count" in ''|*[!0-9]*) _from_count=0 ;; esac
        if [ "$_from_count" -lt "$tb_messages" ]; then
            log_warn "Thunderbird parity check: $_from_count From-$(_pluralize "$_from_count" envelope) found, expected at least $tb_messages — possible silent-write failure."
            note_incomplete "$mail_dir" "Thunderbird mbox — message-count shortfall" \
                "the converted Thunderbird mbox holds $_from_count message envelope(s) but $tb_messages were expected; some messages may not have been written to the Thunderbird/ tree (the verbatim Apple Mail/ mirror is the authoritative copy)"
        fi
        if [ "$tb_errors" -gt 0 ]; then
            log_warn "$tb_errors $(_pluralize "$tb_errors" message) failed to convert to Thunderbird format"
            note_incomplete "$mail_dir" "Thunderbird mbox — $tb_errors message-conversion $(_pluralize "$tb_errors" error)" \
                "$tb_errors message(s) could not be converted into the Thunderbird/ tree; each is still present in the verbatim Apple Mail/ mirror, which is the authoritative copy of those messages"
        fi
        log_info "Validating mbox structure (RFC 4155)..."
        local _f
        while IFS= read -r -d '' _f; do
            validate_mbox_rfc4155 "$_f" || true
        done < <(find "$tb_dir" -type f -print0 2>/dev/null)
    elif [ "$tb_errors" -gt 0 ]; then
        log_warn "$tb_errors $(_pluralize "$tb_errors" message) failed to convert to Thunderbird format — the Thunderbird/ tree is empty"
        note_incomplete "$mail_dir" "Thunderbird mbox — all $tb_errors message-conversion $(_pluralize "$tb_errors" error)" \
            "every message failed to convert into the Thunderbird/ tree; all are still present in the verbatim Apple Mail/ mirror, which is the authoritative copy of those messages"
        rmdir "$tb_dir" 2>/dev/null || true
    else
        rmdir "$tb_dir" 2>/dev/null || true
        log_info "No Thunderbird mbox files written (no convertible messages)"
    fi
    local att_dir="$mail_dir/Attachments"
    _create_output_dir "$att_dir"
    log_info "Extracting attachments..."
    ensure_scratch
    _mail_seen_md5_check() {
        local _h="$1"
        [ -n "$_h" ] || return 1
        local _v="_mail_seen_md5_$_h"
        [ -n "${!_v+x}" ]
    }
    _mail_seen_md5_mark() {
        local _h="$1"
        [ -z "$_h" ] && return 0
        local _v="_mail_seen_md5_$_h"
        printf -v "$_v" 1
    }
    local att_count=0 att_failed=0 att_dupes=0 _af _arel _atarget _abase _amd5
    while IFS= read -r -d '' _af; do
        _abase="${_af##*/}"
        _arel="${_af#"$out_root"/}"
        should_skip_copy "$_af" "$_arel" && continue
        [ "$_abase" = "smime.p7s" ] && continue
        _amd5="$(_md5_hex "$_af")"
        if [ -n "$_amd5" ] && _mail_seen_md5_check "$_amd5"; then
            att_dupes=$((att_dupes + 1))
            continue
        fi
        _atarget="$(_unique_path "$att_dir/$_abase")"
        if ditto -- "$_af" "$_atarget" 2>/dev/null; then
            att_count=$((att_count + 1))
            _mail_seen_md5_mark "$_amd5"
        else
            att_failed=$((att_failed + 1))
            rm -f -- "$_atarget" 2>/dev/null
        fi
    done < <(find "$out_root" -type f \
                \( -path '*.mbox/*/Data/Attachments/*' \
                   -o -path '*.mbox/*/Data/*/Attachments/*' \) \
                -print0 2>/dev/null)
    local _att_count_pass1="$att_count"
    local _mime_emlx_n=0 _mime_with_att=0 _mime_extract_fail=0
    local _emlx
    _mime_emlx_n=$(find "$out_root" -type f -name '*.emlx' 2>/dev/null \
        | wc -l | LC_ALL=C tr -d ' ')
    case "$_mime_emlx_n" in ''|*[!0-9]*) _mime_emlx_n=0 ;; esac
    while IFS= read -r -d '' _emlx; do
        [ -n "$_emlx" ] || continue
        _mime_with_att=$((_mime_with_att + 1))
        _extract_mime_attachments_from_emlx "$_emlx" \
            || _mime_extract_fail=$((_mime_extract_fail + 1))
        case "$_mime_with_att" in *00) mark_activity ;; esac
    done < <(find "$out_root" -type f -name '*.emlx' -print0 2>/dev/null \
        | LC_ALL=C xargs -0 grep -liE --null \
            '^content-type:.*multipart|^[[:space:]]+multipart/|^content-disposition:.*attachment|filename=|name=' \
            /dev/null 2>/dev/null)
    local _att_count_pass2=$((att_count - _att_count_pass1))
    if [ "$_mime_extract_fail" -gt 0 ]; then
        log_warn "$_mime_extract_fail multipart $(_pluralize "$_mime_extract_fail" message) could not be parsed for inline attachments"
        note_incomplete "$mail_dir" "Inline attachment extraction — $_mime_extract_fail malformed $(_pluralize "$_mime_extract_fail" message)" \
            "$_mime_extract_fail multipart message(s) could not be parsed for inline MIME attachments; each message itself is still present in the verbatim Apple Mail/ mirror, so this is an attachment-extraction gap, not message data loss"
    fi
    if [ "$att_count" -gt 0 ] || [ "$att_failed" -gt 0 ]; then
        log_info "Pass 1 (decoded tree): $_att_count_pass1 $(_pluralize "$_att_count_pass1" file)"
        log_info "Pass 2 (inline MIME): $_att_count_pass2 $(_pluralize "$_att_count_pass2" file) from $_mime_with_att scanned candidate $(_pluralize "$_mime_with_att" message) (of $_mime_emlx_n total)"
    fi
    if [ "$att_count" -gt 0 ]; then
        local _att_stat
        _att_stat="$att_count $(_pluralize "$att_count" attachment)"
        [ "$att_dupes" -gt 0 ] && _att_stat="$_att_stat, $att_dupes $(_pluralize "$att_dupes" content-dupe) skipped"
        [ "$att_failed" -gt 0 ] && _att_stat="$_att_stat, $att_failed failed"
        _att_stat="$_att_stat, $(_dir_size_human "$att_dir")"
        log_ok "Wrote Mail/Attachments/ ($_att_stat)"
        if [ "$att_failed" -gt 0 ]; then
            log_warn "$att_failed $(_pluralize "$att_failed" attachment) could not be extracted to Mail/Attachments/"
            note_incomplete "$mail_dir" "Attachment extraction — $att_failed failed" \
                "$att_failed $(_pluralize "$att_failed" attachment) failed to copy/extract into Mail/Attachments/; each affected message is still present in the verbatim Apple Mail/ mirror, so this is an attachment-extraction gap, not message data loss"
        fi
    elif [ "$att_failed" -gt 0 ]; then
        rmdir "$att_dir" 2>/dev/null || true
        log_warn "All $att_failed attachment copy(ies) failed — Mail/Attachments/ left empty."
        note_incomplete "$mail_dir" "All $att_failed mail attachment(s)" \
            "every attachment copy failed — Mail/Attachments/ is empty. Quit Mail.app and re-run."
    else
        rmdir "$att_dir" 2>/dev/null || true
        log_info "No attachments found in any mailbox"
    fi
    mark_success
    sweep_junk_files "$mail_dir"
    rmdir "$mail_dir" 2>/dev/null || true
    if [ "$total_files" -gt 0 ] || [ "$tb_messages" -gt 0 ] || [ "$att_count" -gt 0 ]; then
        local _mail_stat
        _mail_stat="$nonempty_mboxes $(_pluralize "$nonempty_mboxes" mailbox mailboxes), $total_files $(_pluralize "$total_files" file)"
        [ "$tb_messages" -gt 0 ] && _mail_stat="$_mail_stat, $tb_messages Thunderbird $(_pluralize "$tb_messages" msg)"
        [ "$att_count" -gt 0 ] && _mail_stat="$_mail_stat, $att_count $(_pluralize "$att_count" attachment)"
        _mail_stat="$_mail_stat, $(_dir_size_human "$mail_dir")"
        log_ok "Wrote Mail/ ($_mail_stat)"
    fi
    print_summary
    if [ "$ERR_COUNT" -gt 0 ]; then exit 1; fi
    exit 0
}

_maps_has_table() {
    case "$1" in *[!A-Za-z0-9_]*) return 1 ;; esac
    sqlite3 -readonly "$_snap" \
        "SELECT name FROM sqlite_master WHERE type='table' AND name='$1';" 2>/dev/null | grep -q .
}

_maps_has_col() {
    _col_present "$_snap" "$1" "$2"
}

export_maps() {
    local out_root="$1"
    local _maps_root="$out_root/Maps"
    local _maps_dir="$HOME/Library/Containers/com.apple.Maps/Data/Maps"
    if [ ! -d "$_maps_dir" ]; then
        report_no_source "Maps" "not configured" \
            "~/Library/Containers/com.apple.Maps/Data/Maps" \
            "Maps"
    fi
    require_no_collision "$_maps_root"
    _create_output_dir "$_maps_root" "permission denied / disk full?"
    log_info "Source: $_maps_dir"
    local _db="" _db_is_cache=0 _db_all _db_count
    _db_all=$(find "$_maps_dir" -name 'MapsSync_*' \
        -not -name '*_deviceLocalCache*' -not -name '*-wal' -not -name '*-shm' \
        -not -name '*-journal' \
        -type f 2>/dev/null | LC_ALL=C sort)
    _db_count=$(printf '%s\n' "$_db_all" | grep -c .)
    case "$_db_count" in ''|*[!0-9]*) _db_count=0 ;; esac
    _db=$(printf '%s\n' "$_db_all" | head -1)
    if [ "$_db_count" -gt 1 ]; then
        ensure_scratch
        local _secondaries_with_content=0 _secondaries_unverified=0 _sdb _scnt
        local _sdb_list
        _sdb_list=$(printf '%s\n' "$_db_all" | tail -n +2)
        while IFS= read -r _sdb; do
            [ -z "$_sdb" ] && continue
            local _sdb_snap _shist _sfav _scounts
            _sdb_snap="$(snapshot_db "$_sdb" 2>/dev/null)" || _sdb_snap=""
            if [ -z "$_sdb_snap" ]; then
                _secondaries_unverified=$((_secondaries_unverified + 1))
                continue
            fi
            _scounts=$(sqlite3 -readonly -separator $'\x1f' "$_sdb_snap" \
                "SELECT (SELECT COUNT(*) FROM ZHISTORYITEM),
                        (SELECT COUNT(*) FROM ZFAVORITEITEM);" 2>/dev/null)
            if [ -n "$_scounts" ]; then
                _shist="${_scounts%%$'\x1f'*}"
                _sfav="${_scounts#*$'\x1f'}"
                [ "$_sfav" = "$_scounts" ] && _sfav=""
            else
                _shist=$(sqlite3 -readonly "$_sdb_snap" \
                    "SELECT COUNT(*) FROM ZHISTORYITEM;" 2>/dev/null)
                _sfav=$(sqlite3 -readonly "$_sdb_snap" \
                    "SELECT COUNT(*) FROM ZFAVORITEITEM;" 2>/dev/null)
            fi
            case "${_shist:-0}" in ''|*[!0-9]*) _shist=0 ;; esac
            case "${_sfav:-0}"  in ''|*[!0-9]*) _sfav=0 ;; esac
            _scnt=$((_shist + _sfav))
            if [ "$_scnt" -gt 0 ]; then
                _secondaries_with_content=$((_secondaries_with_content + 1))
            fi
        done <<<"$_sdb_list"
        if [ "$_secondaries_with_content" -gt 0 ] || [ "$_secondaries_unverified" -gt 0 ]; then
            local _smsg="found $_db_count MapsSync_*.sqlite candidates; exported from the first one only"
            [ "$_secondaries_with_content" -gt 0 ] && _smsg="$_smsg — $_secondaries_with_content secondary account DB(s) hold user content that was NOT processed"
            [ "$_secondaries_unverified" -gt 0 ] && _smsg="$_smsg — $_secondaries_unverified secondary DB(s) could not be snapshotted (locked by a running Maps.app / WAL skew), so their content is UNVERIFIED (not confirmed empty)"
            _smsg="$_smsg. Re-run with the desired DB selected if its content matters."
            log_warn "$_smsg"
            note_incomplete "$_maps_root" "Maps source database selection" "$_smsg"
        else
            log_info "Found $_db_count MapsSync_*.sqlite candidates under $_maps_dir; secondary DB(s) empty — using the first."
        fi
    fi
    if [ -z "$_db" ]; then
        _db=$(find "$_maps_dir" -name 'MapsSync_*_deviceLocalCache.db' \
            -type f 2>/dev/null | head -1)
        [ -n "$_db" ] && _db_is_cache=1
    fi
    if [ "$_db_is_cache" = "1" ]; then
        log_warn "main MapsSync database not found — exporting from the device-local cache (results may be partial)"
    fi
    local _fav_count=0 _coll_count=0 _hist_count=0
    if [ -n "$_db" ] && [ -f "$_db" ]; then
        log_info "Snapshotting MapsSync database and querying saved places / collections / recents..."
        ensure_scratch
        local _snap=""
        _snap=$(snapshot_db "$_db" 2>/dev/null) || _snap=""
        if [ -n "$_snap" ]; then
            if _maps_has_table ZFAVORITEITEM; then
                local _fav_count_q
                _fav_count_q=$(sqlite3 -readonly "$_snap" \
                    "SELECT COUNT(*) FROM ZFAVORITEITEM;" 2>/dev/null)
                if [ -z "$_fav_count_q" ]; then
                    log_warn "Maps: ZFAVORITEITEM count query failed — drift-check skipped."
                    note_incomplete "$_maps_root" "Saved Places.csv completeness" \
                        "a completeness check on the Maps database failed, so the export could not verify it captured every saved place — Saved Places.csv may be partial"
                    _fav_count=0
                else
                    _fav_count="$_fav_count_q"
                fi
                case "$_fav_count" in ''|*[!0-9]*) _fav_count=0 ;; esac
                if [ "$_fav_count" -gt 0 ]; then
                    local _hidden_clause="" _order="ORDER BY Z_PK"
                    _maps_has_col ZFAVORITEITEM ZHIDDEN && \
                        _hidden_clause="WHERE COALESCE(ZHIDDEN, 0) = 0"
                    _maps_has_col ZFAVORITEITEM ZPOSITIONINDEX && \
                        _order="ORDER BY ZPOSITIONINDEX, Z_PK"
                    local _fav_custom=""
                    _maps_has_col ZFAVORITEITEM ZCUSTOMNAME && _fav_custom="ZCUSTOMNAME"
                    local _fav_place_name=""
                    _fav_place_name="$(_pick_first_col "$_snap" ZFAVORITEITEM \
                        ZMAPITEMNAME ZNAME || true)"
                    local _fav_name_expr="''"
                    if [ -n "$_fav_custom" ] && [ -n "$_fav_place_name" ]; then
                        _fav_name_expr="$(_sql_tsv_safe "COALESCE(NULLIF($_fav_custom, ''), $_fav_place_name, '')")"
                    elif [ -n "$_fav_custom" ]; then
                        _fav_name_expr="$(_sql_tsv_safe "COALESCE($_fav_custom, '')")"
                    elif [ -n "$_fav_place_name" ]; then
                        _fav_name_expr="$(_sql_tsv_safe "COALESCE($_fav_place_name, '')")"
                    fi
                    local _fav_created_expr="NULL"
                    _maps_has_col ZFAVORITEITEM ZCREATETIME && \
                        _fav_created_expr="CASE WHEN ZCREATETIME <= 0 THEN NULL ELSE $(_sql_cd_to_unix ZCREATETIME) END"
                    local _fav_lastvisited_expr="''"
                    _maps_has_col ZFAVORITEITEM ZLASTVISITEDTIME && \
                        _fav_lastvisited_expr="COALESCE(datetime(CASE WHEN ZLASTVISITEDTIME <= 0 THEN NULL ELSE $(_sql_cd_to_unix ZLASTVISITEDTIME) END, 'unixepoch', 'localtime'), '')"
                    local _fav_modified_expr="''"
                    _maps_has_col ZFAVORITEITEM ZMODIFICATIONTIME && \
                        _fav_modified_expr="COALESCE(datetime(CASE WHEN ZMODIFICATIONTIME <= 0 THEN NULL ELSE $(_sql_cd_to_unix ZMODIFICATIONTIME) END, 'unixepoch', 'localtime'), '')"
                    local _fav_phone_expr="''"
                    if _maps_has_col ZFAVORITEITEM ZPHONENUMBER; then
                        _fav_phone_expr="$(_sql_tsv_safe "ZPHONENUMBER")"
                    fi
                    local _fav_url_expr="''" _fav_url_col
                    _fav_url_col="$(_pick_first_col "$_snap" ZFAVORITEITEM \
                        ZURL ZWEBSITEURL || true)"
                    [ -n "$_fav_url_col" ] && \
                        _fav_url_expr="$(_sql_tsv_safe "$_fav_url_col")"
                    local _fav_addr_expr="''" _fav_addr_col
                    _fav_addr_col="$(_pick_first_col "$_snap" ZFAVORITEITEM \
                        ZMAPITEMADDRESS ZORIGINATINGADDRESSSTRING ZADDRESS || true)"
                    [ -n "$_fav_addr_col" ] && \
                        _fav_addr_expr="$(_sql_tsv_safe "$_fav_addr_col")"
                    local _fav_lat_expr="''" _fav_lon_expr="''"
                    _maps_has_col ZFAVORITEITEM ZLATITUDE && \
                        _fav_lat_expr="COALESCE(ZLATITUDE, '')"
                    _maps_has_col ZFAVORITEITEM ZLONGITUDE && \
                        _fav_lon_expr="COALESCE(ZLONGITUDE, '')"
                    local _fav_csv="$_maps_root/Saved Places.csv"
                    local _fav_tmp
                    _fav_tmp="$(mktemp "$_fav_csv.tmp.XXXXXX" 2>/dev/null)" || _fav_tmp="$_fav_csv.tmp.$$"
                    track_output_path "$_fav_tmp"
                    {
                        printf 'ID,Name,Address,Latitude,Longitude,Created,Last Visited,Modified,Phone,URL\r\n'
                        sqlite3 -readonly "$_snap" "
                            SELECT 'maps-fav-' || Z_PK,
                                   $_fav_name_expr,
                                   $_fav_addr_expr,
                                   $_fav_lat_expr,
                                   $_fav_lon_expr,
                                   COALESCE(datetime($_fav_created_expr, 'unixepoch', 'localtime'), ''),
                                   $_fav_lastvisited_expr,
                                   $_fav_modified_expr,
                                   $_fav_phone_expr,
                                   $_fav_url_expr
                            FROM ZFAVORITEITEM
                            $_hidden_clause
                            $_order;
                        " -separator $'\x1f' 2>/dev/null | \
                            while IFS=$'\x1f' read -r _id _name _addr _lat _lon _ct _lv _mt _ph _url; do
                                printf '%s,%s,%s,%s,%s,%s,%s,%s,%s,%s\r\n' \
                                    "$(csv_field "$_id")" "$(csv_field "$_name")" \
                                    "$(csv_field "$_addr")" \
                                    "$(csv_field "$_lat")" "$(csv_field "$_lon")" \
                                    "$(csv_field "$_ct")" "$(csv_field "$_lv")" \
                                    "$(csv_field "$_mt")" "$(csv_field "$_ph")" \
                                    "$(csv_field "$_url")"
                            done
                    } > "$_fav_tmp"
                    if ! _atomic_commit_tmp $? "$_fav_tmp" "$_fav_csv"; then
                        note_incomplete "$_maps_root" "Saved Places.csv" \
                            "the CSV commit failed (disk full / read-only volume) — saved places were not exported"
                        _fav_count=0
                    fi
                    _untrack_output_path "$_fav_tmp"
                    local _fav_emit
                    _fav_emit=$(_count_csv_rows "$_fav_csv")
                    if [ -n "$_hidden_clause" ]; then
                        local _fav_hidden=$((_fav_count - _fav_emit))
                        if [ "$_fav_hidden" -gt 0 ]; then
                            _disclose_excluded "$_fav_hidden hidden saved place(s)" "hidden in Maps"
                        fi
                    elif [ "$_fav_emit" -ne "$_fav_count" ]; then
                        log_warn "Maps drift: discovered $_fav_count saved place(s), emitted $_fav_emit."
                        note_incomplete "$_maps_root" "Saved Places.csv — discovery and emit counts disagree" \
                            "discovered $_fav_count saved place(s) but emitted $_fav_emit; Saved Places.csv may be missing rows"
                    fi
                    _fav_count="$_fav_emit"
                    validate_csv_rfc4180 "$_fav_csv" || true
                    [ "$_fav_count" -eq 0 ] && rm -f -- "$_fav_csv" 2>/dev/null
                fi
            fi
            if _maps_has_table ZCOLLECTION; then
                local _coll_count_q
                _coll_count_q=$(sqlite3 -readonly "$_snap" \
                    "SELECT COUNT(*) FROM ZCOLLECTION;" 2>/dev/null)
                if [ -z "$_coll_count_q" ]; then
                    log_warn "Maps: ZCOLLECTION count query failed — drift-check skipped."
                    note_incomplete "$_maps_root" "Collections.csv completeness" \
                        "a completeness check on the Maps database failed, so the export could not verify it captured every collection — Collections.csv may be partial"
                    _coll_count=0
                else
                    _coll_count="$_coll_count_q"
                fi
                case "$_coll_count" in ''|*[!0-9]*) _coll_count=0 ;; esac
                local _coll_items=0
                if _maps_has_table ZCOLLECTIONITEM; then
                    local _coll_items_q
                    _coll_items_q=$(sqlite3 -readonly "$_snap" \
                        "SELECT COUNT(*) FROM ZCOLLECTIONITEM;" 2>/dev/null)
                    if [ -n "$_coll_items_q" ]; then
                        _coll_items="$_coll_items_q"
                    else
                        log_warn "Maps: ZCOLLECTIONITEM count query failed — collection-membership drift-check skipped."
                        note_incomplete "$_maps_root" "Collections.csv membership completeness" \
                            "a completeness check on the Maps database failed, so the export could not verify it captured every collection-item association — Collections.csv may be partial"
                    fi
                    case "$_coll_items" in ''|*[!0-9]*) _coll_items=0 ;; esac
                fi
                if [ "$_coll_items" -gt 0 ]; then
                    local _coll_csv="$_maps_root/Collections.csv"
                    local _c_title_has=0
                    _maps_has_col ZCOLLECTION ZTITLE && _c_title_has=1
                    local _c_title_expr="''" _c_title_order="c.Z_PK"
                    local _c_titled_pred_c="1=1" _c_titled_pred="1=1"
                    if [ "$_c_title_has" = "1" ]; then
                        _c_title_expr="$(_sql_tsv_safe "c.ZTITLE")"
                        _c_title_order="c.ZTITLE, c.Z_PK"
                        _c_titled_pred_c="COALESCE(TRIM(c.ZTITLE), '') <> ''"
                        _c_titled_pred="COALESCE(TRIM(ZTITLE), '') <> ''"
                    else
                        log_warn "Maps: ZCOLLECTION has no ZTITLE column on this macOS version — Collections.csv exports without collection names (the Collection column is blank; saved items still export)."
                        note_incomplete "$_maps_root" "Collections.csv collection names" \
                            "the Maps collection table is missing its title column on this macOS version, so collection NAMES could not be exported — the saved items still export, but the Collection column is blank for every row"
                    fi
                    local _jt _jpc _jcc
                    _jt="$(_discover_z_join "$_snap" PLACES || true)"
                    if [ -n "$_jt" ]; then
                        _jpc=$(sqlite3 -readonly "$_snap" "
                            SELECT name FROM pragma_table_info('$_jt')
                            WHERE name GLOB 'Z_[0-9]*PLACES' LIMIT 1;" 2>/dev/null)
                        _jcc=$(sqlite3 -readonly "$_snap" "
                            SELECT name FROM pragma_table_info('$_jt')
                            WHERE name GLOB 'Z_[0-9]*COLLECTIONS' LIMIT 1;" 2>/dev/null)
                        case "$_jpc" in *[!A-Za-z0-9_]*) _jpc="" ;; esac
                        case "$_jcc" in *[!A-Za-z0-9_]*) _jcc="" ;; esac
                    fi
                    local _ci_custom=""
                    _maps_has_col ZCOLLECTIONITEM ZCUSTOMNAME && _ci_custom="ci.ZCUSTOMNAME"
                    local _ci_place_name="" _ci_place_col
                    _ci_place_col="$(_pick_first_col "$_snap" ZCOLLECTIONITEM \
                        ZMAPITEMNAME ZNAME || true)"
                    [ -n "$_ci_place_col" ] && _ci_place_name="ci.$_ci_place_col"
                    local _ci_name_expr="''"
                    if [ -n "$_ci_custom" ] && [ -n "$_ci_place_name" ]; then
                        _ci_name_expr="$(_sql_tsv_safe "COALESCE(NULLIF($_ci_custom, ''), $_ci_place_name, '')")"
                    elif [ -n "$_ci_custom" ]; then
                        _ci_name_expr="$(_sql_tsv_safe "COALESCE($_ci_custom, '')")"
                    elif [ -n "$_ci_place_name" ]; then
                        _ci_name_expr="$(_sql_tsv_safe "COALESCE($_ci_place_name, '')")"
                    fi
                    local _ci_created_expr="NULL"
                    _maps_has_col ZCOLLECTIONITEM ZCREATETIME && \
                        _ci_created_expr="CASE WHEN ci.ZCREATETIME <= 0 THEN NULL ELSE $(_sql_cd_to_unix ci.ZCREATETIME) END"
                    local _ci_lat_expr="''" _ci_lon_expr="''"
                    _maps_has_col ZCOLLECTIONITEM ZLATITUDE && \
                        _ci_lat_expr="COALESCE(ci.ZLATITUDE, '')"
                    _maps_has_col ZCOLLECTIONITEM ZLONGITUDE && \
                        _ci_lon_expr="COALESCE(ci.ZLONGITUDE, '')"
                    local _ci_addr_expr="''" _ci_addr_col
                    _ci_addr_col="$(_pick_first_col "$_snap" ZCOLLECTIONITEM \
                        ZMAPITEMADDRESS ZORIGINATINGADDRESSSTRING ZADDRESS || true)"
                    [ -n "$_ci_addr_col" ] && \
                        _ci_addr_expr="$(_sql_tsv_safe "ci.$_ci_addr_col")"
                    local _ci_order="ci.Z_PK"
                    _maps_has_col ZCOLLECTIONITEM ZPOSITIONINDEX && \
                        _ci_order="ci.ZPOSITIONINDEX, ci.Z_PK"
                    local _c_desc_expr="''" _c_desc_col
                    _c_desc_col="$(_pick_first_col "$_snap" ZCOLLECTION \
                        ZCOLLECTIONDESCRIPTION ZSUBTITLE ZDESCRIPTION || true)"
                    [ -n "$_c_desc_col" ] && \
                        _c_desc_expr="$(_sql_tsv_safe "c.$_c_desc_col")"
                    local _c_created_expr="''"
                    _maps_has_col ZCOLLECTION ZCREATETIME && \
                        _c_created_expr="COALESCE(datetime(CASE WHEN c.ZCREATETIME <= 0 THEN NULL ELSE $(_sql_cd_to_unix c.ZCREATETIME) END, 'unixepoch', 'localtime'), '')"
                    local _c_shared_expr="''"
                    _maps_has_col ZCOLLECTION ZISSHARED && \
                        _c_shared_expr="CASE WHEN COALESCE(c.ZISSHARED, 0) = 0 THEN 'no' ELSE 'yes' END"
                    local _mcoll_tmp
                    _mcoll_tmp="$(mktemp "$_coll_csv.tmp.XXXXXX" 2>/dev/null)" || _mcoll_tmp="$_coll_csv.tmp.$$"
                    track_output_path "$_mcoll_tmp"
                    {
                        printf 'ID,Collection,Collection Description,Collection Created,Collection Shared,Name,Address,Latitude,Longitude,Created\r\n'
                        if [ -n "$_jt" ] && [ -n "$_jpc" ] && [ -n "$_jcc" ]; then
                            sqlite3 -readonly "$_snap" "
                                SELECT 'maps-coll-item-' || ci.Z_PK || '-' || COALESCE(c.Z_PK, 0),
                                       $_c_title_expr,
                                       $_c_desc_expr,
                                       $_c_created_expr,
                                       $_c_shared_expr,
                                       $_ci_name_expr,
                                       $_ci_addr_expr,
                                       $_ci_lat_expr,
                                       $_ci_lon_expr,
                                       COALESCE(datetime($_ci_created_expr, 'unixepoch', 'localtime'), '')
                                FROM ZCOLLECTIONITEM ci
                                LEFT JOIN $_jt jt ON jt.$_jpc = ci.Z_PK
                                LEFT JOIN ZCOLLECTION c ON c.Z_PK = jt.$_jcc
                                ORDER BY $_c_title_order, $_ci_order;
                            " -separator $'\x1f' 2>/dev/null
                        else
                            sqlite3 -readonly "$_snap" "
                                SELECT 'maps-coll-item-' || ci.Z_PK,
                                       '', '', '', '',
                                       $_ci_name_expr,
                                       $_ci_addr_expr,
                                       $_ci_lat_expr,
                                       $_ci_lon_expr,
                                       COALESCE(datetime($_ci_created_expr, 'unixepoch', 'localtime'), '')
                                FROM ZCOLLECTIONITEM ci
                                ORDER BY $_ci_order;
                            " -separator $'\x1f' 2>/dev/null
                        fi | while IFS=$'\x1f' read -r _id _coll _cdesc _cct _cshr _name _caddr _lat _lon _ct; do
                            printf '%s,%s,%s,%s,%s,%s,%s,%s,%s,%s\r\n' \
                                "$(csv_field "$_id")" "$(csv_field "$_coll")" \
                                "$(csv_field "$_cdesc")" "$(csv_field "$_cct")" \
                                "$(csv_field "$_cshr")" "$(csv_field "$_name")" \
                                "$(csv_field "$_caddr")" \
                                "$(csv_field "$_lat")" "$(csv_field "$_lon")" \
                                "$(csv_field "$_ct")"
                        done
                    } > "$_mcoll_tmp"
                    if ! _atomic_commit_tmp $? "$_mcoll_tmp" "$_coll_csv"; then
                        note_incomplete "$_maps_root" "Collections.csv" \
                            "the CSV commit failed (disk full / read-only volume) — collections were not exported"
                    fi
                    _untrack_output_path "$_mcoll_tmp"
                    validate_csv_rfc4180 "$_coll_csv" || true
                    if [ -n "$_jt" ] && [ -n "$_jpc" ] && [ -n "$_jcc" ]; then
                        local _empty_colls
                        _empty_colls=$(sqlite3 -readonly "$_snap" "
                            SELECT COUNT(*) FROM ZCOLLECTION c
                            WHERE $_c_titled_pred_c
                              AND NOT EXISTS (
                                  SELECT 1 FROM $_jt jt
                                  WHERE jt.$_jcc = c.Z_PK);
                        " 2>/dev/null)
                        case "$_empty_colls" in ''|*[!0-9]*) _empty_colls=0 ;; esac
                        if [ "$_empty_colls" -gt 0 ]; then
                            note_incomplete "$_maps_root" "Collections.csv — empty collections omitted" \
                                "$_empty_colls titled collection(s) contain no saved items and therefore produce no rows in Collections.csv; the collection name itself is not represented in the export"
                        fi
                    else
                        local _coll_titled
                        _coll_titled=$(sqlite3 -readonly "$_snap" "
                            SELECT COUNT(*) FROM ZCOLLECTION
                             WHERE $_c_titled_pred;
                        " 2>/dev/null)
                        case "$_coll_titled" in ''|*[!0-9]*) _coll_titled=0 ;; esac
                        note_incomplete "$_maps_root" "Collections.csv — collection grouping not exported (fallback path)" \
                            "the Maps schema on this Mac does not expose the item→collection join table this leaf reads; ${_coll_titled} titled collection(s) exist on the source but the export carries items only (Collection column is blank for every row). Empty collections are silently absent from the export entirely."
                    fi
                    _coll_count=$(_count_csv_rows "$_coll_csv")
                    if [ -z "$_jt" ] || [ -z "$_jpc" ] || [ -z "$_jcc" ]; then
                        if [ "$_coll_count" -lt "$_coll_items" ]; then
                            log_warn "Maps drift: $_coll_items collection item(s) discovered, only $_coll_count in Collections.csv."
                            note_incomplete "$_maps_root" "Collections.csv — discovery and emit counts disagree" \
                                "discovered $_coll_items collection item(s) but only $_coll_count landed in Collections.csv — rows were dropped between query and emit"
                        fi
                    fi
                    [ "$_coll_count" -eq 0 ] && rm -f -- "$_coll_csv" 2>/dev/null
                else
                    local _coll_titled_empty
                    if _maps_has_col ZCOLLECTION ZTITLE; then
                        _coll_titled_empty=$(sqlite3 -readonly "$_snap" "
                            SELECT COUNT(*) FROM ZCOLLECTION
                             WHERE COALESCE(TRIM(ZTITLE), '') <> '';
                        " 2>/dev/null)
                    else
                        _coll_titled_empty=$(sqlite3 -readonly "$_snap" \
                            "SELECT COUNT(*) FROM ZCOLLECTION;" 2>/dev/null)
                    fi
                    case "$_coll_titled_empty" in ''|*[!0-9]*) _coll_titled_empty=0 ;; esac
                    if [ "$_coll_titled_empty" -gt 0 ]; then
                        note_incomplete "$_maps_root" "Collections.csv — empty collections omitted" \
                            "$_coll_titled_empty titled collection(s) contain no saved items and therefore produce no rows in Collections.csv; the collection name itself is not represented in the export"
                    fi
                    _coll_count=0
                fi
            fi
            if _maps_has_table ZHISTORYITEM; then
                local _hist_count_q
                _hist_count_q=$(sqlite3 -readonly "$_snap" \
                    "SELECT COUNT(*) FROM ZHISTORYITEM;" 2>/dev/null)
                if [ -z "$_hist_count_q" ]; then
                    log_warn "Maps: ZHISTORYITEM count query failed — drift-check skipped."
                    note_incomplete "$_maps_root" "Recents.csv completeness" \
                        "a completeness check on the Maps database failed, so the export could not verify it captured every recent — Recents.csv may be partial"
                    _hist_count=0
                else
                    _hist_count="$_hist_count_q"
                fi
                case "$_hist_count" in ''|*[!0-9]*) _hist_count=0 ;; esac
                if [ "$_hist_count" -gt 0 ]; then
                    local _hist_csv="$_maps_root/Recents.csv"
                    local _hist_date_expr="NULL" _hist_order="Z_PK"
                    if _maps_has_col ZHISTORYITEM ZCREATETIME; then
                        _hist_date_expr="CASE WHEN ZCREATETIME <= 0 THEN NULL ELSE $(_sql_cd_to_unix ZCREATETIME) END"
                        _hist_order="ZCREATETIME DESC, Z_PK"
                    fi
                    local _hist_type_col=""
                    _hist_type_col="$(_pick_first_col "$_snap" ZHISTORYITEM \
                        ZTYPE ZHISTORYITEMTYPE ZITEMTYPE || true)"
                    local _hist_type_expr="''"
                    if [ -n "$_hist_type_col" ]; then
                        _hist_type_expr="CASE
                            WHEN $_hist_type_col IS NULL THEN ''
                            WHEN $_hist_type_col = 0 THEN 'search'
                            WHEN $_hist_type_col = 1 THEN 'location'
                            WHEN $_hist_type_col = 2 THEN 'route'
                            WHEN $_hist_type_col = 3 THEN 'place'
                            ELSE '' END"
                    fi
                    local _hist_trans_col=""
                    _hist_trans_col="$(_pick_first_col "$_snap" ZHISTORYITEM \
                        ZTRANSPORTTYPE ZROUTINGMETHOD || true)"
                    local _hist_trans_expr="''"
                    if [ -n "$_hist_trans_col" ]; then
                        _hist_trans_expr="CASE
                            WHEN $_hist_trans_col IS NULL THEN ''
                            WHEN $_hist_trans_col = 0 THEN 'driving'
                            WHEN $_hist_trans_col = 1 THEN 'walking'
                            WHEN $_hist_trans_col = 2 THEN 'transit'
                            WHEN $_hist_trans_col = 3 THEN 'cycling'
                            ELSE '' END"
                    fi
                    local _hist_mod_expr="''"
                    _maps_has_col ZHISTORYITEM ZMODIFICATIONTIME && \
                        _hist_mod_expr="COALESCE(datetime(CASE WHEN ZMODIFICATIONTIME <= 0 THEN NULL ELSE $(_sql_cd_to_unix ZMODIFICATIONTIME) END, 'unixepoch', 'localtime'), '')"
                    local _hist_lat_own="" _hist_lon_own=""
                    _maps_has_col ZHISTORYITEM ZLATITUDE  && _hist_lat_own="ZLATITUDE, "
                    _maps_has_col ZHISTORYITEM ZLONGITUDE && _hist_lon_own="ZLONGITUDE, "
                    local _hist_lat_expr="''"
                    local _hist_lon_expr="''"
                    [ -n "$_hist_lat_own" ] && _hist_lat_expr="COALESCE(${_hist_lat_own}'')"
                    [ -n "$_hist_lon_own" ] && _hist_lon_expr="COALESCE(${_hist_lon_own}'')"
                    if _maps_has_col ZHISTORYITEM ZMAPITEM \
                       && _maps_has_table ZMIXINMAPITEM \
                       && _maps_has_col ZMIXINMAPITEM ZLATITUDE \
                       && _maps_has_col ZMIXINMAPITEM ZLONGITUDE; then
                        _hist_lat_expr="COALESCE(${_hist_lat_own}(SELECT m.ZLATITUDE FROM ZMIXINMAPITEM m WHERE m.Z_PK = ZHISTORYITEM.ZMAPITEM), '')"
                        _hist_lon_expr="COALESCE(${_hist_lon_own}(SELECT m.ZLONGITUDE FROM ZMIXINMAPITEM m WHERE m.Z_PK = ZHISTORYITEM.ZMAPITEM), '')"
                    fi
                    local _hist_query_expr="''"
                    _maps_has_col ZHISTORYITEM ZQUERY && \
                        _hist_query_expr="$(_sql_tsv_safe "ZQUERY")"
                    local _hist_locdisp_expr="''"
                    _maps_has_col ZHISTORYITEM ZLOCATIONDISPLAY && \
                        _hist_locdisp_expr="$(_sql_tsv_safe "ZLOCATIONDISPLAY")"
                    local _hist_tmp
                    _hist_tmp="$(mktemp "$_hist_csv.tmp.XXXXXX" 2>/dev/null)" || _hist_tmp="$_hist_csv.tmp.$$"
                    track_output_path "$_hist_tmp"
                    {
                        printf 'ID,Query,Location,Type,Transport,Latitude,Longitude,Date,Modified\r\n'
                        sqlite3 -readonly "$_snap" "
                            SELECT 'maps-hist-' || Z_PK,
                                   $_hist_query_expr,
                                   $_hist_locdisp_expr,
                                   $_hist_type_expr,
                                   $_hist_trans_expr,
                                   $_hist_lat_expr,
                                   $_hist_lon_expr,
                                   COALESCE(datetime($_hist_date_expr, 'unixepoch', 'localtime'), ''),
                                   $_hist_mod_expr
                            FROM ZHISTORYITEM
                            ORDER BY $_hist_order;
                        " -separator $'\x1f' 2>/dev/null | \
                            while IFS=$'\x1f' read -r _id _q _loc _ty _tr _lat _lon _dt _mt; do
                                printf '%s,%s,%s,%s,%s,%s,%s,%s,%s\r\n' \
                                    "$(csv_field "$_id")" "$(csv_field "$_q")" \
                                    "$(csv_field "$_loc")" "$(csv_field "$_ty")" \
                                    "$(csv_field "$_tr")" \
                                    "$(csv_field "$_lat")" "$(csv_field "$_lon")" \
                                    "$(csv_field "$_dt")" "$(csv_field "$_mt")"
                            done
                    } > "$_hist_tmp"
                    _atomic_commit_tmp $? "$_hist_tmp" "$_hist_csv"
                    _untrack_output_path "$_hist_tmp"
                    local _hist_emit
                    _hist_emit=$(_count_csv_rows "$_hist_csv")
                    validate_count_parity "$_hist_count" "$_hist_emit" "Maps recents" "$_maps_root"
                    _hist_count="$_hist_emit"
                    validate_csv_rfc4180 "$_hist_csv" || true
                fi
            fi
        else
            note_incomplete "$_maps_root" "Maps database unreadable" \
                "the Maps database at $_db is present but could not be snapshotted (corrupt, locked, or a scratch-copy failure) — no Maps data could be exported"
        fi
    fi
    local _parts=()
    [ "$_fav_count" -gt 0 ] && _parts+=("$_fav_count $(_pluralize "$_fav_count" "saved place")")
    [ "$_coll_count" -gt 0 ] && _parts+=("$_coll_count $(_pluralize "$_coll_count" "collection entry" "collection entries")")
    [ "$_hist_count" -gt 0 ] && _parts+=("$_hist_count $(_pluralize "$_hist_count" recent)")
    if [ "${#_parts[@]}" -gt 0 ]; then
        local _summary
        _summary="$(IFS=, ; printf '%s' "${_parts[*]}")"
        _summary="${_summary//,/, }"
        log_ok "Wrote Maps/ ($_summary, $(_dir_size_human "$_maps_root"))"
    elif report_have_incomplete "$_maps_root"; then
        log_warn "Maps: an earlier step could not complete$(_disclosure_pointer "Maps/_incomplete.txt")."
    else
        rmdir "$_maps_root" 2>/dev/null || true
        report_empty_source "saved places, collections, or recents" "Maps"
    fi
    return 0
}

maps_main() {
    maybe_show_help "$@"
    _announce_step "Maps export"
    check_dependencies
    local out_arg out_dir
    out_arg="$(_parse_output_folder_arg "$@")" || exit 1
    out_dir="$(resolve_output_dir "$out_arg")" || exit 1
    _announce_output_dir "Maps"
    require_full_disk_access
    export_maps "$out_dir"
    mark_success
    sweep_junk_files "$out_dir"
    print_summary
    if [ "$ERR_COUNT" -gt 0 ]; then exit 1; fi
    exit 0
}

MSG_DIR="$HOME/Library/Messages"
_contact_resolve_cache=""
_contact_resolve_cache_file=""
MESSAGES_USE_IMESSAGE_EXPORTER="${MESSAGES_USE_IMESSAGE_EXPORTER:-1}"
_IME_BIN=""
_IME_VERSION=""

_fetch_imessage_exporter() {
    [ "$MESSAGES_USE_IMESSAGE_EXPORTER" = "1" ] || return 1
    if ! command -v curl >/dev/null 2>&1; then
        log_warn "curl not found — cannot auto-fetch imessage-exporter; HTML conversion skipped"
        return 1
    fi
    ensure_scratch
    local arch asset_arch
    arch="$(uname -m 2>/dev/null)"
    case "$arch" in
        arm64)  asset_arch="aarch64-apple-darwin" ;;
        x86_64) asset_arch="x86_64-apple-darwin" ;;
        *)
            log_warn "Unrecognised architecture '$arch' — cannot pick an imessage-exporter asset; HTML conversion skipped."
            return 1 ;;
    esac
    local _imessage_exporter_fallback_tag="4.2.0"
    local tag
    tag="$(curl -fsSL --max-time 10 \
        https://api.github.com/repos/ReagentX/imessage-exporter/releases/latest \
        2>/dev/null \
        | sed -n 's/.*"tag_name"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' \
        | head -1)"
    if [ -z "$tag" ]; then
        log_warn "GitHub API returned no tag (rate-limited or offline) — using fallback $_imessage_exporter_fallback_tag (no cryptographic verification; trust is HTTPS-transport only)."
        tag="$_imessage_exporter_fallback_tag"
    fi
    local asset_name="imessage-exporter-$asset_arch"
    local url="https://github.com/ReagentX/imessage-exporter/releases/download/${tag}/${asset_name}"
    local bin="$SCRATCH_DIR/$asset_name"
    if ! _fetch_download "$url" "$bin" "imessage-exporter $tag" 120; then
        log_warn "Download failed: $url; HTML conversion skipped."
        return 1
    fi
    [ -s "$bin" ] || { log_warn "Downloaded binary is empty; HTML conversion skipped"; return 1; }
    chmod +x "$bin" 2>/dev/null || {
        log_warn "Cannot chmod +x downloaded binary; HTML conversion skipped."
        return 1
    }
    xattr -d com.apple.quarantine "$bin" 2>/dev/null || true
    if ! _run_with_timeout 30 "$bin" --help >/dev/null 2>&1; then
        log_warn "Downloaded imessage-exporter binary failed or timed out on --help smoke test; HTML conversion skipped."
        return 1
    fi
    _IME_BIN="$bin"
    _IME_VERSION="$tag"
    return 0
}

_msg_ime_diag_field() {  # <diag-text> <label> -> integer on stdout, empty if absent
    printf '%s\n' "$1" \
      | LC_ALL=C awk -v lbl="$2" '
            index($0, lbl) {
                n = $NF; gsub(/[^0-9]/, "", n)
                if (n != "") { print n; exit }
            }'
}

_msg_ime_parity() {
    local _db="$1" _dir="$2" _cat_dir="$3"
    [ -n "${_IME_BIN:-}" ] && [ -x "${_IME_BIN:-}" ] || return 0
    local _diag _bin_msgs _sql_msgs _orphans _deleted _subj
    _subj="$(_report_subject "$_cat_dir")"
    _diag="$("$_IME_BIN" -d -p "$_db" 2>/dev/null)"
    _bin_msgs="$(_msg_ime_diag_field "$_diag" 'Total messages:')"
    if [ -z "$_bin_msgs" ]; then
        log_info "Messages: could not read imessage-exporter's diagnostics — the rendered-message total was not cross-checked."
        [ -n "$_subj" ] && report_review "$_subj" \
            "Export completeness could not be verified" \
            "the conversations were written, but imessage-exporter's diagnostics could not be read (version change or a failed invocation), so its view of the database could not be cross-checked against ours; the exported conversations themselves are unaffected"
        return 0
    fi
    _sql_msgs="$(sqlite3 -readonly "$_db" 'SELECT COUNT(*) FROM message;' 2>/dev/null)"
    case "$_sql_msgs" in ''|*[!0-9]*) _sql_msgs="" ;; esac
    validate_count_parity "$_sql_msgs" "$_bin_msgs" \
        "Messages: renderer's view of chat.db" "$_cat_dir"
    _deleted="$(_msg_ime_diag_field "$_diag" 'Recoverable deleted messages:')"
    case "${_deleted:-0}" in
        ''|0|*[!0-9]*) ;;
        *) _disclose_excluded \
               "$_deleted recoverable deleted $(_pluralize "$_deleted" message)" \
               "held in the database's recoverable-deleted table, which neither renderer exports; restore from Messages (Recently Deleted), then re-run" ;;
    esac
    _orphans="$(_msg_ime_diag_field "$_diag" 'not associated with a chat')"
    case "${_orphans:-0}" in
        ''|0|*[!0-9]*) ;;
        *) log_info "$_orphans $(_pluralize "$_orphans" message) not attached to any conversation — exported to Exported/orphaned.html."
           [ -n "$_subj" ] && report_review "$_subj" \
               "$_orphans $(_pluralize "$_orphans" message) not attached to any conversation" \
               "these messages are not linked to any conversation, usually because the conversation was deleted while the messages were not; they ARE in the export, collected in Exported/orphaned.html rather than filed under a contact" ;;
    esac
    return 0
}

_msg_count_conv_html() {
    local _mcch_n
    _mcch_n="$(find "$1" -maxdepth 1 -type f -name '*.html' ! -name 'index.html' -print0 2>/dev/null | tr -dc '\0' | wc -c | tr -d ' ')"
    case "${_mcch_n:-0}" in ''|*[!0-9]*) _mcch_n=0 ;; esac
    printf '%s' "$_mcch_n"
}

_MSG_ADDRESSBOOK_DBS=()

_msg_find_addressbook_dbs() {
    local _abd="$1" _ab
    _MSG_ADDRESSBOOK_DBS=()
    for _ab in "$_abd/AddressBook-v22.abcddb" \
               "$_abd"/Sources/*/AddressBook-v22.abcddb; do
        [ -f "$_ab" ] && _MSG_ADDRESSBOOK_DBS+=("$_ab")
    done
}

_run_imessage_exporter_html() {
    local messages_root="$1"
    local data_root="$messages_root/Data"
    local exported_db="$data_root/chat.db"
    local exported_dir="$messages_root/Exported"
    [ -n "$_IME_BIN" ] || return 1
    [ -f "$exported_db" ] || {
        log_warn "Exported chat.db not found at $exported_db — HTML conversion skipped."
        return 1
    }
    require_no_collision "$exported_dir"
    track_output_path "$exported_dir"
    mkdir -p "$exported_dir" || {
        log_warn "Cannot create $exported_dir — HTML conversion skipped."
        return 1
    }
    local _ime_home="$SCRATCH_DIR/ime_contacts_home"
    local _ime_sources="$_ime_home/Library/Application Support/AddressBook/Sources"
    if ! mkdir -p "$_ime_sources"; then
        log_warn "Cannot create the imessage-exporter contacts staging dir — falling back to the built-in renderer."
        return 1
    fi
    local _ab_dir="$HOME/Library/Application Support/AddressBook"
    local _ab _ab_snap _ab_found=0 _ab_snapped=0 _ab_idx=0
    _msg_find_addressbook_dbs "$_ab_dir"
    for _ab in "${_MSG_ADDRESSBOOK_DBS[@]+"${_MSG_ADDRESSBOOK_DBS[@]}"}"; do
        _ab_found=$((_ab_found + 1))
        _ab_snap="$(snapshot_db "$_ab")"
        if [ -n "$_ab_snap" ] && [ -f "$_ab_snap" ]; then
            _ab_idx=$((_ab_idx + 1))
            if mkdir -p "$_ime_sources/src$_ab_idx" \
               && cp "$_ab_snap" "$_ime_sources/src$_ab_idx/AddressBook-v22.abcddb"; then
                _ab_snapped=$((_ab_snapped + 1))
            fi
        fi
    done
    if [ "$_ab_found" -gt 0 ] && [ "$_ab_snapped" -eq 0 ]; then
        log_warn "Could not snapshot any AddressBook database — falling back to the built-in renderer."
        return 1
    fi
    rm -f -- "$SCRATCH_DIR/ime_rc" "$SCRATCH_DIR/ime_bin_pid" \
        "$SCRATCH_DIR/ime_timeout" 2>/dev/null || true
    ( cd "$SCRATCH_DIR" && HOME="$_ime_home" "$_IME_BIN" \
        -p "$exported_db" \
        -c full \
        -r "$data_root" \
        -f html \
        -o "$exported_dir" \
        2>&1 >/dev/null &
      _ime_bin=$!
      printf '%s' "$_ime_bin" > "$SCRATCH_DIR/ime_bin_pid"
      wait "$_ime_bin"
      printf '%s' "$?" > "$SCRATCH_DIR/ime_rc" ) \
        | sed -l -E '
            /\[[0-9]+s\] \[/d;
            /No MOV converter found/d;
            /Attachment not found at specified path/d;
            /Attachment .* has no path on disk \(filename column is null\)/d;
            /^[[:space:]]*$/d;
            s/^/  /
        ' >&2 &
    local _ime_pipe_pid=$!
    CHILD_PIDS+=( "$_ime_pipe_pid" )
    local _ime_bin_pid="" _ime_pid_tries=0
    while [ "$_ime_pid_tries" -lt 50 ]; do
        if [ -s "$SCRATCH_DIR/ime_bin_pid" ]; then
            _ime_bin_pid="$(cat "$SCRATCH_DIR/ime_bin_pid" 2>/dev/null)"
            case "$_ime_bin_pid" in ''|*[!0-9]*) _ime_bin_pid="" ;; esac
            [ -n "$_ime_bin_pid" ] && break
        fi
        kill -0 "$_ime_pipe_pid" 2>/dev/null || break
        sleep 0.1 2>/dev/null || true
        _ime_pid_tries=$((_ime_pid_tries + 1))
    done
    [ -n "$_ime_bin_pid" ] && CHILD_PIDS+=( "$_ime_bin_pid" )
    local _ime_to="${MESSAGES_RENDER_TIMEOUT_SEC:-600}"
    case "$_ime_to" in ''|*[!0-9]*|0) _ime_to=600 ;; esac
    ( _e=0
      while kill -0 "$_ime_pipe_pid" 2>/dev/null; do
          if [ "$_e" -ge "$_ime_to" ]; then
              if [ -n "$_ime_bin_pid" ]; then _kill_tree "$_ime_bin_pid"; else _kill_tree "$_ime_pipe_pid"; fi
              : > "$SCRATCH_DIR/ime_timeout" 2>/dev/null || true
              log_warn "imessage-exporter exceeded ${_ime_to}s — killed; falling back to the built-in renderer."
              break
          fi
          sleep 1; _e=$((_e + 1))
      done ) &
    local _ime_wd=$!
    CHILD_PIDS+=( "$_ime_wd" )   # so an abort before the wait below reaps it (else it lingers ~1 s orphaned)
    wait "$_ime_pipe_pid" 2>/dev/null
    wait "$_ime_wd" 2>/dev/null   # watchdog self-exits within ~1 s of the render ending
    local _ime_rc=0
    if [ -f "$SCRATCH_DIR/ime_rc" ]; then
        _ime_rc="$(cat "$SCRATCH_DIR/ime_rc" 2>/dev/null)"
        case "$_ime_rc" in ''|*[!0-9]*) _ime_rc=1 ;; esac
    else
        _ime_rc=1
    fi
    if [ "$_ime_rc" = "0" ]; then
        local _ime_probe_html
        if [ ! -d "$exported_dir" ] \
           || ! IFS= read -r -d '' _ime_probe_html < <(find "$exported_dir" -maxdepth 1 -type f -name '*.html' ! -name 'index.html' -print0 -quit 2>/dev/null); then
            _ime_rc=1
        fi
    fi
    local _i _new_pids=()
    for _i in "${CHILD_PIDS[@]+"${CHILD_PIDS[@]}"}"; do
        [ "$_i" = "$_ime_pipe_pid" ] && continue
        [ -n "$_ime_bin_pid" ] && [ "$_i" = "$_ime_bin_pid" ] && continue
        [ -n "$_ime_wd" ] && [ "$_i" = "$_ime_wd" ] && continue
        _new_pids+=( "$_i" )
    done
    CHILD_PIDS=( "${_new_pids[@]+"${_new_pids[@]}"}" )
    if [ -f "$exported_db" ]; then
        sqlite3 "$exported_db" "PRAGMA wal_checkpoint(TRUNCATE);" >/dev/null 2>&1 || true
    fi
    if [ "$_ime_rc" -ne 0 ]; then
        if [ ! -e "$SCRATCH_DIR/ime_timeout" ]; then
            log_warn "imessage-exporter exited non-zero — HTML output may be incomplete"
        fi
        return 1
    fi
    return 0
}

_resolve_imessage_exporter_filenames() {
    local _exported_dir="$1" _contacts_src="$2"
    [ -d "$_exported_dir" ] || return 0
    ensure_scratch
    local _ime_lookup="$SCRATCH_DIR/ime_contact_lookup"
    local _ime_cache="$SCRATCH_DIR/ime_resolved_cache"
    : > "$_ime_lookup"
    : > "$_ime_cache"
    local _ab_dir="$HOME/Library/Application Support/AddressBook"
    if ! _msg_html_build_contact_lookup_from_db "$_ab_dir" "$_ime_lookup"; then
        log_info "Could not build AddressBook lookup for imessage-exporter — conversation filenames will fall back to raw phone numbers / email addresses for unresolved handles."
    fi
    if [ -n "$_contacts_src" ] \
       && { [ -d "$_contacts_src" ] || [ -f "$_contacts_src" ]; }; then
        local _vcf_lookup="$SCRATCH_DIR/ime_contact_lookup_vcf"
        : > "$_vcf_lookup"
        if _msg_html_build_contact_lookup "$_contacts_src" "$_vcf_lookup"; then
            cat "$_vcf_lookup" >> "$_ime_lookup" 2>/dev/null
        fi
        local _cs_dir
        if [ -d "$_contacts_src" ]; then
            _cs_dir="$_contacts_src"
        else
            _cs_dir="$(dirname "$_contacts_src")"
        fi
        if report_have_incomplete "$_cs_dir"; then
            log_warn "Contacts capture was incomplete — contact resolution is operating on a partial Contacts tree; some handles may render as raw phone numbers / email addresses."
        fi
    fi
    [ -s "$_ime_lookup" ] || return 0
    _contact_resolve_cache=""
    _contact_resolve_cache_file=""
    local _f _basename _id _resolved _newname _target _renamed=0
    for _f in "$_exported_dir"/*.html; do
        [ -f "$_f" ] || continue
        _basename="${_f##*/}"
        _id="${_basename%.html}"
        _newname=""
        case "$_id" in
            *", "*)
                local _resolved_parts="" _part _part_out _any_resolved=0
                local _rest="$_id"
                while [ -n "$_rest" ]; do
                    case "$_rest" in
                        *", "*) _part="${_rest%%", "*}"; _rest="${_rest#*", "}" ;;
                        *)      _part="$_rest";          _rest="" ;;
                    esac
                    _part_out="$_part"
                    case "$_part" in
                        "and "*[0-9]*" others"|"and "*[0-9]*" other") ;;
                        +[0-9]*|[0-9]*|*@*.*)
                            _resolved="$(_msg_html_resolve_contact "$_part" "$_ime_lookup" "$_ime_cache")"
                            if [ -n "$_resolved" ] && [ "$_resolved" != "$_part" ]; then
                                _part_out="$_resolved"
                                _any_resolved=1
                            fi ;;
                    esac
                    if [ -z "$_resolved_parts" ]; then
                        _resolved_parts="$_part_out"
                    else
                        _resolved_parts="$_resolved_parts, $_part_out"
                    fi
                done
                [ "$_any_resolved" = "1" ] && _newname="$(_sanitize_name "$_resolved_parts").html"
                ;;
            +[0-9]*|[0-9]*|*@*.*)
                _resolved="$(_msg_html_resolve_contact "$_id" "$_ime_lookup" "$_ime_cache")"
                if [ -n "$_resolved" ] && [ "$_resolved" != "$_id" ]; then
                    _newname="$(_sanitize_name "$_resolved").html"
                fi
                ;;
            *) ;;  # named chat / unrecognised — leave as-is
        esac
        if [ -n "$_newname" ]; then
            _target="$(_unique_path "$_exported_dir/$_newname")"
            if [ "$_target" != "$_f" ] && mv -- "$_f" "$_target" 2>/dev/null; then
                _renamed=$((_renamed + 1))
            fi
        fi
    done
    if [ "$_renamed" -gt 0 ]; then
        log_info "Resolved $_renamed Exported/ $(_pluralize "$_renamed" filename) from phone/email to contact name"
    fi
    return 0
}

_msg_html_build_contact_lookup_from_db() {
    local _ab_dir="$1" _out="$2"
    [ -d "$_ab_dir" ] || return 1
    : > "$_out" 2>/dev/null || return 1
    ensure_scratch
    local _ab _snap _found=0
    _msg_find_addressbook_dbs "$_ab_dir"
    for _ab in "${_MSG_ADDRESSBOOK_DBS[@]+"${_MSG_ADDRESSBOOK_DBS[@]}"}"; do
        _snap="$(snapshot_db "$_ab" 2>/dev/null)"
        [ -n "$_snap" ] && [ -f "$_snap" ] || continue
        local _pn_owner _em_owner _pn_cols _em_cols
        _pn_owner=""
        _em_owner=""
        _pn_cols="$(sqlite3 -readonly "$_snap" \
            "SELECT name FROM pragma_table_info('ZABCDPHONENUMBER');" 2>/dev/null)"
        _em_cols="$(sqlite3 -readonly "$_snap" \
            "SELECT name FROM pragma_table_info('ZABCDEMAILADDRESS');" 2>/dev/null)"
        if printf '%s\n' "$_pn_cols" | grep -qx 'ZOWNER'; then
            _pn_owner="ZOWNER"
        else
            _pn_owner="$(printf '%s\n' "$_pn_cols" | grep -m1 -E '^Z[0-9]+_OWNER$' || true)"
        fi
        if printf '%s\n' "$_em_cols" | grep -qx 'ZOWNER'; then
            _em_owner="ZOWNER"
        else
            _em_owner="$(printf '%s\n' "$_em_cols" | grep -m1 -E '^Z[0-9]+_OWNER$' || true)"
        fi
        case "$_pn_owner" in ''|*[!A-Za-z0-9_]*) _pn_owner="ZOWNER" ;; esac
        case "$_em_owner" in ''|*[!A-Za-z0-9_]*) _em_owner="ZOWNER" ;; esac
        local _msg_contact_ent
        _msg_contact_ent="$(sqlite3 -readonly "$_snap" "
            SELECT Z_ENT FROM Z_PRIMARYKEY
             WHERE Z_NAME IN ('ABCDContact','ABCDPerson')
             ORDER BY CASE Z_NAME WHEN 'ABCDContact' THEN 0 ELSE 1 END
             LIMIT 1;" 2>/dev/null)"
        case "$_msg_contact_ent" in ''|*[!0-9]*) _msg_contact_ent="" ;; esac
        local _msg_ent_pred=""
        [ -n "$_msg_contact_ent" ] && _msg_ent_pred="AND c.Z_ENT = $_msg_contact_ent"
        sqlite3 -readonly "$_snap" \
            "SELECT 1 FROM ZABCDPHONENUMBER LIMIT 1;" >/dev/null 2>&1 \
            && sqlite3 -readonly -separator $'\t' "$_snap" "
                SELECT p.ZFULLNUMBER,
                       COALESCE(
                           NULLIF(TRIM(COALESCE(c.ZFIRSTNAME,'') || ' ' || COALESCE(c.ZLASTNAME,'')), ''),
                           NULLIF(c.ZNICKNAME, ''),
                           NULLIF(c.ZORGANIZATION, ''),
                           ''
                       )
                  FROM ZABCDPHONENUMBER p
                  JOIN ZABCDRECORD c ON p.$_pn_owner = c.Z_PK
                 WHERE p.ZFULLNUMBER IS NOT NULL
                   AND p.ZFULLNUMBER != ''
                   $_msg_ent_pred;
            " 2>/dev/null | LC_ALL=C awk -F'\t' '
                NF >= 2 && $2 != "" {
                    name = $2
                    gsub(/[\t\r\n]/, " ", name)
                    digits = $1
                    gsub(/[^0-9]/, "", digits)
                    if (digits == "") next
                    print digits "\t" name
                    if (length(digits) > 10) {
                        print substr(digits, length(digits) - 9) "\t" name
                    }
                    _emitted++
                }
                END { exit (_emitted == 0) }
            ' >> "$_out" && _found=1
        sqlite3 -readonly "$_snap" \
            "SELECT 1 FROM ZABCDEMAILADDRESS LIMIT 1;" >/dev/null 2>&1 \
            && sqlite3 -readonly -separator $'\t' "$_snap" "
                SELECT LOWER(e.ZADDRESS),
                       COALESCE(
                           NULLIF(TRIM(COALESCE(c.ZFIRSTNAME,'') || ' ' || COALESCE(c.ZLASTNAME,'')), ''),
                           NULLIF(c.ZNICKNAME, ''),
                           NULLIF(c.ZORGANIZATION, ''),
                           ''
                       )
                  FROM ZABCDEMAILADDRESS e
                  JOIN ZABCDRECORD c ON e.$_em_owner = c.Z_PK
                 WHERE e.ZADDRESS IS NOT NULL
                   AND e.ZADDRESS != ''
                   $_msg_ent_pred;
            " 2>/dev/null | LC_ALL=C awk -F'\t' '
                NF >= 2 && $2 != "" {
                    name = $2
                    gsub(/[\t\r\n]/, " ", name)
                    print $1 "\t" name
                    _emitted++
                }
                END { exit (_emitted == 0) }
            ' >> "$_out" && _found=1
    done
    [ "$_found" = "1" ] && [ -s "$_out" ]
}

_msg_html_build_contact_lookup() {
    local _src="$1" _out="$2"
    local _found=0
    : > "$_out" 2>/dev/null || return 1
    _msg_html_parse_one_vcf() {
        local _vf="$1"
        [ -s "$_vf" ] || return 0
        local _current_fn="" _vcf_line _tel _digits _email
        while IFS= read -r _vcf_line; do
            _vcf_line="${_vcf_line%$'\r'}"
            case "$_vcf_line" in
                FN:*)    _current_fn="${_vcf_line#FN:}"; _current_fn="${_current_fn//$'\t'/ }" ;;
                TEL\;*|TEL:*)
                    _tel="${_vcf_line#*:}"
                    if [ -n "$_current_fn" ] && [ -n "$_tel" ]; then
                        _digits="$(printf '%s' "$_tel" | LC_ALL=C tr -cd '0-9')"
                        if [ -n "$_digits" ]; then
                            printf '%s\t%s\n' "$_digits" "$_current_fn" >> "$_out"
                            if [ "${#_digits}" -gt 10 ]; then
                                printf '%s\t%s\n' "${_digits: -10}" "$_current_fn" >> "$_out"
                            fi
                        fi
                    fi ;;
                EMAIL\;*|EMAIL:*)
                    _email="${_vcf_line#*:}"
                    if [ -n "$_current_fn" ] && [ -n "$_email" ]; then
                        printf '%s\t%s\n' \
                            "$(printf '%s' "$_email" | LC_ALL=C tr '[:upper:]' '[:lower:]')" \
                            "$_current_fn" >> "$_out"
                    fi ;;
                END:VCARD) _current_fn="" ;;
            esac
        done < "$_vf"
    }
    if [ -f "$_src" ]; then
        _msg_html_parse_one_vcf "$_src"
        _found=1
    elif [ -d "$_src" ]; then
        local _vf
        while IFS= read -r -d '' _vf; do
            _msg_html_parse_one_vcf "$_vf"
            _found=1
        done < <(find "$_src" -maxdepth 2 -type f -name '*.vcf' -print0 2>/dev/null)
    fi
    [ "$_found" = "1" ] && [ -s "$_out" ]
}

_msg_html_resolve_contact() {
    local _id="$1" _lookup="$2" _cache="$3"
    [ -z "$_id" ] && return 0
    [ ! -s "$_lookup" ] && { printf '%s' "$_id"; return 0; }
    if [ "${_contact_resolve_cache_file:-}" != "$_cache" ]; then
        _contact_resolve_cache_file="$_cache"
        if [ -s "$_cache" ]; then
            _contact_resolve_cache=$'\n'"$(<"$_cache")"
        else
            _contact_resolve_cache=$'\n'
        fi
    fi
    local _lower_id="" _id_digits="" _last10=""
    case "$_id" in
        *@*)
            case "$_id" in
                *[A-Z]*) _lower_id="$(LC_ALL=C printf '%s' "$_id" | LC_ALL=C tr '[:upper:]' '[:lower:]')" ;;
                *)       _lower_id="$_id" ;;
            esac ;;
    esac
    local _ch _d="" _i=0
    while [ "$_i" -lt "${#_id}" ]; do
        _ch="${_id:_i:1}"
        case "$_ch" in [0-9]) _d="${_d}${_ch}" ;; esac
        _i=$((_i + 1))
    done
    _id_digits="$_d"
    [ "${#_id_digits}" -gt 10 ] && _last10="${_id_digits: -10}"
    local _pk _ptail
    for _pk in "$_id" "$_lower_id" "$_id_digits" "$_last10"; do
        [ -z "$_pk" ] && continue
        case "$_pk" in *[*?[]*) continue ;; esac
        case "$_contact_resolve_cache" in
            *$'\n'"$_pk"$'\t'*)
                _ptail="${_contact_resolve_cache#*$'\n'"$_pk"$'\t'}"
                printf '%s' "${_ptail%%$'\n'*}"
                return 0 ;;
        esac
    done
    local _match=""
    if [ -n "$_lower_id" ] || [ -n "$_id_digits" ] || [ -n "$_last10" ]; then
        _match="$(e="$_lower_id" d="$_id_digits" l="$_last10" LC_ALL=C awk -F'\t' '
            BEGIN { e = ENVIRON["e"]; d = ENVIRON["d"]; l = ENVIRON["l"] }
            (e != "" && $1 == e) || (d != "" && $1 == d) { print $2; exit }
            (l != "" && $1 == l) && _lm == "" { _lm = $2 }
            END { if (_lm != "") print _lm }
        ' "$_lookup" 2>/dev/null)"
    fi
    local _result="${_match:-$_id}"
    printf '%s\t%s\n' "$_id" "$_result" >> "$_cache" 2>/dev/null
    _contact_resolve_cache="${_contact_resolve_cache}${_id}"$'\t'"${_result}"$'\n'
    printf '%s' "$_result"
}

_msg_html_recover_attributed_body() {
    local _hex="$1"
    [ -n "$_hex" ] || { printf ''; return 0; }
    printf '%s' "$_hex" | LC_ALL=C awk '
        function hv(c,   v) {
            v = index("0123456789abcdef", tolower(c));
            return (v > 0) ? v - 1 : -1;
        }
        {
            s = $0;
            gsub(/[^0-9A-Fa-f]/, "", s);
            n = length(s);
            if (n < 4 || (n % 2) != 0) { print ""; exit }
            nb = n / 2;
            for (i = 1; i <= nb; i++) {
                hi = hv(substr(s, 2*i - 1, 1));
                lo = hv(substr(s, 2*i, 1));
                if (hi < 0 || lo < 0) { print ""; exit }
                b[i] = hi * 16 + lo;
            }
            start = 0;
            for (i = 1; i < nb; i++) {
                if (b[i] == 1 && b[i+1] == 43) { start = i + 2; break }
            }
            if (start == 0 || start > nb) { print ""; exit }
            lead = b[start];
            plen = 0; payload = start + 1;
            if (lead == 129) {            # 0x81: uint8 length
                if (start + 1 > nb) { print ""; exit }
                plen = b[start+1];
                payload = start + 2;
            } else if (lead == 130) {     # 0x82: uint16 BE length
                if (start + 2 > nb) { print ""; exit }
                plen = b[start+1] * 256 + b[start+2];
                payload = start + 3;
            } else if (lead == 131) {     # 0x83: uint32 BE length
                if (start + 4 > nb) { print ""; exit }
                plen = b[start+1] * 16777216 \
                     + b[start+2] * 65536 \
                     + b[start+3] * 256 \
                     + b[start+4];
                payload = start + 5;
            } else {
                plen = lead;              # < 0x80: lead byte is length
                payload = start + 1;
            }
            if (plen <= 0) { print ""; exit }
            pend = payload + plen - 1;
            if (pend > nb) pend = nb;
            if (pend > payload && b[pend-1] == 134 && b[pend] == 132) pend = pend - 2;
            if (pend < payload) { print ""; exit }
            out = ""; printable = 0;
            for (i = payload; i <= pend; i++) {
                v = b[i];
                if (v == 0) continue;
                if (v < 32 && v != 9 && v != 10 && v != 13) continue;
                out = out sprintf("%c", v);
                if (v >= 32 || v == 9 || v == 10) printable++;
            }
            if (printable == 0) { print ""; exit }
            print out;
        }
    '
}

_msg_url_encode_path() {
    LC_ALL=C p="$1" awk '
        function encodeseg(s,   out, i, c, n) {
            out = ""
            for (i = 1; i <= length(s); i++) {
                c = substr(s, i, 1)
                if (c ~ /[A-Za-z0-9._~-]/) {
                    out = out c
                } else {
                    n = ordtab[c]
                    out = out sprintf("%%%02X", n)
                }
            }
            return out
        }
        BEGIN {
            p = ENVIRON["p"]
            for (i = 0; i < 256; i++) ordtab[sprintf("%c", i)] = i
            n = split(p, parts, "/")
            out = ""
            for (i = 1; i <= n; i++) {
                if (i > 1) out = out "/"
                if (parts[i] == ".." || parts[i] == "." || parts[i] == "")
                    out = out parts[i]
                else
                    out = out encodeseg(parts[i])
            }
            printf "%s", out
        }
    ' 2>/dev/null
}

_msg_has_schema() {
    case "$1" in *"|$2|"*) return 0 ;; *) return 1 ;; esac
}

_msg_html_render_conversation() {
    local db="$1" chat_id="$2" conv_name="$3" is_group="$4"
    local service_name="$5" _participants="$6" html_file="$7"
    local attachments_base="$8" _lookup="$9" _cache="${10}"
    local _msg_schema="${11:-|}"
    case "$chat_id" in
        ''|*[!0-9]*)
            log_warn "Skipping conversation with non-numeric chat_id: '$chat_id'"
            return 1 ;;
    esac
    local _he _he2 _aname_he
    local _html_tmp _sel_rc=0
    _html_tmp="$(mktemp "$html_file.tmp.XXXXXX" 2>/dev/null)" \
        || _html_tmp="$html_file.tmp.$$"
    track_output_path "$_html_tmp"
    {
        printf '<!DOCTYPE html>\n<html><head>\n<meta charset="UTF-8">\n'
        html_escape "$conv_name" _he
        printf '<title>%s</title>\n' "$_he"
        cat <<'HTMLSTYLE'
<style>
body { font-family: -apple-system, Helvetica, Arial, sans-serif; max-width: 800px; margin: 0 auto; padding: 20px; background: #f5f5f5; color: #1a1a1a; }
h1 { margin-bottom: 4px; }
.info { color: #888; font-size: 13px; margin-bottom: 16px; }
.date-sep { text-align: center; color: #888; font-size: 12px; margin: 16px 0 8px; }
.msg { margin: 4px 0; padding: 8px 12px; border-radius: 16px; max-width: 70%; display: inline-block; word-wrap: break-word; white-space: pre-wrap; }
.row { margin: 2px 0; overflow: hidden; }
.row-me { text-align: right; }
.row-them { text-align: left; }
.from-me { background: #007AFF; color: white; }
.from-me-sms { background: #65C466; color: white; }
.from-them { background: #E9E9EB; color: black; }
.sender { font-size: 11px; color: #888; margin: 8px 0 2px 12px; }
.meta { font-size: 10px; color: #999; margin: 1px 12px; }
.row-me .meta { text-align: right; }
.edited-label { font-size: 10px; opacity: 0.7; margin-left: 4px; }
.attachment { margin: 4px 0; }
.attachment img { max-width: 300px; max-height: 300px; border-radius: 12px; }
.attachment video { max-width: 300px; border-radius: 12px; }
.attachment audio { max-width: 300px; }
.attach-file { font-style: italic; color: #666; font-size: 12px; padding: 6px 12px; background: #f0f0f0; border-radius: 8px; display: inline-block; }
.reaction { font-size: 11px; color: #888; margin: 0 12px; }
.thread-reply { border-left: 2px solid #007AFF; margin-left: 20px; padding-left: 8px; }
.system { text-align: center; font-size: 12px; color: #888; font-style: italic; margin: 8px 0; }
.unsent { text-align: center; font-size: 12px; color: #999; font-style: italic; margin: 8px 0; opacity: 0.75; }
.link-preview { display: inline-block; max-width: 70%; border-radius: 16px; overflow: hidden; text-decoration: none; color: inherit; border: 1px solid #ddd; background: #fff; }
.link-preview .lp-body { padding: 10px 12px; }
.link-preview .lp-url { font-size: 11px; color: #888; margin-bottom: 2px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
.link-preview .lp-title { font-weight: 600; font-size: 14px; color: #1a1a1a; }
.link-preview .lp-summary { font-size: 12px; color: #666; margin-top: 2px; display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; overflow: hidden; }
</style>
</head><body>
HTMLSTYLE
        html_escape "$conv_name" _he
        printf '<h1>%s</h1>\n' "$_he"
        printf '<div class="info">'
        [ -n "$service_name" ] && { html_escape "$service_name" _he; printf '%s' "$_he"; }
        [ "$is_group" = "true" ] && printf ' &mdash; Group chat'
        [ -n "$_participants" ] && { html_escape "$_participants" _he; printf '<br>Participants: %s' "$_he"; }
        printf '</div>\n'
        local _prev_date="" _prev_sender="" _prev_mid=""
        local _extra_cols=""
        if _msg_has_schema "$_msg_schema" date_edited; then
            _extra_cols="${_extra_cols},
                   COALESCE(m.date_edited, 0),
                   CASE WHEN m.date_edited > 0
                        THEN datetime($(_sql_cd_to_unix "m.date_edited"), 'unixepoch', 'localtime')
                        ELSE '' END"
        else
            _extra_cols="${_extra_cols},
                   0,
                   ''"
        fi
        if _msg_has_schema "$_msg_schema" balloon_id; then
            _extra_cols="${_extra_cols},
                   REPLACE(REPLACE(REPLACE(COALESCE(m.balloon_bundle_id, ''), char(31), ''), char(10), ' '), char(13), ' ')"
        else
            _extra_cols="${_extra_cols},
                   ''"
        fi
        if _msg_has_schema "$_msg_schema" expressive_style; then
            _extra_cols="${_extra_cols},
                   REPLACE(REPLACE(REPLACE(COALESCE(m.expressive_send_style_id, ''), char(31), ''), char(10), ' '), char(13), ' ')"
        else
            _extra_cols="${_extra_cols},
                   ''"
        fi
        if _msg_has_schema "$_msg_schema" assoc_emoji; then
            _extra_cols="${_extra_cols},
                   REPLACE(REPLACE(REPLACE(COALESCE(m.associated_message_emoji, ''), char(31), ''), char(10), ' '), char(13), ' ')"
        else
            _extra_cols="${_extra_cols},
                   ''"
        fi
        if _msg_has_schema "$_msg_schema" attributed_body; then
            _extra_cols="${_extra_cols},
                   CASE WHEN m.attributedBody IS NULL THEN ''
                        ELSE quote(m.attributedBody) END"
        else
            _extra_cols="${_extra_cols},
                   ''"
        fi
        if _msg_has_schema "$_msg_schema" assoc_guid; then
            _extra_cols="${_extra_cols},
                   COALESCE(m.associated_message_guid, '')"
        else
            _extra_cols="${_extra_cols},
                   ''"
        fi
        if _msg_has_schema "$_msg_schema" att_is_sticker; then
            _extra_cols="${_extra_cols},
                   COALESCE(a.is_sticker, 0)"
        else
            _extra_cols="${_extra_cols},
                   0"
        fi
        if _msg_has_schema "$_msg_schema" att_uti; then
            _extra_cols="${_extra_cols},
                   REPLACE(REPLACE(REPLACE(COALESCE(a.uti, ''), char(31), ''), char(10), ' '), char(13), ' ')"
        else
            _extra_cols="${_extra_cols},
                   ''"
        fi
        if _msg_has_schema "$_msg_schema" att_hide; then
            _extra_cols="${_extra_cols},
                   COALESCE(a.hide_attachment, 0)"
        else
            _extra_cols="${_extra_cols},
                   0"
        fi
        local _guidmap_file=""
        if _msg_has_schema "$_msg_schema" assoc_guid; then
            _guidmap_file="$SCRATCH_DIR/msg_guidmap_${chat_id}"
            sqlite3 -readonly -separator $'\x1f' "$db" "
                SELECT m.guid,
                       SUBSTR(
                         REPLACE(REPLACE(REPLACE(REPLACE(
                           COALESCE(NULLIF(m.text, ''), ''),
                           char(31), ' '), char(10), ' '), char(13), ' '), char(9), ' '),
                         1, 40)
                FROM chat_message_join cmj
                JOIN message m ON cmj.message_id = m.ROWID
                WHERE cmj.chat_id = '$chat_id'
                  AND COALESCE(m.text, '') <> '';
            " > "$_guidmap_file" 2>/dev/null || : > "$_guidmap_file"
        fi
        local _assoc_type_col="0" _thread_guid_col="''"
        _msg_has_schema "$_msg_schema" assoc_type \
            && _assoc_type_col="COALESCE(m.associated_message_type, 0)"
        _msg_has_schema "$_msg_schema" thread_guid \
            && _thread_guid_col="COALESCE(m.thread_originator_guid, '')"
        sqlite3 -readonly -separator $'\x1f' "$db" "
            SELECT m.ROWID,
                   REPLACE(REPLACE(COALESCE(m.text, ''), char(31), ''), char(10), char(2)),
                   m.is_from_me,
                   datetime($(_sql_cd_to_unix "m.date"), 'unixepoch', 'localtime'),
                   date($(_sql_cd_to_unix "m.date"), 'unixepoch', 'localtime'),
                   REPLACE(REPLACE(REPLACE(COALESCE(h.id, ''), char(31), ''), char(10), ' '), char(13), ' '),
                   m.cache_has_attachments,
                   REPLACE(REPLACE(REPLACE(COALESCE(a.filename, ''), char(31), ''), char(10), ' '), char(13), ' '),
                   REPLACE(REPLACE(REPLACE(COALESCE(a.mime_type, ''), char(31), ''), char(10), ' '), char(13), ' '),
                   REPLACE(REPLACE(REPLACE(COALESCE(a.transfer_name, ''), char(31), ''), char(10), ' '), char(13), ' '),
                   $_assoc_type_col,
                   $_thread_guid_col,
                   REPLACE(REPLACE(REPLACE(COALESCE(m.group_title, ''), char(31), ''), char(10), ' '), char(13), ' '),
                   m.group_action_type,
                   REPLACE(REPLACE(REPLACE(COALESCE(m.service, ''), char(31), ''), char(10), ' '), char(13), ' '),
                   m.item_type,
                   COALESCE(m.handle_id, 0),
                   COALESCE(m.other_handle, 0),
                   REPLACE(REPLACE(REPLACE(COALESCE(oh.id, ''), char(31), ''), char(10), ' '), char(13), ' '),
                   CASE WHEN m.date_read > 0 AND m.date > 0
                        THEN CASE WHEN m.date > 4000000000
                                  THEN (m.date_read - m.date) / 1000000000
                                  ELSE (m.date_read - m.date) END
                        ELSE 0 END${_extra_cols}
            FROM chat_message_join cmj
            JOIN message m ON cmj.message_id = m.ROWID
            LEFT JOIN handle h ON m.handle_id = h.ROWID
            LEFT JOIN handle oh ON m.other_handle = oh.ROWID
            LEFT JOIN message_attachment_join maj ON maj.message_id = m.ROWID
            LEFT JOIN attachment a ON maj.attachment_id = a.ROWID
            WHERE cmj.chat_id = '$chat_id'
            ORDER BY m.date ASC, m.ROWID ASC, maj.ROWID ASC;
        " 2>/dev/null | while IFS=$'\x1f' read -r mid text is_from_me msg_datetime msg_date sender has_attach attach_file mime_type transfer_name assoc_type thread_guid group_title group_action msg_service item_type handle_id other_handle_id other_handle_str read_delta_seconds date_edited edited_datetime balloon_id expressive_style assoc_emoji attributed_body_hex assoc_guid att_is_sticker att_uti att_hide; do
            local _is_dup=false
            [ "$mid" = "$_prev_mid" ] && _is_dup=true
            _prev_mid="$mid"
            assoc_type="${assoc_type#"${assoc_type%%[!0]*}"}"
            assoc_type="${assoc_type:-0}"
            if [ "$_is_dup" != true ] && [ "$assoc_type" = "4000" ]; then
                local _pv_who="Someone"
                if [ "$is_from_me" = "1" ]; then
                    _pv_who="You"
                elif [ -n "$sender" ]; then
                    _pv_who="$(_msg_html_resolve_contact "$sender" "$_lookup" "$_cache")"
                fi
                html_escape "$_pv_who" _he
                printf '<div class="system">%s &middot; [Poll vote]</div>\n' "$_he"
                continue
            fi
            if [ "$_is_dup" != true ] && [ -n "$assoc_type" ] \
               && [ "$assoc_type" -ge 1000 ] 2>/dev/null \
               && [ "$assoc_type" -le 3007 ] 2>/dev/null; then
                local _reaction="" _reaction_verb=""
                case "$assoc_type" in
                    1000) _reaction="placed a sticker on" ;;
                    2000) _reaction="Loved" ;;
                    2001) _reaction="Liked" ;;
                    2002) _reaction="Disliked" ;;
                    2003) _reaction="Laughed at" ;;
                    2004) _reaction="Emphasized" ;;
                    2005) _reaction="Questioned" ;;
                    2006) html_escape "${assoc_emoji:-🙂}" _he; _reaction="reacted $_he to" ;;
                    2007) _reaction="replied with a sticker to" ;;
                    3000) _reaction_verb="removed"; _reaction="Love from" ;;
                    3001) _reaction_verb="removed"; _reaction="Like from" ;;
                    3002) _reaction_verb="removed"; _reaction="Dislike from" ;;
                    3003) _reaction_verb="removed"; _reaction="Laugh from" ;;
                    3004) _reaction_verb="removed"; _reaction="Emphasis from" ;;
                    3005) _reaction_verb="removed"; _reaction="Question from" ;;
                    3006) _reaction_verb="removed"; html_escape "${assoc_emoji:-🙂}" _he; _reaction="$_he reaction from" ;;
                    3007) _reaction_verb="removed"; _reaction="sticker from" ;;
                    *)    _reaction="reacted to" ;;
                esac
                local _who="Me"
                [ "$is_from_me" != "1" ] && [ -n "$sender" ] \
                    && _who="$(_msg_html_resolve_contact "$sender" "$_lookup" "$_cache")"
                local _target_txt=""
                if [ -n "$_guidmap_file" ] && [ -n "$assoc_guid" ] \
                   && [ -f "$_guidmap_file" ]; then
                    local _bare_guid="${assoc_guid##*/}"
                    if [ -n "$_bare_guid" ]; then
                        _target_txt="$(LC_ALL=C awk -F$'\x1f' \
                            -v g="$_bare_guid" '$1 == g { print $2; exit }' \
                            "$_guidmap_file" 2>/dev/null)"
                    fi
                fi
                local _target_phrase="a message"
                if [ -n "$_target_txt" ]; then
                    local _tt_h
                    html_escape "$_target_txt" _tt_h
                    if [ "${#_target_txt}" -ge 40 ]; then
                        _target_phrase="&ldquo;${_tt_h}&hellip;&rdquo;"
                    else
                        _target_phrase="&ldquo;${_tt_h}&rdquo;"
                    fi
                fi
                if [ -n "$text" ]; then
                    local _rt="${text//&/&amp;}"
                    _rt="${_rt//</&lt;}"
                    _rt="${_rt//>/&gt;}"
                    _rt="${_rt//$'\x02'/<br>}"
                    printf '<div class="reaction">%s</div>\n' "$_rt"
                elif [ -n "$_reaction_verb" ]; then
                    html_escape "$_who" _he
                    printf '<div class="reaction">%s %s %s %s</div>\n' "$_he" "$_reaction_verb" "$_reaction" "$_target_phrase"
                else
                    html_escape "$_who" _he
                    printf '<div class="reaction">%s %s %s</div>\n' "$_he" "$_reaction" "$_target_phrase"
                fi
                continue
            fi
            date_edited="${date_edited#"${date_edited%%[!0]*}"}"
            date_edited="${date_edited:-0}"
            if [ "$_is_dup" != true ] && [ -z "$text" ] \
               && [ "$date_edited" != "0" ] \
               && [ "$has_attach" != "1" ] && [ -z "$group_title" ]; then
                local _unsent_who="Someone"
                if [ "$is_from_me" = "1" ]; then
                    _unsent_who="You"
                elif [ -n "$sender" ]; then
                    _unsent_who="$(_msg_html_resolve_contact "$sender" "$_lookup" "$_cache")"
                fi
                html_escape "$_unsent_who" _he
                printf '<div class="unsent">%s unsent a message</div>\n' "$_he"
                continue
            fi
            group_action="${group_action#"${group_action%%[!0]*}"}"
            group_action="${group_action:-0}"
            item_type="${item_type#"${item_type%%[!0]*}"}"
            item_type="${item_type:-0}"
            local _is_group_event=false
            { [ "$item_type" -ne 0 ] 2>/dev/null || [ "$group_action" -ne 0 ] 2>/dev/null || [ -n "$group_title" ]; } && _is_group_event=true
            if [ "$_is_dup" != true ] && [ "$_is_group_event" = "true" ]; then
                local _ga_msg="" _ga_who=""
                [ -n "$other_handle_str" ] && \
                    _ga_who="$(_msg_html_resolve_contact "$other_handle_str" "$_lookup" "$_cache")"
                case "$item_type|$group_action" in
                    1\|0)
                        if [ -n "$other_handle_id" ] && [ "$other_handle_id" -ne 0 ] 2>/dev/null \
                           && [ "$handle_id" = "$other_handle_id" ]; then
                            html_escape "$_ga_who" _he
                            _ga_msg="A participant changed their phone number${_ga_who:+ ($_he)}"
                        else
                            if [ -n "$_ga_who" ]; then
                                html_escape "$_ga_who" _he; _ga_msg="$_he was added to the group"
                            else
                                _ga_msg="A participant was added to the group"
                            fi
                        fi ;;
                    1\|1)
                        if [ -n "$_ga_who" ]; then
                            html_escape "$_ga_who" _he; _ga_msg="$_he was removed from the group"
                        else
                            _ga_msg="A participant was removed from the group"
                        fi ;;
                    2\|*)
                        [ -n "$group_title" ] && \
                            html_escape "$group_title" _he; _ga_msg="Group name changed to &ldquo;$_he&rdquo;" ;;
                    3\|0)  _ga_msg="A participant left the group" ;;
                    3\|1)  _ga_msg="Group photo was changed" ;;
                    3\|2)  _ga_msg="Group photo was removed" ;;
                    3\|4)  _ga_msg="Chat background was changed" ;;
                    3\|6)  _ga_msg="Chat background was removed" ;;
                    6\|*)  _ga_msg="[SharePlay]" ;;
                    *)
                        if [ -n "$group_title" ]; then
                            html_escape "$group_title" _he; _ga_msg="Group name changed to &ldquo;$_he&rdquo;"
                        else
                            html_escape "$item_type" _he; html_escape "$group_action" _he2
                            _ga_msg="[Unknown group event: type=$_he action=$_he2]"
                        fi ;;
                esac
                if [ -n "$_ga_msg" ]; then
                    printf '<div class="system">%s</div>\n' "$_ga_msg"
                    continue
                fi
            fi
            local css_class="from-them" row_class="row-them" _who=""
            if [ "$is_from_me" = "1" ]; then
                row_class="row-me"; _who="Me"
                case "$msg_service" in
                    SMS|sms|RCS|rcs) css_class="from-me-sms" ;;
                    *)               css_class="from-me" ;;
                esac
            elif [ -n "$sender" ]; then
                _who="$(_msg_html_resolve_contact "$sender" "$_lookup" "$_cache")"
            fi
            local _has_content=false
            if [ "$_is_dup" != true ]; then
                if [ "$msg_date" != "$_prev_date" ] && [ -n "$msg_date" ]; then
                    printf '<div class="date-sep">%s</div>\n' "$msg_date"
                    _prev_date="$msg_date"
                    _prev_sender=""
                fi
                if [ "$is_group" = "true" ] && [ "$_who" != "$_prev_sender" ] && [ "$is_from_me" != "1" ]; then
                    html_escape "$_who" _he
                    printf '<div class="sender">%s</div>\n' "$_he"
                fi
                _prev_sender="$_who"
                local _thread_class=""
                [ -n "$thread_guid" ] && _thread_class=" thread-reply"
                local _edited_suffix=""
                if [ "$date_edited" != "0" ]; then
                    if [ -n "$edited_datetime" ]; then
                        _edited_suffix="<span class=\"edited-label\">(edited $edited_datetime)</span>"
                    else
                        _edited_suffix="<span class=\"edited-label\">(edited)</span>"
                    fi
                fi
                text="${text//$'\xef\xbf\xbc'/}"
                if [ -z "$text" ] && [ -n "$attributed_body_hex" ] \
                   && [ "$attributed_body_hex" != "NULL" ] \
                   && [ "$has_attach" != "1" ] \
                   && { [ -z "$balloon_id" ] \
                        || [ "$balloon_id" = "com.apple.messages.URLBalloonProvider" ]; }; then
                    local _ab_hex="$attributed_body_hex"
                    case "$_ab_hex" in
                        [Xx]\'*\') _ab_hex="${_ab_hex#?\'}"; _ab_hex="${_ab_hex%\'}" ;;
                        *) _ab_hex="" ;;
                    esac
                    local _recovered=""
                    [ -n "$_ab_hex" ] && \
                        _recovered="$(_msg_html_recover_attributed_body "$_ab_hex")"
                    if [ -n "$_recovered" ]; then
                        text="${_recovered//$'\n'/$'\x02'}"
                        text="${text//$'\r'/}"
                        text="${text//$'\xef\xbf\xbc'/}"
                    elif [ -z "$balloon_id" ]; then
                        text="[message content not extractable]"
                    fi
                fi
                local raw_text="${text//$'\x02'/ }"
                text="${text//&/&amp;}"
                text="${text//</&lt;}"
                text="${text//>/&gt;}"
                text="${text//$'\x02'/<br>}"
                local _effect_label=""
                if [ -n "$expressive_style" ]; then
                    case "$expressive_style" in
                        com.apple.MobileSMS.expressivesend.impact)       _effect_label="Slam" ;;
                        com.apple.MobileSMS.expressivesend.loud)         _effect_label="Loud" ;;
                        com.apple.MobileSMS.expressivesend.gentle)       _effect_label="Gentle" ;;
                        com.apple.MobileSMS.expressivesend.invisibleink) _effect_label="Invisible Ink" ;;
                        *CKConfettiEffect)      _effect_label="Confetti" ;;
                        *CKHeartEffect)         _effect_label="Heart" ;;
                        *CKBalloonEffect)       _effect_label="Balloons" ;;
                        *CKFireworksEffect)     _effect_label="Fireworks" ;;
                        *CKLasersEffect)        _effect_label="Lasers" ;;
                        *CKShootingStarEffect)  _effect_label="Shooting Star" ;;
                        *CKSparklesEffect)      _effect_label="Sparkles" ;;
                        *CKSpotlightEffect)     _effect_label="Spotlight" ;;
                        *CKEchoEffect)          _effect_label="Echo" ;;
                        *CKHappyBirthdayEffect) _effect_label="Happy Birthday" ;;
                        *) _effect_label="" ;;
                    esac
                fi
                if [ "$balloon_id" = "com.apple.messages.URLBalloonProvider" ]; then
                    local _url=""
                    _url="$(printf '%s' "$raw_text" \
                        | sed -n 's/.*\(https\{0,1\}:\/\/[^< ]*\).*/\1/p' \
                        | sed 's/[.,;:!?]*$//' \
                        | head -1)"
                    if [ -n "$_url" ]; then
                        local _display_domain
                        _display_domain="$(printf '%s' "$_url" | sed 's|https\{0,1\}://||; s|/.*||; s|^www\.||')"
                        html_escape "$_url" _he
                        printf '<div class="row %s%s"><a href="%s" class="link-preview">' "$row_class" "$_thread_class" "$_he"
                        printf '<div class="lp-body">'
                        html_escape "$_display_domain" _he
                        printf '<div class="lp-url">%s</div>' "$_he"
                        local _plain_text _raw_plain
                        _plain_text="$(printf '%s' "$text" | sed 's/<br>//g')"
                        _raw_plain="$(printf '%s' "$raw_text" | tr -d '\n\r' | sed 's/<br>//g')"
                        if [ "$_raw_plain" != "$_url" ] && [ -n "$_plain_text" ]; then
                            printf '<div class="lp-title">%s</div>' "$_plain_text"
                        else
                            html_escape "$_display_domain" _he
                            printf '<div class="lp-title">%s</div>' "$_he"
                        fi
                        printf '</div></a></div>\n'
                        _has_content=true
                    elif [ -n "$text" ]; then
                        printf '<div class="row %s%s"><div class="msg %s">%s%s</div></div>\n' "$row_class" "$_thread_class" "$css_class" "$text" "$_edited_suffix"
                        _has_content=true
                    fi
                elif [ -z "$text" ] && [ -n "$balloon_id" ] && [ "$balloon_id" != "com.apple.messages.URLBalloonProvider" ]; then
                    local _balloon_label=""
                    case "$balloon_id" in
                        *Handwriting*)      _balloon_label="Handwritten Message" ;;
                        *DigitalTouch*)     _balloon_label="Digital Touch" ;;
                        *PeerPayment*)      _balloon_label="Apple Pay" ;;
                        *ActivityMessages*) _balloon_label="Fitness Activity" ;;
                        *PhotosMessages*)   _balloon_label="Photo Slideshow" ;;
                        *SafetyMonitor*)    _balloon_label="Check In" ;;
                        *FindMy*|*findmy*)  _balloon_label="Location Sharing" ;;
                        *)                  _balloon_label="App Message" ;;
                    esac
                    html_escape "$_balloon_label" _he
                    printf '<div class="row %s%s"><div class="msg %s"><em>[%s]</em>%s</div></div>\n' "$row_class" "$_thread_class" "$css_class" "$_he" "$_edited_suffix"
                    _has_content=true
                elif [ -n "$text" ]; then
                    local _effect_suffix=""
                    [ -n "$_effect_label" ] && _effect_suffix="<span class=\"edited-label\"> (sent with $_effect_label)</span>"
                    printf '<div class="row %s%s"><div class="msg %s">%s%s%s</div></div>\n' "$row_class" "$_thread_class" "$css_class" "$text" "$_effect_suffix" "$_edited_suffix"
                    _has_content=true
                fi
            fi
            local _aname="" _render_attach=false
            if [ "$has_attach" = "1" ] && [ -n "$attach_file" ]; then
                _aname="${transfer_name:-${attach_file##*/}}"
                _render_attach=true
                case "$_aname" in
                    *.pluginPayloadAttachment|com.apple.*) _render_attach=false ;;
                esac
                att_hide="${att_hide#"${att_hide%%[!0]*}"}"
                att_hide="${att_hide:-0}"
                [ "$att_hide" = "1" ] && _render_attach=false
            fi
            if [ "$_render_attach" = "true" ]; then
                att_is_sticker="${att_is_sticker#"${att_is_sticker%%[!0]*}"}"
                att_is_sticker="${att_is_sticker:-0}"
                local _is_sticker_att=false
                [ "$att_is_sticker" = "1" ] && _is_sticker_att=true
                local _apath="" _rel="" _src=""
                if [ -n "$attachments_base" ]; then
                    _rel="${attach_file#*/Messages/Attachments/}"
                    case "$_rel" in
                        /*|../*|*/../*) _rel="" ;;
                    esac
                    [ -n "$_rel" ] && _src="$attachments_base/$_rel"
                fi
                local _render_ok=true
                if [ -z "$_rel" ] || [ -z "$_src" ] || [ ! -f "$_src" ]; then
                    html_escape "$_aname" _aname_he
                    printf '<div class="row %s"><div class="attachment"><span class="attach-file"><em>[Attachment not available: %s]</em></span></div></div>\n' \
                        "$row_class" "$_aname_he"
                    _has_content=true
                    _render_ok=false
                fi
                if [ "$_render_ok" = "true" ]; then
                    local _exported_dir="${html_file%/*}"
                    local _asset_rel _asset_dst
                    case "$_rel" in
                        *.[Hh][Ee][Ii][Cc]|*.[Hh][Ee][Ii][Ff])
                            _asset_rel="attachments/${_rel%.*}.jpeg"
                            _asset_dst="$_exported_dir/$_asset_rel"
                            if [ -f "$_asset_dst" ] && [ -s "$_asset_dst" ]; then
                                :
                            elif command -v sips >/dev/null 2>&1 \
                                 && mkdir -p "${_asset_dst%/*}" 2>/dev/null \
                                 && _sips_to_jpeg "$_src" "$_asset_dst.partial" 100 \
                                 && [ -s "$_asset_dst.partial" ] \
                                 && mv -f -- "$_asset_dst.partial" "$_asset_dst" 2>/dev/null; then
                                :
                            else
                                rm -f -- "$_asset_dst.partial" "$_asset_dst" 2>/dev/null
                                log_warn "HEIC conversion failed: $_aname (skipped inline render)"
                                html_escape "$_aname" _aname_he
                                printf '<div class="row %s"><div class="attachment"><span class="attach-file"><em>[Image not available: %s]</em></span></div></div>\n' \
                                    "$row_class" "$_aname_he"
                                _has_content=true
                                _render_ok=false
                            fi
                            if [ "$_render_ok" = "true" ]; then
                                _apath="$_asset_rel"
                                _aname="${_aname%.*}.jpeg"
                                mime_type="image/jpeg"
                            fi ;;
                        *)
                            _asset_rel="attachments/$_rel"
                            _asset_dst="$_exported_dir/$_asset_rel"
                            if { [ -f "$_asset_dst" ] && [ -s "$_asset_dst" ]; } \
                               || { mkdir -p "${_asset_dst%/*}" 2>/dev/null \
                                    && ditto -- "$_src" "$_asset_dst.partial" 2>/dev/null \
                                    && mv -f -- "$_asset_dst.partial" "$_asset_dst" 2>/dev/null; }; then
                                _apath="$_asset_rel"
                            else
                                rm -f -- "$_asset_dst" "$_asset_dst.partial" 2>/dev/null
                                log_warn "Attachment copy failed: $_aname (skipped inline render)"
                                html_escape "$_aname" _aname_he
                                printf '<div class="row %s"><div class="attachment"><span class="attach-file"><em>[Attachment not available: %s]</em></span></div></div>\n' \
                                    "$row_class" "$_aname_he"
                                _has_content=true
                                _render_ok=false
                            fi ;;
                    esac
                fi
                if [ "$_render_ok" = "true" ]; then
                    if [ -z "$mime_type" ] && [ -n "$att_uti" ]; then
                        case "$att_uti" in
                            public.heic)                     mime_type="image/heic" ;;
                            public.heif)                     mime_type="image/heif" ;;
                            public.jpeg)                     mime_type="image/jpeg" ;;
                            public.png)                      mime_type="image/png" ;;
                            com.compuserve.gif)              mime_type="image/gif" ;;
                            org.webmproject.webp|public.webp) mime_type="image/webp" ;;
                            public.tiff)                     mime_type="image/tiff" ;;
                            com.apple.quicktime-movie)       mime_type="video/quicktime" ;;
                            public.mpeg-4|public.mp4)        mime_type="video/mp4" ;;
                            com.apple.m4v-video)             mime_type="video/x-m4v" ;;
                            public.mp3)                      mime_type="audio/mpeg" ;;
                            public.mpeg-4-audio|com.apple.m4a-audio) mime_type="audio/mp4" ;;
                            com.apple.coreaudio-format)      mime_type="audio/x-caf" ;;
                            public.aac-audio)                mime_type="audio/aac" ;;
                        esac
                    fi
                    if [ -z "$mime_type" ]; then
                        case "$_aname" in
                            *.[Hh][Ee][Ii][Cc]|*.[Hh][Ee][Ii][Ff])             mime_type="image/heic" ;;
                            *.[Jj][Pp][Gg]|*.[Jj][Pp][Ee][Gg])                 mime_type="image/jpeg" ;;
                            *.[Pp][Nn][Gg])                                    mime_type="image/png" ;;
                            *.[Gg][Ii][Ff])                                    mime_type="image/gif" ;;
                            *.[Ww][Ee][Bb][Pp])                                mime_type="image/webp" ;;
                            *.[Tt][Ii][Ff][Ff]|*.[Tt][Ii][Ff])                 mime_type="image/tiff" ;;
                            *.[Mm][Oo][Vv])                                    mime_type="video/quicktime" ;;
                            *.[Mm][Pp]4|*.[Mm]4[Vv])                           mime_type="video/mp4" ;;
                            *.[Mm][Pp]3)                                       mime_type="audio/mpeg" ;;
                            *.[Mm]4[Aa]|*.[Aa][Aa][Cc])                        mime_type="audio/mp4" ;;
                            *.[Cc][Aa][Ff])                                    mime_type="audio/x-caf" ;;
                        esac
                    fi
                    local _apath_h _aname_h _mime_h _apath_enc
                    case "$_apath" in
                        attachments/*) _apath_enc="$(_msg_url_encode_path "$_apath")" ;;
                        *)             _apath_enc="$_apath" ;;
                    esac
                    [ -n "$_apath_enc" ] || _apath_enc="$_apath"
                    html_escape "$_apath_enc" _apath_h
                    html_escape "$_aname" _aname_h
                    html_escape "$mime_type" _mime_h
                    printf '<div class="row %s"><div class="attachment">' "$row_class"
                    [ "$_is_sticker_att" = "true" ] && \
                        printf '<span class="attach-file"><em>[Sticker]</em></span> '
                    case "$mime_type" in
                        image/*) printf '<a href="%s"><img src="%s" alt="%s"></a>' "$_apath_h" "$_apath_h" "$_aname_h" ;;
                        video/*) printf '<video controls><source src="%s" type="%s"></video>' "$_apath_h" "$_mime_h" ;;
                        audio/*) printf '<audio controls><source src="%s" type="%s"></audio>' "$_apath_h" "$_mime_h" ;;
                        *)       printf '<span class="attach-file"><a href="%s">%s</a></span>' "$_apath_h" "$_aname_h" ;;
                    esac
                    printf '</div></div>\n'
                    _has_content=true
                fi
            fi
            if [ "$_has_content" = "true" ] && [ "$_is_dup" != true ]; then
                local _meta_extra=""
                [ -n "$msg_service" ] && case "$msg_service" in
                    SMS|sms) _meta_extra=" &middot; SMS" ;;
                    RCS|rcs) _meta_extra=" &middot; RCS" ;;
                esac
                read_delta_seconds="${read_delta_seconds#"${read_delta_seconds%%[!0]*}"}"
                read_delta_seconds="${read_delta_seconds:-0}"
                if [ "$read_delta_seconds" -ge 2 ] 2>/dev/null; then
                    local _rd_label _h _m _d _rd_dur
                    if [ "$is_from_me" = "1" ]; then
                        _rd_label="Read by them"
                    else
                        _rd_label="Read after"
                    fi
                    _d=$(( read_delta_seconds / 86400 ))
                    _h=$(( (read_delta_seconds % 86400) / 3600 ))
                    _m=$(( (read_delta_seconds % 3600) / 60 ))
                    if   [ "$_d" -gt 0 ]; then _rd_dur="${_d}d ${_h}h"
                    elif [ "$_h" -gt 0 ]; then _rd_dur="${_h}h ${_m}m"
                    elif [ "$_m" -gt 0 ]; then _rd_dur="${_m}m"
                    else                       _rd_dur="${read_delta_seconds}s"
                    fi
                    _meta_extra="${_meta_extra} &middot; ${_rd_label} ${_rd_dur}"
                fi
                printf '<div class="meta %s">%s%s</div>\n' "$row_class" "$msg_datetime" "$_meta_extra"
            fi
        done
        _sel_rc=${PIPESTATUS[0]}
        printf '</body></html>\n'
    } > "$_html_tmp"
    ( exit "$_sel_rc" )
    if ! _atomic_commit_tmp $? "$_html_tmp" "$html_file" "conversation HTML"; then
        note_incomplete "${_messages_root:-$(dirname "$html_file")}" "Conversation '$conv_name' (chat_id=$chat_id)" \
            "the transcript query ended early (sqlite3 exit $_sel_rc — likely a lock or DB corruption after partial output); the truncated HTML was discarded rather than shipped as complete — re-run to retry"
    fi
    _untrack_output_path "$_html_tmp"
    rm -f -- "$_guidmap_file" 2>/dev/null
}

_msg_html_emit_index() {
    local _out_dir="$1"
    local _index="$_out_dir/index.html"
    local _idx_tmp
    _idx_tmp="$(mktemp "$_index.tmp.XXXXXX" 2>/dev/null)" \
        || _idx_tmp="$_index.tmp.$$"
    track_output_path "$_idx_tmp"
    local _list_tmp
    _list_tmp="$SCRATCH_DIR/index_list.txt"
    : > "$_list_tmp"
    local _hf _hf_bn
    while IFS= read -r -d '' _hf; do
        _hf_bn="${_hf##*/}"
        case "$_hf_bn" in
            index.html) continue ;;
        esac
        _hf_bn="${_hf_bn//$'\n'/}"; _hf_bn="${_hf_bn//$'\r'/}"
        [ -n "$_hf_bn" ] || continue
        printf '%s\n' "$_hf_bn" >> "$_list_tmp"
    done < <(find "$_out_dir" -maxdepth 1 -type f -name '*.html' -print0 2>/dev/null)
    LC_ALL=C sort -fo "$_list_tmp" "$_list_tmp" 2>/dev/null || true
    local _n
    _n="$(_count_lines "$_list_tmp")"
    {
        cat <<'IDXSTART'
<!DOCTYPE html>
<html><head>
<meta charset="UTF-8">
<title>Messages</title>
<style>
body { font-family: -apple-system, Helvetica, Arial, sans-serif; max-width: 800px; margin: 0 auto; padding: 20px; background: #f5f5f5; color: #1a1a1a; }
h1 { margin-bottom: 4px; }
.info { color: #888; font-size: 13px; margin-bottom: 16px; }
ul.convs { list-style: none; padding: 0; margin: 0; }
ul.convs li { margin: 0; padding: 0; }
ul.convs li a {
    display: block; padding: 10px 12px; border-radius: 12px;
    text-decoration: none; color: #1a1a1a; background: #fff;
    margin: 4px 0; border: 1px solid #e0e0e0; font-size: 14px;
}
ul.convs li a:hover { background: #f0f0f0; }
</style>
</head><body>
IDXSTART
        printf '<h1>Messages — %d %s</h1>\n' "$_n" "$(_pluralize "$_n" conversation)"
        printf '<ul class="convs">\n'
        local _row _title _row_href _href_he _title_he
        while IFS= read -r _row; do
            [ -z "$_row" ] && continue
            _title="${_row%.html}"
            _row_href="$(_msg_url_encode_path "$_row")"
            [ -n "$_row_href" ] || _row_href="$_row"
            html_escape "$_row_href" _href_he
            html_escape "$_title" _title_he
            printf '<li><a href="%s">%s</a></li>\n' \
                "$_href_he" "$_title_he"
        done < "$_list_tmp"
        printf '</ul>\n</body></html>\n'
    } > "$_idx_tmp"
    _atomic_commit_tmp $? "$_idx_tmp" "$_index" "Messages/Exported/index.html"
    _untrack_output_path "$_idx_tmp"
    rm -f -- "$_list_tmp" 2>/dev/null || true
}

_render_messages_html_bash() {
    local _messages_root="$1"
    local _contacts_src="${2:-}"
    local _data_root="$_messages_root/Data"
    local _db="$_data_root/chat.db"
    local _att_base="$_data_root/Attachments"
    local _out_dir="$_messages_root/Exported"
    [ -f "$_db" ] || {
        log_warn "Exported chat.db not found at $_db — bash HTML render skipped."
        return 1
    }
    require_no_collision "$_out_dir"
    track_output_path "$_out_dir"
    mkdir -p "$_out_dir" || {
        log_warn "Cannot create $_out_dir — bash HTML render skipped."
        return 1
    }
    ensure_scratch
    local _msg_schema="|"
    _col_present "$_db" message date_edited                && _msg_schema="${_msg_schema}date_edited|"
    _col_present "$_db" message balloon_bundle_id          && _msg_schema="${_msg_schema}balloon_id|"
    _col_present "$_db" message expressive_send_style_id   && _msg_schema="${_msg_schema}expressive_style|"
    _col_present "$_db" message associated_message_emoji   && _msg_schema="${_msg_schema}assoc_emoji|"
    _col_present "$_db" message attributedBody             && _msg_schema="${_msg_schema}attributed_body|"
    _col_present "$_db" message associated_message_guid    && _msg_schema="${_msg_schema}assoc_guid|"
    _col_present "$_db" message associated_message_type    && _msg_schema="${_msg_schema}assoc_type|"
    _col_present "$_db" message thread_originator_guid     && _msg_schema="${_msg_schema}thread_guid|"
    _col_present "$_db" attachment is_sticker              && _msg_schema="${_msg_schema}att_is_sticker|"
    _col_present "$_db" attachment uti                     && _msg_schema="${_msg_schema}att_uti|"
    _col_present "$_db" attachment hide_attachment         && _msg_schema="${_msg_schema}att_hide|"
    local _contact_lookup="$SCRATCH_DIR/msg_contact_lookup"
    local _resolved_cache="$SCRATCH_DIR/msg_contact_resolved_cache"
    : > "$_contact_lookup"
    : > "$_resolved_cache"
    local _ab_dir="$HOME/Library/Application Support/AddressBook"
    if _msg_html_build_contact_lookup_from_db "$_ab_dir" "$_contact_lookup"; then
        local _db_lines
        _db_lines="$(_count_lines "$_contact_lookup")"
        [ "$_db_lines" -gt 0 ] && \
            log_info "Built contact lookup from AddressBook ($_db_lines $(_pluralize "$_db_lines" identifier))"
    fi
    if [ -n "$_contacts_src" ]; then
        local _vcf_lookup="$SCRATCH_DIR/msg_contact_lookup_vcf"
        : > "$_vcf_lookup"
        if _msg_html_build_contact_lookup "$_contacts_src" "$_vcf_lookup"; then
            cat "$_vcf_lookup" >> "$_contact_lookup" 2>/dev/null
        fi
    fi
    if [ ! -s "$_contact_lookup" ]; then
        log_info "No contact source available — identifiers will render as phone numbers / emails."
    fi
    _contact_resolve_cache=""
    _contact_resolve_cache_file=""
    if [ -s "$_contact_lookup" ]; then
        local _rcn_warmed
        _rcn_warmed="$(_count_lines "$_contact_lookup")"
        case "${_rcn_warmed:-0}" in ''|0|*[!0-9]*) : ;; *)
            _contact_resolve_cache=$'\n'"$(<"$_contact_lookup")"$'\n'
            _contact_resolve_cache_file="$_resolved_cache"
            ;;
        esac
    fi
    local _chat_list_tmp="$SCRATCH_DIR/msg_chat_list"
    if ! sqlite3 -readonly -separator $'\x1f' "$_db" "
        SELECT c.ROWID,
               REPLACE(REPLACE(COALESCE(c.display_name, ''), char(10), ' '), char(13), ' '),
               REPLACE(REPLACE(COALESCE(c.chat_identifier, ''), char(10), ' '), char(13), ' '),
               COALESCE(c.service_name, ''),
               c.style
        FROM chat c
        ORDER BY c.ROWID;
    " > "$_chat_list_tmp" 2>/dev/null; then
        log_warn "Bash HTML render: chat-list query failed (locked / corrupt chat.db?)"
        return 1
    fi
    local _total_chats
    _total_chats="$(_count_lines "$_chat_list_tmp")"
    local conv_count=0 _chat_processed=0
    local _pt_last=0 _pt_inline=0
    local _html_validated=0
    local chat_id display_name chat_identifier service_name chat_style
    while IFS=$'\x1f' read -r chat_id display_name chat_identifier service_name chat_style; do
        case "$chat_id" in ''|*[!0-9]*) continue ;; esac
        _chat_processed=$((_chat_processed + 1))
        _progress_tick "$_chat_processed" "$_total_chats" "conversations rendered"
        local conv_name="$display_name"
        if [ -z "$conv_name" ]; then
            conv_name="$(_msg_html_resolve_contact "$chat_identifier" "$_contact_lookup" "$_resolved_cache")"
        fi
        [ -z "$conv_name" ] && conv_name="chat_${chat_id}"
        local is_group=false
        [ "$chat_style" = "43" ] && is_group=true
        local safe_name
        safe_name="$(_sanitize_name "$conv_name" | LC_ALL=C tr -d '+')"
        case "$safe_name" in ''|Untitled) safe_name="chat_${chat_id}" ;; esac
        local html_file="$_out_dir/${safe_name}.html"
        html_file="$(_unique_path "$html_file")"
        local msg_count _mc_rc msg_raw_count
        msg_count="$(sqlite3 -readonly "$_db" "
            SELECT COUNT(*) FROM chat_message_join cmj
            JOIN message m ON cmj.message_id = m.ROWID
            WHERE cmj.chat_id = '$chat_id';
        " 2>/dev/null)"
        _mc_rc=$?
        if [ "$_mc_rc" -ne 0 ]; then
            log_warn "Message-count query failed for chat '$conv_name' — skipping."
            note_incomplete "$_messages_root" "Conversation '$conv_name' (chat_id=$chat_id)" \
                "the per-chat message-count query against chat.db failed — this conversation was not rendered"
            continue
        fi
        case "$msg_count" in ''|*[!0-9]*) msg_count=0 ;; esac
        msg_raw_count="$(sqlite3 -readonly "$_db" \
            "SELECT COUNT(*) FROM chat_message_join WHERE chat_id = '$chat_id';" 2>/dev/null)"
        case "${msg_raw_count:-}" in ''|*[!0-9]*) msg_raw_count="$msg_count" ;; esac
        if [ "$msg_raw_count" -gt "$msg_count" ]; then
            local _orphan_n=$((msg_raw_count - msg_count))
            log_warn "Conversation '$conv_name': $_orphan_n chat_message_join row(s) point at deleted message ROWIDs — messages silently lost from chat.db (iCloud-sync residue or device retirement). Re-enable 'Sync this iPhone/Mac' in Apple ID > iCloud > Messages and wait for full re-download if you need those messages."
            note_incomplete "$_messages_root" "Conversation '$conv_name' (chat_id=$chat_id)" \
                "$_orphan_n message(s) in this conversation point to entries Apple has already removed from the local Messages database — those messages are not in this export. Re-enable Messages in iCloud (Apple ID > iCloud > Messages) and wait for the download, then re-run."
        fi
        [ "$msg_count" -eq 0 ] && continue
        local _participants=""
        if [ "$is_group" = "true" ]; then
            local _p_id _p_name
            local _part_tmp="$SCRATCH_DIR/msg_participants"
            sqlite3 -readonly "$_db" "
                SELECT h.id FROM chat_handle_join chj
                JOIN handle h ON chj.handle_id = h.ROWID
                WHERE chj.chat_id = '$chat_id'
                ORDER BY h.id;
            " > "$_part_tmp" 2>/dev/null
            while IFS= read -r _p_id; do
                [ -z "$_p_id" ] && continue
                _p_name="$(_msg_html_resolve_contact "$_p_id" "$_contact_lookup" "$_resolved_cache")"
                _participants="${_participants:+${_participants}, }${_p_name}"
            done < "$_part_tmp"
            local _opaque_name=false
            case "$conv_name" in
                chat[0-9]*|chat_[0-9]*) _opaque_name=true ;;
                [0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f])
                    _opaque_name=true ;;
            esac
            if [ "$_opaque_name" = "true" ] && [ -n "$_participants" ]; then
                conv_name="Group: $_participants"
                safe_name="$(_sanitize_name "$conv_name" | LC_ALL=C tr -d '+')"
                html_file="$_out_dir/${safe_name}.html"
                html_file="$(_unique_path "$html_file")"
            fi
        fi
        _msg_html_render_conversation "$_db" "$chat_id" "$conv_name" "$is_group" \
            "$service_name" "$_participants" "$html_file" \
            "$_att_base" "$_contact_lookup" "$_resolved_cache" \
            "$_msg_schema"
        [ -f "$html_file" ] && conv_count=$((conv_count + 1))
        if [ -f "$html_file" ]; then
            local _prune_tmp
            _prune_tmp="$(mktemp "$html_file.tmp.XXXXXX" 2>/dev/null)" || _prune_tmp="$html_file.tmp.$$"
            track_output_path "$_prune_tmp"
            LC_ALL=C awk '
                /class="date-sep"/ {
                    held = $0
                    next
                }
                /class="(msg|reaction|attachment|link-preview|system|unsent)/ {
                    if (held != "") { print held; held = "" }
                    print
                    next
                }
                { print }
            ' "$html_file" > "$_prune_tmp" 2>/dev/null
            _atomic_commit_tmp $? "$_prune_tmp" "$html_file" "orphan-date-sep prune"
            _untrack_output_path "$_prune_tmp"
        fi
        if [ -f "$html_file" ] \
           && ! grep -q 'class="msg\|class="system\|class="unsent\|class="attachment\|class="link-preview' "$html_file" 2>/dev/null; then
            rm -f -- "$html_file" 2>/dev/null
            conv_count=$((conv_count - 1))
        fi
        if [ "$_html_validated" != "1" ] && [ -f "$html_file" ]; then
            validate_html_structure "$html_file"
            _html_validated=1
        fi
    done < "$_chat_list_tmp"
    _progress_end
    if [ "$conv_count" -le 0 ]; then
        log_warn "Bash HTML render produced no usable conversation files."
        rmdir "$_out_dir" 2>/dev/null || true
        return 1
    fi
    _msg_html_emit_index "$_out_dir"
    [ -f "$_out_dir/index.html" ] || log_warn "Messages: Exported/index.html was not written (atomic commit failed) — per-conversation HTML files are still present."
    validate_html_structure "$_out_dir/index.html"
    return 0
}

_is_photo_suitable_ext() {
    case "$1" in
        [Hh][Ee][Ii][Cc]|[Hh][Ee][Ii][Ff]|\
        [Jj][Pp][Gg]|[Jj][Pp][Ee][Gg]|\
        [Pp][Nn][Gg]|[Ww][Ee][Bb][Pp]|\
        [Tt][Ii][Ff][Ff]|[Tt][Ii][Ff]|[Bb][Mm][Pp]|\
        [Mm][Oo][Vv]|[Mm][Pp]4|[Mm]4[Vv]|[Aa][Vv][Ii]|3[Gg][Pp])
            return 0 ;;
    esac
    return 1
}

messages_main() {
    maybe_show_help "$@"
    _announce_step "Messages export"
    check_dependencies
    [ "${_INVOKED_BY_WRAPPER:-0}" = "1" ] || timemachine_suspend
    local out_arg="" arg end_opts=0
    for arg in "$@"; do
        if [ "$end_opts" -eq 0 ]; then
            case "$arg" in
                --) end_opts=1; continue ;;
                --disable-imessage-exporter|--no-imessage-exporter)
                    MESSAGES_USE_IMESSAGE_EXPORTER=0; continue ;;
                -*)
                    die "Unknown flag: $arg" ;;
            esac
        fi
        if [ -n "$out_arg" ]; then
            die "Unexpected extra argument: $arg"
        fi
        out_arg="$arg"
    done
    local out_dir
    out_dir="$(resolve_output_dir "$out_arg")" || exit 1
    _announce_output_dir "Messages"
    log_info "Checking Full Disk Access and discovering Messages source..."
    require_full_disk_access
    warn_if_app_running Messages
    [ -d "$MSG_DIR" ] || die "Messages folder not found: $MSG_DIR
  Open Messages.app once to initialise it, then re-run."
    [ -f "$MSG_DIR/chat.db" ] || die "Messages database not found at $MSG_DIR/chat.db
  Sign in to Messages and let the database initialise, then re-run."
    log_info "Source: $MSG_DIR"
    local _disc_db_files=0 _disc_att_count=0
    local _sf
    for _sf in "$MSG_DIR/chat.db" "$MSG_DIR/chat.db-wal" "$MSG_DIR/chat.db-shm"; do
        [ -f "$_sf" ] && _disc_db_files=$((_disc_db_files + 1))
    done
    local _disc_att_size
    if [ -d "$MSG_DIR/Attachments" ]; then
        _disc_att_count="$(find "$MSG_DIR/Attachments" -type f ! -type l \
            ! -name '.DS_Store' ! -name '._*' ! -name '.localized' \
            ! -name '.VolumeIcon.icns' ! -name '.apdisk' \
            ! -name '.com.apple.timemachine.*' \
            -print0 2>/dev/null | tr -dc '\0' | wc -c | tr -d ' ')"
        case "$_disc_att_count" in ''|*[!0-9]*) _disc_att_count=0 ;; esac
        _disc_att_size="$(_dir_size_human "$MSG_DIR/Attachments")"
        log_info "Found chat.db family ($_disc_db_files $(_pluralize "$_disc_db_files" file)), $_disc_att_count $(_pluralize "$_disc_att_count" attachment) ($_disc_att_size)"
    else
        log_info "Found chat.db family ($_disc_db_files $(_pluralize "$_disc_db_files" file)), no Attachments folder"
    fi
    local _msg_in_icloud=""
    _msg_in_icloud="$(defaults read com.apple.madrid CloudKitSyncEnabled 2>/dev/null \
        || defaults read com.apple.imdpersistence.IMDPersistenceAgent CloudKitEnabled 2>/dev/null \
        || printf '')"
    case "$_msg_in_icloud" in
        1|[Tt]rue|[Yy][Ee][Ss])
            log_warn "Messages-in-iCloud appears enabled. With Optimize Mac Storage, older messages may live only in iCloud — chat.db here will be a snapshot of what's locally available, not the full conversation history. Apple provides no CLI to materialise iCloud-only messages; force-download via Apple ID > iCloud > Messages > Sync this iPhone/Mac > 'Download Now'." ;;
    esac
    local out_root="$out_dir/Messages"
    local data_dir="$out_root/Data"
    require_no_collision "$out_root"
    track_output_path "$out_root"
    mkdir -p "$data_dir" || die "Cannot create $data_dir"
    log_info "Snapshotting chat.db family + integrity check..."
    ensure_scratch
    local _snap
    _snap="$(snapshot_db_or_die "$MSG_DIR/chat.db" "Messages")" || exit 1
    require_db_tables "$_snap" "Messages" \
        message chat handle attachment chat_message_join chat_handle_join \
        message_attachment_join
    local db_count=0 db_src_count=0
    local -a missing_db=()
    local _sf _src_sib _dst_name
    for _sf in "$_snap" "${_snap}-wal" "${_snap}-shm"; do
        case "$_sf" in
            *-wal) _src_sib="$MSG_DIR/chat.db-wal"; _dst_name="chat.db-wal" ;;
            *-shm) _src_sib="$MSG_DIR/chat.db-shm"; _dst_name="chat.db-shm" ;;
            *)     _src_sib="$MSG_DIR/chat.db";      _dst_name="chat.db"      ;;
        esac
        [ -f "$_src_sib" ] || continue
        db_src_count=$((db_src_count + 1))
        if [ -f "$_sf" ] && ditto -- "$_sf" "$data_dir/$_dst_name" 2>/dev/null; then
            db_count=$((db_count + 1))
        else
            log_warn "Could not copy database file: $_dst_name."
        fi
        [ -e "$data_dir/$_dst_name" ] || missing_db+=( "$_dst_name" )
    done
    [ "$db_src_count" -eq 0 ] && die "No chat.db* files found in $MSG_DIR (Full Disk Access?)"
    if [ "${#missing_db[@]}" -gt 0 ]; then
        die "Partial chat.db family — these source files did NOT land in the destination: ${missing_db[*]}
  A chat.db without its -wal / -shm companion files (or vice versa) won't replay correctly on import.
  Likely causes: scratch / target volume out of space, or per-file Permission denied.
  Refusing to publish a corrupted snapshot."
    fi
    if [ -f "$data_dir/chat.db" ]; then
        sqlite3 "$data_dir/chat.db" "PRAGMA wal_checkpoint(TRUNCATE);" >/dev/null 2>&1 || true
        local _ic
        _ic="$(sqlite3 -readonly "$data_dir/chat.db" "PRAGMA integrity_check;" 2>/dev/null | head -1 || true)"
        if [ -n "$_ic" ] && [ "$_ic" != "ok" ]; then
            log_warn "chat.db integrity_check returned: $_ic"
            log_info "Messages.app may have been writing during the snapshot."
            log_info "The copy is openable but some rows may have mis-decoded blobs."
            log_info "Consider re-running with Messages.app quit."
        fi
    fi
    log_info "Copied chat.db family: $db_count $(_pluralize "$db_count" file), $(_dir_size_human "$data_dir")"
    local att_src="$MSG_DIR/Attachments"
    local att_dst="$data_dir/Attachments"
    local att_count=0
    local _msg_stubs_tsv=""
    local _msg_stub_count=0
    local _msg_junk_skipped=0
    if [ -d "$att_src" ]; then
        local _att_src_n
        if ! IFS= read -r -d '' _att_src_n < <(find "$att_src" -mindepth 1 -type f -print0 -quit 2>/dev/null); then
            _att_src_n=""
        fi
        [ -n "$_att_src_n" ] && log_info "Copying Attachments verbatim..."
        mkdir -p "$att_dst" || die "Cannot create $att_dst"
        ensure_scratch
        _msg_stubs_tsv="$SCRATCH_DIR/msg_stubs.tsv"
        : > "$_msg_stubs_tsv"
        local _af _arel _atdir _akept=0 _afail=0 _orig _af_src_sz _af_was_dataless
        local _pt_last=0 _pt_inline=0
        local _att_processed=0
        while IFS= read -r -d '' _af; do
            _arel="${_af#"$att_src"/}"
            if is_icloud_stub "$_af"; then
                _msg_stub_count=$((_msg_stub_count + 1))
                _orig="$(_strip_icloud_stub_name "${_arel##*/}")"
                tsv_escape "$_orig" _tsv_base
                case "$_arel" in
                    */*) tsv_escape "${_arel%/*}" _tsv_dir
                         printf '%s/%s\n' "$_tsv_dir" "$_tsv_base" >> "$_msg_stubs_tsv" ;;
                    *)   printf '%s\n' "$_tsv_base" >> "$_msg_stubs_tsv" ;;
                esac
                _att_processed=$((_att_processed + 1))
                continue
            fi
            if should_skip_copy "$_af" "$_arel"; then
                _msg_junk_skipped=$((_msg_junk_skipped + 1))
                is_macos_alias "$_af" && _att_processed=$((_att_processed + 1))
                continue
            fi
            case "$_arel" in
                */*) _atdir="$att_dst/${_arel%/*}" ;;
                *)   _atdir="$att_dst" ;;
            esac
            [ -d "$_atdir" ] || mkdir -p "$_atdir" 2>/dev/null
            if _ditto_verified "$_af" "$att_dst/$_arel"; then
                _akept=$((_akept + 1))
            else
                _afail=$((_afail + 1))
            fi
            _att_processed=$((_att_processed + 1))
            _progress_tick "$_att_processed" "$_disc_att_count" "attachments copied"
        done < <(find "$att_src" -type f ! -type l -print0 2>/dev/null)
        _progress_end
        if [ "$_afail" -gt 0 ]; then
            log_warn "$_afail $(_pluralize "$_afail" attachment) failed to copy (permissions or transient error)"
            note_incomplete "$out_root" "$_afail Messages $(_pluralize "$_afail" attachment)" \
                "the verbatim copy of these attachments into Messages/Attachments/ failed (permissions or a transient error) — they are not in the export"
        fi
        [ "$_msg_junk_skipped" -gt 0 ] && \
            _disclose_excluded "$_msg_junk_skipped junk path(s)" ".DS_Store / ._* / .localized / aliases"
        att_count="$_akept"
        [ "$att_count" -gt 0 ] && log_info "Copied Attachments: $att_count $(_pluralize "$att_count" file), $(_dir_size_human "$att_dst")"
        if [ "$_msg_stub_count" -gt 0 ]; then
            {
                printf '# Each entry is the recovered relative path under ~/Library/Messages/Attachments/.\n\n'
                printf '[Attachments]\n'
                LC_ALL=C sort -u "$_msg_stubs_tsv"
            } | _write_skipped_report "$out_root" "Messages attachments" \
                    "$_msg_stub_count" "" \
                    "System Settings > Apple ID > iCloud > Messages > Sync this iPhone (on), and disable Optimize Mac Storage system-wide"
        fi
        cleanup_empty_dirs "$att_dst"
    else
        log_info "Attachments folder not present (no media to copy)"
    fi
    log_info "Generating per-conversation HTML..."
    local _html_done=0
    local _msg_msg_n
    _msg_msg_n="$(sqlite3 -readonly "$data_dir/chat.db" "SELECT COUNT(*) FROM message;" 2>/dev/null)"
    case "${_msg_msg_n:-}" in
        ''|*[!0-9]*) _msg_msg_n=-1 ;;
    esac
    if [ "$_msg_msg_n" = "0" ]; then
        log_info "No messages in chat.db — nothing to render (the chat.db family is still exported above)"
        _html_done=1
    fi
    if [ "$_html_done" = "0" ]; then
        if [ "$MESSAGES_USE_IMESSAGE_EXPORTER" = "1" ]; then
            log_info "Using imessage-exporter (rich HTML rendering); will fall back to built-in renderer if the auto-fetch fails."
        else
            log_info "Using fallback path: built-in bash renderer (--disable-imessage-exporter set; lower fidelity)."
        fi
    fi
    if [ "$_html_done" = "0" ] && [ "$MESSAGES_USE_IMESSAGE_EXPORTER" = "1" ]; then
        if _fetch_imessage_exporter; then
            log_info "Fetched imessage-exporter ${_IME_VERSION:-(unknown)} (binary lives in scratch — cleaned on exit)"
            if _run_imessage_exporter_html "$out_root"; then
                local _ime_html_count
                _ime_html_count="$(_msg_count_conv_html "$out_root/Exported")"
                if [ "$_ime_html_count" -gt 0 ]; then
                    log_info "Wrote Messages/Exported/ via imessage-exporter: $_ime_html_count $(_pluralize "$_ime_html_count" "HTML conversation" "HTML conversations") + index, $(_dir_size_human "$out_root/Exported")."
                    local _ime_contacts_src=""
                    [ -d "$out_dir/Contacts" ] && _ime_contacts_src="$out_dir/Contacts"
                    _resolve_imessage_exporter_filenames "$out_root/Exported" "$_ime_contacts_src"
                    _msg_ime_parity "$_snap" "$out_root/Exported" "$out_root"
                    local _ime_first_html
                    if ! IFS= read -r -d '' _ime_first_html < <(find "$out_root/Exported" -maxdepth 1 -type f -name '*.html' ! -name 'index.html' -print0 2>/dev/null | LC_ALL=C sort -z); then
                        _ime_first_html=""
                    fi
                    if [ -n "$_ime_first_html" ]; then
                        validate_html_structure "$_ime_first_html" || true
                    fi
                    _msg_html_emit_index "$out_root/Exported"
                    [ -f "$out_root/Exported/index.html" ] || log_warn "Messages: Exported/index.html was not written (atomic commit failed) — per-conversation HTML files are still present."
                    _html_done=1
                else
                    log_warn "Primary path (imessage-exporter) produced no HTML files — falling back to built-in renderer."
                fi
            else
                log_warn "Primary path (imessage-exporter) failed at render time — falling back to built-in renderer."
            fi
        else
            log_warn "Primary path (imessage-exporter) auto-fetch failed — falling back to built-in renderer."
        fi
        if [ "$_html_done" = "0" ] && [ -d "$out_root/Exported" ]; then
            rm -rf -- "$out_root/Exported" 2>/dev/null || true
        fi
    fi
    if [ "$_html_done" = "0" ]; then
        local _contacts_src=""
        [ -d "$out_dir/Contacts" ] && _contacts_src="$out_dir/Contacts"
        if _render_messages_html_bash "$out_root" "$_contacts_src"; then
            local _bash_html_count
            _bash_html_count="$(_msg_count_conv_html "$out_root/Exported")"
            log_info "Wrote Messages/Exported/ via built-in renderer: $_bash_html_count $(_pluralize "$_bash_html_count" "HTML conversation" "HTML conversations") + index, $(_dir_size_human "$out_root/Exported")."
            _html_done=1
        else
            log_warn "Fallback path (built-in renderer) produced no output — Messages/Exported/ skipped."
            note_incomplete "$out_root" "Messages/Exported/ per-conversation HTML" \
                "neither imessage-exporter nor the built-in renderer produced HTML. Possible causes: a locked or corrupt database, a render failure, or chats that carry no joined messages (orphaned rows). The chat.db family itself IS exported; only the readable HTML rendering is missing — re-run, or open the .db with a SQLite/Messages viewer"
        fi
    fi
    if [ "$att_count" -eq 0 ]; then
        local _stat="$db_count $(_pluralize "$db_count" "database file" "database files"), $att_count $(_pluralize "$att_count" attachment)"
        [ "$_msg_stub_count" -gt 0 ] && \
            _stat="$_stat, $_msg_stub_count cloud-only$(_disclosure_pointer "Messages/_skipped.txt")"
        _stat="$_stat, $(_dir_size_human "$out_root")"
        log_ok "Wrote Messages/ ($_stat)"
        mark_success
        sweep_junk_files "$out_root"
        print_summary
        if [ "$ERR_COUNT" -gt 0 ]; then exit 1; fi
        exit 0
    fi
    log_info "Scanning attachments for Photos-importable media..."
    ensure_scratch
    local _sticker_set="$SCRATCH_DIR/msg_sticker_paths"
    : > "$_sticker_set"
    if [ -f "$data_dir/chat.db" ] \
       && sqlite3 -readonly "$data_dir/chat.db" \
            "SELECT is_sticker FROM attachment LIMIT 1;" >/dev/null 2>&1; then
        sqlite3 -readonly "$data_dir/chat.db" "
            SELECT filename FROM attachment
            WHERE is_sticker = 1 AND filename IS NOT NULL;
        " 2>/dev/null \
            | sed 's|.*/Messages/Attachments/||' \
            | LC_ALL=C sort -u > "$_sticker_set" 2>/dev/null || : > "$_sticker_set"
    fi
    local _sticker_count
    _sticker_count="$(_count_lines "$_sticker_set")"
    local -a cand_paths=() cand_sizes=() _cand_unsized=()
    local f sz
    local _scan_seen=0
    local _pt_last=0 _pt_inline=0
    local _scan_stickers_skipped=0
    local _scan_total
    _scan_total="$(find "$att_dst" -type f ! -type l -print0 2>/dev/null | tr -dc '\0' | wc -c | tr -d ' ')"
    case "$_scan_total" in ''|*[!0-9]*) _scan_total=0 ;; esac
    while IFS= read -r -d '' f; do
        _scan_seen=$((_scan_seen + 1))
        _progress_tick "$_scan_seen" "$_scan_total" "files scanned"
        _is_photo_suitable_ext "${f##*.}" || continue
        local _f_rel="${f#"$att_dst"/}"
        if [ "$_sticker_count" -gt 0 ]; then
            if LC_ALL=C grep -qxF -- "$_f_rel" "$_sticker_set" 2>/dev/null; then
                _scan_stickers_skipped=$((_scan_stickers_skipped + 1))
                continue
            fi
        fi
        _cand_unsized+=( "$f" )
    done < <(find "$att_dst" -type f ! -type l -print0 2>/dev/null)
    if [ "${#_cand_unsized[@]}" -gt 0 ]; then
        while IFS=' ' read -r sz f; do
            case "$sz" in
                ''|0|*[!0-9]*) continue ;;
            esac
            cand_paths+=( "$f" )
            cand_sizes+=( "$sz" )
        done < <(printf '%s\0' "${_cand_unsized[@]}" | xargs -0 stat -f '%z %N' 2>/dev/null)
    fi
    _progress_end
    local n=${#cand_paths[@]}
    log_info "Photos-suitable candidates: $n"
    [ "$_scan_stickers_skipped" -gt 0 ] && \
        _disclose_excluded "$_scan_stickers_skipped sticker $(_pluralize "$_scan_stickers_skipped" attachment)" "not Photos-import material, so kept out of Photos/From Messages/ (still present in Messages/Attachments/)"
    if [ "$n" -eq 0 ]; then
        log_info "No Photos-suitable media in Attachments/."
        local _stat="$db_count $(_pluralize "$db_count" "database file" "database files"), $att_count $(_pluralize "$att_count" attachment)"
        [ "$_msg_stub_count" -gt 0 ] && \
            _stat="$_stat, $_msg_stub_count cloud-only$(_disclosure_pointer "Messages/_skipped.txt")"
        _stat="$_stat, $(_dir_size_human "$out_root")"
        log_ok "Wrote Messages/ ($_stat)"
        mark_success
        sweep_junk_files "$out_root"
        print_summary
        if [ "$ERR_COUNT" -gt 0 ]; then exit 1; fi
        exit 0
    fi
    local idx_file="$SCRATCH_DIR/by_size.tsv"
    local i
    : > "$idx_file"
    for (( i=0; i<n; i++ )); do
        printf '%s\t%d\n' "${cand_sizes[$i]}" "$i" >> "$idx_file"
    done
    LC_ALL=C sort -s -n -k1,1 -o "$idx_file" "$idx_file"
    local for_photos="$out_dir/Photos/From Messages"
    require_no_collision "$for_photos"
    local _pl_hashes="$SCRATCH_DIR/photos_lib.hashes"
    local _pl_sizes="$SCRATCH_DIR/photos_lib.sizes"
    local _pl_dedup_on=0
    : > "$_pl_hashes"; : > "$_pl_sizes"
    local _rpt
    while IFS= read -r -d '' _rpt; do
        LC_ALL=C awk '
            /^\[assets\]$/ { in_assets = 1; next }
            /^\[/ && in_assets { in_assets = 0 }
            in_assets && /^[^#]/ {
                n = split($0, f, "\t")
                if (n >= 6 && f[6] ~ /^[0-9a-fA-F]{32}$/) {
                    print tolower(f[6]) > "/dev/stdout"
                    if (f[5] ~ /^[0-9]+$/) print f[5] > "/dev/stderr"
                }
                if (n >= 8 && f[8] != "") {
                    c = split(f[8], comps, ";")
                    for (i = 1; i <= c; i++) {
                        m = split(comps[i], parts, "|")
                        if (m >= 3 && parts[3] ~ /^[0-9a-fA-F]{32}$/) {
                            print tolower(parts[3]) > "/dev/stdout"
                            if (parts[2] ~ /^[0-9]+$/) print parts[2] > "/dev/stderr"
                        }
                    }
                }
            }
        ' "$_rpt" >> "$_pl_hashes" 2>> "$_pl_sizes"
    done < <(find "$out_dir/Photos" -mindepth 2 -maxdepth 6 -name '*.report' -type f -print0 2>/dev/null)
    if [ -s "$_pl_hashes" ]; then
        LC_ALL=C sort -u -o "$_pl_sizes"  "$_pl_sizes"  2>/dev/null || true
        LC_ALL=C sort -u -o "$_pl_hashes" "$_pl_hashes" 2>/dev/null || true
        _pl_dedup_on=1
        local _pl_n; _pl_n="$(_count_lines "$_pl_hashes")"
        log_info "Deduplicating against the Photos library export ($_pl_n known $(_pluralize "$_pl_n" hash hashes))..."
    fi
    _msg_in_photos_library() {
        [ "$_pl_dedup_on" = "1" ] || return 1
        local _src="$1" _sz="${2:-}" _pre="${3:-}" _h
        case "${_sz:-}" in ''|*[!0-9]*) return 1 ;; esac
        LC_ALL=C grep -F -x -q -- "$_sz" "$_pl_sizes" 2>/dev/null || return 1
        if [ -n "$_pre" ]; then
            _h="$_pre"
        else
            _h="$(_md5_hex "$_src" 2>/dev/null)" || return 1
        fi
        case "${_h:-}" in ''|*[!0-9a-fA-F]*) return 1 ;; esac
        [ "${#_h}" -eq 32 ] || return 1
        LC_ALL=C grep -F -x -q -- "$(printf '%s' "$_h" | LC_ALL=C tr 'A-F' 'a-f')" \
            "$_pl_hashes" 2>/dev/null
    }
    [ -d "$out_dir/Photos" ] || track_output_path "$out_dir/Photos"
    _create_output_dir "$for_photos"
    local kept=0 hash_dupes=0 hashed=0 unique_by_size=0 name_collisions=0
    local photos_lib_dupes=0
    local for_photos_failed=0
    _msg_process_group() {
        if [ "${#group_indices[@]}" -le 1 ]; then
            local idx
            for idx in "${group_indices[@]+"${group_indices[@]}"}"; do
                _msg_copy_to_for_photos "${cand_paths[$idx]}" "${cand_sizes[$idx]}"
                unique_by_size=$((unique_by_size + 1))
            done
        else
            local idx p h
            local _seen_var _seen_keys=()
            for idx in "${group_indices[@]}"; do
                p="${cand_paths[$idx]}"
                h="$(_md5_hex "$p")" || { log_warn "MD5 failed for $p"; for_photos_failed=$((for_photos_failed + 1)); continue; }
                hashed=$((hashed + 1))
                case "${h:-}" in
                    ''|*[!0-9a-fA-F]*)
                        log_warn "MD5 produced no usable hash for $p — copying without dedup"
                        _msg_copy_to_for_photos "$p" "${cand_sizes[$idx]}"
                        continue
                        ;;
                esac
                if [ "${#h}" -ne 32 ]; then
                    log_warn "MD5 produced unexpected hash length for $p (got ${#h}) — copying without dedup"
                    _msg_copy_to_for_photos "$p" "${cand_sizes[$idx]}"
                    continue
                fi
                printf -v _seen_var '_msg_seen_hash_%s' "$h"
                if [ -n "${!_seen_var+x}" ]; then
                    hash_dupes=$((hash_dupes + 1))
                else
                    printf -v "$_seen_var" 1
                    _seen_keys+=( "$_seen_var" )
                    _msg_copy_to_for_photos "$p" "${cand_sizes[$idx]}" "$h"
                fi
            done
            local _sk
            for _sk in "${_seen_keys[@]+"${_seen_keys[@]}"}"; do
                unset "$_sk"
            done
        fi
    }
    _msg_copy_to_for_photos() {
        local src="$1" src_size="${2:-}" src_hash="${3:-}"
        if _msg_in_photos_library "$src" "$src_size" "$src_hash"; then
            photos_lib_dupes=$((photos_lib_dupes + 1))
            return 0
        fi
        local base="${src##*/}"
        local target="$for_photos/$base"
        if [ -e "$target" ] || [ -L "$target" ]; then
            target="$(_unique_path "$target")"
            name_collisions=$((name_collisions + 1))
        fi
        if ditto -- "$src" "$target" 2>/dev/null; then
            kept=$((kept + 1))
        else
            rm -f -- "$target" 2>/dev/null
            log_warn "Copy failed: $base."
            for_photos_failed=$((for_photos_failed + 1))
        fi
    }
    local prev_size="" cur_size cur_idx
    local -a group_indices=()
    while IFS=$'\t' read -r cur_size cur_idx; do
        if [ "$cur_size" != "$prev_size" ]; then
            [ "${#group_indices[@]}" -gt 0 ] && _msg_process_group
            group_indices=()
            prev_size="$cur_size"
        fi
        group_indices+=( "$cur_idx" )
    done < "$idx_file"
    [ "${#group_indices[@]}" -gt 0 ] && _msg_process_group
    if [ "$kept" -eq 0 ]; then
        rmdir "$for_photos" 2>/dev/null || true
        rmdir "$out_dir/Photos" 2>/dev/null || true
        log_info "Photos/From Messages/: 0 files (all candidates failed or duplicated)"
    else
        log_info "Photos/From Messages/: $kept $(_pluralize "$kept" file), $(_dir_size_human "$for_photos")"
        if [ "$hash_dupes" -gt 0 ] || [ "$name_collisions" -gt 0 ]; then
            log_info "hashed $hashed (only same-size candidates), $hash_dupes content-$(_pluralize "$hash_dupes" dupe) skipped, $name_collisions filename $(_pluralize "$name_collisions" collision) suffixed"
        else
            log_info "$unique_by_size unique by size (no hashing), $hashed hashed for size-collision check"
        fi
        [ "$photos_lib_dupes" -gt 0 ] && \
            log_info "$photos_lib_dupes $(_pluralize "$photos_lib_dupes" file) skipped — already captured in your Photos library export"
    fi
    if [ "$for_photos_failed" -gt 0 ]; then
        log_warn "$for_photos_failed $(_pluralize "$for_photos_failed" file) could not be added to Photos/From Messages/ (copy or hash failure)"
        note_incomplete "$out_root" "Photos/From Messages/ subset — $for_photos_failed $(_pluralize "$for_photos_failed" file) missing" \
            "$for_photos_failed candidate $(_pluralize "$for_photos_failed" file) could not be copied or hashed into the Photos/From Messages/ subset; each is still present in the verbatim Messages/Data/Attachments/ mirror, so this is an importable-subset gap, not data loss"
    fi
    log_info "Finalising Messages/ and sweeping junk..."
    local _stat="$db_count $(_pluralize "$db_count" "database file" "database files"), $att_count $(_pluralize "$att_count" attachment)"
    [ "$kept" -gt 0 ] && _stat="$_stat, $kept to Photos/From Messages"
    [ "$_msg_stub_count" -gt 0 ] && \
        _stat="$_stat, $_msg_stub_count cloud-only$(_disclosure_pointer "Messages/_skipped.txt")"
    _stat="$_stat, $(_dir_size_human "$out_root")"
    log_ok "Wrote Messages/ ($_stat)"
    mark_success
    sweep_junk_files "$out_root"
    print_summary
    if [ "$ERR_COUNT" -gt 0 ]; then exit 1; fi
    exit 0
}

_MUSIC_PLAYLIST_CAP_RAW="${MUSIC_PLAYLIST_CAP-}"
: "${MUSIC_PLAYLIST_CAP:=500}"
case "$MUSIC_PLAYLIST_CAP" in
    ''|*[!0-9]*) MUSIC_PLAYLIST_CAP=500 ;;
    0[0-9]*)     MUSIC_PLAYLIST_CAP=$((10#$MUSIC_PLAYLIST_CAP)) ;;
esac

[ "$MUSIC_PLAYLIST_CAP" -gt 100000 ] && MUSIC_PLAYLIST_CAP=500
[ "$MUSIC_PLAYLIST_CAP" -lt 1 ] && MUSIC_PLAYLIST_CAP=500
if [ -n "$_MUSIC_PLAYLIST_CAP_RAW" ] && \
   [ "$_MUSIC_PLAYLIST_CAP_RAW" != "$MUSIC_PLAYLIST_CAP" ] && \
   case "$_MUSIC_PLAYLIST_CAP_RAW" in *[!0-9]*) false;; *) true;; esac; then
    _MUSIC_PLAYLIST_CAP_NOTICE="MUSIC_PLAYLIST_CAP clamped from $_MUSIC_PLAYLIST_CAP_RAW to $MUSIC_PLAYLIST_CAP (allowed range 1..100000)."
fi

unset _MUSIC_PLAYLIST_CAP_RAW
_MUSIC_PLAYLIST_PER_TIMEOUT_RAW="${MUSIC_PLAYLIST_PER_TIMEOUT_SEC-}"
: "${MUSIC_PLAYLIST_PER_TIMEOUT_SEC:=60}"
case "$MUSIC_PLAYLIST_PER_TIMEOUT_SEC" in
    ''|*[!0-9]*) MUSIC_PLAYLIST_PER_TIMEOUT_SEC=60 ;;
    0[0-9]*)     MUSIC_PLAYLIST_PER_TIMEOUT_SEC=$((10#$MUSIC_PLAYLIST_PER_TIMEOUT_SEC)) ;;
esac

[ "$MUSIC_PLAYLIST_PER_TIMEOUT_SEC" -gt 3600 ] && MUSIC_PLAYLIST_PER_TIMEOUT_SEC=60
[ "$MUSIC_PLAYLIST_PER_TIMEOUT_SEC" -lt 1 ] && MUSIC_PLAYLIST_PER_TIMEOUT_SEC=60
if [ -n "$_MUSIC_PLAYLIST_PER_TIMEOUT_RAW" ] && \
   [ "$_MUSIC_PLAYLIST_PER_TIMEOUT_RAW" != "$MUSIC_PLAYLIST_PER_TIMEOUT_SEC" ] && \
   case "$_MUSIC_PLAYLIST_PER_TIMEOUT_RAW" in *[!0-9]*) false;; *) true;; esac; then
    _MUSIC_PER_TIMEOUT_NOTICE="MUSIC_PLAYLIST_PER_TIMEOUT_SEC clamped from $_MUSIC_PLAYLIST_PER_TIMEOUT_RAW to $MUSIC_PLAYLIST_PER_TIMEOUT_SEC (allowed range 1..3600)."
fi

unset _MUSIC_PLAYLIST_PER_TIMEOUT_RAW
_MUSIC_LAUNCHED_BY_US=0
_MUSIC_OUT_ROOT=""

music_playlists_leaf_cleanup_hook() {
    quit_app_iff_we_launched_it Music _MUSIC_LAUNCHED_BY_US
    if [ -n "${_MUSIC_OUT_ROOT:-}" ] && [ -d "$_MUSIC_OUT_ROOT" ]; then
        find "$_MUSIC_OUT_ROOT" -type f \
            \( -name '*.csv.tmp' -o -name '*.m3u.tmp' \) \
            -delete 2>/dev/null || true
    fi
}

_music_has_been_launched() {
    [ -f "$HOME/Library/Preferences/com.apple.Music.plist" ] && return 0
    [ -d "$HOME/Library/Containers/com.apple.Music" ] && return 0
    return 1
}

_write_applescript() {
    ensure_scratch
    _AS_PATH="$SCRATCH_DIR/export_music.applescript"
    cat > "$_AS_PATH" <<'APPLESCRIPT'
on run argv
    set exportDir   to item 1 of argv
    set summaryPath to item 2 of argv

    set sRef to open for access POSIX file summaryPath with write permission
    try
        set eof sRef to 0
        close access sRef
    on error
        try
            close access sRef
        end try
    end try

    set skipNames to {"Library", "Music", "Downloaded", "Recently Added", ¬
                      "Recently Played", "Top 25 Most Played", "Loves", ¬
                      "Genius", "90s Music", "My Top Rated", "Purchased"}

    tell application "Music" to launch
    set prevCount to -1
    set stableHits to 0
    repeat 15 times
        try
            tell application "Music" to set curCount to count of playlists
            if curCount = prevCount and curCount > 0 then
                set stableHits to stableHits + 1
                if stableHits ≥ 2 then exit repeat
            else
                set stableHits to 0
                set prevCount to curCount
            end if
        end try
        delay 0.05
    end repeat

    tell application "Music"
        set plCount to count of playlists

        if plCount > __DOWNPOUR_MUSIC_PLAYLIST_CAP__ then
            set sRef to open for access POSIX file summaryPath with write permission
            try
                write ("ABORT" & tab & "count " & plCount & linefeed) as «class utf8» to sRef starting at eof
                close access sRef
            on error
                try
                    close access sRef
                end try
            end try
            return
        end if

        set consecTimeouts to 0
        set consecTimeoutMax to 5

        repeat with plIdx from 1 to plCount
          try -- outer per-playlist guard: skip any playlist that errors
            set pl to playlist plIdx
            set plName to "Unnamed"
            try
                set plName to name of pl
            end try
            set plName to my sanitize_summary_field(plName)

            set plClass to missing value
            try
                set plClass to class of pl
            end try

            set plIsSmart to false
            try
                if (smart of pl) then set plIsSmart to true
            end try

            set plIsBuiltin to false
            considering case
                if plName is in skipNames then set plIsBuiltin to true
            end considering

            if plIsBuiltin then
                try
                    set sRef to open for access POSIX file summaryPath with write permission
                    write ("SKIPPED-BUILTIN" & tab & plName & linefeed) as «class utf8» to sRef starting at eof
                    close access sRef
                on error
                    try
                        close access sRef
                    end try
                end try
            else if plClass is folder playlist then
                try
                    set sRef to open for access POSIX file summaryPath with write permission
                    write ("SKIPPED-FOLDER" & tab & plName & linefeed) as «class utf8» to sRef starting at eof
                    close access sRef
                on error
                    try
                        close access sRef
                    end try
                end try
            else if plIsSmart then
                try
                    set sRef to open for access POSIX file summaryPath with write permission
                    write ("SKIPPED-SMART" & tab & plName & linefeed) as «class utf8» to sRef starting at eof
                    close access sRef
                on error
                    try
                        close access sRef
                    end try
                end try
            else
                set plTimedOut to false
                set csvWriteOk to false
                set m3uWriteOk to true
                try
                    with timeout of __DOWNPOUR_MUSIC_PER_TIMEOUT__ seconds
                set trackCount to 0
                set reportedTrackCount to -1
                set localCount to 0
                set m3uLines to "#EXTM3U" & linefeed
                set csvLines to "Track,Artist,Album,Album Artist,Genre,Year,Track Number,Disc Number,Rating,Loved,Played Count,Date Added,Kind,Cloud Status,Time,Duration,Persistent ID" & return & linefeed
                set trNames to {}
                set trArtists to {}
                set trAlbums to {}
                set trAlbumArtists to {}
                set trGenres to {}
                set trYears to {}
                set trTrackNums to {}
                set trDiscNums to {}
                set trRatings to {}
                set trLoveds to {}
                set trPlayedCounts to {}
                set trDateAddeds to {}
                set trKinds to {}
                set trCloudStatuses to {}
                set trTimes to {}
                set trDurations to {}
                set trPersistentIDs to {}
                set trLocations to {}

                try
                    set trNames     to name     of every track of pl
                on error _em number _en
                    if _en is -1712 then error _em number _en
                end try
                try
                    set trArtists   to artist   of every track of pl
                on error _em number _en
                    if _en is -1712 then error _em number _en
                end try
                try
                    set trAlbums    to album    of every track of pl
                on error _em number _en
                    if _en is -1712 then error _em number _en
                end try
                try
                    set trAlbumArtists to album artist of every track of pl
                on error _em number _en
                    if _en is -1712 then error _em number _en
                end try
                try
                    set trGenres    to genre    of every track of pl
                on error _em number _en
                    if _en is -1712 then error _em number _en
                end try
                try
                    set trYears     to year     of every track of pl
                on error _em number _en
                    if _en is -1712 then error _em number _en
                end try
                try
                    set trTrackNums to track number of every track of pl
                on error _em number _en
                    if _en is -1712 then error _em number _en
                end try
                try
                    set trDiscNums  to disc number of every track of pl
                on error _em number _en
                    if _en is -1712 then error _em number _en
                end try
                try
                    set trRatings   to rating   of every track of pl
                on error _em number _en
                    if _en is -1712 then error _em number _en
                end try
                try
                    set trLoveds    to loved    of every track of pl
                on error _em number _en
                    if _en is -1712 then error _em number _en
                end try
                try
                    set trPlayedCounts to played count of every track of pl
                on error _em number _en
                    if _en is -1712 then error _em number _en
                end try
                try
                    set trDateAddeds to date added of every track of pl
                on error _em number _en
                    if _en is -1712 then error _em number _en
                end try
                try
                    set trKinds     to kind     of every track of pl
                on error _em number _en
                    if _en is -1712 then error _em number _en
                end try
                try
                    set trCloudStatuses to cloud status of every track of pl
                on error _em number _en
                    if _en is -1712 then error _em number _en
                end try
                try
                    set trTimes     to time     of every track of pl
                on error _em number _en
                    if _en is -1712 then error _em number _en
                end try
                try
                    set trDurations to duration of every track of pl
                on error _em number _en
                    if _en is -1712 then error _em number _en
                end try
                try
                    set trPersistentIDs to persistent ID of every track of pl
                on error _em number _en
                    if _en is -1712 then error _em number _en
                end try
                try
                    set trLocations to location of every track of pl
                on error _em number _en
                    if _en is -1712 then error _em number _en
                end try
                set trackCount to count of trNames
                try
                    set reportedTrackCount to (count of tracks of pl)
                on error _em number _en
                    if _en is -1712 then error _em number _en
                end try

                repeat with i from 1 to trackCount
                    set trName to ""
                    set trArtist to ""
                    set trAlbum to ""
                    set trAlbumArtist to ""
                    set trGenre to ""
                    set trYear to 0
                    set trTrackNum to 0
                    set trDiscNum to 0
                    set trRating to 0
                    set trLoved to ""
                    set trPlayedCount to 0
                    set trDateAdded to ""
                    set trKind to ""
                    set trCloudStatus to ""
                    set trTime to ""
                    set trDur to 0
                    set trPersistentID to ""
                    try
                        set trName to item i of trNames
                        if trName is missing value then set trName to ""
                    end try
                    try
                        set trArtist to item i of trArtists
                        if trArtist is missing value then set trArtist to ""
                    end try
                    try
                        set trAlbum to item i of trAlbums
                        if trAlbum is missing value then set trAlbum to ""
                    end try
                    try
                        set trAlbumArtist to item i of trAlbumArtists
                        if trAlbumArtist is missing value then set trAlbumArtist to ""
                    end try
                    try
                        set trGenre to item i of trGenres
                        if trGenre is missing value then set trGenre to ""
                    end try
                    try
                        set trYear to (item i of trYears) as integer
                    end try
                    try
                        set trTrackNum to (item i of trTrackNums) as integer
                    end try
                    try
                        set trDiscNum to (item i of trDiscNums) as integer
                    end try
                    try
                        set trRating to (item i of trRatings) as integer
                    end try
                    try
                        set trLoved to item i of trLoveds
                        if trLoved is missing value then
                            set trLoved to ""
                        else if trLoved is true then
                            set trLoved to "yes"
                        else
                            set trLoved to "no"
                        end if
                    end try
                    try
                        set trPlayedCount to (item i of trPlayedCounts) as integer
                    end try
                    try
                        set trDateAdded to item i of trDateAddeds
                        if trDateAdded is missing value then
                            set trDateAdded to ""
                        else
                            set trDateAdded to trDateAdded as text
                        end if
                    end try
                    try
                        set trKind to item i of trKinds
                        if trKind is missing value then set trKind to ""
                    end try
                    try
                        set trCloudStatus to item i of trCloudStatuses
                        if trCloudStatus is missing value then
                            set trCloudStatus to ""
                        else
                            set trCloudStatus to trCloudStatus as text
                        end if
                    end try
                    try
                        set trTime to item i of trTimes
                        if trTime is missing value then set trTime to ""
                    end try
                    try
                        set trDur to (item i of trDurations)
                        if trDur is missing value then set trDur to 0
                        set trDur to trDur as integer
                    end try
                    try
                        set trPersistentID to item i of trPersistentIDs
                        if trPersistentID is missing value then set trPersistentID to ""
                    end try

                    set csvLines to csvLines & my csvQuote(trName) & "," & my csvQuote(trArtist) & "," & my csvQuote(trAlbum) & "," & my csvQuote(trAlbumArtist) & "," & my csvQuote(trGenre) & "," & trYear & "," & trTrackNum & "," & trDiscNum & "," & trRating & "," & my csvQuote(trLoved) & "," & trPlayedCount & "," & my csvQuote(trDateAdded) & "," & my csvQuote(trKind) & "," & my csvQuote(trCloudStatus) & "," & my csvQuote(trTime) & "," & trDur & "," & my csvQuote(trPersistentID) & return & linefeed

                    try
                        set trLoc to item i of trLocations
                        if trLoc is not missing value then
                            set trPath to POSIX path of trLoc
                            set m3uArtist to my sanitize_summary_field(trArtist)
                            set m3uName to my sanitize_summary_field(trName)
                            set m3uLines to m3uLines & "#EXTINF:" & trDur & "," & m3uArtist & " - " & m3uName & linefeed
                            set m3uLines to m3uLines & my stripReturns(trPath) & linefeed
                            set localCount to localCount + 1
                        end if
                    end try
                end repeat
                    end timeout
                    set consecTimeouts to 0
                on error errMsg number errNum
                    set trackCount to 0
                    set plTimedOut to true
                    try
                        set sRef to open for access POSIX file summaryPath with write permission
                        write ("TIMEOUT" & tab & plName & tab & my sanitize_summary_field(errMsg) & linefeed) as «class utf8» to sRef starting at eof
                        close access sRef
                    on error
                        try
                            close access sRef
                        end try
                    end try
                    if errNum is -1712 then
                        set consecTimeouts to consecTimeouts + 1
                        if consecTimeouts >= consecTimeoutMax then
                            try
                                set sRef to open for access POSIX file summaryPath with write permission
                                write ("WEDGED" & tab & consecTimeouts & linefeed) as «class utf8» to sRef starting at eof
                                close access sRef
                            on error
                                try
                                    close access sRef
                                end try
                            end try
                            return
                        end if
                    else
                        set consecTimeouts to 0
                    end if
                end try

                set safeName to my _sanitize_name(plName)

                if plTimedOut then
                    set destDir to exportDir
                else
                    set plFolderPath to ""
                    try
                        with timeout of __DOWNPOUR_MUSIC_PER_TIMEOUT__ seconds
                            set plFolderPath to my folderPathFor(pl)
                            if plFolderPath is not "" then
                                do shell script "mkdir -p " & quoted form of (exportDir & "/" & plFolderPath)
                            end if
                        end timeout
                    on error
                        set plFolderPath to ""
                    end try
                    if plFolderPath is "" then
                        set destDir to exportDir
                    else
                        set destDir to exportDir & "/" & plFolderPath
                    end if
                end if

                if trackCount = 0 and not plTimedOut then
                    if reportedTrackCount > 0 then
                        try
                            set sRef to open for access POSIX file summaryPath with write permission
                            write ("ERROR" & tab & my sanitize_summary_field(plName & ": track list unreadable (" & reportedTrackCount & " track(s) reported, 0 read)") & linefeed) as «class utf8» to sRef starting at eof
                            close access sRef
                        on error
                            try
                                close access sRef
                            end try
                        end try
                    else
                        try
                            set sRef to open for access POSIX file summaryPath with write permission
                            write ("SKIPPED-EMPTY" & tab & plName & linefeed) as «class utf8» to sRef starting at eof
                            close access sRef
                        on error
                            try
                                close access sRef
                            end try
                        end try
                    end if
                end if

                set csvPath to my uniquePath(destDir, safeName, ".csv")
                set m3uPath to (text 1 thru -5 of csvPath) & ".m3u"

                if trackCount > 0 then
                    set csvTmpPath to csvPath & ".tmp"
                    set csvWriteOk to false
                    try
                        set fRef to open for access POSIX file csvTmpPath with write permission
                        try
                            set eof fRef to 0
                            write csvLines as «class utf8» to fRef
                            close access fRef
                            do shell script "mv " & quoted form of csvTmpPath & " " & quoted form of csvPath
                            set csvWriteOk to true
                        on error
                            try
                                close access fRef
                            end try
                        end try
                    end try
                    if not csvWriteOk then
                        try
                            do shell script "rm -f " & quoted form of csvTmpPath
                        end try
                    end if
                end if

                if localCount > 0 and csvWriteOk then
                    set m3uTmpPath to m3uPath & ".tmp"
                    set m3uWriteOk to false
                    try
                        set fRef to open for access POSIX file m3uTmpPath with write permission
                        try
                            set eof fRef to 0
                            write m3uLines as «class utf8» to fRef
                            close access fRef
                            do shell script "mv " & quoted form of m3uTmpPath & " " & quoted form of m3uPath
                            set m3uWriteOk to true
                        on error
                            try
                                close access fRef
                            end try
                        end try
                    end try
                    if not m3uWriteOk then
                        try
                            do shell script "rm -f " & quoted form of m3uTmpPath
                        end try
                    end if
                end if

                if not plTimedOut and trackCount > 0 then
                    if trackCount > 0 and not csvWriteOk then
                        set sRef to open for access POSIX file summaryPath with write permission
                        try
                            write ("ERROR" & tab & my sanitize_summary_field(plName & ": CSV write failed (destination folder not writable?)") & linefeed) as «class utf8» to sRef starting at eof
                            close access sRef
                        on error
                            try
                                close access sRef
                            end try
                        end try
                    else if reportedTrackCount > trackCount then
                        set sRef to open for access POSIX file summaryPath with write permission
                        try
                            write ("PARTIAL" & tab & plName & tab & trackCount & tab & reportedTrackCount & linefeed) as «class utf8» to sRef starting at eof
                            close access sRef
                        on error
                            try
                                close access sRef
                            end try
                        end try
                    else if not m3uWriteOk then
                        set sRef to open for access POSIX file summaryPath with write permission
                        try
                            write ("M3UFAIL" & tab & plName & tab & trackCount & tab & localCount & linefeed) as «class utf8» to sRef starting at eof
                            close access sRef
                        on error
                            try
                                close access sRef
                            end try
                        end try
                    else
                        set summaryLine to "OK" & tab & plName & tab & trackCount & tab & localCount
                        set sRef to open for access POSIX file summaryPath with write permission
                        try
                            write (summaryLine & linefeed) as «class utf8» to sRef starting at eof
                            close access sRef
                        on error
                            try
                                close access sRef
                            end try
                        end try
                    end if
                end if
            end if
          on error errStr
              try
                  set sRef to open for access POSIX file summaryPath with write permission
                  try
                      write ("ERROR" & tab & my sanitize_summary_field(errStr) & linefeed) as «class utf8» to sRef starting at eof
                      close access sRef
                  on error
                      try
                          close access sRef
                      end try
                  end try
              end try
          end try
        end repeat
    end tell
end run

on fileExists(posixPath)
    try
        set _a to (POSIX file posixPath) as alias
        return true
    on error
        return false
    end try
end fileExists

on uniquePath(exportDir, baseName, ext)
    set candidate to exportDir & "/" & baseName & ext
    if not my fileExists(candidate) then return candidate
    set counter to 2
    repeat while counter < 100
        set candidate to exportDir & "/" & baseName & "_" & counter & ext
        if not my fileExists(candidate) then return candidate
        set counter to counter + 1
    end repeat
    set _stamp to (do shell script "date +%Y%m%d%H%M%S")
    repeat with _try from 1 to 100
        set _ovf to exportDir & "/" & baseName & "_overflow_" & _stamp & "_" & (random number from 0 to 99999) & ext
        if not my fileExists(_ovf) then return _ovf
    end repeat
    return exportDir & "/" & baseName & "_overflow_" & _stamp & ext
end uniquePath

on csvQuote(val)
    set v to val as text
    repeat with sepChar in {linefeed, return, tab}
        set AppleScript's text item delimiters to (contents of sepChar)
        set theItems to every text item of v
        set AppleScript's text item delimiters to " "
        set v to theItems as string
    end repeat
    if (count of v) > 0 then
        set c1 to character 1 of v
        if c1 is "=" or c1 is "+" or c1 is "-" or c1 is "@" then
            set v to "'" & v
        end if
    end if
    set AppleScript's text item delimiters to "\""
    set parts to every text item of v
    set AppleScript's text item delimiters to "\"\""
    set v to parts as string
    set AppleScript's text item delimiters to ""
    return "\"" & v & "\""
end csvQuote

on _sanitize_name(theName)
    set illegalChars to {":", "/", "\\", "?", "*", "<", ">", "|", "\"", linefeed, return, tab}
    set cleanName to theName
    repeat with c in illegalChars
        set AppleScript's text item delimiters to (contents of c)
        set theItems to every text item of cleanName
        set AppleScript's text item delimiters to "_"
        set cleanName to theItems as string
    end repeat
    set AppleScript's text item delimiters to ""
    repeat while cleanName starts with " " or cleanName starts with "."
        if length of cleanName is 0 then exit repeat
        set cleanName to text 2 thru -1 of cleanName
    end repeat
    repeat while cleanName ends with " " or cleanName ends with "."
        if length of cleanName is 0 then exit repeat
        set cleanName to text 1 thru -2 of cleanName
    end repeat
    set _byte_count to 0
    set _safe_chars to 0
    set _len to length of cleanName
    repeat with _i from 1 to _len
        set cp to id of (character _i of cleanName)
        if cp < 128 then
            set _w to 1
        else if cp < 2048 then
            set _w to 2
        else if cp < 65536 then
            set _w to 3
        else
            set _w to 4
        end if
        if (_byte_count + _w) > 200 then exit repeat
        set _byte_count to _byte_count + _w
        set _safe_chars to _i
    end repeat
    if _safe_chars > 0 and _safe_chars < _len then
        set cleanName to text 1 thru _safe_chars of cleanName
    else if _safe_chars = 0 and _len > 0 then
        set cleanName to ""
    end if
    if cleanName is "" then set cleanName to "Untitled"
    return cleanName
end _sanitize_name

on folderPathFor(pl)
    set chain to {}
    set cur to pl
    set depthCap to 10
    repeat with d from 1 to depthCap
        set par to missing value
        try
            set par to parent of cur
        end try
        if par is missing value then exit repeat
        set parName to "Folder"
        try
            set parName to name of par
        end try
        set parName to my _sanitize_name(my sanitize_summary_field(parName))
        set chain to {parName} & chain
        set cur to par
    end repeat
    if (count of chain) is 0 then return ""
    set AppleScript's text item delimiters to "/"
    set joined to chain as string
    set AppleScript's text item delimiters to ""
    return joined
end folderPathFor

on sanitize_summary_field(theText)
    set cleanText to theText as text
    repeat with sepChar in {tab, linefeed, return}
        set AppleScript's text item delimiters to (contents of sepChar)
        set theItems to every text item of cleanText
        set AppleScript's text item delimiters to " "
        set cleanText to theItems as string
    end repeat
    set AppleScript's text item delimiters to ""
    return cleanText
end sanitize_summary_field

on stripReturns(theText)
    set cleanText to theText as text
    repeat with sepChar in {linefeed, return}
        set AppleScript's text item delimiters to (contents of sepChar)
        set theItems to every text item of cleanText
        set AppleScript's text item delimiters to ""
        set cleanText to theItems as string
    end repeat
    set AppleScript's text item delimiters to ""
    return cleanText
end stripReturns
APPLESCRIPT
    LC_ALL=C sed -i '' \
        -e "s/__DOWNPOUR_MUSIC_PLAYLIST_CAP__/${MUSIC_PLAYLIST_CAP}/g" \
        -e "s/__DOWNPOUR_MUSIC_PER_TIMEOUT__/${MUSIC_PLAYLIST_PER_TIMEOUT_SEC}/g" \
        "$_AS_PATH" \
        || die "Failed to substitute placeholders into the Music AppleScript driver (sed rc=$?). Refusing to run with unsubstituted __DOWNPOUR_*__ tokens — that would leave the playlist cap un-enforced AND make osascript fail opaquely."
}

music_playlists_main() {
    maybe_show_help "$@"
    _announce_step "Music playlists export"
    check_dependencies
    local out_arg out_dir
    out_arg="$(_parse_output_folder_arg "$@")" || exit 1
    out_dir="$(resolve_output_dir "$out_arg")" || exit 1
    _announce_output_dir "Music Playlists"
    log_info "Source: Music.app (via AppleScript)"
    [ -n "${_MUSIC_PLAYLIST_CAP_NOTICE:-}" ] && log_warn "$_MUSIC_PLAYLIST_CAP_NOTICE"
    [ -n "${_MUSIC_PER_TIMEOUT_NOTICE:-}" ] && log_warn "$_MUSIC_PER_TIMEOUT_NOTICE"
    if [ ! -d /System/Applications/Music.app ] \
       && [ ! -d /Applications/Music.app ]; then
        report_no_source "Music.app" "not installed"
    fi
    local out_root="$out_dir/Music Playlists"
    require_no_collision "$out_root"
    _MUSIC_OUT_ROOT="$out_root"
    if ! _music_has_been_launched; then
        log_err "Music.app has never been opened on this Mac."
        log_info "  Open Music.app once, dismiss the welcome / sign-in screens,"
        log_info "  then re-run this script. The connection to Music is blocked"
        log_info "  by Music's first-launch flow until a human dismisses it."
        exit 1
    fi
    log_info "Checking Music Automation permission + waking up Music..."
    _snapshot_app_launch Music _MUSIC_LAUNCHED_BY_US
    _MUSIC_PLAYLIST_COUNT=""
    case "${_MUSIC_AUTOMATION_STATE:-unknown}" in
        granted)
            check_music_automation || {
                log_err "Music Automation: wrapper said granted but probe failed (mid-run revocation?)"
                exit 1
            }
            ;;
        denied|na)
            _tcc_recheck_or_die "Music Automation" check_music_automation \
                "Automation > <terminal> > Music"
            ;;
        *)
            log_info "Probing Music Automation permission (first run will prompt)..."
            if check_music_automation; then
                log_ok "Music Automation: granted"
            else
                log_info "Music Automation not responding. Possible causes:"
                log_info "  • The Automation grant for Music is off — toggle it ON in System Settings > Privacy & Security > Automation > <terminal>."
                log_info "  • Music is open with a welcome / sign-in / iCloud Music dialog blocking automation — bring Music to the front and dismiss any sheets or sign-in prompts."
                log_info "  • Music is still launching — just wait."
                log_info "Polling for up to ${TCC_POLL_TIMEOUT} seconds; the script will proceed when Music starts responding."
                open 'x-apple.systempreferences:com.apple.preference.security?Privacy_Automation' \
                    >/dev/null 2>&1 || true
                if wait_for_grant check_music_automation "Music" "$TCC_POLL_TIMEOUT"; then
                    log_ok "Music Automation: granted"
                else
                    log_err "Music Automation permission was not granted within ${TCC_POLL_TIMEOUT} s."
                    log_info "This export drives Music.app via AppleScript — Music has no on-disk database we can read directly, so AppleScript IS the source. Without Automation, every attempt fails and the export produces zero playlists."
                    log_info "How to grant:"
                    log_info "  • System Settings > Privacy & Security > Automation"
                    log_info "  • Find your terminal (Terminal, iTerm, Ghostty, etc.) in the list. If it isn't there, run any AppleScript that talks to Music so macOS adds the entry."
                    log_info "  • Toggle Music ON under your terminal."
                    log_info "  • Re-run this script."
                    log_info "If you're running over SSH, switch to a local Aqua session — AppleScript needs a window-server session to reach Music.app."
                    ensure_scratch
                    note_incomplete "$out_root" "Music Playlists" \
                        "Music Automation was not granted — this export drives Music.app via AppleScript (Music has no readable on-disk database), so without it no playlists can be read; grant it in System Settings > Privacy & Security > Automation, then re-run"
                    mark_success
                    print_summary
                    exit 0
                fi
            fi
            ;;
    esac
    case "${_MUSIC_PLAYLIST_COUNT:-}" in
        ''|*[!0-9]*)
            log_warn "Music playlist count not available (probe didn't populate _MUSIC_PLAYLIST_COUNT); skipping cap check."
            ;;
        *)
            log_info "Music.app exposes $_MUSIC_PLAYLIST_COUNT $(_pluralize "$_MUSIC_PLAYLIST_COUNT" item) total (Apple built-ins, folders, and smart playlists are filtered out below)"
            if [ "$_MUSIC_PLAYLIST_COUNT" -gt "$MUSIC_PLAYLIST_CAP" ]; then
                log_err "Music.app reports $_MUSIC_PLAYLIST_COUNT playlists — too many to process (cap=$MUSIC_PLAYLIST_CAP)"
                log_info "  This usually means iCloud Music Library is exposing subscription /"
                log_info "  editorial content as 'playlists'. The hard cap protects against"
                log_info "  runaway exports. Raise via MUSIC_PLAYLIST_CAP=N if your library"
                log_info "  legitimately exceeds the default."
                exit 1
            fi
            ;;
    esac
    ensure_scratch
    _create_output_dir "$out_root"
    local summary_file="$SCRATCH_DIR/playlist_summary.txt"
    : > "$summary_file" || die "Cannot create scratch summary file"
    _write_applescript
    local as_out="$SCRATCH_DIR/music_as.out"
    local as_err="$SCRATCH_DIR/music_as.err"
    local MUSIC_OUTER_CEILING_S="${MUSIC_OUTER_CEILING_SEC:-300}"
    local _MUSIC_OUTER_CEILING_RAW="${MUSIC_OUTER_CEILING_SEC-}"
    _clamp_env_int MUSIC_OUTER_CEILING_S 300 86400 >/dev/null
    if [ -n "$_MUSIC_OUTER_CEILING_RAW" ] && \
       [ "$_MUSIC_OUTER_CEILING_RAW" != "$MUSIC_OUTER_CEILING_S" ] && \
       case "$_MUSIC_OUTER_CEILING_RAW" in *[!0-9]*) false;; *) true;; esac; then
        log_warn "MUSIC_OUTER_CEILING_SEC clamped from $_MUSIC_OUTER_CEILING_RAW to $MUSIC_OUTER_CEILING_S (allowed range 1..86400)."
    fi
    local _music_ceiling_label
    if [ "$MUSIC_OUTER_CEILING_S" -lt 300 ]; then
        _music_ceiling_label="${MUSIC_OUTER_CEILING_S}s"
    else
        _music_ceiling_label="$((MUSIC_OUTER_CEILING_S / 60)) min"
    fi
    _as_debug "running playlist export driver (${_music_ceiling_label} wallclock cap; $as_err captures stderr)"
    log_info "Running the Music playlist export (${_music_ceiling_label} time cap)..."
    osascript "$_AS_PATH" "$out_root" "$summary_file" \
        >"$as_out" 2>"$as_err" &
    local pid=$!
    CHILD_PIDS+=( "$pid" )
    _heartbeat_start 60 "... AppleScript driver still running"
    local elapsed=0 _ceiling_hit=0
    while kill -0 "$pid" 2>/dev/null; do
        sleep 1
        elapsed=$((elapsed + 1))
        if [ "$elapsed" -ge "$MUSIC_OUTER_CEILING_S" ]; then
            _ceiling_hit=1
            _heartbeat_stop
            _kill_tree "$pid"
            break
        fi
    done
    wait "$pid" 2>/dev/null
    local rc=$?
    _heartbeat_stop
    local _i _new=()
    for _i in "${CHILD_PIDS[@]+"${CHILD_PIDS[@]}"}"; do
        [ "$_i" = "$pid" ] && continue
        _new+=( "$_i" )
    done
    CHILD_PIDS=( "${_new[@]+"${_new[@]}"}" )
    if [ "$rc" -ne 0 ]; then
        if [ "$_ceiling_hit" -eq 1 ]; then
            log_err "Music automation stopped after the ${_music_ceiling_label} time limit — Music.app stopped responding."
            note_incomplete "$out_root" "Music playlists — time limit" \
                "the Music playlist export was stopped after the ${_music_ceiling_label} wallclock limit; any playlists not yet written when the limit fired are not in the export — raise MUSIC_OUTER_CEILING_SEC (or reduce the library) and re-run"
        else
            local _err_excerpt=""
            [ -s "$as_err" ] && _err_excerpt="$(LC_ALL=C tr '\n' ' ' < "$as_err" | head -c 500)"
            log_err "AppleScript export failed (rc=$rc)${_err_excerpt:+: $_err_excerpt}"
        fi
    fi
    local _swept=0
    if [ -d "$out_root" ]; then
        local _path
        while IFS= read -r -d '' _path; do
            rm -f -- "$_path" 2>/dev/null && _swept=$((_swept + 1))
        done < <(find "$out_root" -type f \
            \( -name '*.csv.tmp' -o -name '*.m3u.tmp' \
               -o \( \( -name '*.csv' -o -name '*.m3u' \) -empty \) \) \
            -print0 2>/dev/null)
    fi
    if [ "$_swept" -gt 0 ]; then
        log_warn "Swept $_swept zero-byte or .tmp $(_pluralize "$_swept" file) from $out_root (AppleScript exited mid-write)"
        note_incomplete "$out_root" "$_swept Music playlist $(_pluralize "$_swept" file)" \
            "these playlist file(s) were not written completely (Music.app stopped responding partway through writing them) and were removed — those playlists are not in the export. Re-run when Music.app is responsive"
    fi
    log_info "Parsing per-playlist summary + filter disclosure..."
    local n_timeout=0 n_error=0 n_abort=0 n_wedged=0 n_builtin_skipped=0
    local n_smart_skipped=0 n_folder_skipped=0 n_empty_skipped=0
    local n_unknown=0 n_ok=0
    local total_tracks=0 total_local=0
    local f1 f2 f3 f4
    if [ -f "$summary_file" ]; then
        while IFS=$'\t' read -r f1 f2 f3 f4; do
            case "$f1" in
                OK)
                    case "$f3" in ''|*[!0-9]*) f3=0 ;; esac
                    case "$f4" in ''|*[!0-9]*) f4=0 ;; esac
                    total_tracks=$((total_tracks + f3))
                    total_local=$((total_local + f4))
                    n_ok=$((n_ok + 1))
                    ;;
                PARTIAL)
                    case "$f3" in ''|*[!0-9]*) f3=0 ;; esac
                    case "$f4" in ''|*[!0-9]*) f4=0 ;; esac
                    total_tracks=$((total_tracks + f3))
                    n_ok=$((n_ok + 1))
                    log_warn "Music playlist \"$f2\" exported $f3 of $f4 tracks Music reported (short read) — the CSV is partial"
                    note_incomplete "$out_root" "Music playlist \"$f2\" — partial track list ($f3 of $f4 tracks)" \
                        "the batched track-name fetch returned $f3 of the $f4 tracks Music reported for this playlist; the exported CSV is partial. Re-run when Music.app is responsive"
                    ;;
                M3UFAIL)
                    case "$f3" in ''|*[!0-9]*) f3=0 ;; esac
                    case "$f4" in ''|*[!0-9]*) f4=0 ;; esac
                    total_tracks=$((total_tracks + f3))
                    n_ok=$((n_ok + 1))
                    log_warn "Music playlist \"$f2\" — the .m3u playlist file could not be written (the CSV exported fine); re-run to regenerate the .m3u file"
                    note_incomplete "$out_root" "Music playlist \"$f2\" — .m3u file missing" \
                        "the per-playlist CSV exported in full but the paired .m3u playlist file could not be written (disk-full / read-only output volume); the .csv is complete — re-run to regenerate the .m3u"
                    ;;
                TIMEOUT) n_timeout=$((n_timeout + 1)) ;;
                ERROR)   n_error=$((n_error + 1)) ;;
                SKIPPED-BUILTIN) n_builtin_skipped=$((n_builtin_skipped + 1)) ;;
                SKIPPED-SMART)   n_smart_skipped=$((n_smart_skipped + 1)) ;;
                SKIPPED-FOLDER)  n_folder_skipped=$((n_folder_skipped + 1)) ;;
                SKIPPED-EMPTY)   n_empty_skipped=$((n_empty_skipped + 1)) ;;
                ABORT)
                    n_abort=$((n_abort + 1))
                    log_err "AppleScript aborted: $f2"
                    ;;
                WEDGED)
                    n_wedged=$((n_wedged + 1))
                    log_warn "The connection to Music stopped responding after $f2 consecutive playlist timeouts; remaining playlists skipped (partial export retained)"
                    note_incomplete "$out_root" "Music playlists not exported (Music stopped responding)" \
                        "the connection to Music.app stopped responding mid-run; every playlist after that point was skipped — the Music Playlists export is partial. Re-run when Music.app is responsive"
                    ;;
                *)  # Unrecognised marker — record it so the
                    n_unknown=$((n_unknown + 1))
                    ;;
            esac
        done < "$summary_file"
    fi
    [ "$n_builtin_skipped" -gt 0 ] && _disclose_excluded "$n_builtin_skipped Apple built-in $(_pluralize "$n_builtin_skipped" playlist)" "e.g. Library, Downloaded, Recently Added"
    [ "$n_smart_skipped" -gt 0 ]  && _disclose_excluded "$n_smart_skipped smart $(_pluralize "$n_smart_skipped" playlist)" "lazy-evaluated, often iCloud-bound — excluded to avoid 60s-per-item timeouts"
    [ "$n_folder_skipped" -gt 0 ] && _disclose_excluded "$n_folder_skipped folder-container $(_pluralize "$n_folder_skipped" playlist)" "not exportable as playlists — the playlists they contain are exported individually"
    [ "$n_empty_skipped" -gt 0 ]  && _disclose_excluded "$n_empty_skipped empty $(_pluralize "$n_empty_skipped" playlist)" "zero tracks — no file written"
    local _n_accounted=$((n_ok + n_timeout + n_error + n_abort \
        + n_wedged + n_builtin_skipped + n_smart_skipped \
        + n_folder_skipped + n_empty_skipped + n_unknown))
    local _n_unreported=0
    case "${_MUSIC_PLAYLIST_COUNT:-}" in
        ''|*[!0-9]*) : ;;
        *) [ "$_MUSIC_PLAYLIST_COUNT" -gt "$_n_accounted" ] \
               && _n_unreported=$((_MUSIC_PLAYLIST_COUNT - _n_accounted)) ;;
    esac
    if [ "$_n_unreported" -gt 0 ] && [ "$n_wedged" -eq 0 ]; then
        log_info "Unaccounted: $_n_unreported $(_pluralize "$_n_unreported" item) Music.app counts but the driver couldn't read by index — usually Apple system / subscription / cloud collections, not lost playlists. Re-run with DEBUG_APPLESCRIPT=1 to see them."
    fi
    [ "$n_unknown" -gt 0 ] && log_info "Unrecognised summary $(_pluralize "$n_unknown" marker): $n_unknown (parser fell through to default case — see export_music_playlists)."
    if [ "$n_abort" -gt 0 ]; then
        note_incomplete "$out_root" "All playlists" \
            "Music.app reported more playlists than the safety cap (MUSIC_PLAYLIST_CAP) allows, so the export stopped before writing any — this usually means a very large library that includes Apple-curated / subscription playlists you didn't create. Raise MUSIC_PLAYLIST_CAP and re-run."
        cleanup_empty_dirs "$out_root"
        rmdir "$out_root" 2>/dev/null || true
        print_summary
        exit 1
    fi
    log_info "Validating CSV/M3U output + counting deliverables..."
    local csv_count=0 m3u_count=0 _mp_path _mp_ext
    while IFS= read -r -d '' _mp_path; do
        _mp_ext="${_mp_path##*.}"
        case "$_mp_ext" in
            csv) csv_count=$((csv_count + 1))
                 validate_csv_rfc4180 "$_mp_path" || true
                 ;;
            m3u) m3u_count=$((m3u_count + 1)) ;;
        esac
    done < <(find "$out_root" -type f \
                  \( -name '*.csv' -o -name '*.m3u' \) -print0 2>/dev/null)
    if [ "$csv_count" -eq 0 ] && [ "$m3u_count" -eq 0 ]; then
        if [ "$n_timeout" -gt 0 ]; then
            note_incomplete "$out_root" "$n_timeout Music $(_pluralize "$n_timeout" playlist)" \
                "reading the tracks for these playlists timed out (a slow iCloud Music library) — they are not in the export; raise MUSIC_PLAYLIST_PER_TIMEOUT_SEC and re-run"
        fi
        if [ "$n_error" -gt 0 ]; then
            note_incomplete "$out_root" "$n_error Music $(_pluralize "$n_error" playlist)" \
                "Music.app returned an error while listing these playlists — they are not in the export"
        fi
        cleanup_empty_dirs "$out_root"
        rmdir "$out_root" 2>/dev/null || true
        if [ "$n_timeout" -gt 0 ] || [ "$n_error" -gt 0 ]; then
            log_warn "No playlists exported (timeouts: $n_timeout, errors: $n_error)"
        elif [ "$_ceiling_hit" -eq 1 ]; then
            log_warn "No playlists exported — the ${_music_ceiling_label} time limit fired before any playlist was written."
        else
            log_warn "No playlists to export — nothing to do."
        fi
        _flag_no_content
        mark_success
        print_summary
        if [ "$ERR_COUNT" -gt 0 ]; then exit 1; fi
        exit 0
    fi
    if [ "$n_timeout" -gt 0 ]; then
        log_warn "$n_timeout $(_pluralize "$n_timeout" playlist) timed out and were skipped"
        note_incomplete "$out_root" "$n_timeout Music $(_pluralize "$n_timeout" playlist)" \
            "track enumeration timed out for these playlists (slow iCloud-Music bridge) — they are not in the export; raise MUSIC_PLAYLIST_PER_TIMEOUT_SEC and re-run"
    fi
    if [ "$n_error" -gt 0 ]; then
        log_warn "$n_error $(_pluralize "$n_error" playlist) failed and were skipped"
        note_incomplete "$out_root" "$n_error Music $(_pluralize "$n_error" playlist)" \
            "Music.app returned an error while listing these playlists — they are not in the export"
    fi
    if [ "$n_wedged" -gt 0 ]; then
        log_info "Skipping the playlist-count check — Music stopped responding; the counts above are partial (the note above records what's incomplete)"
    else
    case "${_MUSIC_PLAYLIST_COUNT:-}" in
        ''|*[!0-9]*) : ;;
        *)
            local _unreported_adj=0
            [ "$_ceiling_hit" -eq 0 ] && _unreported_adj="$_n_unreported"
            local _expected_pl=$((_MUSIC_PLAYLIST_COUNT - n_builtin_skipped \
                - n_smart_skipped - n_folder_skipped - n_empty_skipped \
                - n_timeout - n_error - _unreported_adj))
            [ "$_expected_pl" -lt 0 ] && _expected_pl=0
            if [ "$csv_count" -lt "$_expected_pl" ]; then
                local _missing_pl=$((_expected_pl - csv_count))
                log_warn "Music: expected ~$_expected_pl user $(_pluralize "$_expected_pl" playlist) but only $csv_count CSV $(_pluralize "$csv_count" file) landed — $_missing_pl unaccounted for."
                note_incomplete "$out_root" "$_missing_pl Music $(_pluralize "$_missing_pl" playlist) unaccounted for" \
                    "Music.app reported $_MUSIC_PLAYLIST_COUNT playlist(s); after subtracting $n_builtin_skipped built-in / $n_smart_skipped smart / $n_folder_skipped folder / $n_empty_skipped empty / $n_timeout timed-out / $n_error errored / $_unreported_adj bypassed-system skips, ~$_expected_pl user playlist(s) were expected but only $csv_count CSV file(s) were written — some playlists failed before producing a summary line and are not in the export"
            fi
            ;;
    esac
    fi
    local _stat="$csv_count $(_pluralize "$csv_count" playlist), $total_tracks $(_pluralize "$total_tracks" track), $total_local local"
    _stat="$_stat, $(_dir_size_human "$out_root")"
    if [ "$_ceiling_hit" -eq 1 ]; then
        log_warn "Wrote Music Playlists/ (PARTIAL — stopped at the ${_music_ceiling_label} time limit; $_stat)"
    else
        log_ok "Wrote Music Playlists/ ($_stat)"
    fi
    mark_success
    sweep_junk_files "$out_root"
    cleanup_empty_dirs "$out_root"
    quit_app_iff_we_launched_it Music _MUSIC_LAUNCHED_BY_US
    print_summary
    if [ "$ERR_COUNT" -gt 0 ]; then exit 1; fi
    exit 0
}

NOTES_DB="$HOME/Library/Group Containers/group.com.apple.notes/NoteStore.sqlite"
NOTES_COL_TITLE=""      # the note's title column (typically ZTITLE1)
NOTES_COL_FOLDER=""     # the folder's title column (typically ZTITLE2)
NOTES_LOCKED_EXPR=""    # SQL expression that yields 1 for locked notes
NOTES_ALL_COLS=""       # newline-separated ZICCLOUDSYNCINGOBJECT columns,
NOTES_COL_FOLDERFK=""   # the note->folder foreign-key column. Canonical
NOTES_COL_TYPEUTI=""    # the attachment type-UTI column. Canonical
NOTES_COL_PARENTATT=""  # the attachment->parent-attachment FK column
NOTES_GEN_SELECT=""     # SQL select-expr for the attachment generation
NOTES_COL_MERGEABLE=""  # the table CRDT-blob column. Canonical
NOTES_ATT_ALTTEXT="att.ZALTTEXT"
NOTES_ATT_URLSTRING="att.ZURLSTRING"
NOTES_ATT_TITLE="att.ZTITLE"

_resolve_notes_columns() {
    local snap="$1" all_cols
    local _nrc
    all_cols="$(sqlite3 -readonly "$snap" \
        "SELECT name FROM pragma_table_info('ZICCLOUDSYNCINGOBJECT');" 2>/dev/null)"
    _nrc=$?
    [ "$_nrc" -ne 0 ] && _probe_miss error ZICCLOUDSYNCINGOBJECT '*'
    NOTES_ALL_COLS="$all_cols"
    _col_in_list "$all_cols" 'ZALTTEXT'   && NOTES_ATT_ALTTEXT="att.ZALTTEXT"     || NOTES_ATT_ALTTEXT="''"
    _col_in_list "$all_cols" 'ZURLSTRING' && NOTES_ATT_URLSTRING="att.ZURLSTRING" || NOTES_ATT_URLSTRING="''"
    _col_in_list "$all_cols" 'ZTITLE'     && NOTES_ATT_TITLE="att.ZTITLE"         || NOTES_ATT_TITLE="''"
    NOTES_COL_TITLE="$(printf '%s\n' "$all_cols" \
        | grep '^ZTITLE[0-9][0-9]*$' | sort -t E -k2 -n | head -1)"
    case "$NOTES_COL_TITLE" in *[!A-Za-z0-9_]*) NOTES_COL_TITLE="" ;; esac
    [ -z "$NOTES_COL_TITLE" ] && NOTES_COL_TITLE="ZTITLE1"
    NOTES_COL_FOLDER="$(printf '%s\n' "$all_cols" \
        | grep '^ZTITLE[0-9][0-9]*$' | sort -t E -k2 -n | tail -1)"
    case "$NOTES_COL_FOLDER" in *[!A-Za-z0-9_]*) NOTES_COL_FOLDER="" ;; esac
    if [ -z "$NOTES_COL_FOLDER" ] || [ "$NOTES_COL_FOLDER" = "$NOTES_COL_TITLE" ]; then
        if _col_in_list "$all_cols" 'ZTITLE2'; then
            NOTES_COL_FOLDER="ZTITLE2"
        else
            NOTES_COL_FOLDER=""
        fi
    fi
    if _col_in_list "$all_cols" 'ZISPASSWORDPROTECTED'; then
        NOTES_LOCKED_EXPR="COALESCE(ZISPASSWORDPROTECTED, 0)"
    elif _col_in_list "$all_cols" 'ZPASSWORDPROTECTED'; then
        NOTES_LOCKED_EXPR="COALESCE(ZPASSWORDPROTECTED, 0)"
        log_info "Schema: locked-note = ZPASSWORDPROTECTED (legacy)"
    elif _col_in_list "$all_cols" 'ZCRYPTOITERATIONCOUNT'; then
        NOTES_LOCKED_EXPR="CASE WHEN COALESCE(ZCRYPTOITERATIONCOUNT, 0) > 0 THEN 1 ELSE 0 END"
        log_info "Schema: locked-note = ZCRYPTOITERATIONCOUNT > 0 (legacy)"
    elif _col_in_list "$all_cols" 'ZCRYPTOWRAPPEDKEY'; then
        NOTES_LOCKED_EXPR="CASE WHEN ZCRYPTOWRAPPEDKEY IS NOT NULL THEN 1 ELSE 0 END"
        log_info "Schema: locked-note = ZCRYPTOWRAPPEDKEY IS NOT NULL (legacy)"
    else
        NOTES_LOCKED_EXPR="0"
        log_info "Schema: no locked-note column found (probed: ZISPASSWORDPROTECTED / ZPASSWORDPROTECTED / ZCRYPTOITERATIONCOUNT / ZCRYPTOWRAPPEDKEY) — every note will be treated as unlocked."
    fi
    NOTES_COL_FOLDERFK=""
    if _col_in_list "$all_cols" 'ZFOLDER'; then
        NOTES_COL_FOLDERFK="ZFOLDER"
    elif _col_in_list "$all_cols" 'ZFOLDER2'; then
        NOTES_COL_FOLDERFK="ZFOLDER2"
        log_info "Schema: note folder FK = ZFOLDER2 (legacy)"
    fi
    case "$NOTES_COL_FOLDERFK" in *[!A-Za-z0-9_]*) NOTES_COL_FOLDERFK="" ;; esac
    if [ -z "$NOTES_COL_FOLDERFK" ]; then
        log_warn "Note folder FK column not found (ZFOLDER / ZFOLDER2) — folder hierarchy unavailable, notes will export flat."
        [ "${_nrc:-0}" -eq 0 ] && _probe_miss absent ZICCLOUDSYNCINGOBJECT ZFOLDER
    fi
    NOTES_COL_TYPEUTI=""
    if _col_in_list "$all_cols" 'ZTYPEUTI'; then
        NOTES_COL_TYPEUTI="ZTYPEUTI"
    elif _col_in_list "$all_cols" 'ZTYPEUTI1'; then
        NOTES_COL_TYPEUTI="ZTYPEUTI1"
        log_info "Schema: attachment UTI = ZTYPEUTI1 (legacy)"
    fi
    case "$NOTES_COL_TYPEUTI" in *[!A-Za-z0-9_]*) NOTES_COL_TYPEUTI="" ;; esac
    [ -z "$NOTES_COL_TYPEUTI" ] && NOTES_COL_TYPEUTI="ZTYPEUTI"
    NOTES_COL_PARENTATT=""
    if _col_in_list "$all_cols" 'ZPARENTATTACHMENT'; then
        NOTES_COL_PARENTATT="ZPARENTATTACHMENT"
    fi
    case "$NOTES_COL_PARENTATT" in *[!A-Za-z0-9_]*) NOTES_COL_PARENTATT="" ;; esac
    local _gc _gcols=""
    for _gc in ZGENERATION ZGENERATION1 ZFALLBACKIMAGEGENERATION \
               ZFALLBACKPDFGENERATION ZPAPERBUNDLEGENERATION; do
        if _col_in_list "$all_cols" "$_gc"; then
            _gcols="${_gcols:+$_gcols, }media.$_gc"
        fi
    done
    if [ -n "$_gcols" ]; then
        NOTES_GEN_SELECT="COALESCE($_gcols, '')"
    else
        NOTES_GEN_SELECT="''"
    fi
    NOTES_COL_MERGEABLE=""
    if _col_in_list "$all_cols" 'ZMERGEABLEDATA1'; then
        NOTES_COL_MERGEABLE="ZMERGEABLEDATA1"
    elif _col_in_list "$all_cols" 'ZMERGEABLEDATA'; then
        NOTES_COL_MERGEABLE="ZMERGEABLEDATA"
    fi
    case "$NOTES_COL_MERGEABLE" in *[!A-Za-z0-9_]*) NOTES_COL_MERGEABLE="" ;; esac
}

_NOTE_ATTACH_TAG_AWK='
        function _atesc(s,    r) {
            r = s
            gsub(/&/, "\\&amp;", r); gsub(/</, "\\&lt;", r); gsub(/>/, "\\&gt;", r)
            gsub(/"/, "\\&quot;", r); gsub(/'\''/, "\\&#39;", r)
            return r
        }
        function _aturl(s,    out, i, c) {
            if (!("A" in _atord)) for (i = 0; i < 256; i++) _atord[sprintf("%c", i)] = i
            out = ""
            for (i = 1; i <= length(s); i++) {
                c = substr(s, i, 1)
                if (c ~ /[A-Za-z0-9._~\/-]/) out = out c
                else out = out sprintf("%%%02X", _atord[c])
            }
            return out
        }
        function _atag(name, att_rel,    ext, rel, en, er, jpg, jrel, ej) {
            ext = name; sub(/.*\./, "", ext); ext = tolower(ext)
            rel = att_rel "/" name; en = _atesc(name); er = _atesc(_aturl(rel))
            if (ext == "heic" || ext == "heif") {
                jpg = name; sub(/\.[^.]+$/, ".jpg", jpg)
                jrel = att_rel "/" jpg; ej = _atesc(_aturl(jrel))
                return "<a href=\"" er "\"><img src=\"" ej "\" alt=\"" en "\"></a>"
            }
            if (ext ~ /^(jpg|jpeg|png|gif|webp|tiff|tif|bmp)$/) \
                return "<img src=\"" er "\" alt=\"" en "\">"
            if (ext ~ /^(mov|mp4|m4v|webm)$/) \
                return "<video controls src=\"" er "\">" en "</video>"
            if (ext ~ /^(m4a|mp3|wav|aac)$/) \
                return "<audio controls src=\"" er "\">" en "</audio>"
            return "<a href=\"" er "\">" en "</a>"
        }'

_emit_attachments_section() {
    local note_pk="$1" snap="$2" att_rel="$3" rendered="${4:-}"
    [ -n "$note_pk" ] && [ -n "$snap" ] && [ -n "$att_rel" ] || return 0
    local _att_list _gallery_kids
    _att_list="$(_get_attachment_filenames "$note_pk" "$snap")"
    _gallery_kids="$(_get_gallery_child_filenames "$note_pk" "$snap")"
    if [ -n "$_gallery_kids" ]; then
        if [ -n "$_att_list" ]; then
            _att_list="$_att_list
$_gallery_kids"
        else
            _att_list="$_gallery_kids"
        fi
    fi
    [ -n "$_att_list" ] || return 0
    local _filtered _fn _enc
    _filtered="$(
        while IFS= read -r _fn; do
            [ -n "$_fn" ] || continue
            if [ -n "$rendered" ]; then
                _enc="$(_url_encode_path "$att_rel/$_fn")"
                case "$rendered" in (*"$_enc"*) continue ;; esac
            fi
            printf '%s\n' "$_fn"
        done <<< "$_att_list"
    )"
    [ -n "$_filtered" ] || return 0
    printf '<h2>Attachments</h2>\n<div class="attachments">\n'
    LC_ALL=C awk -v att_rel="$att_rel" '
        '"$_NOTE_ATTACH_TAG_AWK"'
        $0 != "" { printf "<p>%s</p>\n", _atag($0, att_rel) }
    ' <<< "$_filtered"
    printf '</div>\n'
}

_get_attachment_filenames() {
    local note_pk="$1" snap="$2"
    case "$note_pk" in ''|*[!0-9]*) return 1 ;; esac
    local _parent_col="${NOTES_COL_PARENTATT:-}" _parent_filter=""
    case "$_parent_col" in ''|*[!A-Za-z0-9_]*) _parent_col="" ;; esac
    [ -n "$_parent_col" ] && _parent_filter="AND att.$_parent_col IS NULL"
    sqlite3 -readonly "$snap" "
        SELECT REPLACE(REPLACE(REPLACE(COALESCE(media.ZFILENAME, ''), x'0A', ' '), x'0D', ' '), x'09', ' ')
          FROM ZICCLOUDSYNCINGOBJECT att
          LEFT JOIN ZICCLOUDSYNCINGOBJECT media ON media.Z_PK = att.ZMEDIA
         WHERE att.ZNOTE = $note_pk
           AND COALESCE(att.ZMARKEDFORDELETION, 0) = 0
           AND COALESCE(media.ZMARKEDFORDELETION, 0) = 0
           $_parent_filter
           ${attachment_ent:+AND att.Z_ENT = $attachment_ent}
         ORDER BY att.Z_PK ASC;" 2>/dev/null
}

_get_gallery_child_filenames() {
    local note_pk="$1" snap="$2"
    case "$note_pk" in ''|*[!0-9]*) return 1 ;; esac
    local _uti_col="${NOTES_COL_TYPEUTI:-}" _parent_col="${NOTES_COL_PARENTATT:-}"
    case "$_uti_col" in ''|*[!A-Za-z0-9_]*) return 0 ;; esac
    case "$_parent_col" in ''|*[!A-Za-z0-9_]*) return 0 ;; esac
    sqlite3 -readonly "$snap" "
        SELECT REPLACE(REPLACE(REPLACE(COALESCE(cm.ZFILENAME, ''), x'0A', ' '), x'0D', ' '), x'09', ' ')
          FROM ZICCLOUDSYNCINGOBJECT parent
          JOIN ZICCLOUDSYNCINGOBJECT child ON child.$_parent_col = parent.Z_PK
          JOIN ZICCLOUDSYNCINGOBJECT cm ON cm.Z_PK = child.ZMEDIA
         WHERE parent.ZNOTE = $note_pk
           AND parent.$_uti_col = 'com.apple.notes.gallery'
           AND cm.ZFILENAME IS NOT NULL
           -- Mirror the copy loop (_get_attachments_with_ids) exactly: it
           -- copies a child only when BOTH ZFILENAME and ZIDENTIFIER are
           -- non-NULL. Without the ZIDENTIFIER guard the fan-out could list
           -- a child filename that was never copied, leaving a broken <img>
           -- reference in the rendered gallery.
           AND cm.ZIDENTIFIER IS NOT NULL
           AND COALESCE(parent.ZMARKEDFORDELETION, 0) = 0
           AND COALESCE(child.ZMARKEDFORDELETION, 0) = 0
           AND COALESCE(cm.ZMARKEDFORDELETION, 0) = 0
           ${attachment_ent:+AND parent.Z_ENT = $attachment_ent}
         ORDER BY parent.Z_PK ASC, child.Z_PK ASC;" 2>/dev/null
}

_get_attachment_metadata() {
    local note_pk="$1" snap="$2"
    case "$note_pk" in ''|*[!0-9]*) return 1 ;; esac
    local _uti_col="${NOTES_COL_TYPEUTI:-ZTYPEUTI}"
    case "$_uti_col" in *[!A-Za-z0-9_]*) _uti_col="ZTYPEUTI" ;; esac
    sqlite3 -readonly -separator $'\x1f' "$snap" "
        SELECT REPLACE(REPLACE(REPLACE(REPLACE(COALESCE(att.ZIDENTIFIER, ''), x'09', ' '), x'0A', ' '), x'0D', ''), x'1F', ''),
               REPLACE(REPLACE(REPLACE(REPLACE(COALESCE(media.ZFILENAME, ''), x'09', ' '), x'0A', ' '), x'0D', ''), x'1F', ''),
               REPLACE(REPLACE(REPLACE(REPLACE(COALESCE(att.$_uti_col, ''), x'09', ' '), x'0A', ' '), x'0D', ''), x'1F', ''),
               COALESCE(REPLACE(REPLACE(REPLACE(REPLACE(COALESCE($NOTES_ATT_ALTTEXT, ''), x'09', ' '), x'0A', ' '), x'0D', ''), x'1F', ''), ''),
               REPLACE(REPLACE(REPLACE(REPLACE(COALESCE($NOTES_ATT_URLSTRING, ''), x'09', ' '), x'0A', ' '), x'0D', ''), x'1F', ''),
               COALESCE(REPLACE(REPLACE(REPLACE(REPLACE(COALESCE($NOTES_ATT_TITLE, ''), x'09', ' '), x'0A', ' '), x'0D', ''), x'1F', ''), ''),
               REPLACE(REPLACE(REPLACE(COALESCE((
                   SELECT GROUP_CONCAT(REPLACE(cm.ZFILENAME, x'7C', ' '), '|')
                     FROM (
                         SELECT cc.ZMEDIA AS _cm_pk, cc.Z_PK AS _ord_pk
                           FROM ZICCLOUDSYNCINGOBJECT cc
                          WHERE cc.ZPARENTATTACHMENT = att.Z_PK
                            AND COALESCE(cc.ZMARKEDFORDELETION, 0) = 0
                          ORDER BY cc.Z_PK ASC
                     ) c
                     JOIN ZICCLOUDSYNCINGOBJECT cm ON cm.Z_PK = c._cm_pk
                    WHERE cm.ZFILENAME IS NOT NULL
                      AND COALESCE(cm.ZMARKEDFORDELETION, 0) = 0
               ), ''), x'0A', ' '), x'0D', ''), x'1F', '')
          FROM ZICCLOUDSYNCINGOBJECT att
          LEFT JOIN ZICCLOUDSYNCINGOBJECT media ON media.Z_PK = att.ZMEDIA
         WHERE att.ZNOTE = $note_pk
           AND att.ZIDENTIFIER IS NOT NULL
           AND att.ZIDENTIFIER != ''
           AND COALESCE(att.ZMARKEDFORDELETION, 0) = 0
           ${attachment_ent:+AND att.Z_ENT = $attachment_ent}
         ORDER BY att.Z_PK ASC;" 2>/dev/null
}

_get_attachments_with_ids() {
    local note_pk="$1" snap="$2"
    case "$note_pk" in ''|*[!0-9]*) return 1 ;; esac
    local _gen_select="''"
    [ -n "${NOTES_GEN_SELECT:-}" ] && _gen_select="$NOTES_GEN_SELECT"
    sqlite3 -readonly -separator $'\x1f' "$snap" "
        -- Strip LF/CR/TAB from ZFILENAME at the SQL layer (same guard the
        -- sibling _get_attachment_filenames query applies): an embedded LF
        -- would otherwise split this row, desync the separator-delimited
        -- columns the copy loop read -r's, and cascade-corrupt the parsing
        -- of the rest of the note's attachments.
        SELECT REPLACE(REPLACE(REPLACE(COALESCE(media.ZFILENAME, ''), x'0A', ' '), x'0D', ' '), x'09', ' '),
               COALESCE(media.ZIDENTIFIER, ''),
               $_gen_select
          FROM ZICCLOUDSYNCINGOBJECT att
          JOIN ZICCLOUDSYNCINGOBJECT media ON media.Z_PK = att.ZMEDIA
         WHERE att.ZNOTE = $note_pk
           AND media.ZFILENAME IS NOT NULL
           AND media.ZIDENTIFIER IS NOT NULL
           AND COALESCE(att.ZMARKEDFORDELETION, 0) = 0
           AND COALESCE(media.ZMARKEDFORDELETION, 0) = 0
           ${attachment_ent:+AND att.Z_ENT = $attachment_ent}
         ORDER BY att.Z_PK ASC;" 2>/dev/null
}

NOTES_MEDIA_BASE="$HOME/Library/Group Containers/group.com.apple.notes/Accounts"
_NOTES_MEDIA_INDEX=""

_build_notes_media_index() {
    [ -d "$NOTES_MEDIA_BASE" ] || return 1
    ensure_scratch
    _NOTES_MEDIA_INDEX="$SCRATCH_DIR/notes_media_index.tsv"
    [ -s "$_NOTES_MEDIA_INDEX" ] && return 0
    : > "$_NOTES_MEDIA_INDEX"
    local _full _rel
    while IFS= read -r -d '' _full; do
        _rel="${_full#"$NOTES_MEDIA_BASE"/}"
        printf '%s\t%s\n' "$_rel" "$_full"
    done < <(
        LC_ALL=C find "$NOTES_MEDIA_BASE" \
            \( -path '*/Media/*' -o -path '*/FallbackImages/*' \
               -o -path '*/FallbackPDFs/*' \) \
            -type f -print0 2>/dev/null
    ) >> "$_NOTES_MEDIA_INDEX"
    return 0
}

_NOTE_ATTACH_LOCATE_AWK='
        function suffix_match(s, tail,    n, m) {
            if (tail == "") return 0
            n = length(s); m = length(tail)
            if (m > n) return 0
            return substr(s, n - m + 1) == tail
        }
        {
            if (t1 != "" && !found1 && suffix_match($1, t1)) { p1 = $2; found1 = 1; exit }
            else if (!found2 && suffix_match($1, t2)) { if (p2 == "") p2 = $2; found2 = 1 }
            else if (!found3 && suffix_match($1, t3)) { if (p3 == "") p3 = $2; found3 = 1 }
            else if (t4 != "" && !found4 && suffix_match($1, t4)) { if (p4 == "") p4 = $2; found4 = 1 }
            else if (!found5 && suffix_match($1, t5)) { if (p5 == "") p5 = $2; found5 = 1 }
            else if (t6 != "" && !found6 && suffix_match($1, t6)) { if (p6 == "") p6 = $2; found6 = 1 }
        }
        END {
            if (found1) { print p1; exit }
            if (found2) { print p2; exit }
            if (found3) { print p3; exit }
            if (found4) { print p4; exit }
            if (found5) { print p5; exit }
            if (found6) { print p6; exit }
        }'

_locate_attachment_file() {
    local media_id="$1" filename="$2" generation="${3:-}"
    if [ -z "$media_id" ] || [ -z "$filename" ]; then
        return 1
    fi
    [ -d "$NOTES_MEDIA_BASE" ] || return 1
    _build_notes_media_index || return 1
    [ -s "$_NOTES_MEDIA_INDEX" ] || return 1
    local t1="" t2="/Media/$media_id/$filename"
    local t3="/FallbackImages/$media_id/$filename" t4=""
    local t5="/FallbackPDFs/$media_id/$filename" t6=""
    if [ -n "$generation" ]; then
        t1="/Media/$media_id/$generation/$filename"
        t4="/FallbackImages/$media_id/$generation/$filename"
        t6="/FallbackPDFs/$media_id/$generation/$filename"
    fi
    local hit
    hit="$(LC_ALL=C awk -F'\t' \
        -v t1="$t1" -v t2="$t2" -v t3="$t3" \
        -v t4="$t4" -v t5="$t5" -v t6="$t6" \
        "$_NOTE_ATTACH_LOCATE_AWK" "$_NOTES_MEDIA_INDEX")"
    [ -n "$hit" ] && { printf '%s' "$hit"; return 0; }
    local s1="" s2="/Media/$media_id/.$filename.icloud"
    local s3="/FallbackImages/$media_id/.$filename.icloud" s4=""
    local s5="/FallbackPDFs/$media_id/.$filename.icloud" s6=""
    if [ -n "$generation" ]; then
        s1="/Media/$media_id/$generation/.$filename.icloud"
        s4="/FallbackImages/$media_id/$generation/.$filename.icloud"
        s6="/FallbackPDFs/$media_id/$generation/.$filename.icloud"
    fi
    hit="$(LC_ALL=C awk -F'\t' \
        -v t1="$s1" -v t2="$s2" -v t3="$s3" \
        -v t4="$s4" -v t5="$s5" -v t6="$s6" \
        "$_NOTE_ATTACH_LOCATE_AWK" "$_NOTES_MEDIA_INDEX")"
    [ -n "$hit" ] && { printf '%s' "$hit"; return 0; }
    local _rebuild_marker="$SCRATCH_DIR/notes_media_index_rebuilt.$$"
    if [ ! -e "$_rebuild_marker" ]; then
        : > "$_rebuild_marker" 2>/dev/null
        rm -f -- "$_NOTES_MEDIA_INDEX" 2>/dev/null
        _build_notes_media_index || return 1
        [ -s "$_NOTES_MEDIA_INDEX" ] || return 1
        hit="$(LC_ALL=C awk -F'\t' \
            -v t1="$t1" -v t2="$t2" -v t3="$t3" \
            -v t4="$t4" -v t5="$t5" -v t6="$t6" \
            "$_NOTE_ATTACH_LOCATE_AWK" "$_NOTES_MEDIA_INDEX")"
        [ -n "$hit" ] && { printf '%s' "$hit"; return 0; }
    fi
    return 1
}

_html_format_body() {
    local text="$1" att_rel="$2"
    LC_ALL=C awk -v att_rel="$att_rel" '
        function html_esc(s, r) {
            r = s
            gsub(/&/, "\\&amp;", r); gsub(/</, "\\&lt;", r); gsub(/>/, "\\&gt;", r)
            gsub(/"/, "\\&quot;", r); gsub(/'\''/, "\\&#39;", r)
            return r
        }
        '"$_NOTE_ATTACH_TAG_AWK"'
        function process_line(line,    out, before, marker, fname, last) {
            out = ""
            while (match(line, /\[attachment: [^\t]*\t\]|\[attachment: [^]\t]+\]|https?:\/\/[A-Za-z0-9._~:\/?#@!$&()*+,;=%-]+/)) {
                before = substr(line, 1, RSTART-1)
                marker = substr(line, RSTART, RLENGTH)
                line = substr(line, RSTART+RLENGTH)
                if (substr(marker, 1, 1) == "[") {
                    fname = substr(marker, 14)   # drop "[attachment: "
                    sub(/\]$/, "", fname)         # drop closing "]"
                    sub(/\t$/, "", fname)         # drop TAB sentinel if present
                    out = out html_esc(before) _atag(fname, att_rel)
                } else {
                    while (length(marker) > 0) {
                        last = substr(marker, length(marker), 1)
                        if (last == "." || last == "," || last == ";" \
                            || last == ":" || last == "!" || last == "?") {
                            line = last line
                            marker = substr(marker, 1, length(marker)-1)
                        } else { break }
                    }
                    if (length(marker) > 0) {
                        out = out html_esc(before) "<a href=\"" html_esc(marker) "\">" html_esc(marker) "</a>"
                    } else {
                        out = out html_esc(before)
                    }
                }
            }
            return out html_esc(line)
        }
        BEGIN { in_para = 0 }
        /^[[:space:]]*$/ {
            if (in_para) { print "</p>"; in_para = 0 }
            next
        }
        {
            if (in_para == 0) { printf "<p>"; in_para = 1 }
            else printf "<br>"
            printf "%s", process_line($0)
        }
        END { if (in_para) print "</p>" }
    ' <<< "$text"
}

_extract_note_text() {
    local blob="$1"
    [ -s "$blob" ] || return 0
    if ! _is_gzipped "$blob"; then
        cat -- "$blob" 2>/dev/null
        return 0
    fi
    local raw="$blob.raw"
    if ! gzcat "$blob" > "$raw" 2>/dev/null; then
        cp -f -- "$blob" "$raw" 2>/dev/null || return 0
    fi
    local out
    out="$(LC_ALL=C tr -c '[:print:]\200-\377\n\t' '\n' < "$raw" \
        | LC_ALL=C awk 'length >= 8 && gsub(/[[:alpha:]]/,"&") >= 4' \
        | LC_ALL=C grep -Ev '[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}' \
        | LC_ALL=C grep -Ev 'public\.(jpeg|png|tiff|heic|gif|pdf|movie|audio|data|plain-text|html)' \
        | LC_ALL=C grep -v '^com\.apple\.[A-Za-z.]*$' \
        | LC_ALL=C grep -v '^[^[:alpha:]]*[[:alpha:]][^[:alpha:]]*[[:alpha:]][^[:alpha:]]*$' \
        | head -400)"
    rm -f -- "$raw"
    local _iconv_out
    _iconv_out="$(printf '%s' "$out" | iconv -c -f UTF-8 -t UTF-8 2>/dev/null)"
    [ -n "$_iconv_out" ] && out="$_iconv_out"
    if [ -n "$out" ]; then
        local line_count has_space=no
        line_count="$(printf '%s\n' "$out" | wc -l | tr -d ' ')"
        printf '%s\n' "$out" | LC_ALL=C grep -q ' ' && has_space=yes
        if [ "$has_space" = "no" ] && [ "${line_count:-0}" -le 1 ] \
           && [ "${#out}" -gt 63 ]; then
            return 0
        fi
    fi
    printf '%s' "$out"
}

NOTES_FETCH_PROTOC="${NOTES_FETCH_PROTOC:-1}"
HAS_PROTOC=""
PROTOC_BIN=""
PROTOC_VERSION=""

_probe_protoc() {
    command -v protoc >/dev/null 2>&1 || return 1
    if printf '' | _run_with_timeout 15 protoc --decode_raw >/dev/null 2>&1; then
        PROTOC_BIN="protoc"
        HAS_PROTOC="yes"
        return 0
    fi
    return 1
}

_fetch_protoc() {
    [ "$NOTES_FETCH_PROTOC" = "1" ] || return 1
    if ! command -v curl >/dev/null 2>&1; then
        log_warn "curl not found — cannot auto-fetch protoc"
        return 1
    fi
    if ! command -v unzip >/dev/null 2>&1; then
        log_warn "unzip not found — cannot auto-fetch protoc"
        return 1
    fi
    ensure_scratch
    local arch asset_arch
    arch="$(uname -m 2>/dev/null)"
    case "$arch" in
        arm64)  asset_arch="aarch_64" ;;
        x86_64) asset_arch="x86_64" ;;
        *)
            log_warn "Unrecognised architecture '$arch' — cannot pick a protoc asset."
            return 1 ;;
    esac
    local tag ver
    tag="$(curl -fsSL --max-time 10 \
        https://api.github.com/repos/protocolbuffers/protobuf/releases/latest \
        2>/dev/null \
        | sed -n 's/.*"tag_name"[[:space:]]*:[[:space:]]*"\(v[^"]*\)".*/\1/p' \
        | head -1)"
    if [ -z "$tag" ]; then
        log_warn "GitHub API returned no tag (rate-limited or offline) — using fallback v32.0 (no cryptographic verification; trust is HTTPS-transport only)."
        tag="v32.0"
    fi
    ver="${tag#v}"
    local zip_name="protoc-${ver}-osx-${asset_arch}.zip"
    local url="https://github.com/protocolbuffers/protobuf/releases/download/${tag}/${zip_name}"
    local zip_path="$SCRATCH_DIR/$zip_name"
    local extract_dir="$SCRATCH_DIR/protoc-extract"
    if ! _fetch_download "$url" "$zip_path" "protoc $tag" 60; then
        log_warn "Download failed: $url."
        return 1
    fi
    [ -s "$zip_path" ] || { log_warn "Downloaded zip is empty"; return 1; }
    local _ut_err
    _ut_err="$(unzip -tq "$zip_path" 2>&1)"
    if [ $? -ne 0 ]; then
        log_warn "Downloaded zip failed integrity check (likely network truncation, mismatched release tag, or corrupted upstream asset): $_ut_err."
        return 1
    fi
    if ! mkdir -p "$extract_dir"; then
        log_warn "Cannot create $extract_dir."
        return 1
    fi
    if ! unzip -q -o "$zip_path" -d "$extract_dir" 2>/dev/null; then
        log_warn "Failed to unzip $zip_name (after integrity check passed — likely disk-space / quota issue)"
        return 1
    fi
    local bin="$extract_dir/bin/protoc"
    if [ ! -x "$bin" ]; then
        log_warn "protoc binary not found in extracted archive"
        return 1
    fi
    if ! _run_with_timeout 15 "$bin" --version >/dev/null 2>&1; then
        log_warn "Downloaded protoc failed or timed out on --version test."
        return 1
    fi
    if ! printf '' | _run_with_timeout 15 "$bin" --decode_raw >/dev/null 2>&1; then
        log_warn "Downloaded protoc failed or timed out on --decode_raw test."
        return 1
    fi
    PROTOC_BIN="$bin"
    HAS_PROTOC="yes"
    PROTOC_VERSION="$("$bin" --version 2>/dev/null | head -1)"
    return 0
}

_decode_protoc_string() {
    LC_ALL=C awk 'BEGIN { ORS = "" }
    {
        s = $0
        n = length(s)
        i = 1
        while (i <= n) {
            c = substr(s, i, 1)
            if (c == "\\" && i < n) {
                nxt = substr(s, i+1, 1)
                if      (nxt == "\\") { printf "\\";  i += 2; continue }
                else if (nxt == "\"") { printf "\""; i += 2; continue }
                else if (nxt == "n")  { printf "\n"; i += 2; continue }
                else if (nxt == "t")  { printf "\t"; i += 2; continue }
                else if (nxt == "r")  { printf "\r"; i += 2; continue }
                else if (nxt ~ /[0-7]/ && i + 3 <= n) {
                    d2 = substr(s, i+2, 1)
                    d3 = substr(s, i+3, 1)
                    if (d2 ~ /[0-7]/ && d3 ~ /[0-7]/) {
                        val = (nxt - 0) * 64 + (d2 - 0) * 8 + (d3 - 0)
                        if (val >= 0 && val <= 255) {
                            printf "%c", val
                            i += 4
                            continue
                        }
                    }
                }
            }
            printf "%c", c
            i++
        }
    }'
}

_extract_note_text_protoc() {
    local blob="$1" note_pk="${2:-}" snap="${3:-}"
    [ -s "$blob" ] || return 1
    [ -z "$PROTOC_BIN" ] && return 1
    _is_gzipped "$blob" || return 1
    local raw
    raw="$(gzcat "$blob" 2>/dev/null \
            | "$PROTOC_BIN" --decode_raw 2>/dev/null \
            | LC_ALL=C awk '
                /^  [0-9]+ \{$/ { in_note = 1; next }
                in_note && /^  \}$/ { in_note = 0; next }
                in_note && match($0, /^    2: "/) {
                    s = $0; sub(/^    2: "/, "", s); sub(/"$/, "", s)
                    print s; exit
                }')"
    [ -z "$raw" ] && return 1
    local decoded
    decoded="$(printf '%s\n' "$raw" | _decode_protoc_string)"
    local UFFFC=$'\xEF\xBF\xBC'
    case "$decoded" in
        *"$UFFFC"*) ;;
        *) printf '%s' "$decoded"; return 0 ;;
    esac
    local -a att_names=()
    if [ -n "$note_pk" ] && [ -n "$snap" ]; then
        local fname
        local _att_fn_file="$SCRATCH_DIR/_note_att_filenames.tsv"
        _get_attachment_filenames "$note_pk" "$snap" > "$_att_fn_file" 2>/dev/null
        while IFS= read -r fname; do
            att_names+=( "$fname" )
        done < "$_att_fn_file"
    fi
    local idx=0 marker
    while true; do
        case "$decoded" in
            *"$UFFFC"*) ;;
            *) break ;;
        esac
        if [ "$idx" -lt "${#att_names[@]}" ] && [ -n "${att_names[$idx]}" ]; then
            marker="[attachment: ${att_names[$idx]}"$'\t'"]"
        else
            marker="[attachment]"
        fi
        decoded="${decoded/$UFFFC/$marker}"
        idx=$((idx + 1))
    done
    printf '%s' "$decoded"
}

_render_table_html() {
    local note_pk="$1" att_id="$2" snap="$3"
    if [ -z "$note_pk" ] || [ -z "$att_id" ] || [ -z "$snap" ]; then
        return 1
    fi
    [ "$HAS_PROTOC" = "yes" ] || return 1
    case "$att_id" in *[!A-Za-z0-9-]*) return 1 ;; esac
    case "$note_pk" in *[!0-9]*) return 1 ;; esac
    ensure_scratch
    local _col="$NOTES_COL_MERGEABLE"
    [ -n "$_col" ] || return 1
    local blob_path="$SCRATCH_DIR/table_${att_id//[^A-Za-z0-9]/_}.bin"
    sqlite3 -readonly "$snap" \
        "SELECT writefile('$blob_path', $_col) FROM ZICCLOUDSYNCINGOBJECT
          WHERE ZNOTE = $note_pk
            AND ZIDENTIFIER = '$att_id'
            AND $_col IS NOT NULL;" \
        >/dev/null 2>&1
    [ -s "$blob_path" ] || { rm -f -- "$blob_path" 2>/dev/null; return 1; }
    if ! _is_gzipped "$blob_path"; then
        rm -f -- "$blob_path" 2>/dev/null
        return 1
    fi
    local cells
    cells="$(gzcat "$blob_path" 2>/dev/null \
        | "$PROTOC_BIN" --decode_raw 2>/dev/null \
        | LC_ALL=C awk '
            /^[ \t]+2: "/ {
                s = $0
                sub(/^[ \t]+2: "/, "", s)
                sub(/"$/, "", s)
                if (s == "") next
                if (length(s) == 36 && s ~ /^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$/) next
                if (s ~ /^com\.apple\./) next
                if (s ~ /^public\./) next
                if (s ~ /^[0-9A-Fa-f]+$/ && s ~ /[A-Fa-f]/ && length(s) >= 16) next
                out = ""
                n = length(s); i = 1
                while (i <= n) {
                    c = substr(s, i, 1)
                    if (c == "\\" && i < n) {
                        nxt = substr(s, i+1, 1)
                        if      (nxt == "\\") { out = out "\\";  i += 2; continue }
                        else if (nxt == "\"") { out = out "\""; i += 2; continue }
                        else if (nxt == "n")  { out = out "\n"; i += 2; continue }
                        else if (nxt == "t")  { out = out "\t"; i += 2; continue }
                        else if (nxt == "r")  { out = out "\r"; i += 2; continue }
                        else if (nxt ~ /[0-7]/ && i + 3 <= n) {
                            d2 = substr(s, i+2, 1); d3 = substr(s, i+3, 1)
                            if (d2 ~ /[0-7]/ && d3 ~ /[0-7]/) {
                                v = (nxt - 0) * 64 + (d2 - 0) * 8 + (d3 - 0)
                                if (v >= 0 && v <= 255) {
                                    out = out sprintf("%c", v)
                                    i += 4; continue
                                }
                            }
                        }
                    }
                    out = out c; i++
                }
                gsub(/\n/, " ", out)
                gsub(/\x1f/, "", out)
                if (out == "" || out ~ /^[[:space:]]*$/) next
                printf "%s\x1f", out
            }')"
    rm -f -- "$blob_path" 2>/dev/null
    [ -z "$cells" ] && return 1
    LC_ALL=C awk -v RS=$'\x1f' '
        function html_esc(s,    r) {
            r = s
            gsub(/&/, "\\&amp;", r); gsub(/</, "\\&lt;", r); gsub(/>/, "\\&gt;", r)
            gsub(/"/, "\\&quot;", r); gsub(/'\''/, "\\&#39;", r)
            return r
        }
        BEGIN { printf "<table class=\"notes-table\"><tbody>" }
        $0 != "" { printf "<tr><td>%s</td></tr>", html_esc($0) }
        END { print "</tbody></table>" }
    ' <<< "$cells"
}

_extract_note_styled_html() {
    local blob="$1" note_pk="${2:-}" snap="${3:-}" att_rel="${4:-}"
    [ -s "$blob" ] || return 1
    [ -z "$PROTOC_BIN" ] && return 1
    _is_gzipped "$blob" || return 1
    local protoc_out
    protoc_out="$(gzcat "$blob" 2>/dev/null \
                  | "$PROTOC_BIN" --decode_raw 2>/dev/null)"
    [ -z "$protoc_out" ] && return 1
    local raw
    raw="$(printf '%s\n' "$protoc_out" 2>/dev/null \
            | LC_ALL=C awk '
                /^  [0-9]+ \{$/ { in_note = 1; next }
                in_note && /^  \}$/ { in_note = 0; next }
                in_note && match($0, /^    2: "/) {
                    s = $0; sub(/^    2: "/, "", s); sub(/"$/, "", s)
                    print s; exit
                }')"
    [ -z "$raw" ] && return 1
    local decoded
    decoded="$(printf '%s\n' "$raw" | _decode_protoc_string)"
    [ -z "$decoded" ] && return 1
    local runs_tsv
    runs_tsv="$(printf '%s\n' "$protoc_out" | LC_ALL=C awk '
        function fixed32_bits(tok,   h, n, i, c, v, d) {
            if (tok ~ /^0[xX][0-9A-Fa-f]+$/) {
                h = substr(tok, 3); v = 0; n = length(h)
                for (i = 1; i <= n; i++) {
                    c = tolower(substr(h, i, 1))
                    if (c >= "0" && c <= "9") d = c + 0
                    else d = index("abcdef", c) + 9
                    v = v * 16 + d
                }
                return v
            }
            if (tok ~ /^[0-9]+$/) return tok + 0
            return -1
        }
        function f32_decode(v,   sgn, expn, mant, res) {
            if (v < 0) return 0
            sgn = (v >= 2147483648) ? 1 : 0
            if (sgn) v -= 2147483648
            expn = int(v / 8388608)
            mant = v % 8388608
            if (expn == 0)        res = (mant / 8388608) * (2 ^ -126)
            else if (expn == 255) res = 0          # inf/NaN -> clamp to 0
            else                  res = (1 + mant / 8388608) * (2 ^ (expn - 127))
            return sgn ? -res : res
        }
        function f32_to_255(v,   n) {
            n = int(v * 255 + 0.5)
            if (n < 0) n = 0
            if (n > 255) n = 255
            return n
        }
        BEGIN { in_doc_note=0; in_run=0; in_pstyle=0; in_checklist=0; in_attachinfo=0; in_color=0 }
        /^  [0-9]+ \{$/ { in_doc_note = 1; next }
        in_doc_note && /^  \}$/ { in_doc_note = 0; next }
        in_doc_note && !in_run && /^    5 \{$/ {
            in_run = 1
            len_v = 0; style = 0; checked = -1; indent = 0
            weight = 0; under = 0; strike = 0; link = ""; attach_id = ""
            has_pstyle = 0
            align = -1; blockquote = 0
            col_r = 0; col_g = 0; col_b = 0; has_color = 0
            has_r = 0; has_g = 0; has_b = 0
            next
        }
        in_run && /^    \}$/ {
            color_str = ""
            if (has_color && has_r && has_g && has_b) {
                color_str = "rgb(" f32_to_255(col_r) "," \
                            f32_to_255(col_g) "," f32_to_255(col_b) ")"
            }
            _rows[++_nr] = sprintf("%d\t%d\t%d\t%d\t%d\t%d\t%s\t%s\t%d\t%d\t%d\t%s", \
                len_v, (has_pstyle ? style : -1), checked, \
                weight, under, strike, link, attach_id, indent, \
                align, blockquote, color_str)
            in_run = 0; in_pstyle = 0; in_checklist = 0; in_attachinfo = 0; in_color = 0
            next
        }
        in_run && !in_pstyle && !in_checklist && !in_attachinfo && !in_color && /^      1: [0-9]+$/ {
            s = $0; sub(/^.*: /, "", s); len_v = s + 0; next
        }
        in_run && !in_pstyle && !in_checklist && !in_attachinfo && !in_color && /^      2 \{$/ {
            in_pstyle = 1; has_pstyle = 1; next
        }
        in_run && in_pstyle && !in_checklist && /^      \}$/ { in_pstyle = 0; next }
        in_pstyle && !in_checklist && /^        1: [0-9]+$/ {
            s = $0; sub(/^.*: /, "", s); style = s + 0; next
        }
        in_pstyle && !in_checklist && /^        2: [0-9]+$/ {
            s = $0; sub(/^.*: /, "", s); align = s + 0; next
        }
        in_pstyle && !in_checklist && /^        4: [0-9]+$/ {
            s = $0; sub(/^.*: /, "", s); indent = s + 0; next
        }
        in_pstyle && !in_checklist && /^        5 \{$/ { in_checklist = 1; next }
        in_pstyle && !in_checklist && /^        8: [0-9]+$/ {
            s = $0; sub(/^.*: /, "", s); blockquote = s + 0; next
        }
        in_pstyle && /^        9: "/ { _new_schema = 1; next }
        in_checklist && /^        \}$/ { in_checklist = 0; next }
        in_checklist && /^          2: [0-9]+$/ {
            s = $0; sub(/^.*: /, "", s); checked = s + 0; next
        }
        in_run && !in_pstyle && !in_checklist && !in_attachinfo && !in_color && /^      5: [0-9]+$/ {
            s = $0; sub(/^.*: /, "", s); weight = s + 0; next
        }
        in_run && !in_pstyle && !in_checklist && !in_attachinfo && !in_color && /^      6: [0-9]+$/ {
            s = $0; sub(/^.*: /, "", s); under = s + 0; next
        }
        in_run && !in_pstyle && !in_checklist && !in_attachinfo && !in_color && /^      7: [0-9]+$/ {
            s = $0; sub(/^.*: /, "", s); strike = s + 0; next
        }
        in_run && !in_pstyle && !in_checklist && !in_attachinfo && !in_color && /^      9: "/ {
            s = $0
            sub(/^      9: "/, "", s)
            if (substr(s, length(s), 1) == "\"") {
                s = substr(s, 1, length(s) - 1)
            }
            link = s; next
        }
        in_run && !in_pstyle && !in_checklist && !in_attachinfo && !in_color && /^      10 \{$/ {
            in_color = 1; has_color = 1; next
        }
        in_color && /^      \}$/ { in_color = 0; next }
        in_color && /^        1: / {
            s = $0; sub(/^        1: /, "", s)
            bits = fixed32_bits(s)
            if (bits >= 0) { col_r = f32_decode(bits); has_r = 1 }
            next
        }
        in_color && /^        2: / {
            s = $0; sub(/^        2: /, "", s)
            bits = fixed32_bits(s)
            if (bits >= 0) { col_g = f32_decode(bits); has_g = 1 }
            next
        }
        in_color && /^        3: / {
            s = $0; sub(/^        3: /, "", s)
            bits = fixed32_bits(s)
            if (bits >= 0) { col_b = f32_decode(bits); has_b = 1 }
            next
        }
        in_color && /^        4: / { next }
        in_run && !in_pstyle && !in_checklist && !in_attachinfo && !in_color && /^      12 \{$/ {
            in_attachinfo = 1; next
        }
        in_attachinfo && /^      \}$/ { in_attachinfo = 0; next }
        in_attachinfo && /^        1: "/ {
            s = $0
            sub(/^        1: "/, "", s)
            if (substr(s, length(s), 1) == "\"") {
                s = substr(s, 1, length(s) - 1)
            }
            attach_id = s; next
        }
        in_run && !in_pstyle && !in_checklist && !in_attachinfo && !in_color && /^      13: / { _new_schema = 1; next }
        END { if (!_new_schema) for (_i = 1; _i <= _nr; _i++) print _rows[_i] }
    ')"
    [ -z "$runs_tsv" ] && return 1
    local att_meta_pipe=""
    if [ -n "$note_pk" ] && [ -n "$snap" ]; then
        att_meta_pipe="$(_get_attachment_metadata "$note_pk" "$snap")"
    fi
    local att_names_pipe=""
    if [ -n "$att_meta_pipe" ]; then
        att_names_pipe="$(printf '%s\n' "$att_meta_pipe" | awk -F$'\x1f' '$2 != "" {print $2}')"
    fi
    local att_tables_pipe=""
    if [ -n "$att_meta_pipe" ] && [ -n "$note_pk" ] && [ "$HAS_PROTOC" = "yes" ]; then
        local _id _uti _table_html
        while IFS=$'\x1f' read -r _id _ _uti _ _ _ _; do
            [ -z "$_id" ] && continue
            [ "$_uti" = "com.apple.notes.table" ] || continue
            _table_html="$(_render_table_html "$note_pk" "$_id" "$snap" 2>/dev/null)"
            [ -z "$_table_html" ] && continue
            att_tables_pipe="$att_tables_pipe$_id"$'\x1f'"$_table_html"$'\x1e'
        done <<< "$att_meta_pipe"
    fi
    local _runs_rs _names_rs _meta_rs
    _runs_rs="$(printf '%s' "$runs_tsv" | tr '\n' '\036')"
    _names_rs="$(printf '%s' "$att_names_pipe" | tr '\n' '\036')"
    _meta_rs="$(printf '%s' "$att_meta_pipe" | tr '\n' '\036')"
    LC_ALL=C \
    runs_tsv="$_runs_rs" \
    att_names="$_names_rs" \
    att_meta="$_meta_rs" \
    att_tables="$att_tables_pipe" \
    awk \
        -v att_rel="$att_rel" \
        '
        function html_esc(s,    r) {
            r = s
            gsub(/&/, "\\&amp;", r); gsub(/</, "\\&lt;", r); gsub(/>/, "\\&gt;", r)
            gsub(/"/, "\\&quot;", r); gsub(/'\''/, "\\&#39;", r)
            return r
        }
        function attr_esc(s,    r) {
            r = s
            gsub(/&/, "\\&amp;", r); gsub(/"/, "\\&quot;", r)
            return r
        }
        '"$_NOTE_ATTACH_TAG_AWK"'
        function render_by_uti(uti, fname, alttext, urlstr, urltitle, children,    title, href, n_kids, kids, k, out) {
            if (uti ~ /^com\.apple\.notes\.inlinetextattachment\./) {
                sub(/[[:space:]]+$/, "", alttext)
                if (alttext == "") return ""
                return html_esc(alttext)
            }
            if (uti == "public.url") {
                href = safe_href(urlstr)
                title = (urltitle != "" ? urltitle : urlstr)
                if (title == "") return ""
                return "<a href=\"" attr_esc(href) "\">" html_esc(title) "</a>"
            }
            if (uti == "com.apple.notes.gallery") {
                if (children == "") return ""
                n_kids = split(children, kids, "|")
                if (n_kids == 0) return ""
                out = "<div class=\"gallery\">"
                for (k = 1; k <= n_kids; k++) {
                    if (kids[k] != "") out = out _atag(kids[k], att_rel)
                }
                return out "</div>"
            }
            if (fname != "") return _atag(fname, att_rel)
            return "[attachment]"
        }
        function render_table(attach_id) {
            if (attach_id != "" && (attach_id in att_table_html)) {
                return att_table_html[attach_id]
            }
            return "<p class=\"notes-table-stub\"><em>[table — extraction unavailable; install protoc for table support]</em></p>"
        }
        function tag_for_attachment(idx, attach_id,    uti, fname, alt, url, title, children) {
            if (attach_id != "" && (attach_id in att_id_seen)) {
                uti = att_uti[attach_id]
                if (uti == "com.apple.notes.table") return render_table(attach_id)
                fname = att_fname[attach_id]
                alt = att_alt[attach_id]
                url = att_url[attach_id]
                title = att_title[attach_id]
                children = att_children[attach_id]
                return render_by_uti(uti, fname, alt, url, title, children)
            }
            if (idx >= 1 && idx <= n_atts) {
                return _atag(att_name[idx], att_rel)
            }
            return "[attachment]"
        }
        function decode_pstr(s,    n, i, c, nxt, d2, d3, val, out) {
            n = length(s); i = 1; out = ""
            while (i <= n) {
                c = substr(s, i, 1)
                if (c == "\\" && i < n) {
                    nxt = substr(s, i + 1, 1)
                    if      (nxt == "\\") { out = out "\\"; i += 2; continue }
                    else if (nxt == "\"") { out = out "\""; i += 2; continue }
                    else if (nxt == "n")  { out = out "\n"; i += 2; continue }
                    else if (nxt == "t")  { out = out "\t"; i += 2; continue }
                    else if (nxt == "r")  { out = out "\r"; i += 2; continue }
                    else if (nxt ~ /[0-7]/ && i + 3 <= n) {
                        d2 = substr(s, i + 2, 1)
                        d3 = substr(s, i + 3, 1)
                        if (d2 ~ /[0-7]/ && d3 ~ /[0-7]/) {
                            val = (nxt - 0) * 64 + (d2 - 0) * 8 + (d3 - 0)
                            if (val >= 0 && val <= 255) {
                                out = out sprintf("%c", val); i += 4; continue
                            }
                        }
                    }
                }
                out = out c
                i++
            }
            return out
        }
        function safe_href(link,    lc) {
            lc = tolower(link)
            if (lc ~ /^https?:\/\//)  return link
            if (lc ~ /^mailto:/)      return link
            if (lc ~ /^tel:/)         return link
            if (lc ~ /^sms:/)         return link
            if (lc ~ /^ftp:\/\//)     return link
            if (lc ~ /^applenotes:/)  return link
            return "#"
        }
        function wrap_char(text, weight, under, strike, link, color,    out) {
            if (text == "") return ""
            out = text
            if (color != "")                 out = "<span style=\"color:" attr_esc(color) "\">" out "</span>"
            if (link != "")                  out = "<a href=\"" attr_esc(safe_href(link)) "\">" out "</a>"
            if (strike == 1)                 out = "<s>" out "</s>"
            if (under == 1)                  out = "<u>" out "</u>"
            if (weight == 2 || weight == 3)  out = "<em>" out "</em>"
            if (weight == 1 || weight == 3)  out = "<strong>" out "</strong>"
            return out
        }
        function open_list_at(want) {
            list_depth++
            list_kind[list_depth] = want
            if (want == "ul-bullet")     printf "<ul>\n"
            else if (want == "ul-dash")  printf "<ul class=\"dash\">\n"
            else if (want == "ol")       printf "<ol>\n"
            else if (want == "ul-check") printf "<ul class=\"checklist\">\n"
        }
        function close_list_top(    k) {
            if (list_depth <= 0) return
            k = list_kind[list_depth]
            if (k == "ol") printf "</ol>\n"
            else           printf "</ul>\n"
            delete list_kind[list_depth]
            list_depth--
        }
        function manage_list(style, target_depth,    want) {
            if (style == 100)      want = "ul-bullet"
            else if (style == 101) want = "ul-dash"
            else if (style == 102) want = "ol"
            else if (style == 103) want = "ul-check"
            else                   want = ""
            if (want == "") {
                while (list_depth > 0) close_list_top()
                return
            }
            while (list_depth > target_depth) close_list_top()
            if (list_depth == target_depth && list_depth > 0 \
                && list_kind[list_depth] != want) {
                close_list_top()
            }
            while (list_depth < target_depth) open_list_at(want)
        }
        function close_lists() {
            while (list_depth > 0) close_list_top()
        }
        function align_style_attr(align,    v) {
            if      (align == 1) v = "center"
            else if (align == 2) v = "right"
            else if (align == 3) v = "justify"
            else                 return ""
            return " style=\"text-align:" v "\""
        }
        function open_block(style, checked, indent, align, blockquote,    target_depth, sa) {
            target_depth = (style == 100 || style == 101 \
                            || style == 102 || style == 103) \
                           ? indent + 1 : 0
            manage_list(style, target_depth)
            cur_block_indent = indent
            cur_block_align = align
            cur_block_bq = (blockquote != 0 && style != 100 \
                            && style != 101 && style != 102 \
                            && style != 103) ? 1 : 0
            if (cur_block_bq) printf "<blockquote>"
            sa = align_style_attr(align)
            if (style == 0)        printf "<h1%s>", sa
            else if (style == 1)   printf "<h2%s>", sa
            else if (style == 2)   printf "<h3%s>", sa
            else if (style == 4)   printf "<pre%s>", sa
            else if (style == 100 || style == 101 || style == 102) printf "<li%s>", sa
            else if (style == 103) {
                if (checked == 1) printf "<li%s><input type=\"checkbox\" checked disabled> ", sa
                else              printf "<li%s><input type=\"checkbox\" disabled> ", sa
            }
            else                   printf "<p%s>", sa
            cur_block = style
        }
        function close_block() {
            if (cur_block == -2) return
            if (cur_block == 0)       printf "</h1>"
            else if (cur_block == 1)  printf "</h2>"
            else if (cur_block == 2)  printf "</h3>"
            else if (cur_block == 4)  printf "</pre>"
            else if (cur_block == 100 || cur_block == 101 || cur_block == 102 || cur_block == 103) printf "</li>"
            else                      printf "</p>"
            if (cur_block_bq) printf "</blockquote>"
            printf "\n"
            cur_block = -2
            cur_block_bq = 0
        }
        BEGIN {
            runs_tsv   = ENVIRON["runs_tsv"]
            att_names  = ENVIRON["att_names"]
            att_meta   = ENVIRON["att_meta"]
            att_tables = ENVIRON["att_tables"]
            for (i = 0; i < 256; i++) _ord[sprintf("%c", i)] = i
            n_atts = 0; att_idx = 0
            split(att_names, _alines, "\x1e")
            for (i = 1; i in _alines; i++) if (_alines[i] != "") {
                n_atts++; att_name[n_atts] = _alines[i]
            }
            split(att_meta, _mlines, "\x1e")
            for (i in _mlines) {
                if (_mlines[i] == "") continue
                split(_mlines[i], mf, "\x1f")
                if (mf[1] == "") continue
                att_id_seen[mf[1]] = 1
                att_fname[mf[1]]    = (2 in mf ? mf[2] : "")
                att_uti[mf[1]]      = (3 in mf ? mf[3] : "")
                att_alt[mf[1]]      = (4 in mf ? mf[4] : "")
                att_url[mf[1]]      = (5 in mf ? mf[5] : "")
                att_title[mf[1]]    = (6 in mf ? mf[6] : "")
                att_children[mf[1]] = (7 in mf ? mf[7] : "")
            }
            n_tables = split(att_tables, _tlines, "\x1e")
            for (i = 1; i <= n_tables; i++) {
                if (_tlines[i] == "") continue
                _tsep = index(_tlines[i], "\x1f")
                if (_tsep <= 0) continue
                _tid = substr(_tlines[i], 1, _tsep - 1)
                _thtml = substr(_tlines[i], _tsep + 1)
                if (_tid != "") att_table_html[_tid] = _thtml
            }
            n_runs = 0
            split(runs_tsv, _rlines, "\x1e")
            for (i = 1; i in _rlines; i++) {
                if (_rlines[i] == "") continue
                n_runs++
                split(_rlines[i], f, "\t")
                run_len[n_runs]    = f[1] + 0
                run_style[n_runs]  = f[2] + 0
                run_check[n_runs]  = f[3] + 0
                run_weight[n_runs] = f[4] + 0
                run_under[n_runs]  = f[5] + 0
                run_strike[n_runs] = f[6] + 0
                run_link[n_runs]   = decode_pstr(f[7])
                run_attach_id[n_runs] = (8 in f) ? f[8] : ""
                run_indent[n_runs]    = (9 in f) ? (f[9] + 0) : 0
                run_align[n_runs]      = (10 in f) ? (f[10] + 0) : -1
                run_blockquote[n_runs] = (11 in f) ? (f[11] + 0) : 0
                run_color[n_runs]      = (12 in f) ? f[12] : ""
            }
            text_buf = ""
            cur_block = -2
            cur_block_align = -1
            cur_block_bq = 0
            list_depth = 0
        }
        { text_buf = (text_buf == "" ? $0 : text_buf "\n" $0) }
        END {
            if (n_runs == 0) {
                printf "<p>%s</p>\n", html_esc(text_buf)
                exit
            }
            text = text_buf
            tlen = length(text)
            n_chars = 0
            pos = 1
            while (pos <= tlen) {
                b1 = _ord[substr(text, pos, 1)]
                if      (b1 < 128) { blen = 1; u16 = 1 }
                else if (b1 < 192) { blen = 1; u16 = 0 }
                else if (b1 < 224) { blen = 2; u16 = 1 }
                else if (b1 < 240) { blen = 3; u16 = 1 }
                else               { blen = 4; u16 = 2 }
                n_chars++
                c_pos[n_chars] = pos
                c_len[n_chars] = blen
                c_u16[n_chars] = u16
                pos += blen
            }
            ci = 1
            for (r = 1; r <= n_runs; r++) {
                eff_style = run_style[r]
                eff_check = run_check[r]
                target = run_len[r]; consumed = 0
                rs = ci
                while (ci <= n_chars && consumed < target) {
                    consumed += c_u16[ci]
                    ci++
                }
                re = ci - 1
                if (re < rs) continue
                run_text = substr(text, c_pos[rs], \
                    c_pos[re] + c_len[re] - c_pos[rs])
                n_lines = split(run_text, lines, "\n")
                for (li = 1; li <= n_lines; li++) {
                    line = lines[li]
                    has_nl = (li < n_lines)
                    if (line == "" && has_nl) {
                        if (cur_block != -2) close_block()
                        continue
                    }
                    if (cur_block == -2) {
                        open_block(eff_style, eff_check, run_indent[r], \
                                   run_align[r], run_blockquote[r])
                    } else if ((cur_block != eff_style \
                                || cur_block_indent != run_indent[r] \
                                || cur_block_align != run_align[r] \
                                || cur_block_bq != (run_blockquote[r] != 0)) \
                               && line != "") {
                        close_block()
                        open_block(eff_style, eff_check, run_indent[r], \
                                   run_align[r], run_blockquote[r])
                    }
                    s = line
                    out = ""
                    while (1) {
                        idx = index(s, "\357\277\274")
                        if (idx == 0) break
                        before = substr(s, 1, idx - 1)
                        out = out wrap_char(html_esc(before), \
                            run_weight[r], run_under[r], run_strike[r], \
                            run_link[r], run_color[r])
                        att_idx++
                        out = out tag_for_attachment(att_idx, run_attach_id[r])
                        s = substr(s, idx + 3)
                    }
                    out = out wrap_char(html_esc(s), \
                        run_weight[r], run_under[r], run_strike[r], \
                        run_link[r], run_color[r])
                    printf "%s", out
                    if (has_nl) close_block()
                }
            }
            close_block()
            close_lists()
        }
        ' <<< "$decoded" 2>/dev/null
}

_strip_duplicate_title() {
    local text="$1" title="$2"
    [ -z "$text" ] && return 0
    [ -z "$title" ] && { printf '%s' "$text"; return; }
    local first rest
    first="$(printf '%s\n' "$text" | head -1)"
    if [ "$first" = "$title" ] || [ "$first" = " $title" ]; then
        rest="$(printf '%s\n' "$text" | tail -n +2)"
        printf '%s' "$rest"
    else
        printf '%s' "$text"
    fi
}

_notes_idx_rows() {
    local _rel _title _folder _account _pinned _e1 _e2 _e3
    LC_ALL=C sort -t "$(printf '\x1f')" -k4,4 -k3,3 -k2,2 "$_mf" | \
        while IFS="$(printf '\x1f')" read -r _rel _title _folder _account _pinned; do
        printf '<tr>'
        html_escape "${_title:-(untitled)}" _e1
        printf '<td><a href="%s">%s</a></td>' "$(_url_encode_path "$_rel")" "$_e1"
        if [ "$_multi" = "yes" ]; then
            html_escape "${_account:-—}" _e2
            printf '<td>%s</td>' "$_e2"
        fi
        html_escape "${_folder:-—}" _e3
        printf '<td>%s</td>' "$_e3"
        case "$_pinned" in ''|0) printf '<td class="c"></td>' ;; *) printf '<td class="c">📌</td>' ;; esac
        printf '</tr>\n'
    done
}

_notes_emit_index() {
    local _mf="$1" _nc="$2" _root="$3" _multi="$4"
    local _idx_title _idx_h1 _idx_extra_css _idx_thead _idx_rows_fn
    _idx_title="Notes ($_nc)"
    _idx_h1="Notes — $_nc $(_pluralize "$_nc" note)"
    _idx_extra_css='td.c{text-align:center;}'
    _idx_thead="<tr><th>Note</th>$([ "$_multi" = "yes" ] && printf '<th>Account</th>')<th>Folder</th><th class=\"c\">Pinned</th></tr>"
    _idx_rows_fn=_notes_idx_rows
    _emit_html_index "$_root/index.html" "Notes/index.html"
}

notes_main() {
    maybe_show_help "$@"
    _announce_step "Notes export"
    check_dependencies
    local out_arg="" arg end_opts=0
    for arg in "$@"; do
        if [ "$end_opts" -eq 0 ]; then
            case "$arg" in
                --) end_opts=1; continue ;;
                --disable-protoc|--no-protoc)
                    NOTES_FETCH_PROTOC=0; continue ;;
                -*)
                    die "Unknown flag: $arg" ;;
            esac
        fi
        if [ -n "$out_arg" ]; then
            die "Unexpected extra argument: $arg"
        fi
        out_arg="$arg"
    done
    local out_dir
    out_dir="$(resolve_output_dir "$out_arg")" || exit 1
    _announce_output_dir "Notes"
    require_full_disk_access
    warn_if_app_running Notes
    [ -f "$NOTES_DB" ] || die "Notes database not found: $NOTES_DB
  Open Notes.app once to initialise it, then re-run."
    local out_root="$out_dir/Notes"
    require_no_collision "$out_root"
    ensure_scratch
    log_info "Snapshotting Notes database..."
    log_info "Source: $NOTES_DB"
    local snap
    snap="$(snapshot_db_or_die "$NOTES_DB" "Notes")" || exit 1
    require_db_tables "$snap" "Notes" \
        ZICCLOUDSYNCINGOBJECT ZICNOTEDATA Z_PRIMARYKEY
    log_info "Probing schema (entities, columns)..."
    local note_ent folder_ent account_ent attachment_ent
    local _ent_rows _er_name _er_id
    _ent_rows="$(sqlite3 -readonly -separator $'\x1f' "$snap" \
        "SELECT Z_NAME, Z_ENT FROM Z_PRIMARYKEY
          WHERE Z_NAME IN ('ICNote','ICFolder','ICAccount');" 2>/dev/null)"
    while IFS=$'\x1f' read -r _er_name _er_id; do
        case "$_er_name" in
            ICNote)    note_ent="$_er_id" ;;
            ICFolder)  folder_ent="$_er_id" ;;
            ICAccount) account_ent="$_er_id" ;;
        esac
    done <<EOF
$_ent_rows
EOF
    case "${note_ent:-}" in    ''|*[!0-9]*) note_ent="" ;; esac
    case "${folder_ent:-}" in  ''|*[!0-9]*) folder_ent="" ;; esac
    case "${account_ent:-}" in ''|*[!0-9]*) account_ent="" ;; esac
    attachment_ent="$(sqlite3 -readonly "$snap" "SELECT Z_ENT FROM Z_PRIMARYKEY WHERE Z_NAME='ICAttachment';" 2>/dev/null)"
    case "${attachment_ent:-}" in
        ''|*[!0-9]*) attachment_ent="" ;;
    esac
    [ -z "$attachment_ent" ] && \
        log_info "Schema: ICAttachment Z_ENT not in Z_PRIMARYKEY — attachment queries unfiltered (may include junk rows from sibling entities sharing ZNOTE)."
    if [ -z "$note_ent" ] || [ -z "$folder_ent" ]; then
        local _avail_ents
        _avail_ents="$(sqlite3 -readonly "$snap" \
            "SELECT GROUP_CONCAT(Z_NAME, ', ') FROM Z_PRIMARYKEY \
              WHERE Z_NAME LIKE 'IC%';" 2>/dev/null)"
        [ -z "$note_ent" ] && \
            die "Cannot find ICNote entity (Notes schema unrecognised; IC entities present: ${_avail_ents:-none})"
        die "Cannot find ICFolder entity (Notes schema unrecognised; IC entities present: ${_avail_ents:-none})"
    fi
    _resolve_notes_columns "$snap"
    local account_col=""
    account_col="$(sqlite3 -readonly "$snap" "
        SELECT name FROM pragma_table_info('ZICCLOUDSYNCINGOBJECT')
         WHERE name LIKE 'ZACCOUNT%'
           AND name GLOB 'ZACCOUNT[0-9]*'
           AND NOT (name GLOB 'ZACCOUNT*[!0-9]*')
         ORDER BY CAST(SUBSTR(name, 9) AS INTEGER) DESC
         LIMIT 1;" 2>/dev/null)"
    if [ -z "$account_col" ]; then
        if sqlite3 -readonly "$snap" "PRAGMA table_info(ZICCLOUDSYNCINGOBJECT);" 2>/dev/null \
            | grep -q "|ZACCOUNT|"; then
            account_col="ZACCOUNT"
        fi
    fi
    case "$account_col" in *[!A-Za-z0-9_]*) account_col="" ;; esac
    log_info "Dumping folders and accounts..."
    local _acct_select="0"
    [ -n "$account_col" ] && _acct_select="COALESCE($account_col, 0)"
    local _smart_filter="" smart_folders_filtered=0
    if sqlite3 -readonly "$snap" "
        SELECT 1 FROM pragma_table_info('ZICCLOUDSYNCINGOBJECT')
         WHERE name='ZSMARTFOLDERQUERYJSON' LIMIT 1;" 2>/dev/null \
            | grep -q '^1$'; then
        _smart_filter="AND ZSMARTFOLDERQUERYJSON IS NULL"
        local _n_smart
        _n_smart="$(sqlite3 -readonly "$snap" "
            SELECT COUNT(*) FROM ZICCLOUDSYNCINGOBJECT
             WHERE Z_ENT = $folder_ent
               AND COALESCE(ZMARKEDFORDELETION, 0) = 0
               AND ZSMARTFOLDERQUERYJSON IS NOT NULL;" 2>/dev/null)"
        case "${_n_smart:-0}" in
            ''|*[!0-9]*) : ;;
            *) smart_folders_filtered=$_n_smart ;;
        esac
    fi
    local _folder_title_sel="''"
    [ -n "$NOTES_COL_FOLDER" ] && _folder_title_sel="$(_sql_tsv_safe "$NOTES_COL_FOLDER")"
    if ! sqlite3 -readonly -separator $'\x1f' "$snap" "
        SELECT Z_PK, $_folder_title_sel, COALESCE(ZIDENTIFIER, ''),
               $_acct_select,
               COALESCE(ZPARENT, 0)
          FROM ZICCLOUDSYNCINGOBJECT
         WHERE Z_ENT = $folder_ent
           AND COALESCE(ZMARKEDFORDELETION, 0) = 0
           $_smart_filter;
    " > "$SCRATCH_DIR/folders.tsv" 2>/dev/null; then
        log_warn "Notes: folder-hierarchy query failed — notes exported flat (folder nesting lost for this run)"
        : > "$SCRATCH_DIR/folders.tsv"
    fi
    [ "$smart_folders_filtered" -gt 0 ] && _disclose_excluded "$smart_folders_filtered smart $(_pluralize "$smart_folders_filtered" folder)" "saved-query rows that own no notes of their own"
    : > "$SCRATCH_DIR/shared_notes.set"
    if sqlite3 -readonly "$snap" "SELECT 1 FROM sqlite_master WHERE type='table' AND name='ZICCLOUDSHARINGPARTICIPANT' LIMIT 1;" 2>/dev/null | grep -q '^1$'; then
        sqlite3 -readonly "$snap" "
            SELECT DISTINCT ZNOTE FROM ZICCLOUDSHARINGPARTICIPANT WHERE ZNOTE IS NOT NULL;
        " > "$SCRATCH_DIR/shared_notes.set" 2>/dev/null || : > "$SCRATCH_DIR/shared_notes.set"
    fi
    : > "$SCRATCH_DIR/accounts.tsv"
    if [ -n "$account_ent" ] && [ -n "$account_col" ]; then
        local _acct_type_select="0"
        if _col_in_list "$NOTES_ALL_COLS" 'ZACCOUNTTYPE'; then
            _acct_type_select="COALESCE(ZACCOUNTTYPE, 0)"
        fi
        sqlite3 -readonly -separator $'\x1f' "$snap" "
            SELECT Z_PK, COALESCE(ZNAME, ''), $_acct_type_select
              FROM ZICCLOUDSYNCINGOBJECT
             WHERE Z_ENT = $account_ent
               AND COALESCE(ZMARKEDFORDELETION, 0) = 0;
        " > "$SCRATCH_DIR/accounts.tsv"
    fi
    local mdate_col="" cdate_col=""
    local _ncols _ncols_rc
    _ncols="$(sqlite3 -readonly "$snap" \
        "SELECT name FROM pragma_table_info('ZICCLOUDSYNCINGOBJECT');" 2>/dev/null)"
    _ncols_rc=$?
    [ "$_ncols_rc" -ne 0 ] && _probe_miss error ZICCLOUDSYNCINGOBJECT '*'
    for _c in ZMODIFICATIONDATE1 ZMODIFICATIONDATE; do
        if _col_in_list "$_ncols" "$_c"; then mdate_col="$_c"; break; fi
    done
    for _c in ZCREATIONDATE3 ZCREATIONDATE1 ZCREATIONDATE; do
        if _col_in_list "$_ncols" "$_c"; then cdate_col="$_c"; break; fi
    done
    case "$cdate_col" in
        ZCREATIONDATE1|ZCREATIONDATE)
            log_info "Schema: creation date = $cdate_col (legacy)" ;;
    esac
    local _snippet_select="COALESCE(ZSNIPPET, '')"
    if _col_in_list "$_ncols" 'ZATTRIBUTEDSNIPPET'; then
        _snippet_select="COALESCE(ZSNIPPET, ZATTRIBUTEDSNIPPET, '')"
    fi
    case "$mdate_col" in *[!A-Za-z0-9_]*) mdate_col="" ;; esac
    case "$cdate_col" in *[!A-Za-z0-9_]*) cdate_col="" ;; esac
    local _mdate_select="''" _cdate_select="''"
    [ -n "$mdate_col" ] && _mdate_select="COALESCE(n.$mdate_col, '')"
    [ -n "$cdate_col" ] && _cdate_select="COALESCE(n.$cdate_col, '')"
    local _pinned_select="0"
    _col_in_list "$_ncols" 'ZISPINNED' && _pinned_select="COALESCE(n.ZISPINNED, 0)"
    local _order_by="n.Z_PK"
    [ -n "$mdate_col" ] && _order_by="n.$mdate_col DESC, n.Z_PK"
    local _folderfk_select="0"
    [ -n "$NOTES_COL_FOLDERFK" ] && _folderfk_select="COALESCE(n.$NOTES_COL_FOLDERFK, 0)"
    local _folder_filter=""
    [ -n "$NOTES_COL_FOLDERFK" ] && _folder_filter="AND n.$NOTES_COL_FOLDERFK IS NOT NULL"
    sqlite3 -readonly -separator $'\x1f' "$snap" "
        SELECT n.Z_PK, $_folderfk_select,
               $(_sql_tsv_safe "n.$NOTES_COL_TITLE"),
               COALESCE(n.ZNOTEDATA, 0),
               $NOTES_LOCKED_EXPR,
               COALESCE(n.ZIDENTIFIER, ''),
               $_pinned_select,
               $_mdate_select,
               $_cdate_select,
               COALESCE(n.ZMARKEDFORDELETION, 0)
          FROM ZICCLOUDSYNCINGOBJECT n
         WHERE n.Z_ENT = $note_ent
           $_folder_filter
         ORDER BY $_order_by;
    " > "$SCRATCH_DIR/notes.tsv"
    local n_notes
    n_notes="$(_count_lines "$SCRATCH_DIR/notes.tsv")"
    local _n_disc _n_disc_ok=0
    if _n_disc="$(sqlite3 -readonly "$snap" "
        SELECT COUNT(*) FROM ZICCLOUDSYNCINGOBJECT n
         WHERE n.Z_ENT = $note_ent
           $_folder_filter;" 2>/dev/null)"; then
        case "${_n_disc:-}" in
            ''|*[!0-9]*) _n_disc_ok=0 ;;
            *) _n_disc_ok=1 ;;
        esac
    fi
    log_info "Found $n_notes $(_pluralize "$n_notes" note)"
    if [ -n "$NOTES_COL_FOLDERFK" ]; then
        local _n_orphan
        _n_orphan="$(sqlite3 -readonly "$snap" "
            SELECT COUNT(*) FROM ZICCLOUDSYNCINGOBJECT n
             WHERE n.Z_ENT = $note_ent
               AND COALESCE(n.ZMARKEDFORDELETION, 0) = 0
               AND n.$NOTES_COL_FOLDERFK IS NULL;" 2>/dev/null)"
        case "${_n_orphan:-0}" in
            ''|*[!0-9]*) : ;;
            *) [ "$_n_orphan" -gt 0 ] && \
                _disclose_excluded "$_n_orphan folder-less placeholder $(_pluralize "$_n_orphan" note)" "internal Notes stubs, not shown in Notes.app" ;;
        esac
    fi
    if [ "$n_notes" -eq 0 ]; then
        if [ "$_n_disc_ok" -eq 1 ] && [ "$_n_disc" -eq 0 ]; then
            report_empty_source "notes" "Notes"
        else
            log_warn "Notes discovery query failed or disagreed with the emitted note list — no notes could be exported."
            note_incomplete "$out_root" "Notes" \
                "the notes table is present but the export query produced no rows (query failure or schema drift) — no notes were exported"
            mark_success
            print_summary
            exit 0
        fi
    fi
    local _f_line _f_pk
    while IFS= read -r _f_line; do
        _f_pk="${_f_line%%$'\x1f'*}"
        case "$_f_pk" in ''|*[!0-9]*) continue ;; esac
        printf -v "_nf_${_f_pk}" '%s' "$_f_line"
    done < "$SCRATCH_DIR/folders.tsv"
    local _a_line _a_pk
    while IFS= read -r _a_line; do
        _a_pk="${_a_line%%$'\x1f'*}"
        case "$_a_pk" in ''|*[!0-9]*) continue ;; esac
        printf -v "_na_${_a_pk}" '%s' "$_a_line"
    done < "$SCRATCH_DIR/accounts.tsv"
    _folder_name() {
        local fpk="$1" path="" depth=0
        local row ident parent line _f_ref _ignore
        while [ -n "$fpk" ] && [ "$fpk" != "0" ] && [ "$depth" -lt 32 ]; do
            _f_ref="_nf_${fpk}"
            line="${!_f_ref:-}"
            [ -z "$line" ] && break
            IFS=$'\x1f' read -r _ignore row ident _ignore parent <<< "$line"
            case "$ident" in
                TrashFolder*|DefaultTrashFolder*) printf '__TRASH__'; return ;;
            esac
            case "$row" in 'Recently Deleted'|'') row='Notes' ;; esac
            row="${row//\//_}"; row="${row//\\/_}"; row="${row//:/_}"
            row="${row//\"/_}"; row="${row//\?/_}"; row="${row//\*/_}"
            row="${row//|/_}";  row="${row//</_}";  row="${row//>/_}"
            path="$row${path:+/$path}"
            fpk="$parent"
            depth=$((depth + 1))
        done
        [ -z "$path" ] && path="Notes"
        printf '%s' "$path"
    }
    _account_label_for_type() {
        case "$1" in
            1) printf 'iCloud' ;;
            2) printf 'Imported' ;;
            3) printf 'On My Mac' ;;
            4) printf 'Managed' ;;
            5) printf 'Exchange' ;;
            6) printf 'Yahoo' ;;
            7) printf 'AOL' ;;
            8) printf 'Google' ;;
            9) printf 'IMAP' ;;
            *) printf '' ;;
        esac
    }
    _account_name_for_folder() {
        local fpk="$1" apk="" aname="" atype="" _ignore
        local _f_ref="_nf_${fpk}"
        local _f_line="${!_f_ref:-}"
        if [ -n "$_f_line" ]; then
            IFS=$'\x1f' read -r _ignore _ignore _ignore apk _ignore <<< "$_f_line"
        fi
        [ -z "$apk" ] && apk="0"
        if [ "$apk" = "0" ]; then
            printf 'Other'
            return
        fi
        local _a_ref="_na_${apk}"
        local _acct_line="${!_a_ref:-}"
        if [ -n "$_acct_line" ]; then
            IFS=$'\x1f' read -r _ignore aname atype <<< "$_acct_line"
        fi
        if [ -z "$aname" ]; then
            aname="$(_account_label_for_type "$atype")"
        fi
        [ -z "$aname" ] && aname="Other"
        printf '%s' "$aname"
    }
    _create_output_dir "$out_root"
    local per_account="no" accounts_in_use=0
    if [ -n "$account_col" ]; then
        accounts_in_use="$(awk -F$'\x1f' '$4 != "0" && $4 != "" { print $4 }' \
            "$SCRATCH_DIR/folders.tsv" 2>/dev/null | sort -u | wc -l | tr -d ' ')"
        case "$accounts_in_use" in ''|*[!0-9]*) accounts_in_use=0 ;; esac
        [ "$accounts_in_use" -ge 2 ] && per_account="yes"
    fi
    local -a plan_paths=() plan_pks=() plan_titles=() plan_folders=() \
             plan_notedata=() plan_locked=() plan_accounts=() \
             plan_identifiers=() plan_pinned=() plan_mtime=() plan_ctime=()
    local pk fpk t1 ndpk locked nident npinned nmtime nctime ndeleted
    local rd_count=0
    local _untitled_seq=0
    while IFS=$'\x1f' read -r pk fpk t1 ndpk locked nident npinned nmtime nctime ndeleted; do
        [ -z "$pk" ] && continue
        local title="$t1"
        title="${title//\\n/ }"
        title="${title#"${title%%[![:space:]]*}"}"
        title="${title%"${title##*[![:space:]]}"}"
        local _note_untitled=0
        [ -z "$title" ] && _note_untitled=1
        local fname stitle target aname=""
        local _nfsan_ref="_nfsan_${fpk}"
        fname="${!_nfsan_ref-}"
        if [ -z "${!_nfsan_ref+x}" ]; then
            fname="$(_folder_name "$fpk")"
            if [ "$fname" != "__TRASH__" ]; then
                fname="$(printf '%s' "$fname" | awk -F/ -v OFS=/ '
                    {
                        for (i = 1; i <= NF; i++) {
                            s = $i
                            gsub(/[\/\\:?*|"<>]/, "_", s)
                            gsub(/[\001-\037\177]/, "", s)
                            sub(/^[ .]+/, "", s); sub(/[ .]+$/, "", s)
                            if (s == "") s = "Untitled"
                            $i = s
                        }
                        print
                    }')"
            fi
            printf -v "$_nfsan_ref" '%s' "$fname"
        fi
        local _note_deleted=0
        { [ "$ndeleted" = "1" ] || [ "$fname" = "__TRASH__" ]; } && _note_deleted=1
        if [ "$_note_untitled" = "1" ]; then
            _untitled_seq=$((_untitled_seq + 1))
            title="$(printf 'Note #%03d' "$_untitled_seq")"
        fi
        stitle="$(_sanitize_name "$title")"
        if [ "$_note_deleted" = "1" ]; then
            rd_count=$((rd_count + 1))
            fname="Recently Deleted"
            aname=""
            target="$out_root/Recently Deleted/$stitle.html"
        elif [ "$per_account" = "yes" ]; then
            local _nasan_ref="_nasan_${fpk}"
            if [ -z "${!_nasan_ref+x}" ]; then
                printf -v "$_nasan_ref" '%s' "$(_sanitize_name "$(_account_name_for_folder "$fpk")")"
            fi
            aname="${!_nasan_ref}"
            target="$out_root/$aname/$fname/$stitle.html"
        else
            target="$out_root/$fname/$stitle.html"
        fi
        plan_paths+=( "$target" ); plan_pks+=( "$pk" )
        plan_titles+=( "$title" ); plan_folders+=( "$fname" )
        plan_notedata+=( "$ndpk" ); plan_locked+=( "$locked" )
        plan_accounts+=( "$aname" )
        plan_identifiers+=( "$nident" ); plan_pinned+=( "$npinned" )
        plan_mtime+=( "$nmtime" ); plan_ctime+=( "$nctime" )
    done < "$SCRATCH_DIR/notes.tsv"
    [ "$rd_count" -gt 0 ] && \
        log_info "Exported $rd_count deleted $(_pluralize "$rd_count" note) to Recently Deleted/ (in your Notes Recently Deleted folder or marked for deletion) — review and discard if not needed."
    if [ -n "$attachment_ent" ]; then
        local _n_del_att
        _n_del_att="$(sqlite3 -readonly "$snap" \
            "SELECT COUNT(*) FROM ZICCLOUDSYNCINGOBJECT
              WHERE COALESCE(ZMARKEDFORDELETION, 0) != 0
                AND Z_ENT = $attachment_ent;" 2>/dev/null)"
        case "${_n_del_att:-0}" in
            ''|*[!0-9]*) : ;;
            *) [ "$_n_del_att" -gt 0 ] && \
                   log_info "$_n_del_att $(_pluralize "$_n_del_att" attachment) marked deleted in Notes were not exported (deleted attachments are filtered to keep the note-body attachment pairing correct; recover them in Notes if needed)." ;;
        esac
    fi
    [ "${#plan_pks[@]}" -eq 0 ] && { rmdir "$out_root" 2>/dev/null || true; report_empty_source "notes" "Notes"; }
    local i exported=0 locked_count=0 empty_count=0
    local via_protoc=0 via_strings=0 total_attachments=0 stub_count=0
    local via_rawcat=0
    local _decode_failed_count=0
    local att_copy_failed=0 note_write_failed=0 att_mkdir_failed=0 att_query_failed=0
    ensure_scratch
    local _notes_stubs_tsv="$SCRATCH_DIR/notes_stubs.tsv"
    : > "$_notes_stubs_tsv"
    _probe_protoc
    if [ "$HAS_PROTOC" = "yes" ]; then
        log_info "Using protoc on PATH (high-fidelity decoding)."
    elif [ "$NOTES_FETCH_PROTOC" != "1" ]; then
        log_info "Using strings extraction (--disable-protoc set; lower fidelity)."
    else
        log_info "Auto-fetching protoc from GitHub (~3 MB)..."
        if _fetch_protoc; then
            log_info "Using protoc (auto-fetched ${PROTOC_VERSION:-protoc}; high-fidelity decoding)."
        else
            log_info "Using strings extraction (protoc auto-fetch failed; lower fidelity)."
        fi
    fi
    log_info "Bulk-extracting ${#plan_pks[@]} note $(_pluralize "${#plan_pks[@]}" body bodies)..."
    if ! sqlite3 -readonly "$snap" "
        SELECT writefile('$SCRATCH_DIR/note_' || obj.Z_PK || '.bin', nd.ZDATA)
          FROM ZICCLOUDSYNCINGOBJECT obj
          JOIN ZICNOTEDATA nd ON nd.Z_PK = obj.ZNOTEDATA
         WHERE nd.ZDATA IS NOT NULL
           AND length(nd.ZDATA) > 0;
    " >/dev/null 2>&1; then
        log_warn "Bulk-extract of note bodies failed; per-note bodies may be missing."
        note_incomplete "$out_root" "Note body text" \
            "the bulk extraction of note bodies from the database failed — the per-note .html files may have empty or missing body content even though the notes themselves were emitted"
    fi
    if ! sqlite3 -readonly -separator $'\x1f' "$snap" "
        SELECT Z_PK,
               REPLACE(REPLACE($_snippet_select, char(13), ''), char(10), ' ')
          FROM ZICCLOUDSYNCINGOBJECT
         WHERE ($_snippet_select) != '';
    " > "$SCRATCH_DIR/note_snippets.tsv" 2>/dev/null; then
        log_warn "Bulk-extract of note snippets failed; decode-failed notes may lose their ZSNIPPET fallback."
        note_incomplete "$out_root" "Note snippet fallback" \
            "the bulk extraction of note ZSNIPPET summaries failed — any note whose body also failed to decode has no recoverable text and is not separately marked per-note"
    fi
    if [ -s "$SCRATCH_DIR/note_snippets.tsv" ]; then
        local _snip_pk _snip_txt
        while IFS=$'\x1f' read -r _snip_pk _snip_txt; do
            case "$_snip_pk" in ''|*[!0-9]*) continue ;; esac
            case "$_snip_txt" in
                *[$'\x01'-$'\x08'$'\x0b'$'\x0c'$'\x0e'-$'\x1f']*) continue ;;
            esac
            printf -v "_snippet_${_snip_pk}" '%s' "$_snip_txt"
        done < "$SCRATCH_DIR/note_snippets.tsv"
    fi
    log_info "Emitting per-note HTML..."
    local _pt_last=0 _pt_inline=0
    local _html_validated=0
    local _plan_total=${#plan_pks[@]}
    if [ -s "$SCRATCH_DIR/shared_notes.set" ]; then
        while IFS= read -r _shared_pk; do
            [ -n "$_shared_pk" ] && printf -v "_shared_${_shared_pk}" '1'
        done < "$SCRATCH_DIR/shared_notes.set"
    fi
    for (( i=0; i<${#plan_pks[@]}; i++ )); do
        local target="${plan_paths[$i]}" title="${plan_titles[$i]}"
        local fname="${plan_folders[$i]}" ndpk="${plan_notedata[$i]}"
        local locked="${plan_locked[$i]}" note_pk="${plan_pks[$i]}"
        local aname="${plan_accounts[$i]}"
        local nident="${plan_identifiers[$i]}" npinned="${plan_pinned[$i]}"
        local nmtime="${plan_mtime[$i]}" nctime="${plan_ctime[$i]}"
        local target_dir
        if [ -n "$aname" ]; then
            target_dir="$out_root/$aname/$fname"
        else
            target_dir="$out_root/$fname"
        fi
        if ! mkdir -p "$target_dir"; then
            log_warn "Cannot create $target_dir."
            note_incomplete "$out_root" "$title" \
                "could not write per-note HTML — mkdir of the note's folder failed"
            note_write_failed=$((note_write_failed + 1))
            continue
        fi
        if [ -e "$target" ] || [ -L "$target" ]; then
            target="$(_unique_path "$target")"
            plan_paths[$i]="$target"
        fi
        local body=""
        local _body_has_title_h1=0
        if [ "$locked" = "1" ]; then
            body="<p><em>This note is password-protected. To export its content: open Notes.app, unlock the note with its password (Notes will then re-sync the body unencrypted into the local store), then re-run this script.</em></p>"
            locked_count=$((locked_count + 1))
        elif [ "$ndpk" = "0" ] || [ -z "$ndpk" ]; then
            body="<p><em>(empty note)</em></p>"
            empty_count=$((empty_count + 1))
        else
            local blob_path="$SCRATCH_DIR/note_${note_pk}.bin"
            if [ -s "$blob_path" ]; then
                local _stem _att_rel
                _stem="${target##*/}"; _stem="${_stem%.html}"
                _att_rel="$_stem.attachments"
                local styled="" extracted="" clean="" _styled_rc=1
                if [ "$HAS_PROTOC" = "yes" ]; then
                    styled="$(_extract_note_styled_html "$blob_path" "$note_pk" "$snap" "$_att_rel")"
                    _styled_rc=$?   # function's last cmd is the
                fi
                if [ "$_styled_rc" -eq 0 ] && [ -n "$styled" ]; then
                    via_protoc=$((via_protoc + 1))
                    body="$styled"
                    _body_has_title_h1=1
                else
                    if [ "$HAS_PROTOC" = "yes" ]; then
                        extracted="$(_extract_note_text_protoc "$blob_path" "$note_pk" "$snap")"
                        [ -n "$extracted" ] && via_protoc=$((via_protoc + 1))
                    fi
                    if [ -z "$extracted" ]; then
                        extracted="$(_extract_note_text "$blob_path")"
                        if [ -n "$extracted" ]; then
                            if _is_gzipped "$blob_path"; then
                                via_strings=$((via_strings + 1))
                            else
                                via_rawcat=$((via_rawcat + 1))
                            fi
                        fi
                    fi
                    clean="$(_strip_duplicate_title "$extracted" "$title")"
                    if [ -n "$clean" ]; then
                        body="$(_html_format_body "$clean" "$_att_rel")"
                    elif [ -n "$extracted" ]; then
                        body=""
                    else
                        local _snip _snip_ref="_snippet_${note_pk}"
                        _snip="${!_snip_ref:-}"
                        if [ -n "$_snip" ]; then
                            _decode_failed_count=$((_decode_failed_count + 1))
                            body="<p><em>(text decode failed — showing ZSNIPPET fallback below)</em></p>"
                            body="$body
$(_html_format_body "$_snip" "")"
                        else
                            body="<p><em>(no extractable text — see fidelity note in script header)</em></p>"
                        fi
                        empty_count=$((empty_count + 1))
                    fi
                    local _att_section
                    _att_section="$(_emit_attachments_section "$note_pk" "$snap" "$_att_rel" "$body")"
                    if [ -n "$_att_section" ]; then
                        body="$body
$_att_section"
                    fi
                fi
                rm -f -- "$blob_path"
            else
                body="<p><em>(no body data)</em></p>"
                empty_count=$((empty_count + 1))
            fi
        fi
        local _mt_unix _ct_unix _mt_iso="" _ct_iso="" _mt_touch=""
        _mt_unix="$(_cd_ts_to_unix "$nmtime")"
        _ct_unix="$(_cd_ts_to_unix "$nctime")"
        if [ -n "$_mt_unix" ]; then
            _epoch_to_utc_iso_into "$_mt_unix" _mt_iso
            _mt_touch="$(_format_touch_t "$_mt_unix")"
        fi
        if [ -n "$_ct_unix" ]; then
            _epoch_to_utc_iso_into "$_ct_unix" _ct_iso
        fi
        local tmp
        if ! tmp="$(mktemp "$target.tmp.XXXXXX" 2>/dev/null)"; then
            log_warn "Cannot create temp file for $(basename "$target")"
            note_incomplete "$out_root" "$title" \
                "could not write per-note HTML — mktemp of the staging file failed"
            note_write_failed=$((note_write_failed + 1))
            continue
        fi
        track_output_path "$tmp"
        local _is_shared=0
        local _shared_ref="_shared_${note_pk}"
        if [ -n "${!_shared_ref+x}" ]; then
            _is_shared=1
        fi
        local _is_quicknote=0
        case "$nident" in
            SystemActivityFolder-CoreNote-QuickNote*) _is_quicknote=1 ;;
        esac
        {
            printf '<!DOCTYPE html>\n<html>\n<head>\n<meta charset="UTF-8">\n'
            printf '<title>%s</title>\n' "$(html_escape "$title")"
            [ -n "$nident" ]    && printf '<meta name="apple-notes-id" content="%s">\n' "$(html_escape "$nident")"
            [ "$npinned" = "1" ] && printf '<meta name="pinned" content="true">\n'
            [ "$_is_shared" = "1" ] && printf '<meta name="shared" content="true">\n'
            [ "$_is_quicknote" = "1" ] && printf '<meta name="quick-note" content="true">\n'
            [ -n "$_ct_iso" ]   && printf '<meta name="created" content="%s">\n' "$_ct_iso"
            [ -n "$_mt_iso" ]   && printf '<meta name="modified" content="%s">\n' "$_mt_iso"
            printf '</head>\n<body>\n'
            case "$_body_has_title_h1:$body" in
                1:'<h1>'*|1:'<h1 '*) : ;;
                *) printf '<h1>%s</h1>\n' "$(html_escape "$title")" ;;
            esac
            printf '%s\n' "$body"
            printf '</body>\n</html>\n'
        } > "$tmp"
        if ! mv -f -- "$tmp" "$target"; then
            log_warn "Failed to write $target."
            note_incomplete "$out_root" "$title" \
                "could not write per-note HTML — mv of the staging file into place failed"
            note_write_failed=$((note_write_failed + 1))
            rm -f -- "$tmp" 2>/dev/null
            continue
        fi
        _untrack_output_path "$tmp"
        _apply_touch_t "$_mt_touch" "$target"
        exported=$((exported + 1))
        if [ "$_html_validated" != "1" ]; then
            validate_html_structure "$target"
            _html_validated=1
        fi
        _progress_tick "$exported" "$_plan_total" "notes exported"
        if [ "$locked" != "1" ] && [ "$ndpk" != "0" ] && [ -n "$ndpk" ]; then
            local stem att_dir="" a_filename a_mid a_gen a_src
            local _att_dir_failed=""
            stem="${target##*/}"; stem="${stem%.html}"
            local _att_id_file="$SCRATCH_DIR/_note_att_ids.tsv"
            if ! _get_attachments_with_ids "$note_pk" "$snap" > "$_att_id_file" 2>/dev/null; then
                : > "$_att_id_file"
                att_query_failed=$((att_query_failed + 1))
            fi
            while IFS=$'\x1f' read -r a_filename a_mid a_gen; do
                [ -z "$a_filename" ] && continue
                [ -z "$a_mid" ] && continue
                is_macos_junk_path "$a_filename" && continue
                if a_src="$(_locate_attachment_file "$a_mid" "$a_filename" "$a_gen")"; then
                    [ -L "$a_src" ] && continue
                    is_macos_alias "$a_src" && continue
                    if is_icloud_stub "$a_src"; then
                        stub_count=$((stub_count + 1))
                        printf '%s\x1f%s\n' "$stem" \
                            "$(_strip_icloud_stub_name "$(basename "$a_src")")" \
                            >> "$_notes_stubs_tsv"
                        continue
                    fi
                    if [ -z "$att_dir" ]; then
                        att_dir="$target_dir/$stem.attachments"
                        if ! mkdir -p "$att_dir" 2>/dev/null; then
                            att_dir=""
                            if [ -z "$_att_dir_failed" ]; then
                                _att_dir_failed=1
                                att_mkdir_failed=$((att_mkdir_failed + 1))
                                log_warn "Cannot create attachments dir for $stem — its attachments were not exported."
                            fi
                            continue
                        fi
                    fi
                    local _dst="$att_dir/$a_filename"
                    if [ -e "$_dst" ] || [ -L "$_dst" ]; then
                        log_warn "Duplicate attachment '$a_filename' in $stem — keeping the first copy only."
                        continue
                    fi
                    if _ditto_verified "$a_src" "$_dst"; then
                        total_attachments=$((total_attachments + 1))
                        _maybe_sips_heic_sibling "$_dst" "$att_dir/${a_filename%.*}.jpg"
                    else
                        rm -f -- "$_dst" 2>/dev/null   # reap a torn partial
                        att_copy_failed=$((att_copy_failed + 1))
                        log_warn "Failed to copy attachment '$a_filename' in $stem."
                    fi
                fi
            done < "$_att_id_file"
        fi
    done
    _progress_end
    log_info "Finalising (companion files, cleanup, sanity check)..."
    if [ "$via_protoc" -gt 0 ] || [ "$via_strings" -gt 0 ] || [ "$via_rawcat" -gt 0 ]; then
        local _decode_brk="Decode breakdown: $via_protoc via protoc, $via_strings via strings-fallback"
        [ "$via_rawcat" -gt 0 ] && _decode_brk="$_decode_brk, $via_rawcat via raw-cat (verbatim legacy text)"
        log_info "$_decode_brk"
    fi
    [ "$locked_count" -gt 0 ] && log_warn "$locked_count password-protected (placeholder body)"
    [ "$empty_count" -gt 0 ] && log_info "$empty_count empty / unextractable"
    if [ "$_decode_failed_count" -gt 0 ]; then
        log_warn "$_decode_failed_count note(s) had undecodable body data — exported with Apple's ZSNIPPET summary only (see the fidelity note in the script header)"
        note_incomplete "$out_root" "Notes body decode" \
            "$_decode_failed_count note(s) had body content the export could not decode; only Apple's short preview summary was recoverable — the full note text is not in the export"
    fi
    if [ "$att_copy_failed" -gt 0 ]; then
        log_warn "$att_copy_failed note $(_pluralize "$att_copy_failed" attachment) failed to copy"
        note_incomplete "$out_root" \
            "$att_copy_failed note $(_pluralize "$att_copy_failed" attachment)" \
            "the attachment file(s) were on disk but the copy failed — the image / PDF / video content was not exported"
    fi
    if [ "$att_query_failed" -gt 0 ]; then
        log_warn "$att_query_failed $(_pluralize "$att_query_failed" note) could not be queried for attachments — any on-disk attachments were not exported"
        note_incomplete "$out_root" \
            "$att_query_failed $(_pluralize "$att_query_failed" note) — attachment lookup failed" \
            "the attachment-id query failed for these notes; any on-disk attachments (images / PDFs / videos) were not copied or referenced"
    fi
    if [ "$att_mkdir_failed" -gt 0 ]; then
        log_warn "$att_mkdir_failed $(_pluralize "$att_mkdir_failed" note) lost all attachments — could not create the attachments dir"
        note_incomplete "$out_root" \
            "$att_mkdir_failed $(_pluralize "$att_mkdir_failed" note)" \
            "the attachments directory could not be created (mkdir failed) — ALL attachments for these notes were not exported"
    fi
    local _n_parity=""
    [ "$_n_disc_ok" -eq 1 ] && _n_parity="$_n_disc"
    validate_count_parity "$_n_parity" $((exported + note_write_failed)) \
        "Note" "$out_root"
    if [ "$stub_count" -gt 0 ]; then
        {
            printf '# Sections below group by note title (attachment filenames within).\n\n'
            LC_ALL=C sort -u "$_notes_stubs_tsv" \
                | LC_ALL=C awk -F$'\x1f' '
                    $1 != prev { if (prev != "") printf "\n"; printf "[%s]\n", $1; prev=$1 }
                    { print $2 }
                  '
        } | _write_skipped_report "$out_root" "Notes attachments" \
                "$stub_count" "" \
                "disable Optimize Mac Storage system-wide, open Notes.app and let large attachments download"
    fi
    find "$out_root" -mindepth 1 -type d -empty -delete 2>/dev/null || true
    if [ "$exported" -eq 0 ]; then
        rmdir "$out_root" 2>/dev/null || true
    fi
    local _notes_have_index=0
    if [ "$exported" -gt 0 ]; then
        local _notes_index="$SCRATCH_DIR/notes_index.tsv" _ni_n=0 _ni_i _ni_rel
        : > "$_notes_index" 2>/dev/null || true
        for (( _ni_i=0; _ni_i<${#plan_paths[@]}; _ni_i++ )); do
            [ -f "${plan_paths[$_ni_i]}" ] || continue
            _ni_rel="${plan_paths[$_ni_i]#"$out_root/"}"
            printf '%s\x1f%s\x1f%s\x1f%s\x1f%s\n' \
                "$_ni_rel" "${plan_titles[$_ni_i]}" "${plan_folders[$_ni_i]}" \
                "${plan_accounts[$_ni_i]}" "${plan_pinned[$_ni_i]}" \
                >> "$_notes_index" 2>/dev/null || true
            _ni_n=$((_ni_n + 1))
        done
        if [ "$_ni_n" -gt 0 ]; then
            _notes_emit_index "$_notes_index" "$_ni_n" "$out_root" "$per_account"
            validate_html_structure "$out_root/index.html"
            [ -s "$out_root/index.html" ] && _notes_have_index=1
        fi
    fi
    local _stat="$exported $(_pluralize "$exported" note)"
    [ "$per_account" = "yes" ] && _stat="$_stat across $accounts_in_use $(_pluralize "$accounts_in_use" account)"
    [ "$_notes_have_index" -eq 1 ] && _stat="$_stat + index.html"
    [ "$total_attachments" -gt 0 ] && _stat="$_stat, $total_attachments $(_pluralize "$total_attachments" attachment) copied"
    [ "$stub_count" -gt 0 ] && _stat="$_stat, $stub_count cloud-only$(_disclosure_pointer "Notes/_skipped.txt")"
    _stat="$_stat, $(_dir_size_human "$out_root")"
    log_ok "Wrote Notes/ ($_stat)"
    mark_success
    sweep_junk_files "$out_root"
    print_summary
    if [ "$ERR_COUNT" -gt 0 ]; then exit 1; fi
    exit 0
}

_CONFIRM_AUTO_NO_RAW="${CONFIRM_AUTO_NO_SEC-<<unset>>}"
: "${CONFIRM_AUTO_NO_SEC:=10}"
case "$CONFIRM_AUTO_NO_SEC" in
    ''|*[!0-9]*) CONFIRM_AUTO_NO_SEC=10 ;;
    *)           CONFIRM_AUTO_NO_SEC=$((10#$CONFIRM_AUTO_NO_SEC))
                 [ "$CONFIRM_AUTO_NO_SEC" -lt 1 ] && CONFIRM_AUTO_NO_SEC=1 ;;
esac

[ "$CONFIRM_AUTO_NO_SEC" -gt 3600 ] && CONFIRM_AUTO_NO_SEC=10
_PASSWORDS_FILE_WAIT_RAW="${PASSWORDS_FILE_WAIT_SEC-<<unset>>}"
_PASSWORDS_GUI_WAIT_RAW="${PASSWORDS_GUI_WAIT_SEC-<<unset>>}"
: "${PASSWORDS_FILE_WAIT_SEC:=60}"
case "$PASSWORDS_FILE_WAIT_SEC" in
    ''|*[!0-9]*)        PASSWORDS_FILE_WAIT_SEC=60 ;;
    *)                  PASSWORDS_FILE_WAIT_SEC=$((10#$PASSWORDS_FILE_WAIT_SEC))
                        [ "$PASSWORDS_FILE_WAIT_SEC" -lt 1 ] && PASSWORDS_FILE_WAIT_SEC=1
                        [ "$PASSWORDS_FILE_WAIT_SEC" -gt 3600 ] && PASSWORDS_FILE_WAIT_SEC=60 ;;
esac

: "${PASSWORDS_GUI_WAIT_SEC:=10}"
case "$PASSWORDS_GUI_WAIT_SEC" in
    ''|*[!0-9]*)        PASSWORDS_GUI_WAIT_SEC=10 ;;
    *)                  PASSWORDS_GUI_WAIT_SEC=$((10#$PASSWORDS_GUI_WAIT_SEC))
                        [ "$PASSWORDS_GUI_WAIT_SEC" -lt 1 ] && PASSWORDS_GUI_WAIT_SEC=1
                        [ "$PASSWORDS_GUI_WAIT_SEC" -gt 3600 ] && PASSWORDS_GUI_WAIT_SEC=10 ;;
esac

_PASSWORDS_CLAMP_NOTICE=""
[ "$_CONFIRM_AUTO_NO_RAW"      != "<<unset>>" ] && [ "$_CONFIRM_AUTO_NO_RAW"      != "$CONFIRM_AUTO_NO_SEC"      ] && \
    _PASSWORDS_CLAMP_NOTICE="${_PASSWORDS_CLAMP_NOTICE}CONFIRM_AUTO_NO_SEC=$_CONFIRM_AUTO_NO_RAW clamped to $CONFIRM_AUTO_NO_SEC; "
[ "$_PASSWORDS_FILE_WAIT_RAW"  != "<<unset>>" ] && [ "$_PASSWORDS_FILE_WAIT_RAW"  != "$PASSWORDS_FILE_WAIT_SEC"  ] && \
    _PASSWORDS_CLAMP_NOTICE="${_PASSWORDS_CLAMP_NOTICE}PASSWORDS_FILE_WAIT_SEC=$_PASSWORDS_FILE_WAIT_RAW clamped to $PASSWORDS_FILE_WAIT_SEC; "
[ "$_PASSWORDS_GUI_WAIT_RAW" != "<<unset>>" ] && [ "$_PASSWORDS_GUI_WAIT_RAW" != "$PASSWORDS_GUI_WAIT_SEC" ] && \
    _PASSWORDS_CLAMP_NOTICE="${_PASSWORDS_CLAMP_NOTICE}PASSWORDS_GUI_WAIT_SEC=$_PASSWORDS_GUI_WAIT_RAW clamped to $PASSWORDS_GUI_WAIT_SEC; "
_PASSWORDS_CLAMP_NOTICE="${_PASSWORDS_CLAMP_NOTICE%; }"
unset _CONFIRM_AUTO_NO_RAW _PASSWORDS_FILE_WAIT_RAW _PASSWORDS_GUI_WAIT_RAW
PASSWORDS_APP="/System/Applications/Passwords.app"

_confirm_or_skip() {
    if ! ( : </dev/tty ) 2>/dev/null; then
        log_info "No TTY available — skipping passwords export (Touch ID cannot be satisfied unattended)."
        return 1
    fi
    case "${EXPORT_PASSWORDS_CONFIRM:-1}" in
        0) return 0 ;;  # explicit bypass — documented value
        1) ;;            # default: prompt
        *) log_warn "EXPORT_PASSWORDS_CONFIRM should be 0 or 1; got '$EXPORT_PASSWORDS_CONFIRM' — treating as 1 (prompt)" ;;
    esac
    { exec 9</dev/tty; } 2>/dev/null || {
        log_info "Could not open /dev/tty for the confirm prompt — skipping passwords export."
        return 1
    }
    local _ans="" _sec
    for _sec in $(LC_ALL=C seq "$CONFIRM_AUTO_NO_SEC" -1 1); do
        printf '\r  Export passwords from Passwords.app? Touch ID or login password required. [y/N] (auto-no in %ds) ' \
            "$_sec" >&2
        if IFS= read -r -t 1 -n 1 _ans <&9; then
            break
        fi
        _ans=""
    done
    exec 9<&-
    if [ -z "$_ans" ]; then
        printf '\r  Export passwords from Passwords.app? Touch ID or login password required. [y/N] — declined or auto-no (within %d s)\n' "$CONFIRM_AUTO_NO_SEC" >&2
    else
        printf '\n' >&2
    fi
    _LAST_BLANK=0
    case "$_ans" in
        y|Y|yes|YES|Yes) return 0 ;;
    esac
    return 1
}

_passwords_discover_save_dir() {
    local _v
    _v="$(defaults read com.apple.Passwords NSNavLastRootDirectory 2>/dev/null)" || return 0
    _v="${_v%%$'\n'*}"
    case "$_v" in
        /*) [ -d "$_v" ] && printf '%s' "$_v" ;;
    esac
    return 0
}

_passwords_file_is_fresh() {
    local _m
    [ -f "$1" ] || return 1
    _m="$(stat -f %m -- "$1" 2>/dev/null)" || return 1
    case "$_m" in ''|*[!0-9]*) return 1 ;; esac
    case "${_PASSWORDS_RUN_START_EPOCH:-}" in ''|*[!0-9]*) return 1 ;; esac
    [ "$_m" -ge "$_PASSWORDS_RUN_START_EPOCH" ]
}

_passwords_file_predates_run() {
    local _m
    [ -f "$1" ] || return 1
    case "${_PASSWORDS_RUN_START_EPOCH:-}" in ''|*[!0-9]*) return 1 ;; esac
    _m="$(stat -f %m -- "$1" 2>/dev/null)" || return 1
    case "$_m" in ''|*[!0-9]*) return 1 ;; esac
    [ "$_m" -lt "$_PASSWORDS_RUN_START_EPOCH" ]
}

_passwords_write_settled() {
    local _f="$1" _s1 _s2
    [ -f "$_f" ] || return 1
    _s1="$(stat -f %z -- "$_f" 2>/dev/null)" || return 1
    case "$_s1" in ''|*[!0-9]*) return 1 ;; esac
    [ "$_s1" -gt 0 ] || return 1
    sleep 0.3
    _s2="$(stat -f %z -- "$_f" 2>/dev/null)" || return 1
    case "$_s2" in ''|*[!0-9]*) return 1 ;; esac
    [ "$_s2" -gt 0 ] && [ "$_s1" = "$_s2" ]
}

_passwords_file_looks_like_export() {
    local _hdr _first_cell _commas
    [ -s "$1" ] || return 1
    _hdr="$(head -1 -- "$1" 2>/dev/null || printf '')"
    case "$_hdr" in *,*) ;; *) return 1 ;; esac
    _first_cell="${_hdr%%,*}"
    _commas="${_hdr//[!,]/}"
    [ -n "$_first_cell" ] && [ "${#_commas}" -ge 4 ]
}

_passwords_find_fresh_export_in_dir() {
    local _dir="$1" _f _had_nullglob
    [ -d "$_dir" ] || return 1
    shopt -q nullglob; _had_nullglob=$?
    shopt -s nullglob
    for _f in "$_dir"/Passwords*.csv; do
        if _passwords_file_is_fresh "$_f" && _passwords_write_settled "$_f" \
           && _passwords_file_looks_like_export "$_f"; then
            [ "$_had_nullglob" -eq 0 ] || shopt -u nullglob
            printf '%s' "$_f"
            return 0
        fi
    done
    [ "$_had_nullglob" -eq 0 ] || shopt -u nullglob
    return 1
}

_passwords_save_dirs() {
    _PW_SAVE_DIRS=( "$1" "$HOME/Documents" "$HOME/Desktop" "$HOME/Downloads" )
}

_passwords_csv_candidates() {
    _PW_CSV_CANDIDATES=( "$1/Passwords.csv" "$HOME/Documents/Passwords.csv" "$HOME/Desktop/Passwords.csv" "$HOME/Downloads/Passwords.csv" )
}

_passwords_locate_exported_csv() {
    local _out_root="$1" _loc _dyn_dir _dyn_file
    _passwords_csv_candidates "$_out_root"
    for _loc in "${_PW_CSV_CANDIDATES[@]}"; do
        if [ -f "$_loc" ] && _passwords_file_is_fresh "$_loc" && _passwords_write_settled "$_loc"; then
            printf '%s' "$_loc"
            return 0
        fi
    done
    _passwords_save_dirs "$_out_root"
    for _loc in "${_PW_SAVE_DIRS[@]}"; do
        _dyn_file="$(_passwords_find_fresh_export_in_dir "$_loc")"
        if [ -n "$_dyn_file" ]; then
            printf '%s' "$_dyn_file"
            return 0
        fi
    done
    _dyn_dir="$(_passwords_discover_save_dir)"
    if [ -n "$_dyn_dir" ]; then
        _dyn_file="$_dyn_dir/Passwords.csv"
        if [ -f "$_dyn_file" ] && _passwords_file_is_fresh "$_dyn_file" \
           && _passwords_write_settled "$_dyn_file"; then
            printf '%s' "$_dyn_file"
            return 0
        fi
        _dyn_file="$(_passwords_find_fresh_export_in_dir "$_dyn_dir")"
        if [ -n "$_dyn_file" ]; then
            printf '%s' "$_dyn_file"
            return 0
        fi
    fi
    return 1
}

_run_passwords_export() {
    _as_debug "driving Passwords.app GUI to export CSV (Touch ID prompt incoming)"
    ensure_scratch
    local _as_script="$SCRATCH_DIR/passwords_export.applescript"
    local _as_combined="$SCRATCH_DIR/passwords_as.out"
    cat > "$_as_script" <<'APPLESCRIPT'


set kSettleShort to 0.2
set kSettleLong to 0.5

on passwordsRunning()
    tell application "System Events"
        try
            return exists application process "Passwords"
        on error
            return false
        end try
    end tell
end passwordsRunning

on findSavePanelButton(_root)
    tell application "System Events"
        try
            if (class of _root) is button then
                try
                    if ((name of _root) as string) is "Save" then return _root
                end try
                try
                    if (subrole of _root) is "AXDefaultButton" then return _root
                end try
            end if
        end try

        try
            set _kids to UI elements of _root
        on error
            set _kids to {}
        end try
        repeat with _kid in _kids
            set _found to my findSavePanelButton(_kid)
            if _found is not missing value then return _found
        end repeat
    end tell
    return missing value
end findSavePanelButton

on lockAffordancePresent(_root, _depth)
    if _depth > 6 then return false
    tell application "System Events"
        try
            if (class of _root) is text field then
                try
                    if (subrole of _root) is "AXSecureTextField" then return true
                end try
            end if
            if (class of _root) is button then
                set _hay to ""
                try
                    set _hay to _hay & " " & ((name of _root) as string)
                end try
                try
                    set _hay to _hay & " " & ((description of _root) as string)
                end try
                if (_hay contains "Unlock" or _hay contains "Enter Password" or _hay contains "Use Password" or _hay contains "Enter the password" or _hay contains "Touch ID") then
                    return true
                end if
            end if
        end try
        try
            set _kids to UI elements of _root
        on error
            set _kids to {}
        end try
        repeat with _kid in _kids
            if my lockAffordancePresent(_kid, _depth + 1) then return true
        end repeat
    end tell
    return false
end lockAffordancePresent

set _guiWaitSec to 10
try
    set _guiWaitSec to (system attribute "PASSWORDS_GUI_WAIT_SEC") as integer
end try
set frontmostSec to _guiWaitSec
set unlockSec to _guiWaitSec
set savePanelSec to _guiWaitSec
set confirmSheetSec to savePanelSec * 3

tell application "Passwords" to activate
delay 1.5

tell application "System Events"
    tell process "Passwords"
        set _fmCount to 0
        set _fmAbsentStreak to 0
        repeat (frontmostSec * 2) times
            if frontmost then exit repeat
            if my passwordsRunning() then
                set _fmAbsentStreak to 0
            else
                set _fmAbsentStreak to _fmAbsentStreak + 1
                if _fmAbsentStreak ≥ 3 then
                    error "Passwords.app is no longer running — was it quit during launch? Re-run when ready."
                end if
            end if
            try
                set frontmost to true
            end try
            set _fmCount to _fmCount + 1
            if (_fmCount mod 5) is 0 then
                tell application "Passwords" to activate
            end if
            delay kSettleLong
        end repeat

        set unlocked to false
        set _exportItemSeen to false
        set _unlockAbsentStreak to 0
        repeat (unlockSec * 5) times
            if my passwordsRunning() then
                set _unlockAbsentStreak to 0
            else
                set _unlockAbsentStreak to _unlockAbsentStreak + 1
                if _unlockAbsentStreak ≥ 15 then
                    error "Passwords.app is no longer running — was it quit before the vault was unlocked? Re-run when ready."
                end if
            end if
            try
                set fileMenu to missing value
                try
                    set fileMenu to menu "File" of menu bar 1
                end try
                if fileMenu is missing value then
                    try
                        set fileMenu to menu 1 of (menu bar item 2 of menu bar 1)
                    end try
                end if
                if fileMenu is not missing value then
                    repeat with mi in (every menu item of fileMenu)
                        try
                            set _nm to (name of mi) as string
                            if (_nm starts with "Export All" or _nm starts with "Export" or _nm starts with "Esporta" or _nm starts with "Exporter" or _nm starts with "Exportar" or _nm starts with "Exportieren" or _nm starts with "Exporteren" or _nm starts with "Exportera" or _nm starts with "Eksport" or _nm starts with "Экспорт" or _nm starts with "导出" or _nm starts with "匯出" or _nm starts with "내보내기" or _nm starts with "書き出") then
                                set _exportItemSeen to true
                                if (enabled of mi) is true then
                                    set unlocked to true
                                    exit repeat
                                end if
                            end if
                        end try
                    end repeat
                end if
            end try
            if unlocked then exit repeat
            delay kSettleShort
        end repeat
        if not unlocked then
            set _lockSeen to false
            try
                repeat with _wi from 1 to (count of windows)
                    if my lockAffordancePresent(window _wi, 0) then
                        set _lockSeen to true
                        exit repeat
                    end if
                end repeat
            end try
            if _lockSeen then
                error "Passwords.app vault is still locked after " & unlockSec & " s. Unlock the vault and re-run."
            else if _exportItemSeen then
                error "DOWNPOUR_EMPTY_VAULT: Passwords vault is unlocked but the Export menu item is disabled — no saved passwords to export."
            else
                error "Passwords.app vault is still locked after " & unlockSec & " s, or the Export menu item is missing. Unlock the vault and re-run."
            end if
        end if

        delay 0.4

        set exportClicked to false
        try
            click menu item "Export All Passwords to File…" of menu "File" of menu bar 1
            set exportClicked to true
        end try
        if not exportClicked then
            try
                set fileMenu to menu "File" of menu bar 1
                repeat with mi in (every menu item of fileMenu)
                    try
                        if (name of mi) starts with "Export All" then
                            click mi
                            set exportClicked to true
                            exit repeat
                        end if
                    end try
                end repeat
            end try
        end if
        if not exportClicked then
            try
                set fileMI to missing value
                try
                    set fileMI to menu bar item 2 of menu bar 1
                end try
                if fileMI is not missing value then
                    set fileMenu to menu 1 of fileMI
                    set _items to (every menu item of fileMenu)
                    set _n to count of _items
                    set _lastEllipsis to missing value
                    repeat with _j from _n to 1 by -1
                        try
                            set _mi to item _j of _items
                            if (enabled of _mi) is true then
                                set _nm to (name of _mi) as string
                                if (_nm ends with "…" or _nm ends with "...") then
                                    if _lastEllipsis is missing value then
                                        set _lastEllipsis to _mi
                                    end if
                                    if (_nm contains "Export" or _nm contains "Esporta" or _nm contains "Exporter" or _nm contains "Exportar" or _nm contains "Exportieren" or _nm contains "Exporteren" or _nm contains "Exportera" or _nm contains "Eksport" or _nm contains "Экспорт" or _nm contains "导出" or _nm contains "匯出" or _nm contains "내보내기" or _nm contains "書き出") then
                                        click _mi
                                        set exportClicked to true
                                        exit repeat
                                    end if
                                end if
                            end if
                        end try
                    end repeat
                    if (not exportClicked) and _lastEllipsis is not missing value then
                        try
                            click _lastEllipsis
                            set exportClicked to true
                        end try
                    end if
                end if
            end try
        end if
        if not exportClicked then
            error "Could not find an 'Export All Passwords' menu item under File."
        end if

    end tell
end tell

tell application "System Events"
    tell process "Passwords"
        set sheetClicked to false
        repeat (confirmSheetSec * 5) times
            try
                click button "Export Passwords" of sheet 1 of window 1
                set sheetClicked to true
                exit repeat
            end try
            if not sheetClicked then
                try
                    set _btns to buttons of sheet 1 of window 1
                    repeat with _b in _btns
                        try
                            if (name of _b) starts with "Export Passwords" then
                                if (enabled of _b) is true then
                                    click _b
                                    set sheetClicked to true
                                    exit repeat
                                end if
                            end if
                        end try
                    end repeat
                    if sheetClicked then exit repeat
                end try
            end if
            try
                if (exists text field 1 of sheet 1 of window 1) then exit repeat
            end try
            if not (my passwordsRunning()) then exit repeat
            delay kSettleShort
        end repeat
    end tell
end tell

delay kSettleShort
tell application "System Events"
    tell process "Passwords"
        set saveBtn to missing value
        set _attempts to 0
        set _spAbsentStreak to 0
        set _savePanelSeen to false
        set _manualSaveLikely to false
        repeat (savePanelSec * 5) times
            set _attempts to _attempts + 1
            if my passwordsRunning() then
                set _spAbsentStreak to 0
            else
                set _spAbsentStreak to _spAbsentStreak + 1
                if _spAbsentStreak ≥ 6 then
                    error "Passwords.app is no longer running — was it quit before the Save panel appeared? Re-run when ready."
                end if
            end if
            try
                set wincount to count of windows
                repeat with i from 1 to wincount
                    try
                        set w to window i
                        set sheetCount to count of sheets of w
                        repeat with si from 1 to sheetCount
                            set _savePanelSeen to true
                            set saveBtn to my findSavePanelButton(sheet si of w)
                            if saveBtn is not missing value then exit repeat
                        end repeat
                    end try
                    if saveBtn is not missing value then exit repeat
                end repeat
            end try
            if saveBtn is not missing value then exit repeat
            if _savePanelSeen then
                try
                    if not (exists sheet 1 of window 1) then
                        set _manualSaveLikely to true
                        exit repeat
                    end if
                end try
            end if
            delay kSettleShort
        end repeat
        if saveBtn is not missing value then
            log "Auto-click Save: found after " & _attempts & " attempt(s)"
            delay 0.15
            try
                if not (exists sheet 1 of window 1) then
                    set _manualSaveLikely to true
                    set saveBtn to missing value
                end if
            end try
        end if
        if saveBtn is not missing value then
            set _submitDone to false
            try
                with timeout of 2 seconds
                    click saveBtn
                end timeout
                set _submitDone to true
                log "Auto-click Save: clicked (strategy 1: AX click)"
            on error errMsg
                log "Auto-click Save: AX click failed - " & errMsg
                try
                    if not (exists sheet 1 of window 1) then
                        set _manualSaveLikely to true
                    end if
                end try
            end try
            if (not _submitDone) and (not _manualSaveLikely) then
                try
                    with timeout of 2 seconds
                        keystroke return
                    end timeout
                    set _submitDone to true
                    log "Auto-click Save: submitted (strategy 2: keystroke return)"
                on error
                    try
                        if not (exists sheet 1 of window 1) then
                            set _manualSaveLikely to true
                        end if
                    end try
                end try
            end if
            if (not _submitDone) and (not _manualSaveLikely) then
                try
                    with timeout of 2 seconds
                        key code 36
                    end timeout
                    set _submitDone to true
                    log "Auto-click Save: submitted (strategy 3: key code 36)"
                on error
                    try
                        if not (exists sheet 1 of window 1) then
                            set _manualSaveLikely to true
                        end if
                    end try
                end try
            end if
            if (not _submitDone) and (not _manualSaveLikely) then
                try
                    with timeout of 2 seconds
                        key code 76
                    end timeout
                    set _submitDone to true
                    log "Auto-click Save: submitted (strategy 4: keypad Enter)"
                on error
                    try
                        if not (exists sheet 1 of window 1) then
                            set _manualSaveLikely to true
                        end if
                    end try
                end try
            end if
            if _manualSaveLikely then
                log "Auto-click Save: panel disappeared during submit; assuming user clicked Save"
            else if not _submitDone then
                log "Auto-click Save: all 4 submit strategies failed"
            end if
        else if _manualSaveLikely then
            log "Auto-click Save: panel disappeared after being seen; assuming user clicked Save"
        else
            log "Auto-click Save: not found after " & _attempts & " attempt(s) (" & savePanelSec & " s budget exhausted)"
        end if
    end tell
end tell
APPLESCRIPT
    local _passwords_ceiling_s
    _passwords_ceiling_s=$(( PASSWORDS_GUI_WAIT_SEC * 3 + PASSWORDS_FILE_WAIT_SEC + 120 ))
    PASSWORDS_GUI_WAIT_SEC="$PASSWORDS_GUI_WAIT_SEC" \
    osascript "$_as_script" >"$_as_combined" 2>&1 &
    local _as_pid=$!
    CHILD_PIDS+=( "$_as_pid" )
    printf '%s' "$_as_pid" > "$SCRATCH_DIR/passwords_as.pid" 2>/dev/null || true
    local _as_elapsed=0 _as_ceiling_hit=0
    while kill -0 "$_as_pid" 2>/dev/null; do
        sleep 1
        _as_elapsed=$((_as_elapsed + 1))
        if [ "$_as_elapsed" -ge "$_passwords_ceiling_s" ]; then
            _as_ceiling_hit=1
            _kill_with_grace "$_as_pid"
            break
        fi
    done
    wait "$_as_pid" 2>/dev/null
    local _as_rc=$?
    rm -f -- "$SCRATCH_DIR/passwords_as.pid" 2>/dev/null || true
    local _cp _cp_new=()
    for _cp in "${CHILD_PIDS[@]+"${CHILD_PIDS[@]}"}"; do
        [ "$_cp" = "$_as_pid" ] && continue
        _cp_new+=( "$_cp" )
    done
    CHILD_PIDS=( "${_cp_new[@]+"${_cp_new[@]}"}" )
    [ -f "$_as_combined" ] && cat "$_as_combined"
    if [ "$_as_ceiling_hit" -eq 1 ]; then
        printf 'AppleScript driver killed after %ds wallclock ceiling — the Passwords.app AX bridge wedged.\n' \
            "$_passwords_ceiling_s" >&2
    fi
    return "$_as_rc"
}

_PASSWORDS_LAUNCHED_BY_US=0

_PASSWORDS_STASH=()
_PASSWORDS_PREF_HAD_VALUE=0
_PASSWORDS_PREF_ORIGINAL=""
_PASSWORDS_PREF_WRITTEN=0
_PASSWORDS_PREF_RESTORED=0

_PASSWORDS_CANDIDATES=()
_PASSWORDS_FINAL_PATH=""
_PASSWORDS_COMMITTED=0
_PASSWORDS_PURGE_ARMED=0

_purge_orphaned_password_csvs() {
    [ "${_PASSWORDS_PURGE_ARMED:-0}" = "1" ] || return 0
    local _cand _seen_inodes="" _cand_inode
    for _cand in "${_PASSWORDS_CANDIDATES[@]+"${_PASSWORDS_CANDIDATES[@]}"}"; do
        [ "$_cand" = "$_PASSWORDS_FINAL_PATH" ] && continue
        [ -f "$_cand" ] || continue
        _cand_inode="$(stat -f '%d:%i' -- "$_cand" 2>/dev/null)"
        if [ -n "$_cand_inode" ]; then
            case " $_seen_inodes " in
                *" $_cand_inode "*) continue ;;
            esac
            _seen_inodes="$_seen_inodes $_cand_inode"
        fi
        if _passwords_file_predates_run "$_cand"; then
            log_warn "Passwords: left a pre-existing plaintext CSV untouched at $_cand — it predates this run (a failed pre-run stash likely left it in place). downpour did not create it and will not secure-erase it; move or shred it yourself if you no longer want it."
            continue
        fi
        if rm -P -f -- "$_cand" 2>/dev/null; then
            continue
        fi
        if rm -f -- "$_cand" 2>/dev/null; then
            log_warn "Passwords: secure-rm failed at $_cand; fell back to plain rm (plaintext bytes may be forensically recoverable)"
        else
            log_warn "Passwords: COULD NOT REMOVE orphaned plaintext at $_cand — manually shred this file."
        fi
    done
}

_restore_passwords_stash() {
    local _entry _stash _orig
    for _entry in "${_PASSWORDS_STASH[@]+"${_PASSWORDS_STASH[@]}"}"; do
        _stash="${_entry%%$'\x1f'*}"
        _orig="${_entry#*$'\x1f'}"
        if [ -f "$_stash" ] && [ -f "$_orig" ]; then
            rm -P -f -- "$_orig" 2>/dev/null || rm -f -- "$_orig" 2>/dev/null || true
        fi
        if [ -f "$_stash" ] && [ ! -e "$_orig" ]; then
            mv -f -- "$_stash" "$_orig" 2>/dev/null \
                || log_warn "Passwords: could not restore your pre-existing CSV to $_orig — it is at $_stash; move it back by hand."
        fi
    done
    _PASSWORDS_STASH=()
}

_restore_passwords_pref() {
    _restore_defaults_pref _PASSWORDS com.apple.Passwords NSNavLastRootDirectory
}

passwords_leaf_cleanup_hook() {
    quit_app_iff_we_launched_it Passwords _PASSWORDS_LAUNCHED_BY_US
    _purge_orphaned_password_csvs
    if [ "${_PASSWORDS_COMMITTED:-0}" != "1" ] \
       && [ -n "$_PASSWORDS_FINAL_PATH" ] \
       && [ -f "$_PASSWORDS_FINAL_PATH" ]; then
        rm -P -f -- "$_PASSWORDS_FINAL_PATH" 2>/dev/null \
            || rm -f -- "$_PASSWORDS_FINAL_PATH" 2>/dev/null || true
    fi
    if [ -n "${SCRATCH_DIR:-}" ] && [ -s "$SCRATCH_DIR/passwords_as.pid" ]; then
        local _as_orphan
        _as_orphan="$(cat "$SCRATCH_DIR/passwords_as.pid" 2>/dev/null)"
        case "$_as_orphan" in
            ''|*[!0-9]*) : ;;
            *) kill -0 "$_as_orphan" 2>/dev/null && _kill_with_grace "$_as_orphan" ;;
        esac
    fi
    _restore_passwords_stash
    _restore_passwords_pref
}

passwords_main() {
    maybe_show_help "$@"
    _announce_step "Passwords export"
    check_dependencies
    [ -n "${_PASSWORDS_CLAMP_NOTICE:-}" ] && log_warn "Passwords env-knob clamps: $_PASSWORDS_CLAMP_NOTICE"
    local out_arg out_dir
    out_arg="$(_parse_output_folder_arg "$@")" || exit 1
    out_dir="$(resolve_output_dir "$out_arg")" || exit 1
    _announce_output_dir "Passwords"
    if [ ! -d "$PASSWORDS_APP" ]; then
        report_no_source "Passwords" "not installed" "$PASSWORDS_APP"
    fi
    local out_root="$out_dir/Passwords"
    require_no_collision "$out_root"
    local final_path="$out_root/Passwords.csv"
    _PASSWORDS_FINAL_PATH="$final_path"
    _passwords_csv_candidates "$out_root"
    _PASSWORDS_CANDIDATES=( "${_PW_CSV_CANDIDATES[@]}" )
    if ! _confirm_or_skip; then
        log_info "Skipping passwords export at user request — nothing to do."
        _flag_no_content
        mark_success
        print_summary
        exit 0
    fi
    log_info "Checking Accessibility permission..."
    if ! require_accessibility; then
        ensure_scratch
        note_incomplete "$out_root" "Passwords" \
            "Accessibility permission was not granted — Passwords export drives the export menu and save panel through it; grant it in System Settings > Privacy & Security > Accessibility, then re-run"
        mark_success
        print_summary
        exit 0
    fi
    _create_output_dir "$out_root"
    _PASSWORDS_PREF_HAD_VALUE=0
    _PASSWORDS_PREF_ORIGINAL=""
    _save_defaults_pref _PASSWORDS com.apple.Passwords NSNavLastRootDirectory "$out_root"
    _PASSWORDS_STASH=()
    local _save_loc _stash_to
    for _save_loc in \
        "$HOME/Documents/Passwords.csv" \
        "$HOME/Desktop/Passwords.csv" \
        "$HOME/Downloads/Passwords.csv"; do
        if [ -f "$_save_loc" ]; then
            _stash_to="$(mktemp -u "${_save_loc}.preexisting.XXXXXX")" \
                || { log_warn "Could not allocate stash name for $_save_loc — skipping."; continue; }
            _PASSWORDS_STASH+=( "$_stash_to"$'\x1f'"$_save_loc" )
            if ! mv -n -- "$_save_loc" "$_stash_to" 2>/dev/null \
                || [ ! -f "$_stash_to" ] || [ -e "$_save_loc" ]; then
                if [ "${#_PASSWORDS_STASH[@]}" -gt 0 ]; then
                    _PASSWORDS_STASH=( "${_PASSWORDS_STASH[@]:0:$((${#_PASSWORDS_STASH[@]}-1))}" )
                fi
                if [ -f "$_stash_to" ] && [ -e "$_save_loc" ]; then
                    log_warn "Stash target $_stash_to was created during the race window — not stashing $_save_loc."
                elif [ -f "$_stash_to" ] && [ ! -e "$_save_loc" ]; then
                    if mv -n -- "$_stash_to" "$_save_loc" 2>/dev/null \
                       && [ -f "$_save_loc" ] && [ ! -e "$_stash_to" ]; then
                        log_warn "Could not stash $_save_loc — restored it from the partial stash; Save panel may prompt to replace."
                    else
                        log_warn "Could not stash $_save_loc and could not restore it — it may be at $_stash_to."
                    fi
                else
                    log_warn "Could not stash $_save_loc — Save panel may prompt to replace; export may fail."
                fi
            fi
        fi
    done
    _ax_os_check "Passwords export"
    log_info "Source: Passwords.app (via AppleScript)"
    log_info "Launching Passwords.app — macOS will ask for authentication:"
    log_info "  • Unlock the vault — Touch ID or Mac password (only if locked)"
    log_info "  • Authorise the export — Touch ID or Mac password"
    log_info "  • Authorise the file write — Mac password (Touch ID won't substitute)"
    log_info "The script auto-clicks Save itself; default save location is pre-set to the export folder. Up to ${PASSWORDS_FILE_WAIT_SEC}s to finish."
    _snapshot_app_launch Passwords _PASSWORDS_LAUNCHED_BY_US
    _PASSWORDS_PURGE_ARMED=1
    _PASSWORDS_RUN_START_EPOCH="$(date +%s)"
    open -a "Passwords" 2>/dev/null || true
    ensure_scratch
    local ascript_out ascript_rc _as_out_file _driver_pid _driver_waited _driver_file_won _driver_pidfile_pid
    local _exported_path="" _loc _waited=0 _dyn_dir _dyn_file
    _as_out_file="$SCRATCH_DIR/passwords_driver.out"
    local _pw_attempt=0 _pw_max=2
    while [ "$_pw_attempt" -lt "$_pw_max" ]; do
        _pw_attempt=$((_pw_attempt + 1))
        _exported_path=""
        _run_passwords_export >"$_as_out_file" 2>&1 &
        _driver_pid=$!
        CHILD_PIDS+=( "$_driver_pid" )
        ascript_rc=0
        _driver_waited=0
        _driver_file_won=0
        while kill -0 "$_driver_pid" 2>/dev/null; do
            _exported_path="$(_passwords_locate_exported_csv "$out_root")"
            if [ -n "$_exported_path" ]; then
                _driver_file_won=1
                [ "$_exported_path" = "$final_path" ] || _PASSWORDS_CANDIDATES+=( "$_exported_path" )
                log_info "Passwords.csv appeared while the GUI driver was still running — stopping the AppleScript driver and continuing."
                _driver_pidfile_pid=""
                if [ -f "$SCRATCH_DIR/passwords_as.pid" ]; then
                    _driver_pidfile_pid="$(head -1 "$SCRATCH_DIR/passwords_as.pid" 2>/dev/null || printf '')"
                fi
                case "$_driver_pidfile_pid" in
                    ''|*[!0-9]*) ;;
                    *) _kill_with_grace "$_driver_pidfile_pid" ;;
                esac
                _kill_with_grace "$_driver_pid"
                break
            fi
            sleep 1
            _driver_waited=$((_driver_waited + 1))
            if [ $((_driver_waited % 30)) -eq 0 ]; then
                log_info "... still waiting (${_driver_waited}s) — complete the auth prompts to proceed"
            fi
        done
        wait "$_driver_pid" 2>/dev/null
        ascript_rc=$?
        rm -f -- "$SCRATCH_DIR/passwords_as.pid" 2>/dev/null || true
        local _cp _cp_new=()
        for _cp in "${CHILD_PIDS[@]+"${CHILD_PIDS[@]}"}"; do
            [ "$_cp" = "$_driver_pid" ] && continue
            _cp_new+=( "$_cp" )
        done
        CHILD_PIDS=( "${_cp_new[@]+"${_cp_new[@]}"}" )
        ascript_out=""
        [ -f "$_as_out_file" ] && ascript_out="$(cat "$_as_out_file")"
        if [ "$_driver_file_won" -eq 1 ]; then
            ascript_rc=0
        elif [ "$ascript_rc" -ne 0 ]; then
            _exported_path="$(_passwords_locate_exported_csv "$out_root")"
            if [ -n "$_exported_path" ]; then
                [ "$_exported_path" = "$final_path" ] || _PASSWORDS_CANDIDATES+=( "$_exported_path" )
                log_info "Passwords.csv appeared even though the GUI driver exited non-zero — continuing with the exported file."
                ascript_rc=0
            fi
        fi
        [ "$ascript_rc" -eq 0 ] && break
        case "$ascript_out" in
            *DOWNPOUR_EMPTY_VAULT*)
                break
                ;;
            *"vault is still locked"*)
                log_info "Passwords export: the Export menu never became available (vault still locked) — not retrying."
                break
                ;;
        esac
        if [ "$_pw_attempt" -lt "$_pw_max" ] && pgrep -x Passwords >/dev/null 2>&1; then
            log_warn "Passwords export attempt $_pw_attempt failed (rc=$ascript_rc) — re-activating Passwords and retrying once (you may be prompted to authenticate again)."
            osascript -e 'with timeout of 5 seconds' \
                      -e 'tell application "Passwords" to activate' \
                      -e 'end timeout' >/dev/null 2>&1 || true
            sleep 1
        else
            break
        fi
    done
    if [ -z "$_exported_path" ]; then
        case "$ascript_out" in
            *DOWNPOUR_EMPTY_VAULT*)
                log_info "Passwords vault is unlocked but the Export menu is disabled — no saved passwords in the vault."
                rmdir "$out_root" 2>/dev/null || true
                _untrack_output_path "$out_root"
                report_empty_source "passwords"
                ;;
        esac
    fi
    if [ "$ascript_rc" -ne 0 ]; then
        log_err "Passwords export failed (osascript rc=$ascript_rc)"
        if [ -n "$ascript_out" ]; then
            local _line _dn=0
            while IFS= read -r _line; do
                [ -n "$_line" ] || continue
                _dn=$((_dn + 1))
                if [ "$_dn" -gt 12 ]; then
                    log_info "  (diagnostic output truncated)"
                    break
                fi
                log_info "  $_line"
            done <<EOF_DIAG
$ascript_out
EOF_DIAG
        fi
        log_info "Common causes:"
        log_info "  • Authentication canceled at the Touch ID / password prompt, or an auth prompt timed out"
        log_info "  • Vault still locked at the export prompt — unlock Passwords (Touch ID / password) before the unlock budget elapses, then re-run (raise PASSWORDS_GUI_WAIT_SEC for a slower unlock). An empty vault, by contrast, is now reported as a clean 'no passwords to export', not this failure."
        log_info "  • Accessibility not granted to your terminal"
        log_info "  • Passwords.app menu / button wording changed on a non-English macOS install (please report — the failure message above lists the buttons we found)"
        exit 1
    fi
    if [ -n "$ascript_out" ]; then
        local _line _pn=0
        while IFS= read -r _line; do
            if [ -n "${DOWNPOUR_PROBE_UI:-}" ]; then
                [ -n "$_line" ] || continue
                _pn=$((_pn + 1))
                if [ "$_pn" -gt 12 ]; then
                    log_info "  (probe-ui: driver output truncated)"
                    break
                fi
                log_info "  probe-ui: $_line"
                continue
            fi
            case "$_line" in
                *"Auto-click Save:"*) log_info "$_line" ;;
            esac
        done <<EOF_LOG
$ascript_out
EOF_LOG
    fi
    _passwords_csv_candidates "$out_root"
    local _candidates=( "${_PW_CSV_CANDIDATES[@]}" )
    _passwords_save_dirs "$out_root"
    local _wait_budget="$PASSWORDS_FILE_WAIT_SEC" _passwords_gone=0 _gone_streak=0
    log_info "Waiting for Passwords.csv to appear (complete the auth prompts as they appear)..."
    while [ "$_waited" -lt "$_wait_budget" ]; do
        [ -n "$_exported_path" ] && break
        for _loc in "${_candidates[@]}"; do
            if [ -f "$_loc" ] && _passwords_file_is_fresh "$_loc" && _passwords_write_settled "$_loc"; then
                _exported_path="$_loc"
                break 2
            fi
        done
        for _loc in "${_PW_SAVE_DIRS[@]}"; do
            _dyn_file="$(_passwords_find_fresh_export_in_dir "$_loc")"
            if [ -n "$_dyn_file" ]; then
                _PASSWORDS_CANDIDATES+=( "$_dyn_file" )
                _exported_path="$_dyn_file"
                break 2
            fi
        done
        _dyn_dir="$(_passwords_discover_save_dir)"
        if [ -n "$_dyn_dir" ]; then
            _dyn_file="$_dyn_dir/Passwords.csv"
            if [ -f "$_dyn_file" ] && _passwords_file_is_fresh "$_dyn_file" \
               && _passwords_write_settled "$_dyn_file"; then
                _PASSWORDS_CANDIDATES+=( "$_dyn_file" )
                _exported_path="$_dyn_file"
                break
            fi
            _dyn_file="$(_passwords_find_fresh_export_in_dir "$_dyn_dir")"
            if [ -n "$_dyn_file" ]; then
                _PASSWORDS_CANDIDATES+=( "$_dyn_file" )
                _exported_path="$_dyn_file"
                break
            fi
        fi
        if pgrep -x Passwords >/dev/null 2>&1; then
            _gone_streak=0
        else
            _gone_streak=$((_gone_streak + 1))
            if [ "$_gone_streak" -ge 3 ]; then
                _passwords_gone=1
                break
            fi
        fi
        sleep 1
        _waited=$((_waited + 1))
        if [ $((_waited % 30)) -eq 0 ] && [ "$_waited" -lt "$_wait_budget" ]; then
            log_info "... still waiting (${_waited}s of ${_wait_budget}s) — complete the auth prompts to proceed"
        fi
    done
    if [ -z "$_exported_path" ]; then
        if [ "$_passwords_gone" -eq 1 ]; then
            die "Passwords.app is no longer running — the export was likely cancelled."
        fi
        die "Passwords.csv did not appear within ${_wait_budget}s — export was likely canceled. (If you saved it to a custom folder, we also checked the Save panel's last-used location and a fresh Passwords.csv wasn't found there either; move it into $out_root and it'll be picked up on the next run, or re-run and let the export auto-save.)"
    fi
    if [ ! -s "$_exported_path" ]; then
        rm -f -- "$_exported_path" 2>/dev/null
        die "Passwords.csv landed at $_exported_path but is 0 bytes — likely canceled mid-save; no export produced"
    fi
    if [ "${_PASSWORDS_LAUNCHED_BY_US:-0}" = "1" ]; then
        osascript -e 'with timeout of 15 seconds' \
                  -e 'tell application "Passwords" to quit' \
                  -e 'end timeout' >/dev/null 2>&1
    fi
    if [ "$_exported_path" = "$out_root/Passwords.csv" ]; then
        log_info "Picked up exported file from the export folder (defaults-write took effect)"
    else
        log_info "Picked up exported file from $_exported_path"
    fi
    log_info "Validating CSV header + finalising Passwords.csv..."
    local _hdr
    _hdr="$(head -1 -- "$_exported_path" 2>/dev/null || printf '')"
    case "$_hdr" in
        *,*) ;;  # has at least one comma — possible CSV
        *)
            log_warn "Exported file at $_exported_path does not look like a Passwords export (no comma on header row)"
            _hdr="" ;;
    esac
    if [ -n "$_hdr" ]; then
        local _first_cell _commas
        _first_cell="${_hdr%%,*}"
        _commas="${_hdr//[!,]/}"
        if [ -z "$_first_cell" ] || [ "${#_commas}" -lt 4 ]; then
            log_warn "Exported file at $_exported_path does not look like a Passwords export (header is not a ≥5-column CSV row)"
        fi
    fi
    if [ "$_exported_path" != "$final_path" ]; then
        if ! mv -f -- "$_exported_path" "$final_path"; then
            die "Cannot move $_exported_path to $final_path"
        fi
    fi
    _PASSWORDS_COMMITTED=1
    _PASSWORDS_PURGE_ARMED=0
    _restore_passwords_stash
    _restore_passwords_pref
    local _count
    _count="$(awk '
        { line = $0
          for (i = 1; i <= length(line); i++)
              if (substr(line, i, 1) == "\"") inq = !inq
          if (inq == 0) rec++ }
        END { c = rec - 1; if (c < 0) c = 0; print c }
    ' "$final_path" 2>/dev/null)"
    case "$_count" in
        ''|*[!0-9]*) _count=0 ;;
    esac
    log_ok "Wrote Passwords/ ($_count $(_pluralize "$_count" password), $(_dir_size_human "$out_root"))"
    log_info "Plaintext file — keep on encrypted volume only; do not sync to cloud."
    log_info "Note: passkeys and Wi-Fi passwords are NOT in Apple's Passwords.app CSV export."
    mark_success
    sweep_junk_files "$out_root"
    quit_app_iff_we_launched_it Passwords _PASSWORDS_LAUNCHED_BY_US
    print_summary
    if [ "$ERR_COUNT" -gt 0 ]; then exit 1; fi
    exit 0
}

_photos_discover_system_library() {
    _lib_path=""
    _lib_source=""
    local raw lib_path
    if [ -n "${PHOTO_LIBRARY_SYSTEM_PATH:-}" ]; then
        lib_path="$(_expand_tilde "$PHOTO_LIBRARY_SYSTEM_PATH")"
        if [ -d "$lib_path" ] && [ -f "$lib_path/database/Photos.sqlite" ]; then
            _lib_path="$lib_path"; _lib_source="env PHOTO_LIBRARY_SYSTEM_PATH"
            return 0
        fi
        log_warn "PHOTO_LIBRARY_SYSTEM_PATH set but not a valid library ($lib_path) — using discovery."
    fi
    raw="$(defaults read com.apple.Photos SystemLibraryPath 2>/dev/null || true)"
    if [ -n "$raw" ]; then
        lib_path="$(_expand_tilde "$raw")"
        if [ -d "$lib_path" ] && [ -f "$lib_path/database/Photos.sqlite" ]; then
            _lib_path="$lib_path"
            _lib_source="defaults com.apple.Photos SystemLibraryPath"
            return 0
        fi
    fi
    raw="$(defaults read com.apple.cloudphotod LibraryPath 2>/dev/null || true)"
    if [ -n "$raw" ]; then
        lib_path="$(_expand_tilde "$raw")"
        if [ -d "$lib_path" ] && [ -f "$lib_path/database/Photos.sqlite" ]; then
            _lib_path="$lib_path"
            _lib_source="defaults com.apple.cloudphotod LibraryPath"
            return 0
        fi
    fi
    raw="$(defaults read com.apple.Photos LibraryLocation 2>/dev/null || true)"
    if [ -n "$raw" ]; then
        lib_path="$(_expand_tilde "$raw")"
        if [ -d "$lib_path" ] && [ -f "$lib_path/database/Photos.sqlite" ]; then
            _lib_path="$lib_path"
            _lib_source="defaults com.apple.Photos LibraryLocation"
            return 0
        fi
    fi
    lib_path="$HOME/Pictures/Photos Library.photoslibrary"
    if [ -d "$lib_path" ] && [ -f "$lib_path/database/Photos.sqlite" ]; then
        _lib_path="$lib_path"
        _lib_source="default location (~/Pictures/Photos Library.photoslibrary)"
        return 0
    fi
    return 1
}

_discover_all_libraries() {
    local depth="${PHOTOS_DISCOVERY_DEPTH:-4}"
    local -a roots=( "$HOME/Pictures" )
    local r p
    {
        for r in "${roots[@]}"; do
            [ -d "$r" ] || continue
            while IFS= read -r -d '' p; do
                [ -f "$p/database/Photos.sqlite" ] || continue
                printf '%s\0' "$p"
            done < <(find "$r" -maxdepth "$depth" -type d -name '*.photoslibrary' -print0 2>/dev/null)
        done
    } | sort -uz
}

photos__skip_handler() {
    [ "${_SKIP_HANDLER_RUNNING:-0}" = "1" ] && return 0
    _SKIP_HANDLER_RUNNING=1
    trap '' USR1
    _SKIP_REQUESTED=1
    _SKIP_REQUESTED_GLOBAL=1
    log_warn "Skip requested — skipping the current operation."
    trap _skip_handler USR1 2>/dev/null || true
    _SKIP_HANDLER_RUNNING=0
}

_PHOTOS_PRE_RUNNING=0
pgrep -x Photos >/dev/null 2>&1 && _PHOTOS_PRE_RUNNING=1
_PHOTOS_LAUNCHED_BY_US=0

photos_leaf_cleanup_hook() {
    timemachine_resume
    if [ "${_PHOTOS_PRE_RUNNING:-0}" != "1" ] && pgrep -x Photos >/dev/null 2>&1; then
        _PHOTOS_LAUNCHED_BY_US=1
        quit_app_iff_we_launched_it Photos _PHOTOS_LAUNCHED_BY_US
    fi
}

photos_main() {
    maybe_show_help "$@"
    _announce_step "Photos export"
    check_dependencies
    _PHOTOS_PRE_RUNNING=0
    pgrep -x Photos >/dev/null 2>&1 && _PHOTOS_PRE_RUNNING=1
    local out_arg="" arg end_opts=0
    for arg in "$@"; do
        if [ "$end_opts" -eq 0 ]; then
            case "$arg" in
                --) end_opts=1; continue ;;
                --no-system-originals)  PHOTOS_SYS_COPY=no; continue ;;
                --no-system-report)     PHOTOS_SYS_REPORT=no; continue ;;
                --other-libraries)      PHOTOS_OTHER_COPY=yes; PHOTOS_OTHER_REPORT=yes; continue ;;
                --no-other-originals)   PHOTOS_OTHER_COPY=no; continue ;;
                --no-other-report)      PHOTOS_OTHER_REPORT=no; continue ;;
                --no-verify-shared-matches|--disable-verify-shared-matches)
                                        PHOTOS_VERIFY_SHARED_MATCHES=0; continue ;;
                -*)
                    die "Unknown flag: $arg" ;;
            esac
        fi
        if [ -n "$out_arg" ]; then
            die "Unexpected extra argument: $arg"
        fi
        out_arg="$arg"
    done
    if [ -z "${PHOTO_LIBRARIES_EXPLICIT:-}" ] \
       && [ "$PHOTOS_SYS_COPY"    != "yes" ] \
       && [ "$PHOTOS_SYS_REPORT"   != "yes" ] \
       && [ "$PHOTOS_OTHER_COPY"   != "yes" ] \
       && [ "$PHOTOS_OTHER_REPORT" != "yes" ]; then
        log_info "No Photos content selected for export — nothing to do."
        _flag_no_content
        mark_success
        print_summary
        exit 0
    fi
    [ "${_INVOKED_BY_WRAPPER:-0}" = "1" ] || timemachine_suspend
    local out_dir
    out_dir="$(resolve_output_dir "$out_arg")" || exit 1
    _announce_output_dir "Photos"
    if [ -z "${PHOTO_LIBRARIES_EXPLICIT:-}" ]; then
        log_info "System library: copy=${PHOTOS_SYS_COPY}, report=${PHOTOS_SYS_REPORT}"
        log_info "Other libraries: copy=${PHOTOS_OTHER_COPY}, report=${PHOTOS_OTHER_REPORT}"
    else
        log_info "Enumerate mode: per-library copy/report flags set via PHOTO_LIBRARIES_EXPLICIT (see per-library row below)."
    fi
    require_full_disk_access
    [ "${_PHOTOS_PRE_RUNNING:-1}" = "1" ] && warn_if_app_running Photos
    local photos_dir="$out_dir/Photos"
    _create_output_dir "$photos_dir"
    local -a _lib_paths=() _lib_tags=() _lib_copy=() _lib_report=()
    local -a libs=()
    local system_lib=""
    if _photos_discover_system_library; then
        system_lib="${_lib_path%/}"
    fi
    if [ -n "${PHOTO_LIBRARIES_EXPLICIT:-}" ]; then
        log_info "Reading enumerate-mode library selections from PHOTO_LIBRARIES_EXPLICIT..."
        local _rec _path _copy _report _tag
        local _old_ifs="$IFS"
        local -a _recs=()
        IFS=$'\x1f' read -r -a _recs <<< "$PHOTO_LIBRARIES_EXPLICIT"
        IFS="$_old_ifs"
        for _rec in "${_recs[@]}"; do
            [ -n "$_rec" ] || continue
            local -a _fields=()
            IFS=$'\x1e' read -r -a _fields <<< "$_rec"
            IFS="$_old_ifs"
            if [ "${#_fields[@]}" -ne 3 ]; then
                log_warn "PHOTO_LIBRARIES_EXPLICIT record has ${#_fields[@]} fields (expected 3) — skipping: $_rec"
                continue
            fi
            _path="${_fields[0]:-}"
            _copy="${_fields[1]:-no}"
            _report="${_fields[2]:-no}"
            [ -n "$_path" ] || continue
            case "$_copy" in
                yes|no) ;;
                *) log_warn "PHOTO_LIBRARIES_EXPLICIT 'copy' field for $_path is not 'yes' or 'no' (got '$_copy') — treating as 'no'"
                   _copy=no ;;
            esac
            case "$_report" in
                yes|no) ;;
                *) log_warn "PHOTO_LIBRARIES_EXPLICIT 'report' field for $_path is not 'yes' or 'no' (got '$_report') — treating as 'no'"
                   _report=no ;;
            esac
            [ -d "$_path" ] || {
                log_warn "PHOTO_LIBRARIES_EXPLICIT path does not exist: $_path — skipping"
                continue
            }
            local _path_n="${_path%/}"
            local _sysl_n="${system_lib%/}"
            if [ -n "$_sysl_n" ] && [ "$_path_n" = "$_sysl_n" ]; then
                _tag="system"
            else
                _tag="other"
            fi
            local _dup=0 _existing
            for _existing in "${_lib_paths[@]+"${_lib_paths[@]}"}"; do
                if [ "${_existing%/}" = "$_path_n" ]; then
                    _dup=1; break
                fi
            done
            if [ "$_dup" = "1" ]; then
                log_warn "PHOTO_LIBRARIES_EXPLICIT contains duplicate path — keeping the first occurrence: $_path"
                continue
            fi
            _lib_paths+=( "$_path" )
            _lib_tags+=( "$_tag" )
            _lib_copy+=( "$_copy" )
            _lib_report+=( "$_report" )
        done
        if [ "${#_lib_paths[@]}" -eq 0 ]; then
            log_warn "PHOTO_LIBRARIES_EXPLICIT was set but no valid libraries resolved — nothing to do."
            local _pl_want="" _pl_rec _pl_n=0
            for _pl_rec in "${_recs[@]+"${_recs[@]}"}"; do
                [ -n "$_pl_rec" ] || continue
                _pl_want="$_pl_want${_pl_rec%%$'\x1e'*}"$'\n'
                _pl_n=$((_pl_n + 1))
            done
            report_incomplete "$(_report_subject "$photos_dir")" \
                "no named photo library could be opened" \
                "PHOTO_LIBRARIES_EXPLICIT named $_pl_n $(_pluralize "$_pl_n" library libraries) and none resolved to a readable Photos.sqlite. Check the paths (an external volume may not be mounted) and re-run." \
                "$_pl_want"
            _flag_no_content
            mark_success; print_summary; exit 0
        fi
        local _valid_idx _valid_path _bad_count=0
        local -a _keep_paths=() _keep_tags=() _keep_copy=() _keep_report=()
        for ((_valid_idx = 0; _valid_idx < ${#_lib_paths[@]}; _valid_idx++)); do
            _valid_path="${_lib_paths[$_valid_idx]}"
            if [ ! -f "$_valid_path/database/Photos.sqlite" ]; then
                log_warn "PHOTO_LIBRARIES_EXPLICIT entry is not a Photos library (no database/Photos.sqlite): $_valid_path — skipping"
                _bad_count=$((_bad_count + 1))
            else
                _keep_paths+=( "$_valid_path" )
                _keep_tags+=( "${_lib_tags[$_valid_idx]}" )
                _keep_copy+=( "${_lib_copy[$_valid_idx]}" )
                _keep_report+=( "${_lib_report[$_valid_idx]}" )
            fi
        done
        if [ "$_bad_count" -gt 0 ] && [ "${#_keep_paths[@]}" -eq 0 ]; then
            die "Every PHOTO_LIBRARIES_EXPLICIT entry is invalid; fix the env var and re-run."
        fi
        if [ "$_bad_count" -gt 0 ]; then
            _lib_paths=( "${_keep_paths[@]+"${_keep_paths[@]}"}" )
            _lib_tags=( "${_keep_tags[@]+"${_keep_tags[@]}"}" )
            _lib_copy=( "${_keep_copy[@]+"${_keep_copy[@]}"}" )
            _lib_report=( "${_keep_report[@]+"${_keep_report[@]}"}" )
            log_info "Proceeding with ${#_lib_paths[@]} valid library/libraries (skipped $_bad_count invalid entry/entries)."
        fi
        if [ -n "$system_lib" ]; then
            local _sys_present=0 _ep
            for _ep in "${_lib_paths[@]+"${_lib_paths[@]}"}"; do
                [ "${_ep%/}" = "$system_lib" ] && { _sys_present=1; break; }
            done
            if [ "$_sys_present" -eq 0 ]; then
                log_info "System Photo Library is outside ~/Pictures ($system_lib) — not shown in the photo-library menu; including it with copy + report ON so it isn't skipped."
                _lib_paths=(  "$system_lib" "${_lib_paths[@]+"${_lib_paths[@]}"}" )
                _lib_tags=(   "system"      "${_lib_tags[@]+"${_lib_tags[@]}"}" )
                _lib_copy=(   "yes"         "${_lib_copy[@]+"${_lib_copy[@]}"}" )
                _lib_report=( "yes"         "${_lib_report[@]+"${_lib_report[@]}"}" )
            fi
        fi
    else
        log_info "Discovering Photos libraries..."
        case "${PHOTOS_DISCOVERY_DEPTH:-4}" in
            ''|*[!0-9]*) die "PHOTOS_DISCOVERY_DEPTH must be a non-negative integer (got: ${PHOTOS_DISCOVERY_DEPTH})" ;;
        esac
        local p
        while IFS= read -r -d '' p; do
            libs+=( "$p" )
        done < <(_discover_all_libraries)
        if [ "${#libs[@]}" -eq 0 ]; then
            if [ -n "$system_lib" ]; then
                libs=( "$system_lib" )
            else
                log_err "No Photos libraries found."
                log_info "Searched:"
                log_info "  • ~/Pictures"
                log_info "Open Photos.app once to choose your library, then re-run."
                exit 1
            fi
        fi
        log_info "Detecting system library..."
        if [ -n "$system_lib" ]; then
            local _have_sys=0 _l _sys_norm="${system_lib%/}"
            for _l in "${libs[@]}"; do
                if [ "${_l%/}" = "$_sys_norm" ]; then _have_sys=1; break; fi
            done
            if [ "$_have_sys" -eq 0 ]; then
                libs=( "$system_lib" "${libs[@]}" )
            fi
        fi
        if [ "${#libs[@]}" -eq 1 ]; then
            log_info "Found 1 photo library:"
        else
            log_info "Found ${#libs[@]} photo libraries:"
        fi
        local lib
        for lib in "${libs[@]}"; do
            if [ "${lib%/}" = "$system_lib" ]; then
                log_info "  • [system] $lib"
            else
                log_info "  • [other]  $lib"
            fi
        done
        local _di_tag _di_copy _di_report
        for lib in "${libs[@]}"; do
            if [ -z "$system_lib" ] || [ "${lib%/}" = "$system_lib" ]; then
                _di_tag="system"
                _di_copy="$PHOTOS_SYS_COPY"
                _di_report="$PHOTOS_SYS_REPORT"
            else
                _di_tag="other"
                _di_copy="$PHOTOS_OTHER_COPY"
                _di_report="$PHOTOS_OTHER_REPORT"
            fi
            _lib_paths+=( "$lib" )
            _lib_tags+=( "$_di_tag" )
            _lib_copy+=( "$_di_copy" )
            _lib_report+=( "$_di_report" )
        done
    fi
    local i tag total_libs=${#_lib_paths[@]}
    local copies=0 reports=0
    local _did_anything=0
    local _worker_failed=0
    libs=( "${_lib_paths[@]+"${_lib_paths[@]}"}" )
    local _sa_planned=0 _sect_total=$total_libs _sect_n=0
    if [ "$total_libs" -gt 0 ]; then
        local _plan_list="" _pi _pn _pops
        for (( _pi=0; _pi<total_libs; _pi++ )); do
            _pn="$(basename "${_lib_paths[$_pi]}" .photoslibrary)"
            [ "${_lib_tags[$_pi]}" = "system" ] && _pn="$_pn (iCloud)"
            if   [ "${_lib_copy[$_pi]}" = "yes" ] && [ "${_lib_report[$_pi]}" = "yes" ]; then _pops="copy+report"
            elif [ "${_lib_copy[$_pi]}" = "yes" ];   then _pops="copy only"
            elif [ "${_lib_report[$_pi]}" = "yes" ]; then _pops="report only"
            else                                          _pops="skip"
            fi
            _plan_list="${_plan_list:+$_plan_list, }$_pn [$_pops]"
            [ "${_lib_tags[$_pi]}" = "system" ] \
                && { [ "${SHARED_COPY:-yes}" = "yes" ] || [ "${SHARED_REPORT:-yes}" = "yes" ]; } \
                && _sa_planned=1
        done
        [ "$_sa_planned" -eq 1 ] && _sect_total=$((_sect_total + 1))
        log_info "Libraries to export ($total_libs): $_plan_list"
        if [ "$_sa_planned" -eq 1 ]; then
            log_info "Photos runs as $_sect_total sections below (one ── header each): $total_libs $(_pluralize "$total_libs" library libraries) plus a Shared Albums pass (system library)."
        else
            log_info "Photos runs as $_sect_total $(_pluralize "$_sect_total" section sections) below, one ── header per library."
        fi
    fi
    for (( i=0; i<total_libs; i++ )); do
        if [ "${_SKIP_REQUESTED:-0}" = "1" ]; then
            log_info "Skipping library ${libs[$i]##*/} (user pressed 's' between libraries)."
            _SKIP_REQUESTED=0
            continue
        fi
        tag="${_lib_tags[$i]}"
        local _do_copy="${_lib_copy[$i]}" _do_report="${_lib_report[$i]}"
        local _do_shared_source="no"
        [ "$tag" = "system" ] && _do_shared_source="$PHOTOS_INCLUDE_SHARED_SOURCE"
        local _hdr_stem; _hdr_stem="$(basename "${libs[$i]}" .photoslibrary)"
        [ "$tag" = "system" ] && _hdr_stem="$_hdr_stem (iCloud)"
        _sect_n=$((_sect_n + 1))
        log_step "Library ($((i+1))/$total_libs) [$tag]: $_hdr_stem"
        local _did_skip_path=0
        if [ "$_do_copy" != "yes" ] && [ "$_do_report" != "yes" ] && [ "$_do_shared_source" != "yes" ]; then
            log_info "Skipped this library's own originals and report (its own-scope toggles are off)."
            _did_skip_path=1
        fi
        ensure_scratch
        _SKIP_REQUESTED=0
        _PL_RESOLVED_STEM=""
        local _rc=0
        _pl_run_one_library "${libs[$i]}" "$out_dir" \
            "$_do_copy" "$_do_report" \
            "${PHOTO_LIBRARY_DOWNLOAD_MISSING:-1}" "$_do_shared_source" \
            || _rc=$?
        local _resolved_stem="${_PL_RESOLVED_STEM:-}"
        if [ "$_rc" -eq 0 ]; then
            [ -n "$_resolved_stem" ] && _untrack_output_path "$photos_dir/Libraries/$_resolved_stem"
            [ "$_do_copy" = "yes" ] && [ "${_PL_COPY_DF_SKIPPED:-0}" != "1" ] && copies=$((copies + 1))
            [ "$_do_report" = "yes" ] && reports=$((reports + 1))
            if [ "$_do_copy" = "yes" ] || [ "$_do_report" = "yes" ]; then
                _did_anything=1
            fi
            if [ "$_did_skip_path" = "1" ]; then
                _did_anything=1
                log_info "Wrote skip markers."
            fi
            if [ "$tag" = "system" ] \
               && { [ "${SHARED_COPY:-yes}" = "yes" ] || [ "${SHARED_REPORT:-yes}" = "yes" ]; }; then
                local _sa_stem="$_resolved_stem"
                [ -n "$_sa_stem" ] || _sa_stem="$(basename "${libs[$i]}" .photoslibrary) (iCloud)"
                _sect_n=$((_sect_n + 1))
                log_step "Shared albums [system]: $_sa_stem — section $_sect_n of $_sect_total"
                local _sa_root="$out_dir/Photos/Libraries/$_sa_stem/Shared Albums"
                SHARED_ALBUMS_OUT_ROOT="$_sa_root"
                _SKIP_REQUESTED=0
                track_output_path "$_sa_root"
                local _sa_rc=0
                _sa_run "$out_dir" || _sa_rc=$?
                if [ "$_sa_rc" = "0" ]; then
                    _untrack_output_path "$_sa_root"
                else
                    log_warn "Shared albums for this library are incomplete or missing (exit $_sa_rc) — the library's own originals were still exported."
                    note_incomplete "$_sa_root" "Shared Albums${_resolved_stem:+ ($_resolved_stem)}" \
                        "the shared-albums pass exited with code $_sa_rc — some or all shared albums could not be exported (commonly a Photos Automation / Full Disk Access denial, or a Photos schema this build did not recognise); this library's own originals WERE exported"
                fi
                if [ -d "$_sa_root" ]; then
                    local _sa_root_first
                    if IFS= read -r -d '' _sa_root_first < <(find "$_sa_root" -mindepth 1 -print0 -quit 2>/dev/null); then
                        _did_anything=1
                    fi
                fi
            fi
            _consolidate_library_reports "$_resolved_stem" "$out_dir"
        else
            log_warn "Library worker for ${libs[$i]} exited with code $_rc — this Photos library is incomplete or missing (any other libraries were still exported)."
            if [ -n "$_resolved_stem" ] && [ -d "$photos_dir/Libraries/$_resolved_stem" ]; then
                chmod -R u+w "$photos_dir/Libraries/$_resolved_stem" 2>/dev/null || true
                rm -rf -- "$photos_dir/Libraries/$_resolved_stem" 2>/dev/null || true
            fi
            [ -n "$_resolved_stem" ] && _untrack_output_path "$photos_dir/Libraries/$_resolved_stem"
            note_incomplete "$photos_dir" "Library: $(basename "${libs[$i]}")" \
                "the per-library export worker for this Photos library exited with code $_rc and its partial output was removed — this library is NOT in the export (other libraries, if any, were exported)"
            _worker_failed=1
        fi
    done
    if [ "$total_libs" -gt 0 ]; then
        if [ "$_sect_n" -lt "$_sect_total" ]; then
            local _short=$((_sect_total - _sect_n))
            if [ "$_worker_failed" = "1" ]; then
                log_info "Photos: $_sect_n of $_sect_total $(_pluralize "$_sect_total" section sections) finished — $_short not run (a library worker failed, so its dependent section did not run)."
            else
                log_info "Photos: $_sect_n of $_sect_total $(_pluralize "$_sect_total" section sections) finished — $_short skipped."
            fi
        fi
    fi
    if [ "$copies" -gt 0 ] || [ "$reports" -gt 0 ]; then
        local _msg=""
        if [ "$copies" -gt 0 ]; then
            _msg="Copied originals for $copies $(_pluralize "$copies" library libraries)"
        fi
        if [ "$reports" -gt 0 ]; then
            if [ -n "$_msg" ]; then
                _msg="$_msg, wrote $reports $(_pluralize "$reports" report)"
            else
                _msg="Wrote $reports $(_pluralize "$reports" report)"
            fi
        fi
        local _roll_dirs=() _roll_sub
        for _roll_sub in "$photos_dir"/*/; do
            [ -d "$_roll_sub" ] || continue
            case "${_roll_sub%/}" in
                */"From Messages") continue ;;
            esac
            _roll_dirs+=( "${_roll_sub%/}" )
        done
        local _roll_size="0B"
        [ "${#_roll_dirs[@]}" -gt 0 ] && \
            _roll_size="$(du -sch "${_roll_dirs[@]}" 2>/dev/null | awk 'END{print $1}')"
        _msg="$_msg ($_roll_size total)"
        log_ok "$_msg"
    elif [ "$_did_anything" = "1" ]; then
        log_ok "Photos export complete — every selected library was skipped (see per-library skip markers under Photos/)"
    fi
    if [ "$_did_anything" = "1" ]; then
        mark_success
    fi
    if [ "${_SKIP_REQUESTED_GLOBAL:-0}" = "1" ] \
       && [ "$_did_anything" != "1" ] \
       && [ -n "${_LEAF_COUNTS_DIR:-}" ] \
       && [ -w "$_LEAF_COUNTS_DIR" ]; then
        : > "$_LEAF_COUNTS_DIR/$_LEAF_COUNTS_ID.skipped" 2>/dev/null || true
    fi
    sweep_junk_files "$photos_dir"
    rmdir "$photos_dir/Libraries" 2>/dev/null || true
    rmdir "$photos_dir" 2>/dev/null || true
    quit_app_iff_we_launched_it Photos _PHOTOS_LAUNCHED_BY_US
    if [ "${_INVOKED_BY_WRAPPER:-0}" != "1" ]; then
        _LEAF_REPORT_CATEGORY="Photos"
        _LEAF_REPORT_DIR="$photos_dir"
    fi
    print_summary
    if [ "$ERR_COUNT" -gt 0 ] || [ "$_worker_failed" = "1" ]; then exit 1; fi
    mark_success
    exit 0
}

_SKIP_REQUESTED=0
_PHOTOS_DIR=""

_recount_report_section() {
    local _file="$1" _section="$2"
    LC_ALL=C awk -v sect="[$_section]" '
        $0 == sect { inseg=1; next }
        inseg && /^\[/ { inseg=0 }
        inseg && /^#/ { next }
        inseg && /^$/ { inseg=0 }
        inseg { c++ }
        END { print c+0 }
    ' "$_file" 2>/dev/null
}

_photos_parse_md5_lines() {
    awk '
        /^MD5 \(/ {
            line = $0
            if (match(line, / = [0-9a-f]{32}$/)) {
                hex = substr(line, RSTART + 3)
                p = substr(line, 1, RSTART - 1)
                sub(/^MD5 \(/, "", p); sub(/\)$/, "", p)
                printf "%s\t%s\n", p, hex
            }
        }
    '
}

_cons_xsec() {
    LC_ALL=C awk -v s="[$2]" '
        $0==s { f=1; next }
        f && /^\[/ { f=0 }
        f && /^$/  { f=0 }
        f && /^#/  { next }
        f { print }
    ' "$1" 2>/dev/null
}

_cons_pfx_assets() {
    LC_ALL=C awk -F'\t' -v OFS='\t' -v p="$1" '{
        if (NF>=4 && $4!="") $4 = p $4
        if (NF>=8 && $8!="") {
            n=split($8,c,";"); o=""
            for (i=1;i<=n;i++) { m=split(c[i],g,"|"); o=(o==""?"":o";") p g[1] (m>=2?"|" g[2]:"") (m>=3?"|" g[3]:"") }
            $8=o
        }
        if (NF==8) $9 = ""
        print
    }'
}

_fetch_czkawka() {
    [ -n "${_CZKAWKA_BIN:-}" ] && { printf '%s\n' "$_CZKAWKA_BIN"; return 0; }
    [ "${_CZKAWKA_TRIED:-0}" = "1" ] && return 1
    _CZKAWKA_TRIED=1
    command -v curl >/dev/null 2>&1 || { log_warn "czkawka: curl not available — shared-album matches stay filename-only."; return 1; }
    local _arch _asset _want_sha
    _arch="$(uname -m 2>/dev/null)"
    case "$_arch" in
        arm64)  _asset="mac_czkawka_cli_arm64";  _want_sha="62895a4873c79516a7c07d3fbfdc7fda1f7ff806d589558e40f56c7e959828a3" ;;
        x86_64) _asset="mac_czkawka_cli_x86_64"; _want_sha="ed360781c1da7b5596ba05feeaf87ea18f46f2125b4fdb4feb4fbac6ddb5d418" ;;
        *) log_warn "czkawka: unrecognised arch '$_arch' — shared-album matches stay filename-only."; return 1 ;;
    esac
    ensure_scratch
    local _bin="$SCRATCH_DIR/czkawka_cli"
    local _tag="11.0.1"
    local _url="https://github.com/qarmin/czkawka/releases/download/${_tag}/${_asset}"
    if ! _fetch_download "$_url" "$_bin" "czkawka_cli ($_asset $_tag)" 120 >&2 || [ ! -s "$_bin" ]; then
        log_warn "czkawka download failed (network?) — shared-album matches stay filename-only."
        rm -f "$_bin" 2>/dev/null; return 1
    fi
    local _got_sha
    _got_sha="$(shasum -a 256 -- "$_bin" 2>/dev/null | awk '{print tolower($1)}')"
    if [ "$_got_sha" != "$_want_sha" ]; then
        log_warn "czkawka: SHA-256 mismatch (expected $_want_sha, got ${_got_sha:-none}) — refusing to run it; shared-album matches stay filename-only."
        rm -f "$_bin" 2>/dev/null; return 1
    fi
    chmod +x "$_bin" 2>/dev/null || { log_warn "czkawka chmod failed — matches stay filename-only."; rm -f "$_bin" 2>/dev/null; return 1; }
    local _czhome="$SCRATCH_DIR/czk_home"; mkdir -p "$_czhome/cfg" "$_czhome/cache"
    if ! _run_with_timeout 30 \
        env HOME="$_czhome" \
        CZKAWKA_CONFIG_PATH="$_czhome/cfg" CZKAWKA_CACHE_PATH="$_czhome/cache" \
        "$_bin" --version >/dev/null 2>&1; then
        log_warn "czkawka smoke-test failed or timed out (incompatible binary?) — matches stay filename-only."
        rm -f "$_bin" 2>/dev/null; return 1
    fi
    _CZKAWKA_BIN="$_bin"
    printf '%s\n' "$_bin"
    return 0
}

_verify_lowq_pairs() {
    local _lq="$1" _assets="$2" _out="$3"
    local _tmp="$SCRATCH_DIR/lq_verified.tsv"
    local _do=1
    case "${PHOTOS_VERIFY_SHARED_MATCHES:-1}" in 0|n*|N*|f*|F*) _do=0 ;; esac
    command -v sips >/dev/null 2>&1 || _do=0
    local _czk=""
    [ "$_do" = "1" ] && { _czk="$(_fetch_czkawka)" || _do=0; }
    if [ "$_do" != "1" ]; then
        LC_ALL=C awk -F'\t' -v OFS='\t' '{print $1,$2,$3,"unchecked"}' "$_lq" > "$_tmp" && mv -f "$_tmp" "$_lq"
        return 0
    fi
    local _nd="$SCRATCH_DIR/lq_norm"; rm -rf "$_nd" 2>/dev/null; mkdir -p "$_nd"
    LC_ALL=C awk -F'\t' -v out="$_out" '
        FNR==NR { need[$2]=1; need[$3]=1; next }
        ($1 in need) && !($1 in seen) { seen[$1]=1; print $1 "\t" out "/Photos/Libraries/" $4 }
    ' "$_lq" "$_assets" > "$SCRATCH_DIR/lq_tofetch.tsv"
    local _u _abs
    while IFS=$'\t' read -r _u _abs; do
        if [ -f "$_abs" ] && sips -s format png -Z 256 "$_abs" --out "$_nd/$_u.png" >/dev/null 2>&1; then
            sips -r 90  "$_nd/$_u.png" --out "$_nd/${_u}__r90.png"  >/dev/null 2>&1
            sips -r 180 "$_nd/$_u.png" --out "$_nd/${_u}__r180.png" >/dev/null 2>&1
            sips -r 270 "$_nd/$_u.png" --out "$_nd/${_u}__r270.png" >/dev/null 2>&1
        fi
    done < "$SCRATCH_DIR/lq_tofetch.tsv"
    local _ctxt="$SCRATCH_DIR/lq_czk.txt"; : > "$_ctxt"
    local _czhome="$SCRATCH_DIR/czk_home"; mkdir -p "$_czhome/cfg" "$_czhome/cache"
    _run_with_timeout "${PHOTOS_CZKAWKA_TIMEOUT_SEC:-300}" \
        env HOME="$_czhome" \
        CZKAWKA_CONFIG_PATH="$_czhome/cfg" CZKAWKA_CACHE_PATH="$_czhome/cache" \
        "$_czk" image -d "$_nd" -R -H -W -m 1 -c 16 -s 18 -N -M -f "$_ctxt" >/dev/null 2>&1
    [ "$?" -eq 124 ] && log_warn "czkawka exceeded ${PHOTOS_CZKAWKA_TIMEOUT_SEC:-300}s — killed; shared-album matches stay filename-only."
    LC_ALL=C awk -F'\t' -v OFS='\t' -v ctxt="$_ctxt" '
        BEGIN {
            g=0; inrun=0
            while ((getline line < ctxt) > 0) {
                if (line ~ /^"/) {
                    p=line; sub(/^"/,"",p); sub(/".*/,"",p)
                    m=split(p,aa,"/"); bn=aa[m]; sub(/\.png$/,"",bn)
                    u=bn; sub(/__r[0-9]+$/,"",u)   # strip the rotation suffix -> base uuid
                    ugrp[u,g]=1                     # (some rotation of) uuid u is in group g
                    inrun=1
                } else if (inrun) { g++; inrun=0 }
            }
            if (inrun) g++   # count an unterminated final group — czkawka may omit a trailing blank line after the last group, which would otherwise leave gmax one short and mislabel that group filename-only
            close(ctxt); gmax=g
        }
        {
            v="filename"
            for (i=0; i<gmax; i++) { if ((($2,i) in ugrp) && (($3,i) in ugrp)) { v="content"; break } }
            print $1,$2,$3,v
        }
    ' "$_lq" > "$_tmp" && mv -f "$_tmp" "$_lq"
}

_verify_lowq_matches() {
    local _lq="$1" _assets="$2" _shalb="$3" _out="$4"
    [ -s "$_lq" ] && _verify_lowq_pairs "$_lq" "$_assets" "$_out"
    if [ -s "$_shalb" ]; then
        local _sp="$SCRATCH_DIR/sh_verified.tsv"
        LC_ALL=C awk -F'\t' -v OFS='\t' -v lq="$_lq" '
            BEGIN { while ((getline l < lq) > 0) { n=split(l,a,"\t"); if (n>=4 && a[4]=="content") vc[a[1]]++ } close(lq) }
            { print $0, (($1 in vc)?vc[$1]:0) }
        ' "$_shalb" > "$_sp" && mv -f "$_sp" "$_shalb"
    fi
}

_consolidate_library_reports() {
    local _stem="$1" _out="$2"
    [ -n "$_stem" ] || return 0
    local _ld="$_out/Photos/Libraries/$_stem"
    local _own="$_ld/$_stem.report"
    local _sa="$_ld/Shared Albums/Shared Albums.report"
    local _syn="$_ld/Shared with You (not in library)/$_stem.report"
    local _mom="$_ld/Shared Moments/$_stem.report"
    local _combined="$_out/Photos/Libraries/$_stem.report"
    [ -f "$_own" ] || [ -f "$_sa" ] || [ -f "$_syn" ] || [ -f "$_mom" ] || return 0
    ensure_scratch
    local _A="$SCRATCH_DIR/cons_assets.tsv"   _T="$SCRATCH_DIR/cons_trashed.tsv"
    local _M="$SCRATCH_DIR/cons_meta.tsv"     _AL="$SCRATCH_DIR/cons_albums.tsv"
    local _CO="$SCRATCH_DIR/cons_contrib.tsv" _CA="$SCRATCH_DIR/cons_captions.tsv"
    local _CM="$SCRATCH_DIR/cons_comments.tsv" _LQ="$SCRATCH_DIR/cons_lowq.tsv"
    local _FV="$SCRATCH_DIR/cons_favorites.tsv" _MD="$SCRATCH_DIR/cons_assetmeta.tsv"
    : > "$_A"; : > "$_T"; : > "$_M"; : > "$_AL"; : > "$_CO"; : > "$_CA"; : > "$_CM"; : > "$_LQ"; : > "$_FV"; : > "$_MD"
    if [ -f "$_own" ]; then
        _cons_xsec "$_own" assets  | _cons_pfx_assets "$_stem/" >> "$_A"
        _cons_xsec "$_own" trashed | _cons_pfx_assets "$_stem/" >> "$_T"
        _cons_xsec "$_own" favorites >> "$_FV"
        _cons_xsec "$_own" albums >> "$_AL"
        _cons_xsec "$_own" asset_metadata >> "$_MD"
    fi
    if [ -f "$_sa" ]; then
        _cons_xsec "$_sa" assets | _cons_pfx_assets "$_stem/Shared Albums/" >> "$_A"
        _cons_xsec "$_sa" shared_albums >> "$_M"
        _cons_xsec "$_sa" albums >> "$_AL"
        _cons_xsec "$_sa" contributors >> "$_CO"
        _cons_xsec "$_sa" captions     >> "$_CA"
        _cons_xsec "$_sa" comments     >> "$_CM"
        local _lq_in=("$_sa"); [ -f "$_own" ] && _lq_in=("$_own" "$_sa")
        LC_ALL=C awk -F'\t' -v OFS='\t' '
            FNR==1 { sec="" }
            /^\[/ { sec=substr($0,2,length($0)-2); next }
            /^#/  { next }
            $0=="" { next }
            sec=="assets" && NF>=3 { if($3=="on-disk") ond[$1]=1 }
            sec=="library_full_res" && NF>=3 { ln++; L[ln]=$1 FS $2 FS $3 }
            END {
                for(i=1;i<=ln;i++){
                    split(L[i],f,FS)
                    if((f[2] in ond) && (f[3] in ond)) print f[1], f[2], f[3]
                }
            }
        ' "${_lq_in[@]}" >> "$_LQ"
    fi
    [ -f "$_syn" ] && _cons_xsec "$_syn" assets | _cons_pfx_assets "$_stem/Shared with You (not in library)/" >> "$_A"
    [ -f "$_mom" ] && _cons_xsec "$_mom" assets | _cons_pfx_assets "$_stem/Shared Moments/" >> "$_A"
    _verify_lowq_matches "$_LQ" "$_A" "$_M" "$_out"
    local _hdr_src=""
    [ -f "$_own" ] && _hdr_src="$_own"
    [ -z "$_hdr_src" ] && [ -f "$_sa" ]  && _hdr_src="$_sa"
    [ -z "$_hdr_src" ] && [ -f "$_syn" ] && _hdr_src="$_syn"
    [ -z "$_hdr_src" ] && [ -f "$_mom" ] && _hdr_src="$_mom"
    local _dg_count _dg_bytes _dg_unhashed
    _dg_count=$(LC_ALL=C awk -F'\t' '$3=="on-disk"{n++} END{print n+0}' "$_A" 2>/dev/null)
    _dg_bytes=$(LC_ALL=C awk -F'\t' '$3=="on-disk"{s+=($5+0)} END{printf "%d\n", s+0}' "$_A" 2>/dev/null)
    _dg_unhashed=$(LC_ALL=C awk -F'\t' '$3=="on-disk" && $6==""{n++} END{print n+0}' "$_A" 2>/dev/null)
    local _tmp; _tmp="$(mktemp "$_combined.tmp.XXXXXX" 2>/dev/null)" || _tmp="$SCRATCH_DIR/cons_report.tmp"
    track_output_path "$_tmp"
    {
        if [ -n "$_hdr_src" ]; then
            LC_ALL=C awk '/^#/{ print; next } { exit }' "$_hdr_src"
        fi
        printf '# asset_count: %s\n' "$_dg_count"
        printf '# total_bytes: %s\n' "$_dg_bytes"
        printf '# assets_unhashed: %s\n' "$_dg_unhashed"
        printf '\n[assets]\n'
        printf '# asset_uuid\toriginal_filename\tstatus\trel_path\tsize\thash\tflags\tcompanions\tcapture_date\n'
        printf '# Every file this library exported, across all sources (own originals, Shared Albums, Shared with You, Shared Moments). status: on-disk | not-on-disk.\n'
        LC_ALL=C sort "$_A"
        printf '\n[trashed]\n'
        printf '# asset_uuid\toriginal_filename\tstatus\trel_path\tsize\thash\tflags\tcompanions\tcapture_date\n'
        printf '# Recently-Deleted own-library masters, copied to <stem>/Recently Deleted/.\n'
        LC_ALL=C sort "$_T"
        if [ -s "$_M" ]; then
            printf '\n[shared_albums]\n'
            printf '# album_uuid\talbum_name\tbucket\towner\texpires\tpublic\tshare_url\tasset_count_reported_by_apple\tmembers_with_full_res_copy\tmembers_with_verified_full_res_copy\n'
            LC_ALL=C sort "$_M"
        fi
        if [ -s "$_AL" ]; then
            printf '\n[albums]\n'
            printf '# album_uuid\talbum_name\tasset_uuid\n'
            LC_ALL=C sort "$_AL"
        fi
        if [ -s "$_CO" ]; then
            printf '\n[contributors]\n'
            printf '# album_uuid\tasset_uuid\tcontributor_name\n'
            LC_ALL=C sort "$_CO"
        fi
        if [ -s "$_CA" ]; then
            printf '\n[captions]\n'
            printf '# album_uuid\tasset_uuid\tcaption\n'
            LC_ALL=C sort "$_CA"
        fi
        if [ -s "$_CM" ]; then
            printf '\n[comments]\n'
            printf '# album_uuid\tasset_uuid\tdatetime\tcommenter\tkind\ttext\tmine\n'
            LC_ALL=C sort "$_CM"
        fi
        if [ -s "$_LQ" ]; then
            printf '\n[low_quality_shared]\n'
            printf '# album_uuid\tlow_quality_uuid\tfull_quality_uuid\tverified\n'
            LC_ALL=C sort "$_LQ"
        fi
        if [ -s "$_FV" ]; then
            printf '\n[favorites]\n'
            printf '# asset_uuid\n'
            LC_ALL=C sort "$_FV"
        fi
        if [ -s "$_MD" ]; then
            printf '\n[asset_metadata]\n'
            printf '# asset_uuid\ttitle\tcaption\tkeywords\n'
            LC_ALL=C sort "$_MD"
        fi
        printf '\n'
        :
    } > "$_tmp" 2>/dev/null \
        && mv -f -- "$_tmp" "$_combined" 2>/dev/null \
        || { rm -f -- "$_tmp" 2>/dev/null; log_warn "failed to write consolidated $_stem.report"; \
             note_incomplete "$(dirname "$_combined")" "$_stem consolidated report" \
                 "the consolidated per-library report could not be written (disk full / read-only output volume) — the per-section source reports remain in the export un-folded"; \
             return 1; }
    _untrack_output_path "$_tmp"
    rm -f -- "$_own" "$_sa" "$_syn" "$_mom" 2>/dev/null
    rmdir "$_ld/Shared Albums" 2>/dev/null; rmdir "$_ld" 2>/dev/null
    local _exp _got
    _exp="$(LC_ALL=C awk 'END{print NR+0}' "$_A" 2>/dev/null)"
    _got="$(_recount_report_section "$_combined" assets)"
    case "$_got" in ''|*[!0-9]*) _got=0 ;; esac
    case "$_exp" in ''|*[!0-9]*) _exp=0 ;; esac
    if [ "$_got" -lt "$_exp" ]; then
        log_warn "Consolidated $_stem.report is short — wrote $_got of $_exp asset row(s); the file may be truncated."
        note_incomplete "$_out/Photos/Libraries" "$_stem.report" \
            "the consolidated report write was truncated ($_got of $_exp asset rows) — disk-full or torn write"
    fi
    log_ok "Wrote Photos/Libraries/$_stem.report ($_got $(_pluralize "$_got" asset))"
}

case "$PHOTOS_PERLIB_HEADROOM_MB" in
    ''|*[!0-9]*)      PHOTOS_PERLIB_HEADROOM_MB=500 ;;
    0)                PHOTOS_PERLIB_HEADROOM_MB=0   ;;
    0[0-9]*)          PHOTOS_PERLIB_HEADROOM_MB=500 ;;
    *) [ "$PHOTOS_PERLIB_HEADROOM_MB" -gt 1048576 ] && PHOTOS_PERLIB_HEADROOM_MB=500 ;;
esac

: "${PHOTO_LIBRARY_COPY:=yes}"
: "${PHOTO_LIBRARY_REPORT:=yes}"
: "${PHOTO_LIBRARY_ALBUMS:=yes}"
: "${PHOTO_LIBRARY_FAVORITES:=yes}"
: "${PHOTO_LIBRARY_INCLUDE_SHARED_SOURCE:=yes}"
case "$PHOTO_LIBRARY_DOWNLOAD_MISSING" in
    1|y|Y|yes|YES|true|TRUE) PHOTO_LIBRARY_DOWNLOAD_MISSING=1 ;;
    *)                       PHOTO_LIBRARY_DOWNLOAD_MISSING=0 ;;
esac

case "$PHOTO_LIBRARY_DOWNLOAD_TIMEOUT_SEC" in
    ''|*[!0-9]*)        PHOTO_LIBRARY_DOWNLOAD_TIMEOUT_SEC=60 ;;
    0)                  PHOTO_LIBRARY_DOWNLOAD_TIMEOUT_SEC=1 ;;
    *) [ "$PHOTO_LIBRARY_DOWNLOAD_TIMEOUT_SEC" -gt 3600 ] && PHOTO_LIBRARY_DOWNLOAD_TIMEOUT_SEC=60 ;;
esac

_PL_AS_DISABLED=0
_PL_AS_CONSEC_FAILURES=0
_PL_DL_TMPDIR=""
_PL_AS_DISABLE_THRESHOLD=10

_PL_OWN_FIND_PRUNE=( ! -type l ! -name '.*' ! -path '*/INFLIGHT/*' ! -path '*/INFLIGHT_JOBS/*' ! -name '*.plist' ! -name 'serverconfiguration*' ! -name 'personID*' )

_PL_SCOPE_FIND_PRUNE=( ! -type l ! -name '.*' ! -name '*.plist' ! -name 'serverconfiguration*' ! -name 'personID*' )

_pl_export_asset() {
    _photos_export_asset "$1" "$PHOTO_LIBRARY_DOWNLOAD_TIMEOUT_SEC" pl_export
    local _rc=$?
    _PL_DL_TMPDIR="$_PHOTOS_EXPORT_TMPDIR"
    if [ "$_rc" -eq 0 ]; then
        _PL_AS_CONSEC_FAILURES=0
        return 0
    fi
    _PL_AS_CONSEC_FAILURES=$((_PL_AS_CONSEC_FAILURES + 1))
    if [ "$_PL_AS_CONSEC_FAILURES" -ge "$_PL_AS_DISABLE_THRESHOLD" ]; then
        log_warn "Photos.app downloads: $_PL_AS_CONSEC_FAILURES consecutive failures — disabling further iCloud downloads for the rest of this run (the export keeps whatever is already on disk)."
        _PL_AS_DISABLED=1
    fi
    return 1
}

_pl_download_evicted() {
    local dest_originals="$1"
    : > "$SCRATCH_DIR/downloaded.set"
    [ "$PHOTO_LIBRARY_DOWNLOAD_MISSING" = "1" ] || return 0
    [ "$PHOTO_LIBRARY_COPY" = "yes" ] || return 0
    [ "${_PL_COPY_DF_SKIPPED:-0}" = "1" ] && return 0
    [ "${_PL_COPY_USER_SKIPPED:-0}" = "1" ] && return 0
    [ "$_PL_AS_DISABLED" = "1" ] && return 0
    [ -s "$SCRATCH_DIR/assets.tsv" ] || return 0
    [ -f "$SCRATCH_DIR/report_ondisk.tsv" ] || return 0
    local _evicted="$SCRATCH_DIR/evicted.tsv"
    LC_ALL=C awk '
        FILENAME ~ /report_ondisk/ { split($0,r,"\t"); od[r[1]]=1; next }
        FILENAME ~ /assets/ {
            n=split($0,a,"\x1f"); uuid=a[2]; dir=a[3]; orig=a[6]; tr=a[9]
            if (tr != "" && tr != "0") next
            if (!(dir ~ /^[0-9A-Fa-f]$/)) next
            if (uuid in od) next
            ext=orig; sub(/.*\./,"",ext); ext=tolower(ext)
            if (ext==orig || ext=="") ext="jpeg"
            print uuid "\t" orig "\t" ext
        }
    ' "$SCRATCH_DIR/report_ondisk.tsv" "$SCRATCH_DIR/assets.tsv" > "$_evicted" 2>/dev/null
    local _n_ev; _n_ev="$(_count_lines "$_evicted")"
    [ "${_n_ev:-0}" -gt 0 ] || return 0
    local _avail_kb _df_out _df_failed=0
    _df_out="$(df -P -k "$dest_originals" 2>/dev/null)"
    if [ -z "$_df_out" ]; then
        _df_failed=1
        _avail_kb=0
        log_warn "Cannot determine available disk space for the iCloud download (df failed — stale mount or permission issue?); proceeding without the per-file free-space guard."
    else
        _avail_kb="$(printf '%s\n' "$_df_out" | awk 'END{print $4}')"
        case "$_avail_kb" in ''|*[!0-9]*) _avail_kb=0 ;; esac
    fi
    log_info "Downloading $_n_ev evicted $(_pluralize "$_n_ev" original) from iCloud via Photos.app (Optimize Mac Storage); sizes unknown until fetched..."
    if ( : </dev/tty >/dev/tty ) 2>/dev/null; then
        log_info "(press 's' to skip the rest of this library's iCloud download)"
    fi
    mkdir -p "$dest_originals" 2>/dev/null || true
    local _dl_ok=0 _dl_fail=0 _dl_cfail=0 _dl_skip=0 _dl_userskip=0
    local _eu _eorig _eext _dl_path _target _sz _md5 _ci _cf _cext _ctarget _csz _cmd5
    _heartbeat_start 30 "... iCloud download still running"
    while IFS=$'\t' read -r _eu _eorig _eext; do
        [ -n "$_eu" ] || continue
        if [ "$_SKIP_REQUESTED" = "1" ]; then
            log_warn "Skipped rest of iCloud downloads on user request (downloaded $_dl_ok so far)"
            _SKIP_REQUESTED=0; _dl_userskip=1; break
        fi
        [ "$_PL_AS_DISABLED" = "1" ] && { _dl_skip=$((_dl_skip + 1)); continue; }
        local _dl_extra=()
        if ! _pl_export_asset "$_eu"; then _dl_fail=$((_dl_fail + 1)); continue; fi
        _sz="$(stat -f '%z' "$_dl_path" 2>/dev/null)"; case "$_sz" in ''|*[!0-9]*) _sz=0 ;; esac
        if [ "$_df_failed" = "0" ] && [ "$(( _sz / 1024 + 51200 ))" -gt "$_avail_kb" ]; then
            local _df_now _avail_now
            _df_now="$(df -P -k "$dest_originals" 2>/dev/null)"
            if [ -n "$_df_now" ]; then
                _avail_now="$(printf '%s\n' "$_df_now" | awk 'END{print $4}')"
                case "$_avail_now" in ''|*[!0-9]*) _avail_now="$_avail_kb" ;; esac
                _avail_kb="$_avail_now"
            fi
            if [ "$(( _sz / 1024 + 51200 ))" -gt "$_avail_kb" ]; then
                log_warn "Skipping downloaded original $_eorig — would exceed free space on the export volume."
                rm -rf -- "$_PL_DL_TMPDIR" 2>/dev/null || true
                _dl_skip=$((_dl_skip + 1)); continue
            fi
        fi
        local _dl_dir; _pl_category_into "$_eu" _dl_dir
        mkdir -p "$dest_originals/$_dl_dir" 2>/dev/null || true
        local _dl_base="${_dl_path##*/}" _dl_ext
        _dl_ext="${_dl_base##*.}"
        case "$_dl_ext" in ''|"$_dl_base") _dl_ext="$_eext" ;; esac
        _dl_ext="$(printf '%s' "$_dl_ext" | tr 'A-Z' 'a-z')"
        _target="$dest_originals/$_dl_dir/$_eu.$_dl_ext"
        if [ -e "$_target" ]; then
            local _dstem="${_target%.*}" _dext="${_target##*.}" _dn=2
            [ "$_dext" = "$_target" ] && _dext=""    # no extension
            _target="${_dstem}_dl${_dext:+.$_dext}"
            while [ -e "$_target" ] && [ "$_dn" -lt 1000 ]; do
                if [ -n "$_dext" ]; then _target="${_dstem}_dl${_dn}.${_dext}"; else _target="${_dstem}_dl${_dn}"; fi
                _dn=$((_dn + 1))
            done
        fi
        if ! { ditto -- "$_dl_path" "$_target" 2>/dev/null \
               && [ -s "$_target" ] \
               && ! _materialized_copy_incomplete "$_sz" "$_target"; }; then
            rm -f -- "$_target" 2>/dev/null   # reap the torn dest partial (the tmpdir reap below only clears the scratch SOURCE)
            rm -rf -- "$_PL_DL_TMPDIR" 2>/dev/null || true
            _dl_fail=$((_dl_fail + 1)); continue
        fi
        local _cd_ref="_capdate_${_eu//-/_}"; _apply_touch_t "${!_cd_ref:-}" "$_target"
        _md5="$(_md5_hex "$_target")"
        local _tsz; _tsz="$(stat -f '%z' "$_target" 2>/dev/null)"; case "$_tsz" in ''|*[!0-9]*) _tsz="$_sz" ;; esac
        printf '%s\t%s\t%s\t%s\t%s\n' "$_eu" "$_dl_dir/${_target##*/}" "$_tsz" "" "$_md5" \
            >> "$SCRATCH_DIR/report_ondisk.tsv"
        printf '%s\n' "$_eu" >> "$SCRATCH_DIR/downloaded.set"
        _avail_kb=$(( _avail_kb - _tsz / 1024 ))
        _ci=1
        for _cf in "${_dl_extra[@]+"${_dl_extra[@]}"}"; do
            _cext="${_cf##*.}"; _ctarget="$dest_originals/$_dl_dir/${_eu}_${_ci}.${_cext}"
            if ditto -- "$_cf" "$_ctarget" 2>/dev/null && [ -s "$_ctarget" ]; then
                _csz="$(stat -f '%z' "$_ctarget" 2>/dev/null)"; case "$_csz" in ''|*[!0-9]*) _csz=0 ;; esac
                _cmd5="$(_md5_hex "$_ctarget")"
                printf '%s\t%s\t%s\t%s\t%s\n' "${_eu}_${_ci}" "$_dl_dir/${_ctarget##*/}" "$_csz" "" "$_cmd5" \
                    >> "$SCRATCH_DIR/report_ondisk.tsv"
                _avail_kb=$(( _avail_kb - _csz / 1024 ))
            else
                rm -f -- "$_ctarget" 2>/dev/null
                _dl_cfail=$((_dl_cfail + 1))
            fi
            _ci=$((_ci + 1))
        done
        rm -rf -- "$_PL_DL_TMPDIR" 2>/dev/null || true
        _dl_ok=$((_dl_ok + 1))
        if [ "$_SKIP_REQUESTED" = "1" ]; then
            log_warn "Skipped rest of iCloud downloads on user request (downloaded $_dl_ok so far)"
            _SKIP_REQUESTED=0; _dl_userskip=1; break
        fi
    done < "$_evicted"
    _heartbeat_stop
    local _msg
    _msg="Downloaded $_dl_ok evicted $(_pluralize "$_dl_ok" original) from iCloud into Photos/${dest_originals##*/Photos/}/"
    [ "$_dl_fail" -gt 0 ] && _msg="$_msg; $_dl_fail failed"
    [ "$_dl_skip" -gt 0 ] && _msg="$_msg; $_dl_skip skipped"
    log_info "$_msg"
    if [ "$_dl_fail" -gt 0 ] || [ "$_dl_cfail" -gt 0 ] || [ "$_dl_skip" -gt 0 ] || [ "$_dl_userskip" = 1 ]; then
        local _why=""
        if [ "$_dl_fail" -gt 0 ] || [ "$_dl_skip" -gt 0 ]; then
            _why="$_dl_fail evicted original(s) failed to download and $_dl_skip were skipped (space limit or user skip) — they are not in the export"
        fi
        [ "$_dl_cfail" -gt 0 ] && _why="${_why:+$_why; }$_dl_cfail companion file(s) (e.g. a Live Photo's motion clip) failed to copy — not in the export"
        [ "$_dl_userskip" = 1 ] && _why="${_why:+$_why; }the download phase was stopped early by the user ('s'), so the remaining evicted originals were not fetched"
        note_incomplete "$_PHOTOS_DIR" "Photos library iCloud downloads: $(basename "$lib")" "$_why"
    fi
    return 0
}

_pl_disclose_evicted_gap() {
    [ "$PHOTO_LIBRARY_COPY" = "yes" ] || return 0
    [ -s "$SCRATCH_DIR/assets.tsv" ] || return 0
    [ -f "$SCRATCH_DIR/report_ondisk.tsv" ] || return 0
    local _gap _gap_trashed _gap_ref _counts
    _counts="$(LC_ALL=C awk '
        FILENAME ~ /report_ondisk/ { split($0,r,"\t"); od[r[1]]=1; next }
        FILENAME ~ /assets/ {
            n=split($0,a,"\x1f"); uuid=a[2]; dir=a[3]; sat=a[7]; tr=a[9]
            if (!(dir ~ /^[0-9A-Fa-f]$/)) {
                if ((sat+0) == 10 || dir ~ /^\//) {
                    if ((tr == "" || tr == "0") && !(uuid in od)) rf++
                }
                next
            }
            if (uuid in od) next
            if (tr != "" && tr != "0") t++; else c++
        }
        END { print (c+0) " " (t+0) " " (rf+0) }
    ' "$SCRATCH_DIR/report_ondisk.tsv" "$SCRATCH_DIR/assets.tsv" 2>/dev/null)"
    _gap="${_counts%% *}"; _gap_ref="${_counts##* }"
    _gap_trashed="${_counts#* }"; _gap_trashed="${_gap_trashed%% *}"
    case "$_gap" in ''|*[!0-9]*) _gap=0 ;; esac
    case "$_gap_trashed" in ''|*[!0-9]*) _gap_trashed=0 ;; esac
    case "$_gap_ref" in ''|*[!0-9]*) _gap_ref=0 ;; esac
    if [ "$_gap" -gt 0 ]; then
        local _hint="the 'Download iCloud-only originals' option is off — turn it on (or download them in Photos.app first: Settings > iCloud > Download Originals to this Mac), then re-run"
        [ "$PHOTO_LIBRARY_DOWNLOAD_MISSING" = "1" ] && _hint="they could not all be fetched from iCloud (Photos Automation denied, a download failure, or insufficient space) — grant Photos Automation or download them in Photos.app, then re-run"
        log_warn "$_gap $(_pluralize "$_gap" original) evicted to iCloud (Optimize Mac Storage) and NOT in this export — $_hint."
        note_incomplete "$_PHOTOS_DIR" "Photos library: $(basename "$lib") evicted originals" \
            "$_gap own original(s) are evicted to iCloud and were not captured (not on disk; Optimize Mac Storage). $_hint"
    fi
    [ "$_gap_trashed" -gt 0 ] && \
        _disclose_excluded "$_gap_trashed evicted $(_pluralize "$_gap_trashed" original) in Recently Deleted" "deleted AND evicted to iCloud, so on neither this Mac nor this export; recover in Photos' Recently Deleted within ~30 days, or download originals before deleting"
    if [ "$_gap_ref" -gt 0 ]; then
        log_warn "$_gap_ref referenced $(_pluralize "$_gap_ref" original) $(_pluralize "$_gap_ref" lives live) on an external volume (kept outside the library) and $(_pluralize "$_gap_ref" is are) NOT in this export — in Photos, select $(_pluralize "$_gap_ref" it them) and choose File > Consolidate to import the $(_pluralize "$_gap_ref" original), then re-run."
        report_review "$(_report_subject "$_PHOTOS_DIR")" "Photos library: $(basename "$lib") — referenced originals (outside the library)" \
            "$_gap_ref $(_pluralize "$_gap_ref" original) $(_pluralize "$_gap_ref" is are) referenced from an external volume (kept outside the .photoslibrary) and $(_pluralize "$_gap_ref" was were) not captured — the bytes live outside the library, so no export can reach them. In Photos, select $(_pluralize "$_gap_ref" it them) and choose File > Consolidate to import the $(_pluralize "$_gap_ref" original) into the library, then re-run."
    fi
    return 0
}

: "${PHOTO_LIBRARY_PATH:=}"

_write_lib_marker() {
    local lib_dir="$1" marker_basename="$2"
    shift 2
    local _title="${marker_basename%.txt}" _prose
    _prose="$(printf '%s\n' "$@")"
    report_incomplete "$(_report_subject "$lib_dir")" "$_title" "$_prose"
    _PL_LIB_MARKED="$lib_dir"
}

_write_skipped_marker_system_only() {
    local lib_dir="$1" lib_stem="$2" lib_path="$3" op="$4"
    local op_label
    case "$op" in
        originals) op_label="Photo copy" ;;
        report)    op_label="Library report" ;;
        *)         op_label="Operation" ;;
    esac
    _write_lib_marker "$lib_dir" "$lib_stem $op skipped.txt" \
        "$op_label skipped — this library was not selected" \
        "" \
        "Library:        $lib_path" \
        "To include it:  re-run with --other-libraries"
}

_write_skipped_marker_diskspace() {
    local lib_dir="$1" lib_stem="$2" lib_path="$3"
    local size_gb="$4" count="$5" avail_gb="$6"
    _write_lib_marker "$lib_dir" "$lib_stem originals skipped.txt" \
        "Originals copy skipped — insufficient disk space" \
        "" \
        "Library:    $lib_path" \
        "Size:       ~$size_gb GB ($count file(s))" \
        "Available:  ~$avail_gb GB on the export volume"
}

_write_skipped_marker_dffail() {
    local lib_dir="$1" lib_stem="$2" lib_path="$3" count="$4"
    _write_lib_marker "$lib_dir" "$lib_stem originals skipped.txt" \
        "Originals copy skipped — could not check free disk space" \
        "" \
        "Library:    $lib_path" \
        "Size:       $count file(s)" \
        "Reason:     the export volume's free space could not be determined (df failed — a stale mount, permission issue, or unhealthy volume), so the copy was skipped rather than risk overrunning the disk. Re-run once the volume is healthy."
}

_write_skipped_marker_user() {
    local lib_dir="$1" lib_stem="$2" lib_path="$3"
    local phase="$4" kept="$5" total="$6"
    _write_lib_marker "$lib_dir" "$lib_stem $phase partial — user skipped.txt" \
        "$phase skipped — user pressed 's' during this library" \
        "" \
        "Library:    $lib_path" \
        "Progress:   $kept of $total file(s) processed before the skip"
}

_plan_library_stem() {
    local lib="$1" out_dir="$2" stem_override="${3:-}"
    local stem parent candidate i
    stem="${stem_override:-$(basename "$lib" .photoslibrary)}"
    candidate="$out_dir/$stem"
    if mkdir "$candidate" 2>/dev/null; then
        printf '%s' "$stem"; return 0
    fi
    parent="$(basename "$(dirname "$lib")")"
    candidate="$out_dir/$stem ($parent)"
    if mkdir "$candidate" 2>/dev/null; then
        printf '%s' "$stem ($parent)"; return 0
    fi
    i=2
    while true; do
        candidate="$out_dir/$stem ($parent) $i"
        if mkdir "$candidate" 2>/dev/null; then
            printf '%s' "$stem ($parent) $i"; return 0
        fi
        i=$((i + 1))
        [ "$i" -gt 999 ] && return 1
    done
}

_copy_library_originals() {
    local lib="$1" dest_root="$2"
    local copied=0 copied_rd=0 skipped=0 cp_failures=0
    _lib_copied=0
    _lib_skipped=0
    local originals_root="$lib/originals"
    [ -d "$originals_root" ] || originals_root="$lib/Masters"
    if [ ! -d "$originals_root" ]; then
        log_warn "No originals/ tree in $lib (nothing to copy)"
        return 0
    fi
    local recently_deleted_root
    recently_deleted_root="$dest_root/Recently Deleted"
    local _photos_db_c="$lib/database/Photos.sqlite"
    if [ -f "$_photos_db_c" ]; then
        local _snap_c _tu
        _snap_c="$(snapshot_db "$_photos_db_c" 2>/dev/null)" || _snap_c=""
        if [ -n "$_snap_c" ]; then
            while IFS= read -r _tu; do
                [ -n "$_tu" ] && printf -v "_trk_${_tu//-/_}" '%s' 1
            done < <(sqlite3 -readonly "$_snap_c" \
                "SELECT ZUUID FROM ZASSET WHERE COALESCE(ZTRASHEDSTATE,0)!=0;" 2>/dev/null)
        else
            log_warn "Could not snapshot Photos.sqlite for the Recently-Deleted split — any trashed originals still on disk will be copied as live photos. Re-run if this library matters."
            note_incomplete "$_PHOTOS_DIR" "Photos library Recently-Deleted split: $(basename "$lib")" \
                "the trashed-asset snapshot could not be built, so Recently-Deleted originals (if any) are not separated into Recently Deleted/ and may appear in the live [assets] inventory"
        fi
    fi
    log_info "Counting files to copy..."
    local _count=0 _kb=0 _c=0 _kb_partial=0
    _count_scope() {
        local _r="$1"
        [ -d "$_r" ] || { printf '0 0'; return; }
        local _first
        find "$_r" -type f "${_PL_OWN_FIND_PRUNE[@]}" \
            -print0 2>/dev/null \
        | {
            if IFS= read -r -d '' _first; then
                { printf '%s\0' "$_first"; cat; } \
                  | xargs -0 stat -f '%z' 2>/dev/null \
                  | awk 'BEGIN { c=0; s=0 } { c++; s += $1 } END { printf "%d %d", c, int(s/1024) }'
            else
                printf '0 0'
            fi
        }
    }
    _c=0; _kb_partial=0
    read -r _c _kb_partial < <(_count_scope "$originals_root")
    _count=$((_count + ${_c:-0})); _kb=$((_kb + ${_kb_partial:-0}))
    local _gb=$((_kb / 1048576))
    mark_activity
    local _lib_dir _lib_stem
    _lib_dir="$dest_root"
    _lib_stem="$(basename "$_lib_dir")"
    local _avail_kb _need_kb
    local _df_out
    _df_out="$(df -P -k "$_lib_dir" 2>/dev/null)"
    if [ -z "$_df_out" ]; then
        log_warn "Cannot determine available disk space on $_lib_dir (df failed — stale mount or permission issue?)"
        log_warn "Skipping $lib originals copy."
        _write_skipped_marker_dffail "$_lib_dir" "$_lib_stem" "$lib" "$_count"
        _lib_copied=0
        _lib_skipped=0
        return 0
    fi
    _avail_kb="$(printf '%s\n' "$_df_out" | awk 'END{print $4}')"
    case "$_avail_kb" in ''|*[!0-9]*) _avail_kb=0 ;; esac
    _need_kb=$((_kb + PHOTOS_PERLIB_HEADROOM_MB * 1024))
    local _avail_gb
    _avail_gb=$((_avail_kb / 1048576))
    if [ "$_avail_kb" -lt "$_need_kb" ]; then
        local _mb=$((_kb / 1024)) _avail_mb=$((_avail_kb / 1024))
        local _need_disp _avail_disp
        if [ "$_gb" -gt 0 ]; then _need_disp="~${_gb} GB"
        elif [ "$_mb" -gt 0 ]; then _need_disp="~${_mb} MB"
        else _need_disp="~${_kb} KB"; fi
        if [ "$_avail_gb" -gt 0 ]; then _avail_disp="~${_avail_gb} GB"
        elif [ "$_avail_mb" -gt 0 ]; then _avail_disp="~${_avail_mb} MB"
        else _avail_disp="~${_avail_kb} KB"; fi
        log_warn "Insufficient disk space for $lib originals copy."
        log_warn "Need ${_need_disp}; only ${_avail_disp} available on the export volume."
        log_warn "Skipping copy and continuing$(_disclosure_pointer)."
        _write_skipped_marker_diskspace "$_lib_dir" "$_lib_stem" "$lib" \
            "$_gb" "$_count" "$_avail_gb"
        _PL_COPY_DF_SKIPPED=1
        _lib_copied=0
        _lib_skipped=0
        return 0
    fi
    if [ "$_count" -gt 0 ]; then
        local _mb=$((_kb / 1024))
        local _size_disp
        if [ "$_gb" -gt 0 ]; then
            _size_disp="~${_gb} GB"
        elif [ "$_mb" -gt 0 ]; then
            _size_disp="~${_mb} MB"
        else
            _size_disp="~${_kb} KB"
        fi
        log_info "Copying $_count $(_pluralize "$_count" file), $_size_disp total (export volume: ~${_avail_gb} GB free)..."
        if ( : </dev/tty >/dev/tty ) 2>/dev/null; then
            log_info "(press 's' to skip the rest of this library's copy phase)"
        fi
    fi
    if [ ! -d "$dest_root" ]; then
        log_warn "Library export dir missing: $dest_root (skipping copy)"
        return 1
    fi
    local _copy_start_seconds=$SECONDS
    local _copied_bytes_total=0
    local _tick_inline=0
    _copy_walk() {
        local root="$1" rel_prefix="$2"
        [ -d "$root" ] || return 0
        local f rel target target_dir _size
        local _last_tick="$SECONDS"
        local _tick_interval=5
        while IFS= read -r -d '' f; do
            rel="${f##*/}"
            if should_skip_copy "$f" "$rel"; then
                skipped=$((skipped + 1))
                continue
            fi
            local _walk_uuid _walk_tref _to_rd=0
            _walk_uuid="${rel%.*}"; _walk_uuid="${_walk_uuid%_*}"
            _walk_tref="_trk_${_walk_uuid//-/_}"
            if [ -n "${!_walk_tref:-}" ]; then
                target="$recently_deleted_root/$rel"; _to_rd=1
            else
                local _walk_catdir; _pl_category_into "$_walk_uuid" _walk_catdir; rel="$_walk_catdir/$rel"
                target="$dest_root/$rel"
            fi
            target_dir="${target%/*}"
            if ! mkdir -p "$target_dir" 2>/dev/null; then
                [ "$_tick_inline" = "1" ] && { printf '\n'; _tick_inline=0; }
                log_warn "mkdir failed: $rel"
                cp_failures=$((cp_failures + 1))
                continue
            fi
            if [ -e "$target" ]; then
                local _cstem _cext _cn=2
                case "${target##*/}" in
                    *.*) _cstem="${target%.*}"; _cext="${target##*.}" ;;
                    *)   _cstem="$target";      _cext="" ;;
                esac
                while [ -e "$target" ] && [ "$_cn" -lt 1000 ]; do
                    if [ -n "$_cext" ]; then target="${_cstem}_${_cn}.${_cext}"; else target="${_cstem}_${_cn}"; fi
                    _cn=$((_cn + 1))
                done
                rel="${target#"$dest_root"/}"
                [ "$_tick_inline" = "1" ] && { printf '\n'; _tick_inline=0; }
                log_warn "originals basename collision after hex-flatten (corrupt/non-standard library?) — kept as $rel"
            fi
            _size="$(stat -f '%z' "$f" 2>/dev/null)"
            case "$_size" in ''|*[!0-9]*) _size=0 ;; esac
            if [ -e "$target" ]; then
                [ "$_tick_inline" = "1" ] && { printf '\n'; _tick_inline=0; }
                log_warn "Copy refused: destination already exists: $rel"
                cp_failures=$((cp_failures + 1))
            elif ditto -- "$f" "$target" 2>/dev/null \
                 && [ -s "$target" ] \
                 && ! _materialized_copy_incomplete "$_size" "$target"; then
                copied=$((copied + 1))
                [ "$_to_rd" = 1 ] && copied_rd=$((copied_rd + 1))
                _copied_bytes_total=$((_copied_bytes_total + _size))
                local _cd_ref="_capdate_${_walk_uuid//-/_}"; _apply_touch_t "${!_cd_ref:-}" "$target"
            else
                [ "$_tick_inline" = "1" ] && { printf '\n'; _tick_inline=0; }
                log_warn "Copy failed: $rel"
                rm -f -- "$target" 2>/dev/null
                cp_failures=$((cp_failures + 1))
            fi
            if [ $((SECONDS - _last_tick)) -ge "$_tick_interval" ]; then
                local _eta_suffix=""
                local _copy_elapsed=$((SECONDS - _copy_start_seconds))
                if [ "$_kb" -gt 0 ] \
                   && [ "$_copied_bytes_total" -gt 1073741824 ] \
                   && [ "$_copy_elapsed" -ge 5 ]; then
                    local _total_bytes=$((_kb * 1024))
                    local _remaining=$((_total_bytes - _copied_bytes_total))
                    if [ "$_remaining" -gt 0 ]; then
                        local _eta_s=$((_remaining * _copy_elapsed / _copied_bytes_total))
                        _eta_suffix=" (ETA $(_fmt_duration "$_eta_s"))"
                    fi
                fi
                if [ "$_count" -gt 0 ]; then
                    if [ -t 1 ]; then
                        printf '\r  ... %s/%s copied%s\033[K' \
                            "$copied" "$_count" "$_eta_suffix"
                        _tick_inline=1
                    else
                        log_info "... $copied/$_count copied$_eta_suffix"
                    fi
                else
                    if [ -t 1 ]; then
                        printf '\r  ... %s copied\033[K' "$copied"
                        _tick_inline=1
                    else
                        log_info "... $copied copied"
                    fi
                fi
                _last_tick=$SECONDS
                mark_activity
            fi
            if [ "$_SKIP_REQUESTED" = "1" ]; then
                [ "$_tick_inline" = "1" ] && { printf '\n'; _tick_inline=0; }
                return 0
            fi
        done < <(find "$root" -type f "${_PL_OWN_FIND_PRUNE[@]}" \
                    -print0 2>/dev/null)
        [ "$_tick_inline" = "1" ] && { printf '\n'; _tick_inline=0; }
    }
    _copy_walk "$originals_root" ""
    local _own_dirs=("$dest_root/Not Shared" "$dest_root/Shared by Me" "$dest_root/Shared with You")
    local _ced
    for _ced in "${_own_dirs[@]}" "$recently_deleted_root" "$dest_root/Recently Deleted"; do
        [ -d "$_ced" ] && cleanup_empty_dirs "$_ced"
    done
    if [ "$_SKIP_REQUESTED" = "1" ]; then
        log_warn "Skipped rest of originals copy on user request (kept $copied $(_pluralize "$copied" file); removing partial tree)"
        _write_skipped_marker_user "$_lib_dir" "$_lib_stem" "$lib" \
            "originals copy" "$copied" "$_count"
        local _rm_d _rm_fail=0
        for _rm_d in "${_own_dirs[@]}" "$dest_root/Recently Deleted"; do
            [ -d "$_rm_d" ] || continue
            chmod -R u+w "$_rm_d" 2>/dev/null || true
            rm -rf -- "$_rm_d" 2>/dev/null || _rm_fail=1
        done
        if [ "$_rm_fail" = "1" ]; then
            log_warn "Skip cleanup: rm -rf of the partial own-photo tree under $dest_root failed (likely Spotlight indexer or open file handle) — partial originals may remain on disk."
            note_incomplete "$_lib_dir" \
                "$_lib_stem partial originals tree" \
                "you pressed 's' to skip this library's originals copy, but rm -rf of the partial own-photo tree under $dest_root failed (likely a Spotlight indexer holding a file open, or a transient permission issue). Inspect and remove manually if needed."
        fi
        copied=0
        _PL_COPY_USER_SKIPPED=1
        _SKIP_REQUESTED=0
    elif [ "$copied" -gt 0 ]; then
        local _copied_orig=$(( copied - copied_rd ))
        if [ "$_copied_orig" -gt 0 ]; then
            local _own_sz; _own_sz="$(du -shc "${_own_dirs[@]}" 2>/dev/null | awk 'END{print $1}')"; [ -n "$_own_sz" ] || _own_sz="0"
            log_ok "Copied $_copied_orig $(_pluralize "$_copied_orig" original) to Photos/Libraries/$_lib_stem/ (Not Shared / Shared by Me / Shared with You; $_own_sz)"
        fi
        [ "$copied_rd" -gt 0 ] && log_ok "Copied $copied_rd $(_pluralize "$copied_rd" file) to Photos/Libraries/$_lib_stem/Recently Deleted/ ($(_dir_size_human "$recently_deleted_root"))"
    elif [ "$_count" -gt 0 ]; then
        log_warn "0 of $_count $(_pluralize "$_count" file) copied (every file filtered or failed)"
    fi
    if [ "$_SKIP_REQUESTED" != "1" ] && [ "$cp_failures" -gt 0 ]; then
        log_warn "$cp_failures $(_pluralize "$cp_failures" file) failed to copy (mkdir/cp error) in $_lib_stem"
        note_incomplete "$_lib_dir" "Originals copy: $_lib_stem" \
            "$cp_failures $(_pluralize "$cp_failures" file) failed to copy (mkdir or cp error — disk, permissions, or filesystem fault); the own-photo folders for this library are missing those files"
    fi
    if [ "$_SKIP_REQUESTED" != "1" ]; then
        validate_count_parity "$_count" \
            "$((copied + skipped + cp_failures))" \
            "Photos originals: $_lib_stem" "$_lib_dir"
    fi
    _lib_copied=$copied
    _lib_skipped=$skipped
    return 0
}

_pl_count_cached_shares() {
    local lib="$1" n=0
    [ -d "$lib/scopes/cloudsharing" ] || { printf 0; return; }
    n="$(find "$lib/scopes/cloudsharing" -type f "${_PL_SCOPE_FIND_PRUNE[@]}" -print0 \
            2>/dev/null | grep -zcE '/[0-9A-Fa-f]{8}-[0-9A-Fa-f-]+\.[^/]+$')"
    case "$n" in ''|*[!0-9]*) n=0 ;; esac
    printf '%s' "$n"
}

_pl_copy_cached_shares() {
    local lib="$1" lib_dir="$2"
    local _dest="$lib_dir/Shared Albums (cached)"
    mkdir -p "$_dest" 2>/dev/null || { printf 0; return; }
    local _copied=0 _f _bn _t
    while IFS= read -r -d '' _f; do
        [ -f "$_f" ] || continue
        _bn="${_f##*/}"; _t="$_dest/$_bn"
        [ -e "$_t" ] && _t="$(_unique_path "$_t")"
        if ditto -- "$_f" "$_t" 2>/dev/null; then _copied=$((_copied + 1)); else rm -f -- "$_t" 2>/dev/null; fi
    done < <(find "$lib/scopes/cloudsharing" -type f "${_PL_SCOPE_FIND_PRUNE[@]}" -print0 2>/dev/null \
                | grep -zE '/[0-9A-Fa-f]{8}-[0-9A-Fa-f-]+\.[^/]+$')
    if [ "$_copied" -gt 0 ]; then
        report_review "$(_report_subject "$_dest")" "extra shared photos (bonus copy)" \
            "$_copied photo(s) from iCloud Shared Albums were still cached in this library, so we copied them to its \"Shared Albums (cached)\" folder as a bonus — nothing you need to do. A few cloud-only ones may be missing, and album names and comments aren't included."
    else
        rmdir "$_dest" 2>/dev/null
    fi
    printf '%s' "$_copied"
}

_pl_enumerate_assets() {
    local snap="$1" lib="$2"
    sqlite3 -bail -readonly -separator $'\x1f' "$snap" "
        SELECT a.Z_PK, a.ZUUID,
               $(_sql_tsv_safe "COALESCE(a.ZDIRECTORY, '')"),
               $(_sql_tsv_safe "COALESCE(a.ZFILENAME, '')"),
               COALESCE(a.ZFAVORITE, 0),
               $(_sql_tsv_safe aa.ZORIGINALFILENAME),
               COALESCE(a.ZSAVEDASSETTYPE, 0),
               COALESCE(a.ZHIDDEN, 0),
               COALESCE(a.ZTRASHEDSTATE, 0)
          FROM ZASSET a
          LEFT JOIN ZADDITIONALASSETATTRIBUTES aa ON aa.ZASSET = a.Z_PK
         ORDER BY a.Z_PK;
    " > "$SCRATCH_DIR/assets.tsv" 2>/dev/null
}

_pl_build_uuid_map() {
    LC_ALL=C awk -F$'\x1f' -v OFS='\t' '{print $2, $6}' \
        "$SCRATCH_DIR/assets.tsv" | LC_ALL=C sort -t$'\t' -k1,1 \
        > "$SCRATCH_DIR/uuid_meta.tsv"
    LC_ALL=C awk -F'\t' -v OFS='\t' '{print $1, $2, ""}' \
        "$SCRATCH_DIR/uuid_meta.tsv" > "$SCRATCH_DIR/uuid_lookup.tsv"
    local _ul_lines _as_lines
    _ul_lines=$(_count_lines "$SCRATCH_DIR/uuid_lookup.tsv")
    _as_lines=$(_count_lines "$SCRATCH_DIR/assets.tsv")
    if [ "$_ul_lines" -ne "$_as_lines" ]; then
        log_warn "uuid_lookup.tsv has $_ul_lines rows; expected $_as_lines (from assets.tsv) — scratch volume may have run short of space; some original filenames may be missing from the manifest"
    fi
}

_pl_materialize_albums() {
    local lib_dir="$1"
    [ -s "$SCRATCH_DIR/report_albums.body" ] || return 0
    [ -s "$SCRATCH_DIR/report_assets.body" ] || return 0
    LC_ALL=C awk -F'\t' -v OFS='\t' '
        NR==FNR { if ($1 != "" && $1 !~ /^#/) { rel[$1]=$4; orig[$1]=$2 } next }
        ($1 ~ /^#/) { next }
        ($3 in rel) { print $2, rel[$3], orig[$3] }
    ' "$SCRATCH_DIR/report_assets.body" "$SCRATCH_DIR/report_albums.body" \
        > "$SCRATCH_DIR/albums_materialize.tsv" 2>/dev/null || return 0
    [ -s "$SCRATCH_DIR/albums_materialize.tsv" ] || return 0
    local _alb_root="$lib_dir/Not Shared/Albums"
    local _n_copied=0 _n_fail=0
    local _apath _rel _orig _src _dstdir _dst _seg _safe _base _ext _n _oldifs _apath_noglob
    while IFS=$'\t' read -r _apath _rel _orig; do
        [ -n "$_apath" ] && [ -n "$_rel" ] && [ -n "$_orig" ] || continue
        _src="$lib_dir/$_rel"
        [ -f "$_src" ] || continue
        _dstdir="$_alb_root"
        _apath_noglob=0; case "$-" in *f*) _apath_noglob=1 ;; esac
        _oldifs="$IFS"; IFS='/'; set -f
        for _seg in $_apath; do
            [ -n "$_seg" ] || continue
            _safe="$(_sanitize_name "$_seg")"
            [ -z "$_safe" ] && _safe="_"
            _dstdir="$_dstdir/$_safe"
        done
        IFS="$_oldifs"; [ "$_apath_noglob" = "0" ] && set +f
        mkdir -p "$_dstdir" 2>/dev/null || { _n_fail=$((_n_fail + 1)); continue; }
        _dst="$_dstdir/$(_sanitize_name "$_orig")"
        case "$_dst" in */) _dst="$_dst${_src##*/}" ;; esac
        if [ -e "$_dst" ]; then
            case "${_dst##*/}" in
                *.*) _base="${_dst%.*}"; _ext=".${_dst##*.}" ;;
                *)   _base="$_dst";      _ext="" ;;
            esac
            _n=2
            while [ -e "${_base}_${_n}${_ext}" ]; do _n=$((_n + 1)); done
            _dst="${_base}_${_n}${_ext}"
        fi
        if ditto "$_src" "$_dst" 2>/dev/null; then
            _n_copied=$((_n_copied + 1))
        else
            _n_fail=$((_n_fail + 1))
            rm -f "$_dst" 2>/dev/null
        fi
    done < "$SCRATCH_DIR/albums_materialize.tsv"
    [ -d "$_alb_root" ] && cleanup_empty_dirs "$_alb_root" 2>/dev/null
    rmdir "$_alb_root" 2>/dev/null || true
    rmdir "$lib_dir/Not Shared" 2>/dev/null || true
    if [ "$_n_copied" -gt 0 ]; then
        local _n_albums
        _n_albums="$(LC_ALL=C cut -f1 "$SCRATCH_DIR/albums_materialize.tsv" \
            | LC_ALL=C sort -u | grep -c .)"
        log_ok "Copied $_n_copied $(_pluralize "$_n_copied" file) into $_n_albums local $(_pluralize "$_n_albums" album) under Not Shared/Albums/ (duplicates of assets already in the category folders)"
    fi
    [ "$_n_fail" -gt 0 ] && \
        log_warn "$_n_fail album-folder $(_pluralize "$_n_fail" copy copies) into Not Shared/Albums/ failed"
    return 0
}

_pl_materialize_favorites() {
    local lib_dir="$1"
    [ -s "$SCRATCH_DIR/report_favorites.body" ] || return 0
    [ -s "$SCRATCH_DIR/report_assets.body" ] || return 0
    LC_ALL=C awk -F'\t' -v OFS='\t' '
        NR==FNR { if ($1 != "" && $1 !~ /^#/) { rel[$1]=$4; orig[$1]=$2 } next }
        ($1 in rel) { print rel[$1], orig[$1] }
    ' "$SCRATCH_DIR/report_assets.body" "$SCRATCH_DIR/report_favorites.body" \
        > "$SCRATCH_DIR/favorites_materialize.tsv" 2>/dev/null || return 0
    [ -s "$SCRATCH_DIR/favorites_materialize.tsv" ] || return 0
    local _fav_root="$lib_dir/Favorites"
    local _n_copied=0 _n_fail=0 _rel _orig _src _dst _base _ext _n
    while IFS=$'\t' read -r _rel _orig; do
        [ -n "$_rel" ] && [ -n "$_orig" ] || continue
        _src="$lib_dir/$_rel"
        [ -f "$_src" ] || continue
        mkdir -p "$_fav_root" 2>/dev/null || { _n_fail=$((_n_fail + 1)); continue; }
        _dst="$_fav_root/$(_sanitize_name "$_orig")"
        case "$_dst" in */) _dst="$_dst${_src##*/}" ;; esac
        if [ -e "$_dst" ]; then
            case "${_dst##*/}" in
                *.*) _base="${_dst%.*}"; _ext=".${_dst##*.}" ;;
                *)   _base="$_dst";      _ext="" ;;
            esac
            _n=2
            while [ -e "${_base}_${_n}${_ext}" ]; do _n=$((_n + 1)); done
            _dst="${_base}_${_n}${_ext}"
        fi
        if ditto "$_src" "$_dst" 2>/dev/null; then
            _n_copied=$((_n_copied + 1))
        else
            _n_fail=$((_n_fail + 1)); rm -f "$_dst" 2>/dev/null
        fi
    done < "$SCRATCH_DIR/favorites_materialize.tsv"
    [ -d "$_fav_root" ] && cleanup_empty_dirs "$_fav_root" 2>/dev/null
    rmdir "$_fav_root" 2>/dev/null || true
    [ "$_n_copied" -gt 0 ] && \
        log_ok "Copied $_n_copied favorited $(_pluralize "$_n_copied" file) into Favorites/ (duplicates of assets already in the category folders)"
    [ "$_n_fail" -gt 0 ] && \
        log_warn "$_n_fail favorite-folder $(_pluralize "$_n_fail" copy copies) into Favorites/ failed"
    return 0
}

_pl_build_report() {
    local lib="$1" out_file="$2" tag="$3"   # tag = "system" or "other"
    local photos_db="$lib/database/Photos.sqlite"
    [ -f "$photos_db" ] || {
        log_warn "Photos database not found in $lib (skipping)"
        note_incomplete "$_PHOTOS_DIR" "Photos library: $(basename "$lib")" \
            "the library's Photos.sqlite database was not found — this library could not be read (no .report or evicted-original download)"
        return 1
    }
    local snap
    snap="$(snapshot_db "$photos_db")" || {
        log_warn "Cannot snapshot $lib (skipping)"
        note_incomplete "$_PHOTOS_DIR" "Photos library: $(basename "$lib")" \
            "the library's Photos.sqlite database could not be snapshotted for reading — this library could not be read (no .report or evicted-original download)"
        return 1
    }
    local _uncaptured_shares=0 _cached_captured=0
    if [ "$tag" = "other" ]; then
        _uncaptured_shares="$(_pl_count_cached_shares "$lib")"
        if [ "${_uncaptured_shares:-0}" -gt 0 ]; then
            if [ "${PHOTO_LIBRARY_COPY:-no}" = "yes" ]; then
                _cached_captured="$(_pl_copy_cached_shares "$lib" "${out_file%/*}")"
                log_info "  Copied $_cached_captured extra shared-album $(_pluralize "$_cached_captured" photo) cached in this library to Shared Albums (cached)/ as a bonus (a few may be missing)."
            else
                log_info "  Note: this library has $_uncaptured_shares extra shared-album $(_pluralize "$_uncaptured_shares" photo) cached in it that this report-only run does not copy — re-run with --other-libraries (or PHOTOS_OTHER_COPY=yes) to include them."
            fi
        fi
    fi
    mark_activity
    log_info "Reading library metadata (assets)..."
    if ! _pl_enumerate_assets "$snap" "$lib"; then
        log_warn "Could not read the photo list for $lib (skipping)"
        note_incomplete "$_PHOTOS_DIR" "Photos library: $(basename "$lib")" \
            "the asset-enumeration query against the library database failed — this library could not be read (no .report or evicted-original download)"
        return 1
    fi
    local tmp_out
    tmp_out="$(mktemp "$out_file.tmp.XXXXXX")" || { log_warn "Cannot create temp file for $(basename "$out_file")"; return 1; }
    track_output_path "$tmp_out"
    : > "$tmp_out"
    {
        _photos_report_header "$lib"
        if [ "${_PL_COPY_DF_SKIPPED:-0}" = "1" ]; then
            printf '# originals_in_export: no (copy skipped — insufficient disk space; rows below are cataloged from the source library, not copied into this export)\n'
        elif [ "${_PL_COPY_USER_SKIPPED:-0}" = "1" ]; then
            printf '# originals_in_export: no (copy skipped on user request; rows below are cataloged from the source library, not copied into this export)\n'
        fi
        printf '\n'
    } >> "$tmp_out"
    local originals_root="$lib/originals"
    [ -d "$originals_root" ] || originals_root="$lib/Masters"
    _pl_build_uuid_map
    mark_activity
    if [ "$PHOTO_LIBRARY_REPORT" != "yes" ]; then
        log_info "Checking which originals actually landed (no .report requested — this pass only finds what's missing)..."
    else
        log_info "Counting originals to hash (walking the library tree)..."
    fi
    local _total_count=0 _total_kb=0 _r _r_count _r_kb
    local -a _hash_roots=( "$originals_root" )
    for _r in "${_hash_roots[@]}"; do
        [ -d "$_r" ] || continue
        _r_count="$(find "$_r" -type f "${_PL_OWN_FIND_PRUNE[@]}" \
            -print0 2>/dev/null | tr -dc '\0' | wc -c | tr -d ' ')"
        case "$_r_count" in ''|*[!0-9]*) _r_count=0 ;; esac
        if [ "$_r_count" -gt 0 ]; then
            _r_kb="$(find "$_r" -type f "${_PL_OWN_FIND_PRUNE[@]}" \
                -print0 2>/dev/null \
                | xargs -0 stat -f '%z' 2>/dev/null \
                | awk 'BEGIN{s=0} {s+=$1} END{printf "%d", int(s/1024)}')"
        else
            _r_kb=0
        fi
        case "$_r_kb" in ''|*[!0-9]*) _r_kb=0 ;; esac
        _total_count=$((_total_count + _r_count))
        _total_kb=$((_total_kb + _r_kb))
    done
    local _total_gb=$((_total_kb / 1048576))
    if [ "$_total_count" -gt 0 ]; then
        local _total_mb=$((_total_kb / 1024))
        if [ "$_total_gb" -gt 0 ]; then
            log_info "Hashing $_total_count $(_pluralize "$_total_count" file), ~${_total_gb} GB total..."
        elif [ "$_total_mb" -gt 0 ]; then
            log_info "Hashing $_total_count $(_pluralize "$_total_count" file), ~${_total_mb} MB total..."
        else
            log_info "Hashing $_total_count $(_pluralize "$_total_count" file), ~${_total_kb} KB total..."
        fi
        if ( : </dev/tty >/dev/tty ) 2>/dev/null; then
            log_info "(press 's' to skip the rest of this library's hash phase)"
        fi
    fi
    local emitted_originals=0
    local _hash_start_seconds=$SECONDS
    local _hashed_bytes_total=0
    : > "$SCRATCH_DIR/report_ondisk.tsv"
    _walk_assets() {
        local root="$1" rel_prefix="$2"
        [ -d "$root" ] || return 0
        local f rel uuid origname flags size mtime md5 _stat_pair
        local _last_tick="$SECONDS"
        local _tick_interval=5
        local _walk_in
        _walk_in="$(mktemp "$SCRATCH_DIR/walk_in.XXXXXX")" \
            || _walk_in="$SCRATCH_DIR/walk_in.$$.$RANDOM"
        local _md5_lookup="" _walk_count
        LC_ALL=C find "$root" -type f "${_PL_OWN_FIND_PRUNE[@]}" \
                    -print0 2>/dev/null \
              | LC_ALL=C tr '\0' '\n' \
              | LC_ALL=C awk -v OFS='\t' \
                  -v lookup="$SCRATCH_DIR/uuid_lookup.tsv" '
                BEGIN {
                    while ((getline line < lookup) > 0) {
                        n = split(line, f, "\t")
                        origname[f[1]] = (n >= 2 ? f[2] : "")
                        flags[f[1]]    = (n >= 3 ? f[3] : "")
                    }
                    close(lookup)
                }
                {
                    full = $0
                    if (full == "") next
                    gsub(/\n/, " ", full)
                    bn = full; sub(/.*\//, "", bn)
                    uuid = bn; sub(/\..*$/, "", uuid)
                    print full, uuid, origname[uuid], flags[uuid]
                }' > "$_walk_in" 2>/dev/null
        _walk_count="$(_count_lines "$_walk_in")"
        if [ "$_walk_count" -ge 2000 ]; then
            _md5_lookup="$(mktemp "$SCRATCH_DIR/walk_md5.XXXXXX" 2>/dev/null)" \
                || _md5_lookup="$SCRATCH_DIR/walk_md5.$$.$RANDOM"
            local _md5_batch=() _md5_bp _MD5_BATCH=100
            while IFS= read -r _md5_bp; do
                _md5_batch+=( "$_md5_bp" )
                if [ "${#_md5_batch[@]}" -ge "$_MD5_BATCH" ]; then
                    md5 "${_md5_batch[@]}" 2>/dev/null \
                        | _photos_parse_md5_lines >> "$_md5_lookup"
                    _md5_batch=()
                    [ "$_SKIP_REQUESTED" = "1" ] && break
                fi
            done < <(awk -F'\t' '{ print $1 }' "$_walk_in" 2>/dev/null)
            if [ "${#_md5_batch[@]}" -gt 0 ] && [ "$_SKIP_REQUESTED" != "1" ]; then
                md5 "${_md5_batch[@]}" 2>/dev/null \
                    | _photos_parse_md5_lines >> "$_md5_lookup"
            fi
            local _walk_in_joined
            _walk_in_joined="$(mktemp "$SCRATCH_DIR/walk_joined.XXXXXX" 2>/dev/null)" \
                || _walk_in_joined="$SCRATCH_DIR/walk_joined.$$.$RANDOM"
            awk -F'\t' -v lookup="$_md5_lookup" '
                BEGIN {
                    while ((getline line < lookup) > 0) {
                        n = split(line, lf, "\t")
                        if (n >= 2) md5[lf[1]] = lf[2]
                    }
                    close(lookup)
                }
                { print $0 "\t" md5[$1] }
            ' "$_walk_in" > "$_walk_in_joined"
            mv -f -- "$_walk_in_joined" "$_walk_in"
            rm -f -- "$_md5_lookup" 2>/dev/null
        fi
        local _tick_inline=0
        local _precomputed_md5
        while IFS=$'\t' read -r f uuid origname flags _precomputed_md5; do
            [ -z "$f" ] && continue
            rel="${f##*/}"
            local _wa_parent="${uuid%_*}"
            local _wa_catdir; _pl_category_into "$_wa_parent" _wa_catdir; rel="$_wa_catdir/$rel"
            should_skip_copy "$f" "$rel" && continue
            _stat_pair="$(stat -f '%z %m' "$f" 2>/dev/null)"
            size="${_stat_pair%% *}"
            mtime="${_stat_pair##* }"
            if [ -n "$_precomputed_md5" ]; then
                md5="$_precomputed_md5"
            else
                md5="$(_md5_hex "$f")"
            fi
            if [ -z "$md5" ]; then
                [ "$_tick_inline" = "1" ] && { printf '\n'; _tick_inline=0; }
                log_warn "MD5 failed: $rel."
                printf '%s\t%s\t%s\t%s\t%s\n' \
                    "$uuid" "$rel" "$size" "$mtime" "" >> "$SCRATCH_DIR/report_ondisk.tsv"
                continue
            fi
            printf '%s\t%s\t%s\t%s\t%s\n' \
                "$uuid" "$rel" "$size" "$mtime" "$md5" >> "$SCRATCH_DIR/report_ondisk.tsv"
            emitted_originals=$((emitted_originals + 1))
            case "$size" in
                ''|*[!0-9]*) ;;
                *) _hashed_bytes_total=$((_hashed_bytes_total + size)) ;;
            esac
            if [ $((SECONDS - _last_tick)) -ge "$_tick_interval" ]; then
                if [ "$_total_count" -gt 0 ]; then
                    local _eta_suffix=""
                    local _hash_elapsed=$((SECONDS - _hash_start_seconds))
                    if [ "$_total_kb" -gt 0 ] \
                       && [ "$_hashed_bytes_total" -gt 1073741824 ] \
                       && [ "$_hash_elapsed" -ge 5 ]; then
                        local _total_bytes=$((_total_kb * 1024))
                        local _remaining=$((_total_bytes - _hashed_bytes_total))
                        if [ "$_remaining" -gt 0 ]; then
                            local _eta_s=$((_remaining * _hash_elapsed / _hashed_bytes_total))
                            _eta_suffix=" (ETA $(_fmt_duration "$_eta_s"))"
                        fi
                    fi
                    if [ -t 1 ]; then
                        printf '\r  ... %s/%s hashed%s\033[K' \
                            "$emitted_originals" "$_total_count" "$_eta_suffix"
                        _tick_inline=1
                    else
                        log_info "... $emitted_originals/$_total_count hashed$_eta_suffix"
                    fi
                else
                    if [ -t 1 ]; then
                        printf '\r  ... %s hashed\033[K' "$emitted_originals"
                        _tick_inline=1
                    else
                        log_info "... $emitted_originals hashed"
                    fi
                fi
                _last_tick=$SECONDS
                mark_activity
            fi
            if [ "$_SKIP_REQUESTED" = "1" ]; then
                [ "$_tick_inline" = "1" ] && { printf '\n'; _tick_inline=0; }
                rm -f -- "$_walk_in" 2>/dev/null
                return 0
            fi
        done < "$_walk_in"
        rm -f -- "$_walk_in" 2>/dev/null
        [ "$_tick_inline" = "1" ] && { printf '\n'; _tick_inline=0; }
    }
    _walk_assets "$originals_root" ""
    [ "$emitted_originals" -eq 0 ] && log_warn "No own-library original files found in $lib"
    log_info "Hashed $emitted_originals $(_pluralize "$emitted_originals" file)"
    if [ "$_SKIP_REQUESTED" = "1" ]; then
        log_warn "Skipped rest of asset hashing on user request (kept $emitted_originals $(_pluralize "$emitted_originals" row); .report will not be written)"
        local _lib_dir _lib_stem
        _lib_dir="$(dirname "$out_file")"
        _lib_stem="$(basename "$_lib_dir")"
        _write_skipped_marker_user "$_lib_dir" "$_lib_stem" "$lib" \
            "asset hashing" "$emitted_originals" "$_total_count"
        rm -f -- "$tmp_out" 2>/dev/null || true
        _untrack_output_path "$tmp_out"   # tracked above; drop it like the report-off path does
        _SKIP_REQUESTED=0
        _PL_REPORT_SKIPPED=1
        return 1
    fi
    _pl_download_evicted "$(dirname "$out_file")"
    _pl_disclose_evicted_gap
    if [ "$PHOTO_LIBRARY_REPORT" != "yes" ]; then
        rm -f -- "$tmp_out" 2>/dev/null || true
        _untrack_output_path "$tmp_out"
        return 0
    fi
    mark_activity
    log_info "Building manifest (assets + Recently Deleted)..."
    {
        printf '[assets]\n'
        printf '# asset_uuid\toriginal_filename\tstatus\trel_path\tsize\thash\tflags\tcompanions\tcapture_date\n'
        printf '# One row per file copied into this library'\''s category folders — Not Shared / Shared by Me / Shared with You (your own photos). status is always on-disk — only files actually present are listed. Shared-album / Shared-with-You / shared-moment content lives in scopes/ and is never copied here; Recently Deleted assets are in the [trashed] section.\n'
        printf '# companions: extra on-disk resource files belonging to this asset (Live Photo motion video, etc.), each as rel_path|size|md5, ;-separated; empty when none. The primary master is the asset row above; companions are also copied into the same category folder'\''. The flags column is reserved (downpour-photos-report v1 shape) and left empty by this manifest.\n'
    } >> "$tmp_out"
    LC_ALL=C awk -F$'\x1f' '$9!="" && $9!="0"{print $2}' \
        "$SCRATCH_DIR/assets.tsv" 2>/dev/null | LC_ALL=C sort -u \
        > "$SCRATCH_DIR/trashed.set"
    : > "$SCRATCH_DIR/report_trashed.body"
    LC_ALL=C awk -F'\t' -v OFS='\t' \
        -v meta="$SCRATCH_DIR/uuid_meta.tsv" \
        -v trashed="$SCRATCH_DIR/trashed.set" \
        -v downloaded="$SCRATCH_DIR/downloaded.set" \
        -v capmeta="$SCRATCH_DIR/class.tsv" \
        -v trashed_file="$SCRATCH_DIR/report_trashed.body" '
        BEGIN {
            while ((getline l < meta) > 0) {
                n = split(l, m, "\t"); orig[m[1]] = (n >= 2 ? m[2] : "")
            }
            close(meta)
            while ((getline t < trashed) > 0) { if (t != "") tr[t] = 1 }
            close(trashed)
            while ((getline d < downloaded) > 0) { if (d != "") dl[d] = 1 }
            close(downloaded)
            while ((getline c < capmeta) > 0) {
                cn = split(c, cm, "\t"); if (cn >= 4) cap[cm[1]] = cm[4]
            }
            close(capmeta)
        }
        {
            key = $1; rel = $2; size = $3; md5 = $5
            if (key ~ /_[0-9]+$/) {
                parent = key; sub(/_[0-9]+$/, "", parent)
                desc = rel "|" size "|" md5
                comp[parent] = (parent in comp) ? (comp[parent] ";" desc) : desc
                next
            }
            od_rel[key] = rel; od_size[key] = size; od_md5[key] = md5
        }
        function strip_cat(s) {
            sub(/^.*\//, "", s)
            return "Recently Deleted/" s
        }
        function strip_cat_comp(c,    n, d, i) {
            if (c == "") return ""
            n = split(c, d, ";"); _o = ""
            for (i = 1; i <= n; i++) { sub(/^.*\//, "", d[i]); d[i] = "Recently Deleted/" d[i]; _o = (_o == "") ? d[i] : (_o ";" d[i]) }
            return _o
        }
        END {
            for (u in od_rel) {
                _rel = od_rel[u]; _comp = (u in comp) ? comp[u] : ""
                if (u in tr) { _rel = strip_cat(_rel); _comp = strip_cat_comp(_comp) }
                row = u OFS orig[u] OFS "on-disk" OFS _rel OFS od_size[u] OFS od_md5[u] OFS ((u in dl) ? "downloaded" : "") OFS _comp OFS (u in cap ? cap[u] : "")
                if (u in tr) print row > trashed_file
                else         print row
            }
        }
    ' "$SCRATCH_DIR/report_ondisk.tsv" | LC_ALL=C sort > "$SCRATCH_DIR/report_assets.body"
    LC_ALL=C awk -F$'\x1f' '$5!="" && $5!="0"{print $2}' "$SCRATCH_DIR/assets.tsv" 2>/dev/null \
        | LC_ALL=C sort -u > "$SCRATCH_DIR/favorites.set"
    LC_ALL=C awk -F'\t' -v OFS='\t' 'NR==FNR{f[$1]=1;next} ($1 in f){print $1}' \
        "$SCRATCH_DIR/favorites.set" "$SCRATCH_DIR/report_assets.body" 2>/dev/null \
        | LC_ALL=C sort > "$SCRATCH_DIR/report_favorites.body"
    : > "$SCRATCH_DIR/report_albums.body"
    local _alb_ji _alb_junc="" _alb_jcol="" _alb_acol="" _alb_rest
    _alb_ji="$(_photos_discover_album_junction "$snap" 2>/dev/null)"
    if [ -n "$_alb_ji" ]; then
        _alb_junc="${_alb_ji%%$'\t'*}"; _alb_rest="${_alb_ji#*$'\t'}"
        _alb_jcol="${_alb_rest%%$'\t'*}"; _alb_acol="${_alb_rest#*$'\t'}"
    fi
    if [ -n "$_alb_junc" ]; then
        sqlite3 -readonly -separator $'\t' "$snap" "
            SELECT g.ZUUID,
                   $(_sql_tsv_safe "TRIM(COALESCE(p3.ZTITLE||'/','')||COALESCE(p2.ZTITLE||'/','')||COALESCE(p1.ZTITLE||'/','')||g.ZTITLE)"),
                   a.ZUUID
              FROM ZGENERICALBUM g
              JOIN $_alb_junc j ON j.$_alb_jcol = g.Z_PK
              JOIN ZASSET a ON a.Z_PK = j.$_alb_acol
              LEFT JOIN ZGENERICALBUM p1 ON p1.Z_PK = g.ZPARENTFOLDER AND p1.ZKIND = 4000
              LEFT JOIN ZGENERICALBUM p2 ON p2.Z_PK = p1.ZPARENTFOLDER AND p2.ZKIND = 4000
              LEFT JOIN ZGENERICALBUM p3 ON p3.Z_PK = p2.ZPARENTFOLDER AND p3.ZKIND = 4000
             WHERE g.ZKIND = 2 AND COALESCE(g.ZTRASHEDSTATE,0) = 0
               AND g.ZTITLE IS NOT NULL AND g.ZTITLE <> '' AND COALESCE(a.ZTRASHEDSTATE,0) = 0;
        " 2>/dev/null > "$SCRATCH_DIR/albums_raw.tsv" || : > "$SCRATCH_DIR/albums_raw.tsv"
        LC_ALL=C awk -F'\t' -v OFS='\t' '
            NR==FNR { rel[$1]=$4; orig[$1]=$2; next }
            ($3 in rel) { print $1, $2, $3 }
        ' "$SCRATCH_DIR/report_assets.body" "$SCRATCH_DIR/albums_raw.tsv" 2>/dev/null \
            | LC_ALL=C sort > "$SCRATCH_DIR/report_albums.body"
    fi
    if [ "${PHOTO_LIBRARY_ALBUMS:-yes}" = "yes" ] && [ "$PHOTO_LIBRARY_COPY" = "yes" ]; then
        _pl_materialize_albums "${out_file%/*}"
    fi
    if [ "${PHOTO_LIBRARY_FAVORITES:-yes}" = "yes" ] && [ "$PHOTO_LIBRARY_COPY" = "yes" ]; then
        _pl_materialize_favorites "${out_file%/*}"
    fi
    : > "$SCRATCH_DIR/report_meta.body"
    local _kw_junc="" _kw_aacol="" _kw_kcol="" _kw_t _kw_cols _kw_expr="''" _kw_exists="0"
    for _kw_t in $(sqlite3 -readonly "$snap" "SELECT name FROM sqlite_master WHERE type='table' AND name GLOB 'Z_[0-9]*KEYWORDS';" 2>/dev/null); do
        _kw_cols="$(sqlite3 -readonly "$snap" "SELECT name FROM pragma_table_info('$_kw_t');" 2>/dev/null)"
        _kw_aacol="$(printf '%s\n' "$_kw_cols" | grep -m1 -E '^Z_[0-9]+ASSETATTRIBUTES$')"
        _kw_kcol="$(printf '%s\n' "$_kw_cols" | grep -m1 -E '^Z_[0-9]+KEYWORDS$')"
        [ -n "$_kw_aacol" ] && [ -n "$_kw_kcol" ] && { _kw_junc="$_kw_t"; break; }
        _kw_aacol=""; _kw_kcol=""
    done
    case "$_kw_junc$_kw_aacol$_kw_kcol" in *[!A-Za-z0-9_]*) _kw_junc=""; _kw_aacol=""; _kw_kcol="" ;; esac
    if [ -n "$_kw_junc" ]; then
        _kw_expr="COALESCE((SELECT group_concat(k.ZTITLE,';') FROM $_kw_junc jk JOIN ZKEYWORD k ON k.Z_PK=jk.$_kw_kcol WHERE jk.$_kw_aacol=aa.Z_PK),'')"
        _kw_exists="EXISTS(SELECT 1 FROM $_kw_junc jk WHERE jk.$_kw_aacol=aa.Z_PK)"
    fi
    local _md_title_sel="''" _md_desc_sel="''" _md_where=""
    if _col_present "$snap" ZADDITIONALASSETATTRIBUTES ZTITLE; then
        _md_title_sel="COALESCE(aa.ZTITLE,'')"
        _md_where="(aa.ZTITLE IS NOT NULL AND aa.ZTITLE<>'')"
    fi
    if _col_present "$snap" ZADDITIONALASSETATTRIBUTES ZASSETDESCRIPTION; then
        _md_desc_sel="COALESCE(aa.ZASSETDESCRIPTION,'')"
        _md_where="${_md_where:+$_md_where OR }(aa.ZASSETDESCRIPTION IS NOT NULL AND aa.ZASSETDESCRIPTION<>'')"
    fi
    if [ "$_md_title_sel" = "''" ] && [ "$_md_desc_sel" = "''" ]; then
        log_info "Schema: ZADDITIONALASSETATTRIBUTES has no ZTITLE/ZASSETDESCRIPTION — [asset_metadata] carries keywords only."
    fi
    _md_where="${_md_where:+$_md_where OR }$_kw_exists"
    sqlite3 -readonly -separator $'\t' "$snap" "
        SELECT a.ZUUID,
               $(_sql_tsv_safe "$_md_title_sel"),
               $(_sql_tsv_safe "$_md_desc_sel"),
               $(_sql_tsv_safe "$_kw_expr")
          FROM ZASSET a JOIN ZADDITIONALASSETATTRIBUTES aa ON aa.ZASSET=a.Z_PK
         WHERE COALESCE(a.ZTRASHEDSTATE,0)=0
           AND ( $_md_where );
    " 2>/dev/null > "$SCRATCH_DIR/meta_raw.tsv" || : > "$SCRATCH_DIR/meta_raw.tsv"
    LC_ALL=C awk -F'\t' -v OFS='\t' '
        NR==FNR { od[$1]=1; next }
        ($1 in od) { print }
    ' "$SCRATCH_DIR/report_assets.body" "$SCRATCH_DIR/meta_raw.tsv" 2>/dev/null \
        | LC_ALL=C sort > "$SCRATCH_DIR/report_meta.body"
    [ -f "$SCRATCH_DIR/report_trashed.body" ] && \
        LC_ALL=C sort -o "$SCRATCH_DIR/report_trashed.body" "$SCRATCH_DIR/report_trashed.body" 2>/dev/null || true
    cat "$SCRATCH_DIR/report_assets.body" >> "$tmp_out" 2>/dev/null || true
    printf '\n' >> "$tmp_out"
    local n_assets n_companions
    n_assets="$(LC_ALL=C awk 'END{print NR+0}' "$SCRATCH_DIR/report_assets.body")"
    n_companions="$(LC_ALL=C awk -F'\t' '$8!=""{n=split($8,_c,";"); t+=n} END{print t+0}' "$SCRATCH_DIR/report_assets.body" "$SCRATCH_DIR/report_trashed.body")"
    case "$n_assets"     in ''|*[!0-9]*) n_assets=0 ;; esac
    case "$n_companions" in ''|*[!0-9]*) n_companions=0 ;; esac
    local _assets_written
    _assets_written="$(_recount_report_section "$tmp_out" assets)"
    if [ "${_assets_written:-0}" != "$n_assets" ]; then
        log_warn "Photos report [assets] section truncated: produced $n_assets rows, $_assets_written landed in $(basename "$out_file") — disk may be full."
        note_incomplete "$_PHOTOS_DIR" "Photos library report: $(basename "$lib")" \
            "the [assets] section of the .report was truncated mid-write (produced $n_assets rows, only $_assets_written written) — likely out of disk space"
    fi
    {
        printf '[trashed]\n'
        printf '# asset_uuid\toriginal_filename\tstatus\trel_path\tsize\thash\tflags\tcompanions\tcapture_date\n'
        printf '# One row per Recently-Deleted (trashed) own-library asset, copied to Recently Deleted/ (NOT the live category folders). status is always on-disk — only files actually present are listed.\n'
    } >> "$tmp_out"
    local n_trashed n_trashed_written
    n_trashed="$(_count_lines "$SCRATCH_DIR/report_trashed.body")"
    cat "$SCRATCH_DIR/report_trashed.body" >> "$tmp_out" 2>/dev/null || true
    printf '\n' >> "$tmp_out"
    n_trashed_written="$(_recount_report_section "$tmp_out" trashed)"
    if [ "${n_trashed_written:-0}" != "$n_trashed" ]; then
        log_warn "Photos report [trashed] section truncated: produced $n_trashed rows, $n_trashed_written landed in $(basename "$out_file") — disk may be full."
        note_incomplete "$_PHOTOS_DIR" "Photos library report: $(basename "$lib")" \
            "the [trashed] section of the .report was truncated mid-write (produced $n_trashed rows, only $n_trashed_written written) — likely out of disk space"
    fi
    if [ -s "$SCRATCH_DIR/report_favorites.body" ]; then
        {
            printf '[favorites]\n'
            printf '# asset_uuid\n'
            printf '# One row per on-disk own asset the user marked favorite (ZASSET.ZFAVORITE=1).\n'
            cat "$SCRATCH_DIR/report_favorites.body"
            printf '\n'
        } >> "$tmp_out"
    fi
    if [ -s "$SCRATCH_DIR/report_albums.body" ]; then
        {
            printf '[albums]\n'
            printf '# album_uuid\talbum_name\tasset_uuid\n'
            printf '# Own user-album (ZGENERICALBUM ZKIND=2) membership; one row per (album, on-disk member). album_name is the qualified Folder/Sub/Album path.\n'
            cat "$SCRATCH_DIR/report_albums.body"
            printf '\n'
        } >> "$tmp_out"
    fi
    if [ -s "$SCRATCH_DIR/report_meta.body" ]; then
        {
            printf '[asset_metadata]\n'
            printf '# asset_uuid\ttitle\tcaption\tkeywords\n'
            printf '# Per-asset user title (ZTITLE) / caption (ZASSETDESCRIPTION) / ;-joined keywords. One row per on-disk asset carrying at least one.\n'
            cat "$SCRATCH_DIR/report_meta.body"
            printf '\n'
        } >> "$tmp_out"
    fi
    mark_activity
    : # per-section report written silently; folded into the consolidated Photos/Libraries/<stem>.report below
    if ! mv -f -- "$tmp_out" "$out_file"; then
        log_warn "Cannot finalise $out_file."
        rm -f -- "$tmp_out"
        return 1
    fi
    case "$emitted_originals" in ''|*[!0-9]*) emitted_originals=0 ;; esac
    case "$n_trashed"         in ''|*[!0-9]*) n_trashed=0 ;;         esac
    local _proc_msg
    _proc_msg="$n_assets $(_pluralize "$n_assets" asset)"
    [ "$n_companions" -gt 0 ] && _proc_msg="$_proc_msg, $n_companions companion $(_pluralize "$n_companions" file) (e.g. Live Photo motion video)"
    [ "$n_trashed" -gt 0 ] && _proc_msg="$_proc_msg, $n_trashed in Recently Deleted"
    log_info "Processed: $_proc_msg"
    local _comp_std _comp_swy _comp_sbm
    _comp_std="$(LC_ALL=C awk -F'\t' '$4 ~ /^Not Shared\//{n++} END{print n+0}' "$SCRATCH_DIR/report_assets.body" 2>/dev/null)"
    _comp_swy="$(LC_ALL=C awk -F'\t' '$4 ~ /^Shared with You\//{n++} END{print n+0}' "$SCRATCH_DIR/report_assets.body" 2>/dev/null)"
    _comp_sbm="$(LC_ALL=C awk -F'\t' '$4 ~ /^Shared by Me\//{n++} END{print n+0}' "$SCRATCH_DIR/report_assets.body" 2>/dev/null)"
    case "$_comp_std" in ''|*[!0-9]*) _comp_std=0 ;; esac
    case "$_comp_swy" in ''|*[!0-9]*) _comp_swy=0 ;; esac
    case "$_comp_sbm" in ''|*[!0-9]*) _comp_sbm=0 ;; esac
    if [ "$((_comp_swy + _comp_sbm))" -gt 0 ]; then
        log_info "  Composition: $_comp_std your own, $_comp_swy Shared with You, $_comp_sbm shared by you (sorted into the category folders)"
    fi
    return 0
}

_pl_build_classification() {
    local _snap="$1"
    : > "$SCRATCH_DIR/class.tsv"
    [ -n "$_snap" ] && [ -f "$_snap" ] || return 0
    sqlite3 -readonly -separator $'\t' "$_snap" "
        WITH t4 AS (
            SELECT aa.ZORIGINALFILENAME fn, COUNT(*) c
              FROM ZASSET za JOIN ZADDITIONALASSETATTRIBUTES aa ON aa.ZASSET=za.Z_PK
             WHERE za.ZSAVEDASSETTYPE=4
               AND aa.ZORIGINALFILENAME IS NOT NULL AND aa.ZORIGINALFILENAME<>''
             GROUP BY aa.ZORIGINALFILENAME)
        SELECT za.ZUUID,
               CASE
                 WHEN aa.ZSYNDICATIONIDENTIFIER IS NOT NULL AND aa.ZSYNDICATIONIDENTIFIER<>'' THEN 'shared-with-you'
                 WHEN t4.c = 1 THEN 'shared-by-me'
                 ELSE 'standard'
               END,
               CASE WHEN za.ZDATECREATED IS NULL OR za.ZDATECREATED = 0 THEN ''
                    ELSE strftime('%Y%m%d%H%M.%S', datetime(
                         (CASE WHEN za.ZDATECREATED > 4000000000 THEN za.ZDATECREATED/1e9 ELSE za.ZDATECREATED END) + 978307200,
                         'unixepoch', 'localtime')) END,
               CASE WHEN za.ZDATECREATED IS NULL OR za.ZDATECREATED = 0 THEN ''
                    ELSE strftime('%Y-%m-%dT%H:%M:%SZ', datetime(
                         (CASE WHEN za.ZDATECREATED > 4000000000 THEN za.ZDATECREATED/1e9 ELSE za.ZDATECREATED END) + 978307200,
                         'unixepoch')) END
          FROM ZASSET za
          JOIN ZADDITIONALASSETATTRIBUTES aa ON aa.ZASSET=za.Z_PK
          LEFT JOIN t4 ON t4.fn = aa.ZORIGINALFILENAME;
    " > "$SCRATCH_DIR/class.tsv" 2>/dev/null || : > "$SCRATCH_DIR/class.tsv"
    local _cl_u _cl_c _cl_d _cl_iso
    while IFS=$'\t' read -r _cl_u _cl_c _cl_d _cl_iso; do
        case "$_cl_u" in [0-9A-Fa-f]*-*-*-*-*) ;; *) continue ;; esac
        printf -v "_cls_${_cl_u//-/_}" '%s' "$_cl_c"
        [ -n "$_cl_d" ] && printf -v "_capdate_${_cl_u//-/_}" '%s' "$_cl_d"
    done < "$SCRATCH_DIR/class.tsv"
}

_pl_category_into() {
    local _ref="_cls_${1//-/_}" _d
    case "${!_ref:-standard}" in
        shared-by-me)    _d='Shared by Me' ;;
        shared-with-you) _d='Shared with You' ;;
        *)               _d='Not Shared' ;;
    esac
    printf -v "$2" '%s' "$_d"
}

_pl_export_scope_tree() {
    local _ss_src="$1" _ss_dest="$2" _ss_report="$3" _ss_lib="$4" _ss_label="$5"
    [ -d "$_ss_src" ] || return 0
    local _ss_any
    if ! IFS= read -r -d '' _ss_any < <(find -H "$_ss_src" -type f -print0 -quit 2>/dev/null); then
        return 0
    fi
    ensure_scratch
    log_info "Capturing $_ss_label (shared-source content the library walk excludes)..."
    if ! mkdir -p "$_ss_dest"; then
        log_warn "Cannot create $_ss_dest — skipping $_ss_label."
        return 0
    fi
    track_output_path "$_ss_dest"
    local _ss_od="$SCRATCH_DIR/scope_ondisk.tsv"
    local _ss_meta="$SCRATCH_DIR/scope_meta.tsv"
    : > "$_ss_od"; : > "$_ss_meta"
    local _ss_f _ss_bn _ss_dst _ss_sz _ss_md5 _ss_uuid _ss_rel _ss_n=0 _ss_fail=0
    while IFS= read -r -d '' _ss_f; do
        _ss_bn="${_ss_f##*/}"
        is_icloud_stub "$_ss_bn" && continue
        should_skip_copy "$_ss_f" "$_ss_bn" && continue
        _ss_dst="$_ss_dest/$_ss_bn"
        [ -e "$_ss_dst" ] && _ss_dst="$(_unique_path "$_ss_dst")"
        if ditto -- "$_ss_f" "$_ss_dst" 2>/dev/null && [ -e "$_ss_dst" ]; then
            _ss_sz="$(stat -f %z "$_ss_dst" 2>/dev/null)"
            case "$_ss_sz" in ''|*[!0-9]*) _ss_sz=0 ;; esac
            _ss_md5="$(_md5_hex "$_ss_dst")"
            _ss_rel="${_ss_dst##*/}"
            _ss_uuid="${_ss_rel##*/}"; _ss_uuid="${_ss_uuid%.*}"
            printf '%s\t%s\t%s\t\t%s\n' "$_ss_uuid" "$_ss_rel" "$_ss_sz" "$_ss_md5" >> "$_ss_od"
            printf '%s\t%s\n' "$_ss_uuid" "$_ss_rel" >> "$_ss_meta"
            _ss_n=$((_ss_n + 1))
        else
            rm -f -- "$_ss_dst" 2>/dev/null
            _ss_fail=$((_ss_fail + 1))
        fi
    done < <(find -H "$_ss_src" -type f -print0 2>/dev/null)
    if [ "$_ss_fail" -gt 0 ]; then
        log_warn "$_ss_label: $_ss_fail file(s) could not be copied (unreadable source / iCloud placeholder did not materialize)."
        note_incomplete "$_PHOTOS_DIR" "Photos — $_ss_label" \
            "$_ss_fail file(s) of shared-source content ($_ss_label) could not be copied — the source was unreadable or an iCloud placeholder failed to materialize on read. Re-run after downloading the originals locally."
    fi
    if [ ! -s "$_ss_od" ]; then
        rmdir "$_ss_dest" 2>/dev/null || true
        _untrack_output_path "$_ss_dest"   # tracked above; drop it now the dir is gone
        rm -f -- "$_ss_od" "$_ss_meta" 2>/dev/null
        return 0
    fi
    local _ss_body="$SCRATCH_DIR/scope_assets.body"
    LC_ALL=C awk -F'\t' -v OFS='\t' -v meta="$_ss_meta" '
        BEGIN { while ((getline l < meta) > 0) { n=split(l,m,"\t"); orig[m[1]]=(n>=2?m[2]:"") } close(meta) }
        { key=$1; rel=$2; size=$3; md5=$5
          if (key ~ /_[0-9]+$/) { parent=key; sub(/_[0-9]+$/,"",parent); desc=rel"|"size"|"md5; comp[parent]=(parent in comp)?(comp[parent] ";" desc):desc; next }
          od_rel[key]=rel; od_size[key]=size; od_md5[key]=md5 }
        END { for (u in od_rel) print u, orig[u], "on-disk", od_rel[u], od_size[u], od_md5[u], "", ((u in comp)?comp[u]:"") }
    ' "$_ss_od" | LC_ALL=C sort > "$_ss_body"
    local _ss_tmp _ss_write_ok=0; _ss_tmp="$(mktemp "$_ss_report.tmp.XXXXXX" 2>/dev/null)" || _ss_tmp="$SCRATCH_DIR/scope_report.tmp"
    track_output_path "$_ss_tmp"
    {
        _photos_report_header "$_ss_lib"
        printf '\n[assets]\n'
        printf '# asset_uuid\toriginal_filename\tstatus\trel_path\tsize\thash\tflags\tcompanions\n'
        printf '# One row per %s file copied here. These are shared-source masters (content shared TO this Mac) the library originals/ walk excludes; this is their only local copy. status is always on-disk.\n' "$_ss_label"
        cat "$_ss_body"
        printf '\n'
        :
    } > "$_ss_tmp" 2>/dev/null \
        && mv -f -- "$_ss_tmp" "$_ss_report" 2>/dev/null \
        && _ss_write_ok=1 \
        || { rm -f -- "$_ss_tmp" 2>/dev/null; log_warn "$_ss_label: failed to write .report file"; }
    _untrack_output_path "$_ss_tmp"
    local _ss_assets; _ss_assets="$(LC_ALL=C awk 'END{print NR+0}' "$_ss_body")"
    if [ "$_ss_write_ok" != 1 ] && [ "${_ss_assets:-0}" -gt 0 ]; then
        note_incomplete "$_PHOTOS_DIR" "Photos — $_ss_label" \
            "the $_ss_label report could not be written (disk full / read-only volume) — $_ss_assets captured file(s) are on disk but are omitted from the Photos manifest. Re-run once space is available."
    fi
    : # scope-capture report folded into the consolidated Photos/Libraries/<stem>.report
    rm -f -- "$_ss_od" "$_ss_meta" "$_ss_body" 2>/dev/null
}

_pl_run_one_library() {
    PHOTO_LIBRARY_PATH="$1"
    _PL_COPY_DF_SKIPPED=0
    _PL_COPY_USER_SKIPPED=0
    local out_arg="$2"
    PHOTO_LIBRARY_COPY="$3"
    PHOTO_LIBRARY_REPORT="$4"
    PHOTO_LIBRARY_DOWNLOAD_MISSING="$5"
    PHOTO_LIBRARY_INCLUDE_SHARED_SOURCE="$6"
    local _pl_err0="$ERR_COUNT"
    rm -f -- "$SCRATCH_DIR"/assets.tsv "$SCRATCH_DIR"/uuid_meta.tsv \
        "$SCRATCH_DIR"/uuid_lookup.tsv "$SCRATCH_DIR"/report_ondisk.tsv \
        "$SCRATCH_DIR"/report_assets.body "$SCRATCH_DIR"/report_trashed.body \
        "$SCRATCH_DIR"/trashed.set "$SCRATCH_DIR"/downloaded.set \
        "$SCRATCH_DIR"/evicted.tsv "$SCRATCH_DIR"/class.tsv \
        "$SCRATCH_DIR"/scope_ondisk.tsv "$SCRATCH_DIR"/scope_meta.tsv \
        "$SCRATCH_DIR"/scope_assets.body "$SCRATCH_DIR"/scope_report.tmp 2>/dev/null || true
    unset ${!_cls_@} ${!_capdate_@} ${!_trk_@} 2>/dev/null || true
    _PL_AS_CONSEC_FAILURES=0; _PL_AS_DISABLED=0
    local _both_off=0
    if [ "$PHOTO_LIBRARY_COPY"   != "yes" ] \
       && [ "$PHOTO_LIBRARY_REPORT" != "yes" ] \
       && [ "$PHOTO_LIBRARY_INCLUDE_SHARED_SOURCE" != "yes" ]; then
        _both_off=1
        if [ -n "$PHOTO_LIBRARY_PATH" ] && [ ! -d "$PHOTO_LIBRARY_PATH" ]; then
            log_info "Both PHOTO_LIBRARY_COPY and PHOTO_LIBRARY_REPORT are off — nothing to do."
            return 0
        fi
        if [ -z "$PHOTO_LIBRARY_PATH" ] && ! _photos_discover_system_library >/dev/null 2>&1; then
            log_info "Both PHOTO_LIBRARY_COPY and PHOTO_LIBRARY_REPORT are off — nothing to do."
            return 0
        fi
    fi
    local lib_path=""
    if [ -n "$PHOTO_LIBRARY_PATH" ]; then
        lib_path="$PHOTO_LIBRARY_PATH"
    elif _photos_discover_system_library; then
        lib_path="$_lib_path"
    else
        log_err "No library specified and no system library detected."
        log_info "Set PHOTO_LIBRARY_PATH=/path/to/Lib.photoslibrary, or open"
        log_info "Photos.app once to choose your library, then re-run."
        return 1
    fi
    if [ ! -d "$lib_path" ]; then
        log_err "Photo library does not exist: $lib_path"; return 1
    fi
    if [ ! -f "$lib_path/database/Photos.sqlite" ]; then
        log_err "Not a valid .photoslibrary bundle (no database/Photos.sqlite): $lib_path"; return 1
    fi
    local out_dir="$out_arg"
    local tag="other" system_lib=""
    if _photos_discover_system_library; then
        system_lib="${_lib_path%/}"
    fi
    if [ -z "$system_lib" ] || [ "${lib_path%/}" = "$system_lib" ]; then
        tag="system"
    fi
    local _out_stem
    _out_stem="$(basename "$lib_path" 2>/dev/null)"
    _out_stem="${_out_stem%.photoslibrary}"
    [ -z "$_out_stem" ] && _out_stem="(library)"
    [ "$tag" = "system" ] && _out_stem="$_out_stem (iCloud)"
    _announce_output_dir "Photos/Libraries/$_out_stem"
    log_info "Type: [$tag]; copy=$PHOTO_LIBRARY_COPY, report=$PHOTO_LIBRARY_REPORT"
    require_full_disk_access
    [ "${_PHOTOS_PRE_RUNNING:-1}" = "1" ] && warn_if_app_running Photos
    if [ "$PHOTO_LIBRARY_DOWNLOAD_MISSING" = "1" ] && [ "$PHOTO_LIBRARY_COPY" = "yes" ]; then
        [ "${_PHOTOS_LAUNCHED_BY_US:-0}" != "1" ] && _snapshot_app_launch Photos _PHOTOS_LAUNCHED_BY_US
        case "${_PHOTOS_AUTOMATION_STATE:-unknown}" in
            granted) : ;;
            denied|na)
                if check_photos_automation; then
                    _PHOTOS_AUTOMATION_STATE=granted
                    log_ok "Photos Automation: granted"
                else
                    log_warn "Photos Automation not granted — skipping the iCloud download of evicted originals; the export copies only what is already on disk. Grant it in System Settings > Privacy & Security > Automation, then re-run to capture cloud-only originals."
                    _PL_AS_DISABLED=1
                fi ;;
            *)
                if check_photos_automation; then
                    _PHOTOS_AUTOMATION_STATE=granted
                    log_ok "Photos Automation: granted"
                elif [ -t 1 ] && wait_for_grant check_photos_automation "Photos" "$TCC_POLL_TIMEOUT"; then
                    _PHOTOS_AUTOMATION_STATE=granted
                    log_ok "Photos Automation: granted"
                else
                    log_warn "Photos Automation not granted — skipping the iCloud download of evicted originals; the export copies only what is already on disk."
                    _PL_AS_DISABLED=1
                fi ;;
        esac
    fi
    local _download_wanted=0
    if [ "$PHOTO_LIBRARY_DOWNLOAD_MISSING" = "1" ] \
       && [ "$PHOTO_LIBRARY_COPY" = "yes" ] \
       && [ "${_PL_AS_DISABLED:-0}" != "1" ]; then
        _download_wanted=1
    fi
    local photos_dir="$out_dir/Photos"
    _PHOTOS_DIR="$photos_dir"
    _create_output_dir "$photos_dir"
    local libraries_dir="$photos_dir/Libraries"
    _create_output_dir "$libraries_dir"
    local _base_stem
    _base_stem="$(basename "$lib_path" .photoslibrary)"
    [ "$tag" = "system" ] && _base_stem="$_base_stem (iCloud)"
    local stem
    stem="$(_plan_library_stem "$lib_path" "$libraries_dir" "$_base_stem")" \
        || { log_err "Cannot allocate destination subfolder for $lib_path (Photos/Libraries/ may be full)"; return 1; }
    track_output_path "$libraries_dir/$stem"
    local lib_dir="$libraries_dir/$stem"
    if [ ! -d "$lib_dir" ]; then
        log_err "Planned subfolder $lib_dir is no longer present"; return 1
    fi
    _PL_RESOLVED_STEM="$stem"
    if [ "$_both_off" = "1" ]; then
        _write_skipped_marker_system_only "$lib_dir" "$stem" "$lib_path" originals
        _write_skipped_marker_system_only "$lib_dir" "$stem" "$lib_path" report
        log_info "Both PHOTO_LIBRARY_COPY and PHOTO_LIBRARY_REPORT are off — wrote skip markers."
        return 0
    fi
    ensure_scratch
    _pl_build_classification "$(snapshot_db "$lib_path/database/Photos.sqlite" 2>/dev/null)"
    log_info "Source: $lib_path"
    local copy_ok=0 report_ok=0
    local _lib_copied=0 _lib_skipped=0
    if [ "$PHOTO_LIBRARY_COPY" = "yes" ]; then
        if _copy_library_originals "$lib_path" "$lib_dir"; then
            [ "$_lib_copied" -gt 0 ] && copy_ok=1
        fi
    fi
    if [ "$PHOTO_LIBRARY_REPORT" = "yes" ] || [ "$_download_wanted" = "1" ] \
       || [ "$PHOTO_LIBRARY_COPY" = "yes" ]; then
        local out_file="$lib_dir/$stem.report"
        _PL_REPORT_SKIPPED=0
        if _pl_build_report "$lib_path" "$out_file" "$tag"; then
            [ "$PHOTO_LIBRARY_REPORT" = "yes" ] && report_ok=1
        fi
    fi
    rmdir "$lib_dir" 2>/dev/null || true
    local _did_anything=0
    if [ "$_download_wanted" = "1" ] && [ -s "$SCRATCH_DIR/downloaded.set" ]; then
        _did_anything=1
    fi
    if [ "$PHOTO_LIBRARY_INCLUDE_SHARED_SOURCE" = "yes" ]; then
        _pl_export_scope_tree "$lib_path/scopes/syndication/originals" \
            "$lib_dir/Shared with You (not in library)" \
            "$lib_dir/Shared with You (not in library)/$stem.report" \
            "$lib_path" "Shared with You (not in library)"
        _pl_export_scope_tree "$lib_path/scopes/momentshared/originals" \
            "$lib_dir/Shared Moments" \
            "$lib_dir/Shared Moments/$stem.report" \
            "$lib_path" "Shared Moments"
        if [ -d "$lib_dir/Shared with You (not in library)" ] || [ -d "$lib_dir/Shared Moments" ]; then
            _did_anything=1
        fi
    fi
    if [ "$PHOTO_LIBRARY_COPY" = "yes" ]; then
        if [ "$copy_ok" = "1" ]; then
            _did_anything=1
        else
            if [ "${_PL_LIB_MARKED:-}" != "$photos_dir/Libraries/$stem" ]; then
                log_warn "No originals copied for this library."
            fi
        fi
    fi
    if [ "$PHOTO_LIBRARY_REPORT" = "yes" ]; then
        if [ "$report_ok" = "1" ]; then
            : # the per-library report is folded into the consolidated Photos/Libraries/<stem>.report (see _consolidate_library_reports)
            _did_anything=1
        elif [ "${_PL_REPORT_SKIPPED:-0}" = "1" ]; then
            _did_anything=1
        elif [ "$copy_ok" = "1" ]; then
            log_warn "Report failed for this library — the copied originals are kept; the per-library .report is incomplete."
            note_incomplete "$photos_dir" "Library: $stem" \
                "the per-library .report could not be written for this Photos library, but its copied originals ARE kept in the export"
            _did_anything=1
        else
            log_err "Report failed for this library."
        fi
    fi
    if [ "$ERR_COUNT" -gt "$_pl_err0" ]; then return 1; fi
    return 0
}

_photos_discover_album_junction() {
    local snap="$1"
    local album_ent
    album_ent="$(sqlite3 -readonly "$snap" "SELECT Z_ENT FROM Z_PRIMARYKEY WHERE Z_NAME='Album' OR Z_NAME='GenericAlbum' ORDER BY Z_NAME='Album' DESC LIMIT 1;" 2>/dev/null)"
    [ -z "$album_ent" ] && return 1
    case "$album_ent" in *[!0-9]*) return 1 ;; esac
    local table="Z_${album_ent}ASSETS"
    local present
    present="$(sqlite3 -readonly "$snap" "SELECT name FROM sqlite_master WHERE type='table' AND name='$table';" 2>/dev/null)"
    [ -z "$present" ] && return 1
    local cols album_col asset_col
    cols="$(sqlite3 -readonly "$snap" "SELECT name FROM pragma_table_info('$table');" 2>/dev/null)"
    album_col="$(printf '%s\n' "$cols" | grep -m1 "^Z_${album_ent}ALBUMS$")"
    asset_col="$(printf '%s\n' "$cols" | grep -E '^Z_[0-9]+ASSETS$' | grep -v "^$album_col\$" | head -1)"
    if [ -z "$album_col" ] || [ -z "$asset_col" ]; then
        return 1
    fi
    case "$asset_col" in *[!A-Za-z0-9_]*) return 1 ;; esac
    case "$album_col" in *[!A-Za-z0-9_]*) return 1 ;; esac
    printf '%s\t%s\t%s' "$table" "$album_col" "$asset_col"
}

_resolve_cached_master() {
    local uuid="$1" _p
    [ -n "${_CM_TSV:-}" ] && [ -f "${_CM_TSV:-}" ] || return 1
    _p="$(awk -F$'\x1f' -v u="$uuid" '$1==u{print $2; exit}' "$_CM_TSV" 2>/dev/null)"
    [ -n "$_p" ] && [ -f "$_p" ] && { printf '%s' "$_p"; return 0; }
    return 1
}

_AS_DISABLED=0
_LIB_PATH_G=""
_HAS_AUTOMATION="no"
_AS_CONSEC_FAILURES=0
_AS_RESTART_THRESHOLD=10
_AS_RESTART_COUNT=0
_AS_RESTART_MAX=3
_AS_RESTART_QUIT_PAUSE=3
_AS_RESTART_LAUNCH_PAUSE=2
case "$SHARED_ALBUMS_PER_ASSET_SEC" in
    ''|*[!0-9]*)        SHARED_ALBUMS_PER_ASSET_SEC=60 ;;
    0)                  SHARED_ALBUMS_PER_ASSET_SEC=1 ;;
    *) [ "$SHARED_ALBUMS_PER_ASSET_SEC" -gt 3600 ] && SHARED_ALBUMS_PER_ASSET_SEC=60 ;;
esac

_photos_restart() {
    if [ "$_AS_RESTART_COUNT" -ge "$_AS_RESTART_MAX" ]; then
        return 1
    fi
    if [ "${_PHOTOS_PRE_RUNNING:-0}" = "1" ]; then
        log_warn "Photos.app appears to have stopped responding ($_AS_CONSEC_FAILURES consecutive AppleScript failures) but you opened it before our run — refusing to quit it (would kill your session); falling back to local-only copy for the remainder of this run."
        note_incomplete "$_PHOTOS_DIR" "Cloud-only shared-album assets (after Photos.app stopped responding)" \
            "Photos.app stopped responding and could not be restarted (it was already open before this run); from that point only locally-cached shared-album assets were copied — any cloud-only assets were not fetched. Re-run with Photos.app quit"
        _AS_DISABLED=1
        return 1
    fi
    _AS_RESTART_COUNT=$((_AS_RESTART_COUNT + 1))
    log_warn "Photos.app appears to have stopped responding ($_AS_CONSEC_FAILURES consecutive AppleScript failures); restarting (#$_AS_RESTART_COUNT/$_AS_RESTART_MAX)"
    _as_debug "quitting Photos.app for restart"
    _as_quit_or_launch_watched() {
        local _verb="$1"
        _run_with_timeout 25 osascript \
            -e 'with timeout of 15 seconds' \
            -e "tell application \"Photos\" to $_verb" \
            -e 'end timeout' >/dev/null 2>&1
    }
    _as_quit_or_launch_watched quit  || true
    sleep "$_AS_RESTART_QUIT_PAUSE"
    _as_quit_or_launch_watched launch || true
    sleep "$_AS_RESTART_LAUNCH_PAUSE"
    _AS_CONSEC_FAILURES=0
    return 0
}

_applescript_export_asset() {
    _photos_export_asset "$1" "$SHARED_ALBUMS_PER_ASSET_SEC" sa_export
    local _rc=$?
    if [ "$_rc" -eq 0 ]; then
        _AS_CONSEC_FAILURES=0
        return 0
    fi
    _AS_CONSEC_FAILURES=$((_AS_CONSEC_FAILURES + 1))
    if [ "$_AS_CONSEC_FAILURES" -ge "$_AS_RESTART_THRESHOLD" ]; then
        if ! _photos_restart; then
            log_warn "AppleScript restart cap reached — disabling per-asset AppleScript downloads for the remainder of this run."
            _AS_DISABLED=1
        fi
    fi
    return 1
}

_sa_run() {
    local _sib_copy_failed_count=0
    local _sa_err0="$ERR_COUNT"
    local out_dir="$1"
    if [ "$SHARED_COPY" != "yes" ] && [ "$SHARED_REPORT" != "yes" ]; then
        log_info "Both SHARED_COPY and SHARED_REPORT are off — Shared Albums export is a no-op."
        return 0
    fi
    local _sa_rel="${SHARED_ALBUMS_OUT_ROOT:-$out_dir/Photos/Shared Albums}"
    _announce_output_dir "${_sa_rel#"$out_dir/"}"
    log_info "Mode: copy=${SHARED_COPY}, report=${SHARED_REPORT}"
    if [ ! -d /System/Applications/Photos.app ] \
       && [ ! -d /Applications/Photos.app ]; then
        log_warn "Shared albums not available: Photos.app is not installed on this Mac."
        return 0
    fi
    if [ "${_FDA_STATE:-}" != "granted" ] && [ "${PHOTO_LIBRARY_OFFLINE:-0}" != "1" ] && ! check_full_disk_access; then
        log_warn "Shared albums: Full Disk Access not granted — skipping the shared-albums pass (the library's own originals are unaffected; this leaves the export partial)."
        return 1
    fi
    if ! _photos_discover_system_library; then
        log_err "No Photos library found."
        log_info "Open Photos.app once to choose your library, then re-run."
        return 1
    fi
    local lib="$_lib_path"
    local lib_stem="${lib##*/}"; lib_stem="${lib_stem%.photoslibrary}"
    _LIB_PATH_G="$lib"
    log_info "System library: $lib (via $_lib_source)"
    log_info "Source: $lib (Photos library + AppleScript)"
    local photos_dir="$out_dir/Photos"
    _PHOTOS_DIR="$photos_dir"
    _create_output_dir "$photos_dir"
    local out_root="${SHARED_ALBUMS_OUT_ROOT:-$photos_dir/Libraries/$lib_stem (iCloud)/Shared Albums}"
    if [ -e "$out_root" ] || [ -L "$out_root" ]; then
        log_err "Shared albums: output exists, refusing to clobber: '$out_root'"
        return 1
    fi
    local photos_db="$lib/database/Photos.sqlite"
    [ -f "$photos_db" ] || { log_err "Shared albums: Photos database not found: $photos_db"; return 1; }
    log_info "Checking Photos Automation permission + waking up Photos..."
    if [ "${PHOTO_LIBRARY_OFFLINE:-0}" = "1" ]; then
        log_info "Offline mode: shared-album members resolved cache-only (no Automation, no downloads)."
        _HAS_AUTOMATION="no"
        _PHOTOS_LAUNCHED_BY_US=0
    elif [ "$SHARED_COPY" != "yes" ]; then
        log_info "Skipped: report-only mode (SHARED_COPY=no, no asset fetching)."
        _HAS_AUTOMATION="no"
        _PHOTOS_LAUNCHED_BY_US=0
    else
    if [ "${_PHOTOS_LAUNCHED_BY_US:-0}" != "1" ]; then
        _snapshot_app_launch Photos _PHOTOS_LAUNCHED_BY_US
    fi
    case "${_PHOTOS_AUTOMATION_STATE:-unknown}" in
        granted)
            : # Trust the wrapper; no probe, no info line.
            ;;
        denied|na)
            if check_photos_automation >/dev/null 2>&1; then
                log_ok "Photos Automation granted."
            else
                log_warn "Shared albums: Photos Automation not granted — cannot fetch cloud-only album members (the export will be partial)."
                log_info "  Grant it in: System Settings > Privacy & Security > Automation > <terminal> > Photos, then re-run."
                return 1
            fi
            ;;
        *)
            log_info "Probing Photos Automation permission (first run will prompt)..."
            if check_photos_automation; then
                _PHOTOS_AUTOMATION_STATE=granted
                log_ok "Photos Automation: granted"
            else
                log_info "Photos Automation not responding. Possible causes:"
                log_info "  • The Automation grant for Photos is off — toggle it ON in System Settings > Privacy & Security > Automation > <terminal>."
                log_info "  • Photos is open with a welcome / library-chooser / iCloud sign-in dialog blocking automation — bring Photos to the front and dismiss any sheets or sign-in prompts."
                log_info "  • Photos is still launching — just wait."
                log_info "Polling for up to ${TCC_POLL_TIMEOUT} seconds; the script will proceed when Photos starts responding."
                open 'x-apple.systempreferences:com.apple.preference.security?Privacy_Automation' \
                    >/dev/null 2>&1 || true
                if wait_for_grant check_photos_automation "Photos" "$TCC_POLL_TIMEOUT"; then
                    _PHOTOS_AUTOMATION_STATE=granted
                    log_ok "Photos Automation: granted"
                else
                    log_warn "Photos Automation permission was not granted within ${TCC_POLL_TIMEOUT} s — shared albums will be partial (the library's own originals are unaffected)."
                    log_info "This export needs Photos.app to download cloud-only shared-album assets (PhotoKit's cloud-fetch isn't reachable from a shell). Without it, every shared-with-me asset that hasn't already been cached locally would be reported missing — a partial export."
                    log_info "How to grant:"
                    log_info "  • System Settings > Privacy & Security > Automation"
                    log_info "  • Find your terminal (Terminal, iTerm, Ghostty, etc.) in the list. If it isn't there, run any AppleScript that talks to Photos so macOS adds the entry."
                    log_info "  • Toggle Photos ON under your terminal."
                    log_info "  • Re-run this script."
                    log_info "If you're running over SSH, switch to a local Aqua session — AppleScript needs a window-server session to reach Photos.app."
                    return 1
                fi
            fi
            ;;
    esac
    _HAS_AUTOMATION="yes"
    osascript -e 'with timeout of 15 seconds' \
              -e 'tell application "Photos" to launch' \
              -e 'end timeout' >/dev/null 2>&1 || true
    sleep 2
    fi  # close SHARED_COPY gate around the Automation + warm-up block
    log_info "Snapshotting Photos.sqlite + discovering shared albums (ZGENERICALBUM + ZSHARE)..."
    ensure_scratch
    local snap
    snap="$(snapshot_db_or_die "$photos_db" "Photos library")" || return 1
    if ! sqlite3 -readonly "$snap" "SELECT 1 FROM ZGENERICALBUM LIMIT 1;" >/dev/null 2>&1 \
       && ! sqlite3 -readonly "$snap" "SELECT 1 FROM ZSHARE LIMIT 1;" >/dev/null 2>&1; then
        local _sa_tbls
        _sa_tbls="$(sqlite3 -readonly "$snap" "SELECT GROUP_CONCAT(name, ' ') FROM sqlite_master WHERE type='table';" 2>/dev/null)"
        log_warn "Shared albums: Photos.sqlite schema unrecognised — neither ZGENERICALBUM nor ZSHARE present.
  Apple may have changed the schema in a macOS update; please report this.
  Tables in this database: ${_sa_tbls:-(none)}"
        return 1
    fi
    local _use_zshare=0
    if sqlite3 -readonly "$snap" "SELECT 1 FROM ZSHARE LIMIT 1;" >/dev/null 2>&1 \
       && _col_present "$snap" ZSHARE ZTITLE \
       && [ -n "$(sqlite3 -readonly "$snap" "SELECT 1 FROM ZSHARE WHERE ZTITLE IS NOT NULL AND ZTITLE != '' LIMIT 1;" 2>/dev/null)" ]; then
        _use_zshare=1
    fi
    local junc_info junction="" junc_album_col="" junc_asset_col=""
    if [ "$_use_zshare" != 1 ]; then
        junc_info="$(_photos_discover_album_junction "$snap")"
        if [ -n "$junc_info" ]; then
            junction="${junc_info%%$'\t'*}"
            local rest="${junc_info#*$'\t'}"
            junc_album_col="${rest%%$'\t'*}"
            junc_asset_col="${rest#*$'\t'}"
        fi
    fi
    local _shared_disc_failed=0
    : > "$SCRATCH_DIR/photos_shared_albums.tsv"
    if [ "$_use_zshare" != 1 ]; then
    sqlite3 -readonly -separator $'\x1f' "$snap" "
        SELECT 'ZGENERICALBUM', Z_PK, COALESCE(ZUUID,''),
               $(_sql_tsv_safe ZTITLE),
               COALESCE(ZCLOUDOWNERHASHEDPERSONID, ''),
               $(_sql_tsv_safe ZCLOUDOWNERFIRSTNAME),
               $(_sql_tsv_safe ZCLOUDOWNERLASTNAME),
               COALESCE(ZCREATIONDATE, ''),
               COALESCE(ZSTARTDATE, ''),
               COALESCE(ZENDDATE, '')
          FROM ZGENERICALBUM
         WHERE ZKIND IN (1505, 3571)
           AND COALESCE(ZTRASHEDSTATE, 0) = 0
           AND ZTITLE IS NOT NULL AND ZTITLE != ''
           -- Filter Apple-internal sync placeholder albums.
           -- Photos creates rows titled 'progress-sync' and
           -- 'in-progress-share' during CloudKit sync sessions
           -- (no backticks in this comment: it is inside a
           -- double-quoted bash string and backticks would be
           -- evaluated as command substitution). They have valid
           -- titles but are infrastructure, not user-shared
           -- content. Filter the specific known prefixes;
           -- user-typed titles legitimately containing hyphens
           -- are unaffected.
           AND ZTITLE NOT LIKE 'progress-sync%'
           AND ZTITLE NOT LIKE 'in-progress-%'
         ORDER BY ZTITLE, Z_PK;
    " >> "$SCRATCH_DIR/photos_shared_albums.tsv" 2>/dev/null || _shared_disc_failed=1
    fi  # _use_zshare != 1 (legacy ZGENERICALBUM discovery)
    : > "$SCRATCH_DIR/zshare_meta.tsv"
    if sqlite3 -readonly "$snap" "SELECT 1 FROM ZSHARE LIMIT 1;" >/dev/null 2>&1; then
        local _zshare_tmp="$SCRATCH_DIR/shared_albums_zshare.tsv"
        local _zs_uuid _zs_title _zs_ohash _zs_ofirst _zs_olast
        local _zs_create _zs_start _zs_end
        if _col_present "$snap" ZSHARE ZUUID; then
            _zs_uuid="COALESCE(s.ZUUID,'')"; else _zs_uuid="'' AS ZUUID"
            log_info "Schema: ZSHARE.ZUUID absent — shared-album dedup key empty for ZSHARE rows."
        fi
        local _zshare_has_title=1
        if _col_present "$snap" ZSHARE ZTITLE; then
            _zs_title="$(_sql_tsv_safe s.ZTITLE)"
        else
            _zs_title="''"; _zshare_has_title=0
            log_info "Schema: ZSHARE.ZTITLE absent — ZSHARE-sourced albums cannot be discovered."
        fi
        if _col_present "$snap" ZSHARE ZCLOUDOWNERHASHEDPERSONID; then
            _zs_ohash="COALESCE(s.ZCLOUDOWNERHASHEDPERSONID,'')"
        else
            _zs_ohash="'' AS ZCLOUDOWNERHASHEDPERSONID"
        fi
        if _col_present "$snap" ZSHARE ZCLOUDOWNERFIRSTNAME; then
            _zs_ofirst="$(_sql_tsv_safe s.ZCLOUDOWNERFIRSTNAME)"
        else
            _zs_ofirst="'' AS ZCLOUDOWNERFIRSTNAME"
        fi
        if _col_present "$snap" ZSHARE ZCLOUDOWNERLASTNAME; then
            _zs_olast="$(_sql_tsv_safe s.ZCLOUDOWNERLASTNAME)"
        else
            _zs_olast="'' AS ZCLOUDOWNERLASTNAME"
        fi
        if _col_present "$snap" ZSHARE ZCREATIONDATE; then
            _zs_create="COALESCE(s.ZCREATIONDATE,'')"
        else
            _zs_create="'' AS ZCREATIONDATE"
        fi
        if _col_present "$snap" ZSHARE ZSTARTDATE; then
            _zs_start="COALESCE(s.ZSTARTDATE,'')"
        else
            _zs_start="'' AS ZSTARTDATE"
        fi
        if _col_present "$snap" ZSHARE ZENDDATE; then
            _zs_end="COALESCE(s.ZENDDATE,'')"
        else
            _zs_end="'' AS ZENDDATE"
        fi
        if [ "$_zshare_has_title" = "1" ]; then
            sqlite3 -readonly -separator $'\x1f' "$snap" "
                SELECT 'ZSHARE', s.Z_PK, $_zs_uuid,
                       $_zs_title,
                       $_zs_ohash,
                       $_zs_ofirst,
                       $_zs_olast,
                       $_zs_create,
                       $_zs_start,
                       $_zs_end
                  FROM ZSHARE s
                 WHERE COALESCE(s.ZTRASHEDSTATE, 0) = 0
                   AND s.ZTITLE IS NOT NULL AND s.ZTITLE != ''
                   AND s.ZTITLE NOT LIKE 'progress-sync%'
                   AND s.ZTITLE NOT LIKE 'in-progress-%'
                   AND EXISTS (
                       SELECT 1 FROM ZASSET a
                        WHERE a.ZCOLLECTIONSHARE = s.Z_PK
                          AND COALESCE(a.ZTRASHEDSTATE, 0) = 0
                   )
                 ORDER BY s.ZTITLE, s.Z_PK;
            " > "$_zshare_tmp" 2>/dev/null || { : > "$_zshare_tmp"; _shared_disc_failed=1; }
        else
            : > "$_zshare_tmp"
        fi
        local _zm_url _zm_perm _zm_expiry _zm_pcount _zm_vcount _zm_acount
        local _zm_any=0
        if _col_present "$snap" ZSHARE ZSHAREURL; then
            _zm_url="$(_sql_tsv_safe s.ZSHAREURL)"; _zm_any=1
        else _zm_url="''"; fi
        if _col_present "$snap" ZSHARE ZPUBLICPERMISSION; then
            _zm_perm="COALESCE(s.ZPUBLICPERMISSION,'')"; _zm_any=1
        else _zm_perm="''"; fi
        if _col_present "$snap" ZSHARE ZEXPIRYDATE; then
            _zm_expiry="COALESCE(s.ZEXPIRYDATE,'')"; _zm_any=1
        else _zm_expiry="''"; fi
        if _col_present "$snap" ZSHARE ZCLOUDPHOTOCOUNT; then
            _zm_pcount="COALESCE(s.ZCLOUDPHOTOCOUNT,'')"; _zm_any=1
        else _zm_pcount="''"; fi
        if _col_present "$snap" ZSHARE ZCLOUDVIDEOCOUNT; then
            _zm_vcount="COALESCE(s.ZCLOUDVIDEOCOUNT,'')"; _zm_any=1
        else _zm_vcount="''"; fi
        if _col_present "$snap" ZSHARE ZASSETCOUNT; then
            _zm_acount="COALESCE(s.ZASSETCOUNT,'')"; _zm_any=1
        else _zm_acount="''"; fi
        if [ "$_zm_any" -eq 1 ]; then
            sqlite3 -readonly -separator $'\x1f' "$snap" "
                SELECT s.Z_PK, $_zm_url, $_zm_perm, $_zm_expiry,
                       $_zm_pcount, $_zm_vcount, $_zm_acount
                  FROM ZSHARE s
                 WHERE COALESCE(s.ZTRASHEDSTATE, 0) = 0;
            " > "$SCRATCH_DIR/zshare_meta.tsv" 2>/dev/null \
                || : > "$SCRATCH_DIR/zshare_meta.tsv"
        else
            log_info "Schema: ZSHARE carries no share-metadata columns (ZSHAREURL/ZPUBLICPERMISSION/etc.) — the .report header omits the share-metadata lines."
        fi
        if [ -s "$_zshare_tmp" ]; then
            cat "$_zshare_tmp" >> "$SCRATCH_DIR/photos_shared_albums.tsv"
        fi
    fi
    if [ "$_use_zshare" = 1 ] \
       && _col_present "$snap" ZGENERICALBUM ZCLOUDOWNERHASHEDPERSONID \
       && _col_present "$snap" ZGENERICALBUM ZUUID; then
        local _gao_line _gao_uuid _gao_rest
        while IFS= read -r _gao_line; do
            _gao_uuid="${_gao_line%%$'\x1f'*}"
            case "$_gao_uuid" in [0-9A-Fa-f]*-*-*-*-*) ;; *) continue ;; esac
            _gao_rest="${_gao_line#*$'\x1f'}"
            printf -v "_gao_${_gao_uuid//-/_}" '%s' "$_gao_rest"
        done < <(sqlite3 -readonly -separator $'\x1f' "$snap" "
            SELECT COALESCE(ZUUID,''),
                   COALESCE(ZCLOUDOWNERHASHEDPERSONID,''),
                   $(_sql_tsv_safe ZCLOUDOWNERFIRSTNAME),
                   $(_sql_tsv_safe ZCLOUDOWNERLASTNAME)
              FROM ZGENERICALBUM
             WHERE ZUUID IS NOT NULL AND ZUUID != ''
               AND ZCLOUDOWNERHASHEDPERSONID IS NOT NULL
               AND ZCLOUDOWNERHASHEDPERSONID != '';
        " 2>/dev/null)
    fi
    log_info "Building contributors + comments + assets + album-membership maps..."
    : > "$SCRATCH_DIR/contributors.tsv"
    sqlite3 -readonly -separator $'\x1f' "$snap" "
        SELECT hash, COALESCE(NULLIF(TRIM(fn || ' ' || ln), ''), full)
          FROM (
            SELECT ZINVITEEHASHEDPERSONID AS hash,
                   COALESCE($(_sql_tsv_safe ZINVITEEFIRSTNAME),'') AS fn,
                   COALESCE($(_sql_tsv_safe ZINVITEELASTNAME),'')  AS ln,
                   COALESCE($(_sql_tsv_safe ZINVITEEFULLNAME),'')  AS full
              FROM ZCLOUDSHAREDALBUMINVITATIONRECORD
             WHERE ZINVITEEHASHEDPERSONID IS NOT NULL
               AND ZINVITEEHASHEDPERSONID != ''
            UNION
            SELECT ZCLOUDOWNERHASHEDPERSONID,
                   COALESCE($(_sql_tsv_safe ZCLOUDOWNERFIRSTNAME),''),
                   COALESCE($(_sql_tsv_safe ZCLOUDOWNERLASTNAME),''),
                   ''
              FROM ZGENERICALBUM
             WHERE ZCLOUDOWNERHASHEDPERSONID IS NOT NULL
               AND ZCLOUDOWNERHASHEDPERSONID != ''
          )
         WHERE hash IS NOT NULL AND hash != '';
    " > "$SCRATCH_DIR/contributors.tsv" 2>/dev/null || : > "$SCRATCH_DIR/contributors.tsv"
    local _cn_hash _cn_name
    while IFS=$'\x1f' read -r _cn_hash _cn_name; do
        [ -z "$_cn_hash" ] && continue
        case "$_cn_hash" in *[!A-Za-z0-9_]*) continue ;; esac
        local _cn_key="_cn_${_cn_hash}"
        [ -n "${!_cn_key:-}" ] && continue
        printf -v "$_cn_key" '%s' "$_cn_name"
    done < "$SCRATCH_DIR/contributors.tsv"
    local _cmt_mine_expr
    if _col_present "$snap" ZCLOUDSHAREDCOMMENT ZISMYCOMMENT; then
        _cmt_mine_expr="COALESCE(ZISMYCOMMENT,0)"
    else
        _cmt_mine_expr="0"
        log_info "Schema: ZCLOUDSHAREDCOMMENT.ZISMYCOMMENT absent — [comments] section 'mine' column always 0"
    fi
    : > "$SCRATCH_DIR/comments.tsv"
    sqlite3 -readonly -separator $'\x1f' "$snap" "
        SELECT asset_pk,
               COALESCE(CASE WHEN ZCOMMENTDATE IS NULL OR ZCOMMENTDATE = 0 THEN ''
                   ELSE strftime('%Y-%m-%dT%H:%M:%SZ',
                       datetime($(_sql_cd_to_unix ZCOMMENTDATE),
                                'unixepoch')) END, ''),
               COALESCE(ZISLIKE, 0),
               $(_sql_tsv_safe "COALESCE(ZCOMMENTERHASHEDPERSONID, '')"),
               $(_sql_tsv_safe ZCOMMENTTEXT),
               COALESCE(mine, 0)
          FROM (
            SELECT ZCOMMENTEDASSET AS asset_pk, ZCOMMENTDATE,
                   ZISLIKE, ZCOMMENTERHASHEDPERSONID, ZCOMMENTTEXT,
                   $_cmt_mine_expr AS mine
              FROM ZCLOUDSHAREDCOMMENT
             WHERE ZCOMMENTEDASSET IS NOT NULL
            UNION ALL
            SELECT ZLIKEDASSET AS asset_pk, ZCOMMENTDATE,
                   ZISLIKE, ZCOMMENTERHASHEDPERSONID, ZCOMMENTTEXT,
                   $_cmt_mine_expr AS mine
              FROM ZCLOUDSHAREDCOMMENT
             WHERE ZLIKEDASSET IS NOT NULL
               AND ZCOMMENTEDASSET IS NULL
          )
         ORDER BY asset_pk, ZCOMMENTDATE;
    " > "$SCRATCH_DIR/comments.tsv" 2>/dev/null || : > "$SCRATCH_DIR/comments.tsv"
    local _cmt_line _cmt_pk _cmt_key _cmt_existing
    while IFS= read -r _cmt_line; do
        _cmt_pk="${_cmt_line%%$'\x1f'*}"
        case "$_cmt_pk" in ''|*[!0-9]*) continue ;; esac
        _cmt_key="_cmts_${_cmt_pk}"
        _cmt_existing="${!_cmt_key:-}"
        if [ -n "$_cmt_existing" ]; then
            printf -v "$_cmt_key" '%s\n%s' "$_cmt_existing" "$_cmt_line"
        else
            printf -v "$_cmt_key" '%s' "$_cmt_line"
        fi
    done < "$SCRATCH_DIR/comments.tsv"
    local n_shared
    n_shared="$(_count_lines "$SCRATCH_DIR/photos_shared_albums.tsv")"
    log_info "Found $n_shared shared $(_pluralize "$n_shared" album)"
    if [ "$n_shared" -eq 0 ]; then
        if [ "$_shared_disc_failed" = "1" ]; then
            log_warn "Shared albums: the discovery query failed — unable to confirm whether you have iCloud Shared Albums; none were exported."
            note_incomplete "$_PHOTOS_DIR" "Shared albums — could not enumerate" \
                "the shared-album discovery query against the Photos library errored (a transient database error or a schema change), so downpour.sh could not determine whether you have iCloud Shared Albums and exported none. Re-run; if it persists, report it so the schema probe can be fixed."
            return 0
        fi
        rmdir "$photos_dir" 2>/dev/null || true
        log_info "No shared albums to export."
        return 0
    fi
    local _cap_expr
    if _col_present "$snap" ZADDITIONALASSETATTRIBUTES ZTITLE \
       && _col_present "$snap" ZADDITIONALASSETATTRIBUTES ZASSETDESCRIPTION; then
        _cap_expr="$(_sql_tsv_safe "COALESCE(NULLIF(aa.ZTITLE,''), aa.ZASSETDESCRIPTION)")"
    elif _col_present "$snap" ZADDITIONALASSETATTRIBUTES ZTITLE; then
        _cap_expr="$(_sql_tsv_safe aa.ZTITLE)"
        log_info "Schema: ZADDITIONALASSETATTRIBUTES.ZASSETDESCRIPTION absent — captions use ZTITLE only."
    elif _col_present "$snap" ZADDITIONALASSETATTRIBUTES ZASSETDESCRIPTION; then
        _cap_expr="$(_sql_tsv_safe aa.ZASSETDESCRIPTION)"
        log_info "Schema: ZADDITIONALASSETATTRIBUTES.ZTITLE absent — captions use ZASSETDESCRIPTION only."
    else
        _cap_expr="''"
        log_info "Schema: ZADDITIONALASSETATTRIBUTES has no caption column (ZTITLE/ZASSETDESCRIPTION) — per-asset captions unavailable."
    fi
    local _owner_expr
    if _col_present "$snap" ZASSET ZCLOUDOWNERHASHEDPERSONID; then
        _owner_expr="COALESCE(a.ZCLOUDOWNERHASHEDPERSONID, '')"
    else
        _owner_expr="''"
        log_info "Schema: ZASSET.ZCLOUDOWNERHASHEDPERSONID absent — shared-with-me owner attribution unavailable."
    fi
    local _origfn_expr
    if _col_present "$snap" ZADDITIONALASSETATTRIBUTES ZORIGINALFILENAME; then
        _origfn_expr="$(_sql_tsv_safe aa.ZORIGINALFILENAME)"
    else
        _origfn_expr="''"
        log_info "Schema: ZADDITIONALASSETATTRIBUTES.ZORIGINALFILENAME absent — original filenames unavailable for shared-album matching."
    fi
    sqlite3 -readonly -separator $'\x1f' "$snap" "
        SELECT a.Z_PK, a.ZUUID,
               COALESCE(a.ZDIRECTORY, ''),
               COALESCE(a.ZFILENAME, ''),
               $_origfn_expr,
               $_owner_expr,
               $_cap_expr
          FROM ZASSET a
          LEFT JOIN ZADDITIONALASSETATTRIBUTES aa ON aa.ZASSET = a.Z_PK
         WHERE COALESCE(a.ZTRASHEDSTATE, 0) = 0;
    " 2>/dev/null > "$SCRATCH_DIR/all_assets.tsv" || : > "$SCRATCH_DIR/all_assets.tsv"
    local _aa_line _aa_pk
    while IFS= read -r _aa_line; do
        _aa_pk="${_aa_line%%$'\x1f'*}"
        case "$_aa_pk" in ''|*[!0-9]*) continue ;; esac
        printf -v "_aa_${_aa_pk}" '%s' "$_aa_line"
    done < "$SCRATCH_DIR/all_assets.tsv"
    local _cm_count=0
    _CM_TSV=""
    if [ "$SHARED_COPY" = "yes" ] && [ -d "$_LIB_PATH_G/scopes/cloudsharing" ]; then
        _CM_TSV="$SCRATCH_DIR/cm.tsv"
        : > "$_CM_TSV"
        local _cm_f _cm_bn _cm_uuid
        while IFS= read -r -d '' _cm_f; do
            _cm_bn="${_cm_f##*/}"
            _cm_uuid="${_cm_bn%.*}"
            case "$_cm_uuid" in *_[0-9]*) continue ;; esac
            case "$_cm_uuid" in [0-9A-Fa-f]*-*-*-*-*) ;; *) continue ;; esac
            printf '%s\x1f%s\n' "$_cm_uuid" "$_cm_f" >> "$_CM_TSV"
            _cm_count=$((_cm_count + 1))
        done < <(find "$_LIB_PATH_G/scopes/cloudsharing" -type f "${_PL_SCOPE_FIND_PRUNE[@]}" \
                    -print0 2>/dev/null)
        [ "$_cm_count" -gt 0 ] && log_info "Indexed $_cm_count locally-cached shared-album $(_pluralize "$_cm_count" master) for reliable cached-master lookup."
    fi
    : > "$SCRATCH_DIR/junction.tsv"
    if [ -n "$junction" ] && [ -n "$junc_album_col" ] && [ -n "$junc_asset_col" ]; then
        sqlite3 -readonly -separator $'\x1f' "$snap" "
            SELECT $junc_album_col, $junc_asset_col
              FROM $junction ORDER BY $junc_album_col, $junc_asset_col;
        " > "$SCRATCH_DIR/junction.tsv" 2>/dev/null || : > "$SCRATCH_DIR/junction.tsv"
    fi
    : > "$SCRATCH_DIR/collection_share.tsv"
    if sqlite3 -readonly "$snap" "SELECT ZCOLLECTIONSHARE FROM ZASSET LIMIT 1;" >/dev/null 2>&1; then
        sqlite3 -readonly -separator $'\x1f' "$snap" "
            SELECT ZCOLLECTIONSHARE, Z_PK
              FROM ZASSET
             WHERE ZCOLLECTIONSHARE IS NOT NULL
               AND COALESCE(ZTRASHEDSTATE, 0) = 0
             ORDER BY ZCOLLECTIONSHARE, Z_PK;
        " > "$SCRATCH_DIR/collection_share.tsv" 2>/dev/null || : > "$SCRATCH_DIR/collection_share.tsv"
    fi
    mkdir -p "$SCRATCH_DIR/members_by_album/junction" \
             "$SCRATCH_DIR/members_by_album/share" 2>/dev/null || true
    awk -F$'\x1f' -v dir="$SCRATCH_DIR/members_by_album/junction" '
        $1 ~ /^[0-9]+$/ { print >> (dir "/" $1) }
    ' "$SCRATCH_DIR/junction.tsv" 2>/dev/null || true
    awk -F$'\x1f' -v dir="$SCRATCH_DIR/members_by_album/share" '
        $1 ~ /^[0-9]+$/ { print >> (dir "/" $1) }
    ' "$SCRATCH_DIR/collection_share.tsv" 2>/dev/null || true
    local _zm_line _zm_pk _zm_rest
    while IFS= read -r _zm_line; do
        _zm_pk="${_zm_line%%$'\x1f'*}"
        case "$_zm_pk" in ''|*[!0-9]*) continue ;; esac
        _zm_rest="${_zm_line#*$'\x1f'}"
        printf -v "_zm_${_zm_pk}" '%s' "$_zm_rest"
    done < "$SCRATCH_DIR/zshare_meta.tsv"
    local -a bm_src=() bm_pk=() bm_title=() bm_owner=() bm_created=() bm_start=() bm_end=() bm_uuid=()
    local -a wm_src=() wm_pk=() wm_title=() wm_owner=() wm_created=() wm_start=() wm_end=() wm_uuid=()
    local asource apk auuid atitle aowner ofirst olast acreated astart aend clean_title owner_name
    local _gao_ref _gao_val _gao_no
    while IFS=$'\x1f' read -r asource apk auuid atitle aowner ofirst olast acreated astart aend; do
        [ -z "$apk" ] && continue
        case "$asource" in ZGENERICALBUM|ZSHARE) ;; *) continue ;; esac
        if [ -n "$auuid" ]; then
            case "$auuid" in
                *[!A-Za-z0-9-]*)
                    log_warn "Shared albums: skipping non-canonical UUID '$auuid' from $asource"
                    continue
                    ;;
            esac
            local _seen_ref="_seen_uuid_${auuid//-/_}"
            if [ -n "${!_seen_ref:-}" ]; then
                log_info "Shared albums: deduplicating cross-source UUID $auuid (also present as $asource); the album landed via the first source already and the second-source row is skipped."
                continue
            fi
            printf -v "$_seen_ref" '%s' '1'
        fi
        atitle="${atitle//\\n/ }"
        clean_title="$(_sanitize_name "$atitle")"
        [ -z "$clean_title" ] && clean_title="Album-$apk"
        if [ "$asource" = ZSHARE ] && [ -z "$aowner" ] && [ -n "$auuid" ]; then
            _gao_ref="_gao_${auuid//-/_}"; _gao_val="${!_gao_ref:-}"
            if [ -n "$_gao_val" ]; then
                aowner="${_gao_val%%$'\x1f'*}"
                _gao_no="${_gao_val#*$'\x1f'}"
                ofirst="${_gao_no%%$'\x1f'*}"
                olast="${_gao_no#*$'\x1f'}"
            fi
        fi
        owner_name="$(printf '%s %s' "$ofirst" "$olast" \
            | sed -e 's/^ *//' -e 's/ *$//')"
        if [ -z "$aowner" ]; then
            bm_src+=( "$asource" ); bm_uuid+=( "$auuid" )
            bm_pk+=( "$apk" ); bm_title+=( "$clean_title" )
            bm_owner+=( "" ); bm_created+=( "$acreated" )
            bm_start+=( "$astart" ); bm_end+=( "$aend" )
        else
            if [ -z "$owner_name" ]; then
                owner_name="(${aowner:0:8})"
            fi
            clean_title="$clean_title ($(_sanitize_name "$owner_name"))"
            wm_src+=( "$asource" ); wm_uuid+=( "$auuid" )
            wm_pk+=( "$apk" ); wm_title+=( "$clean_title" )
            wm_owner+=( "$owner_name" ); wm_created+=( "$acreated" )
            wm_start+=( "$astart" ); wm_end+=( "$aend" )
        fi
    done < "$SCRATCH_DIR/photos_shared_albums.tsv"
    if [ "${#bm_src[@]}" -ne "${#bm_pk[@]}" ] || \
       [ "${#bm_src[@]}" -ne "${#bm_title[@]}" ] || \
       [ "${#bm_src[@]}" -ne "${#bm_owner[@]}" ] || \
       [ "${#bm_src[@]}" -ne "${#bm_created[@]}" ] || \
       [ "${#bm_src[@]}" -ne "${#bm_start[@]}" ] || \
       [ "${#bm_src[@]}" -ne "${#bm_end[@]}" ]; then
        log_err "Internal invariant violation: bm_* parallel array lengths disagree (src=${#bm_src[@]} pk=${#bm_pk[@]} title=${#bm_title[@]} owner=${#bm_owner[@]} created=${#bm_created[@]} start=${#bm_start[@]} end=${#bm_end[@]}). This is a refactor bug; please report."
        return 1
    fi
    if [ "${#wm_src[@]}" -ne "${#wm_pk[@]}" ] || \
       [ "${#wm_src[@]}" -ne "${#wm_title[@]}" ] || \
       [ "${#wm_src[@]}" -ne "${#wm_owner[@]}" ] || \
       [ "${#wm_src[@]}" -ne "${#wm_created[@]}" ] || \
       [ "${#wm_src[@]}" -ne "${#wm_start[@]}" ] || \
       [ "${#wm_src[@]}" -ne "${#wm_end[@]}" ]; then
        log_err "Internal invariant violation: wm_* parallel array lengths disagree (src=${#wm_src[@]} pk=${#wm_pk[@]} title=${#wm_title[@]} owner=${#wm_owner[@]} created=${#wm_created[@]} start=${#wm_start[@]} end=${#wm_end[@]}). This is a refactor bug; please report."
        return 1
    fi
    _dedup_album_titles() {
        local _arr="$1" _cnt _i _name _suffixed _next _hex _var
        local _dat_keys=()
        eval "_cnt=\${#${_arr}[@]}"
        for (( _i=0; _i<_cnt; _i++ )); do
            eval "_name=\${${_arr}[$_i]}"
            _hex="$(printf '%s' "$_name" | od -An -tx1 | tr -d ' \n')"
            _var="_dat_${_hex}"
            if [ -z "${!_var+x}" ]; then
                printf -v "$_var" 1
                _dat_keys+=( "$_var" )
            else
                _next=$(( ${!_var} + 1 ))
                _suffixed="$_name ($_next)"
                local _hex2 _var2
                _hex2="$(printf '%s' "$_suffixed" | od -An -tx1 | tr -d ' \n')"
                _var2="_dat_${_hex2}"
                while [ -n "${!_var2+x}" ]; do
                    _next=$(( _next + 1 ))
                    _suffixed="$_name ($_next)"
                    _hex2="$(printf '%s' "$_suffixed" | od -An -tx1 | tr -d ' \n')"
                    _var2="_dat_${_hex2}"
                done
                printf -v "$_var" "$_next"
                printf -v "$_var2" 1
                _dat_keys+=( "$_var2" )
                log_warn "Duplicate shared-album title '$_name' in the same bucket — disambiguating to '$_suffixed'"
                note_incomplete "$_PHOTOS_DIR" "Shared album \"$_name\"" \
                    "two shared albums in the same bucket carry the same title; this one was renamed to \"$_suffixed\" so both export. Shared-with-me albums can't be renamed at the source, so the suffix is downpour.sh's disambiguation."
                eval "${_arr}[$_i]=\$_suffixed"
            fi
        done
        local _v
        for _v in "${_dat_keys[@]+"${_dat_keys[@]}"}"; do
            unset "$_v"
        done
    }
    [ "${#bm_title[@]}" -gt 0 ] && _dedup_album_titles bm_title
    [ "${#wm_title[@]}" -gt 0 ] && _dedup_album_titles wm_title
    log_info "Bucketed $n_shared shared $(_pluralize "$n_shared" album) (${#bm_pk[@]} by me, ${#wm_pk[@]} with me)"
    [ "${#bm_pk[@]}" -gt 0 ] && log_info "  • Shared-by-me copies here are usually iCloud-downscaled; your library export keeps your own copy of each (Photos/Libraries/<library>/Shared by Me/)."
    [ "${#wm_pk[@]}" -gt 0 ] && log_info "  • Shared-with-me copies are typically the ONLY local copy (these assets are not in your own library originals)."
    if [ -z "$junction" ]; then
        local _skipped_no_junction=0 _src
        for _src in "${bm_src[@]+"${bm_src[@]}"}" "${wm_src[@]+"${wm_src[@]}"}"; do
            [ "$_src" = "ZGENERICALBUM" ] && _skipped_no_junction=$((_skipped_no_junction + 1))
        done
        [ "$_skipped_no_junction" -gt 0 ] && _disclose_excluded "$_skipped_no_junction $(_pluralize "$_skipped_no_junction" album) with no member list" "leftover discovery rows in this library's photo database"
    fi
    _create_output_dir "$out_root"
    [ "${#bm_pk[@]}" -gt 0 ] && mkdir -p "$out_root/Shared by Me"
    [ "${#wm_pk[@]}" -gt 0 ] && mkdir -p "$out_root/Shared with You"
    _cocoa_iso() {
        local u; u="$(_cd_ts_to_unix "$1")"; [ -z "$u" ] && return 0
        TZ=UTC date -r "$u" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null
    }
    _contrib_name() {
        local h="$1"
        [ -z "$h" ] && return 0
        case "$h" in *[!A-Za-z0-9_]*) return 0 ;; esac
        local _ref="_cn_${h}"
        printf '%s' "${!_ref:-}"
    }
    _copy_album_members() {
        local source="$1" apk="$2" parent="$3" title="$4"
        local owner_name="$5" created_raw="$6" start_raw="$7" end_raw="$8"
        local _sa_uuid="${9:-}"
        local member_file _sa_sd="$SCRATCH_DIR"
        case "$source" in
            ZSHARE)        member_file="$_sa_sd/members_by_album/share/$apk" ;;
            ZGENERICALBUM) member_file="$_sa_sd/members_by_album/junction/$apk" ;;
            *)             member_file="$_sa_sd/members_by_album/junction/$apk" ;;
        esac
        [ -f "$member_file" ] || member_file="/dev/null"
        local dst="$parent/$title"
        local _album_dir="$dst"
        if ! mkdir -p "$_album_dir"; then
            log_warn "Cannot create $_album_dir — skipping album."
            note_incomplete "$_PHOTOS_DIR" "Shared album: $title" \
                "could not create its destination folder under Photos/Libraries/$lib_stem/Shared Albums/ — this album was not exported"
            return 1
        fi
        local _contrib_tsv="$SCRATCH_DIR/share_${apk}_contributors.tsv"
        local _comments_tsv="$SCRATCH_DIR/share_${apk}_comments.tsv"
        local _captions_tsv="$SCRATCH_DIR/share_${apk}_captions.tsv"
        local _lib_masters_tsv="$SCRATCH_DIR/share_${apk}_libmasters.tsv"
        local _end_iso
        _end_iso="$(_cocoa_iso "$end_raw")"
        local _zm_url="" _zm_perm="" _zm_expiry="" _zm_pcount=""
        local _zm_vcount="" _zm_acount="" _apple_count=""
        if [ "$source" = "ZSHARE" ]; then
            local _zm_ref="_zm_${apk}" _zm_block
            _zm_block="${!_zm_ref:-}"
            if [ -n "$_zm_block" ]; then
                IFS=$'\x1f' read -r _zm_url _zm_perm _zm_expiry \
                    _zm_pcount _zm_vcount _zm_acount <<<"$_zm_block"
            fi
        fi
        case "$_zm_pcount$_zm_vcount" in
            ''|*[!0-9]*) ;;
            *) _apple_count=$(( ${_zm_pcount:-0} + ${_zm_vcount:-0} )) ;;
        esac
        if [ -z "$_apple_count" ]; then
            case "$_zm_acount" in
                ''|*[!0-9]*) ;;
                *) _apple_count="$_zm_acount" ;;
            esac
        fi
        local _expiry_iso=""
        [ -n "$_zm_expiry" ] && _expiry_iso="$(_cocoa_iso "$_zm_expiry")"
        local _public_str=""
        case "$_zm_perm" in
            ''|*[!0-9]*) ;;
            0)  _public_str="no" ;;
            *)  _public_str="yes" ;;
        esac
        if [ "$SHARED_COPY" = "yes" ]; then
            : > "$_contrib_tsv"
            : > "$_comments_tsv"
            : > "$_captions_tsv"
        fi
        local _lib_masters_active=0
        if [ -z "$owner_name" ] \
           && { [ "$SHARED_COPY" = "yes" ] || [ "$SHARED_REPORT" = "yes" ]; }; then
            : > "$_lib_masters_tsv"
            _lib_masters_active=1
        fi
        local _album_report_originals=""
        local _album_report_missing=""
        if [ "$SHARED_REPORT" = "yes" ]; then
            _album_report_originals="$SCRATCH_DIR/share_${apk}_originals.tsv"
            _album_report_missing="$SCRATCH_DIR/share_${apk}_missing.tsv"
            : > "$_album_report_originals"
            : > "$_album_report_missing"
        fi
        local copied=0 missing=0 downloaded=0 contributed=0 commented=0 captioned=0 reported=0
        local _lib_master_n=0
        local _members_walked=0
        local jpk asset_pk row member_pk member_uuid member_dir member_filename member_orig member_owner member_caption _companions
        while IFS=$'\x1f' read -r jpk asset_pk; do
            _dl_path=""; _dl_extra=()
            if [ "${_SKIP_REQUESTED:-0}" = "1" ]; then
                _SKIP_REQUESTED=0
                log_info "  Skipped remaining members of '$title' (user pressed 's')."
                break
            fi
            _members_walked=$((_members_walked + 1))
            local _aa_ref="_aa_${asset_pk}"
            row="${!_aa_ref:-}"
            [ -z "$row" ] && continue
            IFS=$'\x1f' read -r member_pk member_uuid member_dir member_filename member_orig member_owner member_caption <<<"$row"
            _companions=""
            if [ "$_lib_masters_active" = "1" ]; then
                local _lm_bn="${member_orig:-$member_filename}"
                local _lm_lref="_libmaster_${_lm_bn//[!A-Za-z0-9_]/_}"
                local _lm_lval="${!_lm_lref:-}"
                if [ -n "$_lm_lval" ]; then
                    local _lm_real _lm_cnt _lm_muuid _lm_mfn
                    IFS=$'\x1f' read -r _lm_real _lm_cnt _lm_muuid _lm_mfn <<<"$_lm_lval"
                    if [ "$_lm_real" = "$_lm_bn" ] && [ "$_lm_cnt" = "1" ]; then
                        printf '%s\t%s\n' "$member_uuid" "$_lm_muuid" \
                            >> "$_lib_masters_tsv"
                        _lib_master_n=$((_lib_master_n + 1))
                    fi
                fi
            fi
            if [ "$SHARED_COPY" != "yes" ]; then
                reported=$((reported + 1))
                if [ "$SHARED_REPORT" = "yes" ]; then
                    local _bn_r="${member_orig:-$member_filename}"
                    _bn_r="$(_sanitize_name "$_bn_r")"
                    printf '%s\t%s\t%s\t\n' \
                        "$member_uuid" "$_bn_r" "$_bn_r" \
                        >> "$_album_report_missing"
                    if [ -n "$member_owner" ]; then
                        local _cname_r; _cname_r="$(_contrib_name "$member_owner")"
                        if [ -n "$_cname_r" ]; then
                            printf '%s\t%s\n' "$member_uuid" "$_cname_r" >> "$_contrib_tsv"
                            contributed=$((contributed + 1))
                        fi
                    fi
                    if [ -n "$member_caption" ]; then
                        printf '%s\t%s\n' "$member_uuid" "${member_caption//\\n/ }" >> "$_captions_tsv"
                        captioned=$((captioned + 1))
                    fi
                    local _mk_r="_cmts_${member_pk}" _mblock_r _cdt_r _islike_r _ch_r _ctext_r _cmine_r _kind_r _textout_r _cname2_r
                    _mblock_r="${!_mk_r:-}"
                    if [ -n "$_mblock_r" ]; then
                        while IFS=$'\x1f' read -r _ _cdt_r _islike_r _ch_r _ctext_r _cmine_r; do
                            [ -z "$_cdt_r$_ch_r$_ctext_r" ] && continue
                            case "$_cmine_r" in 1) _cmine_r=1 ;; *) _cmine_r=0 ;; esac
                            if [ "$_islike_r" = "1" ]; then
                                _kind_r="like"
                                if [ -n "$_ctext_r" ]; then _textout_r="${_ctext_r//\\n/ }"; else _textout_r="(liked)"; fi
                            else
                                _kind_r="comment"; _textout_r="${_ctext_r//\\n/ }"
                            fi
                            _cname2_r="$(_contrib_name "$_ch_r")"; [ -z "$_cname2_r" ] && _cname2_r="$_ch_r"
                            printf '%s\t%s\t%s\t%s\t%s\t%s\n' \
                                "$member_uuid" "$_cdt_r" "$_cname2_r" "$_kind_r" "$_textout_r" "$_cmine_r" \
                                >> "$_comments_tsv"
                            commented=$((commented + 1))
                        done <<< "$_mblock_r"
                    fi
                fi
                continue
            fi
            local src_path="" _src_from_bridge=0
            if src_path="$(_resolve_cached_master "$member_uuid")"; then
                :
            elif [ "$_HAS_AUTOMATION" = "yes" ] && [ "$_AS_DISABLED" -eq 0 ]; then
                if _applescript_export_asset "$member_uuid"; then
                    src_path="$_dl_path"
                    _src_from_bridge=1   # source is the scratch download, not an in-library cached master
                fi
            fi
            if [ "${_SKIP_REQUESTED:-0}" = "1" ]; then
                _SKIP_REQUESTED=0
                log_info "  Skipped '$title' download (user pressed 's')."
                break
            fi
            if [ -z "$src_path" ] || [ ! -f "$src_path" ]; then
                log_warn "$title: '${member_orig:-$member_filename}' not local and download not available"
                missing=$((missing + 1))
                if [ "$SHARED_REPORT" = "yes" ]; then
                    local _bn_m="${member_orig:-$member_filename}"
                    _bn_m="$(_sanitize_name "$_bn_m")"
                    printf '%s\t%s\t%s\t\n' \
                        "$member_uuid" "$_bn_m" "$_bn_m" \
                        >> "$_album_report_missing"
                fi
                continue
            fi
            [ -L "$src_path" ] && {
                log_warn "$title: '${member_orig:-$member_filename}' source is a symlink — skipped"
                if [ "$SHARED_REPORT" = "yes" ]; then
                    local _bn_sl="${member_orig:-$member_filename}"; _bn_sl="$(_sanitize_name "$_bn_sl")"
                    printf '%s\t%s\t%s\t\n' "$member_uuid" "$_bn_sl" "$_bn_sl" >> "$_album_report_missing"
                fi
                missing=$((missing + 1)); continue;
            }
            is_macos_alias "$src_path" && {
                log_warn "$title: '${member_orig:-$member_filename}' source is a Finder alias — skipped"
                if [ "$SHARED_REPORT" = "yes" ]; then
                    local _bn_al="${member_orig:-$member_filename}"; _bn_al="$(_sanitize_name "$_bn_al")"
                    printf '%s\t%s\t%s\t\n' "$member_uuid" "$_bn_al" "$_bn_al" >> "$_album_report_missing"
                fi
                missing=$((missing + 1)); continue;
            }
            local dst_name="${member_orig:-$member_filename}"
            dst_name="$(_sanitize_name "$dst_name")"
            local target="$_album_dir/$dst_name"
            if [ -e "$target" ] || [ -L "$target" ]; then
                local stem ext suffix
                if [ -n "$member_uuid" ]; then
                    suffix="${member_uuid%%-*}"
                    case "$dst_name" in
                        *.*) ext="${dst_name##*.}"
                             stem="${dst_name%.*}"
                             target="$(_unique_path "$_album_dir/${stem}-${suffix}.${ext}")" ;;
                        *)   target="$(_unique_path "$_album_dir/${dst_name}-${suffix}")" ;;
                    esac
                else
                    case "$dst_name" in
                        *.*) ext="${dst_name##*.}"
                             stem="${dst_name%.*}"
                             target="$(_unique_path "$_album_dir/${stem}.${ext}")" ;;
                        *)   target="$(_unique_path "$_album_dir/${dst_name}")" ;;
                    esac
                fi
            fi
            local _ok=0 _via_scratch="$_src_from_bridge"
            case "$_via_scratch" in
                1)
                    if mv -f -- "$src_path" "$target" 2>/dev/null; then
                        copied=$((copied + 1)); downloaded=$((downloaded + 1)); _ok=1
                    else
                        rm -f -- "$target" 2>/dev/null
                        log_warn "$title: move failed for ${member_orig:-$member_filename}"
                        note_incomplete "$_PHOTOS_DIR" "Shared album \"$title\": ${member_orig:-$member_filename}" \
                            "the asset could not be moved into the export — it is not in Photos/Libraries/$lib_stem/Shared Albums/"
                    fi ;;
                *)
                    local _as_src_size
                    _as_src_size="$(stat -f '%z' -- "$src_path" 2>/dev/null)"
                    if ditto -- "$src_path" "$target" 2>/dev/null \
                       && [ -s "$target" ] \
                       && ! _materialized_copy_incomplete "$_as_src_size" "$target"; then
                        copied=$((copied + 1)); _ok=1
                    else
                        rm -f -- "$target" 2>/dev/null
                        log_warn "$title: copy failed for ${member_orig:-$member_filename}"
                        note_incomplete "$_PHOTOS_DIR" "Shared album \"$title\": ${member_orig:-$member_filename}" \
                            "the asset could not be copied into the export — it is not in Photos/Libraries/$lib_stem/Shared Albums/"
                    fi ;;
            esac
            if [ "$_ok" = 1 ] && [ "$_via_scratch" = 0 ]; then
                local _src_dir _sib _sib_ext _sib_dst _stem
                _src_dir="$(dirname "$src_path")"
                case "$target" in
                    *.*) _stem="${target%.*}" ;;
                    *)   _stem="$target" ;;
                esac
                local _src_stem
                case "$src_path" in
                    *.*) _src_stem="${src_path%.*}" ;;
                    *)   _src_stem="$src_path" ;;
                esac
                local _sib_cand
                for _sib_cand in \
                    "$_src_dir/${member_uuid}_3.mov" \
                    "$_src_dir/${member_uuid}_3.MOV" \
                    "${_src_stem}.mov" \
                    "${_src_stem}.MOV"
                do
                    [ -f "$_sib_cand" ] || continue
                    [ "$_sib_cand" = "$src_path" ] && continue
                    [ -L "$_sib_cand" ] && continue
                    is_macos_alias "$_sib_cand" && continue
                    _sib="$_sib_cand"
                    _sib_ext="${_sib##*.}"
                    _sib_dst="${_stem}.$_sib_ext"
                    if [ -e "$_sib_dst" ] || [ -L "$_sib_dst" ]; then
                        local suffix="${member_uuid%%-*}"
                        _sib_dst="${_stem}-${suffix}.$_sib_ext"
                    fi
                    local _sib_src_size
                    _sib_src_size="$(stat -f '%z' -- "$_sib" 2>/dev/null)"
                    if ditto -- "$_sib" "$_sib_dst" 2>/dev/null \
                        && [ -s "$_sib_dst" ] \
                        && ! _materialized_copy_incomplete "$_sib_src_size" "$_sib_dst"; then
                        _companions="${_companions:+$_companions;}$(basename "$_sib_dst")|$(stat -f %z -- "$_sib_dst" 2>/dev/null)|$(_md5_hex "$_sib_dst")"
                    else
                        rm -f -- "$_sib_dst" 2>/dev/null
                        _sib_copy_failed_count=$((_sib_copy_failed_count + 1))
                    fi
                    break
                done
                case "$src_path" in
                    *".poster."[Jj][Pp][Gg]|*".poster."[Jj][Pp][Ee][Gg])
                        for _sib_ext in MP4 mp4 mov MOV; do
                            _sib="$_src_dir/${member_uuid}.medium.$_sib_ext"
                            [ -f "$_sib" ] || continue
                            [ -L "$_sib" ] && continue
                            is_macos_alias "$_sib" && continue
                            local _vid_dst="${_stem}.$_sib_ext"
                            if [ -e "$_vid_dst" ] || [ -L "$_vid_dst" ]; then
                                local _vsuffix="${member_uuid%%-*}"
                                _vid_dst="${_stem}-${_vsuffix}.$_sib_ext"
                            fi
                            local _vid_src_size
                            _vid_src_size="$(stat -f '%z' -- "$_sib" 2>/dev/null)"
                            if ditto -- "$_sib" "$_vid_dst" 2>/dev/null \
                                && [ -s "$_vid_dst" ] \
                                && ! _materialized_copy_incomplete "$_vid_src_size" "$_vid_dst"; then
                                _companions="${_companions:+$_companions;}$(basename "$_vid_dst")|$(stat -f %z -- "$_vid_dst" 2>/dev/null)|$(_md5_hex "$_vid_dst")"
                            else
                                rm -f -- "$_vid_dst" 2>/dev/null
                                _sib_copy_failed_count=$((_sib_copy_failed_count + 1))
                            fi
                            break
                        done
                        ;;
                esac
            fi
            if [ "$_ok" = 1 ] && [ "$_via_scratch" = 1 ] \
               && [ "${#_dl_extra[@]:-0}" -gt 0 ]; then
                local _stem _sib _sib_ext _sib_dst
                case "$target" in
                    *.*) _stem="${target%.*}" ;;
                    *)   _stem="$target"     ;;
                esac
                for _sib in "${_dl_extra[@]+"${_dl_extra[@]}"}"; do
                    [ -f "$_sib" ] || continue
                    _sib_ext="${_sib##*.}"
                    _sib_dst="${_stem}.${_sib_ext}"
                    if [ -e "$_sib_dst" ] || [ -L "$_sib_dst" ]; then
                        local _xsuffix="${member_uuid%%-*}"
                        _sib_dst="${_stem}-${_xsuffix}.${_sib_ext}"
                    fi
                    if mv -f -- "$_sib" "$_sib_dst" 2>/dev/null; then
                        _companions="${_companions:+$_companions;}$(basename "$_sib_dst")|$(stat -f %z -- "$_sib_dst" 2>/dev/null)|$(_md5_hex "$_sib_dst")"
                    else
                        log_warn "$title: sibling-move failed for $(basename "$_sib")"
                        note_incomplete "$_PHOTOS_DIR" "Shared album \"$title\": sibling file $(basename "$_sib")" \
                            "a paired sibling file (raw/edited companion of an asset) could not be moved into the export"
                    fi
                done
            fi
            if [ "$_via_scratch" = 1 ]; then
                rm -rf -- "${_PHOTOS_EXPORT_TMPDIR:-}" 2>/dev/null
            fi
            if [ "$SHARED_COPY" = "yes" ]; then
            if [ "$_ok" = "1" ] && [ -n "$member_owner" ]; then
                local _cname
                _cname="$(_contrib_name "$member_owner")"
                if [ -n "$_cname" ]; then
                    printf '%s\t%s\n' \
                        "$member_uuid" "$_cname" >> "$_contrib_tsv"
                    contributed=$((contributed + 1))
                fi
            fi
            if [ "$_ok" = "1" ] && [ -n "$member_caption" ]; then
                printf '%s\t%s\n' \
                    "$member_uuid" "${member_caption//\\n/ }" \
                    >> "$_captions_tsv"
                captioned=$((captioned + 1))
            fi
            if [ "$_ok" = "1" ]; then
                local _cdt _is_like _ch _ctext _cmine _cname2 _kind _text_out
                local _mk="_cmts_${member_pk}"
                local _mblock="${!_mk:-}"
                if [ -n "$_mblock" ]; then
                    while IFS=$'\x1f' read -r _ _cdt _is_like _ch _ctext _cmine; do
                        [ -z "$_cdt$_ch$_ctext" ] && continue
                        case "$_cmine" in 1) _cmine=1 ;; *) _cmine=0 ;; esac
                        if [ "$_is_like" = "1" ]; then
                            _kind="like"
                            if [ -n "$_ctext" ]; then
                                _text_out="${_ctext//\\n/ }"
                            else
                                _text_out="(liked)"
                            fi
                        else
                            _kind="comment"
                            _text_out="${_ctext//\\n/ }"
                        fi
                        _cname2="$(_contrib_name "$_ch")"
                        [ -z "$_cname2" ] && _cname2="$_ch"
                        printf '%s\t%s\t%s\t%s\t%s\t%s\n' \
                            "$member_uuid" "$_cdt" "$_cname2" "$_kind" "$_text_out" "$_cmine" \
                            >> "$_comments_tsv"
                        commented=$((commented + 1))
                    done <<< "$_mblock"
                fi
            fi
            fi  # close per-asset file block (SHARED_COPY=yes path)
            if [ "$SHARED_REPORT" = "yes" ]; then
                local _bn_c _cname_c="" _cap_c
                _bn_c="$(basename "$target")"
                if [ -n "$member_owner" ]; then
                    _cname_c="$(_contrib_name "$member_owner")"
                    [ -z "$_cname_c" ] && _cname_c="$member_owner"
                fi
                _cap_c="${member_caption//\\n/ }"
                _cap_c="${_cap_c//$'\t'/ }"
                if [ "$_ok" = "1" ] && [ -f "$target" ]; then
                    local _sz _mt _st
                    _st="$(stat -f '%z %m' -- "$target" 2>/dev/null)"
                    _sz="${_st%% *}"; _mt="${_st##* }"
                    case "$_sz" in ''|*[!0-9]*) _sz=0 ;; esac
                    case "$_mt" in ''|*[!0-9]*) _mt=0 ;; esac
                    local _flags=""
                    [ "$_via_scratch" = "1" ] && _flags="downloaded"
                    printf '%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n' \
                        "$member_uuid" "$_bn_c" "${_sz:-0}" "${_mt:-0}" \
                        "$target" "$_bn_c" "$_flags" "$_companions" \
                        >> "$_album_report_originals"
                else
                    printf '%s\t%s\t%s\t\n' \
                        "$member_uuid" "$_bn_c" "$_bn_c" \
                        >> "$_album_report_missing"
                fi
            fi
        done < "$member_file"
        if [ "$_members_walked" -gt 0 ] \
           && [ "$copied" -eq 0 ] && [ "$missing" -eq 0 ] && [ "$reported" -eq 0 ]; then
            log_warn "$title: all $_members_walked member(s) were unresolvable — album dropped"
            note_incomplete "$_PHOTOS_DIR" "Shared album \"$title\" unresolvable" \
                "$_members_walked member(s) were listed for this shared album but none could be resolved to an asset record (every member missed the local asset map) — nothing was exported and no .report was written. The album's members may be cloud-only and not yet indexed locally; re-run after opening the album in Photos.app so it syncs."
        fi
        if [ "$SHARED_COPY" != "yes" ]; then
            log_info "$title: $reported $(_pluralize "$reported" asset) catalogued (report-only)"
        elif [ "$downloaded" -gt 0 ]; then
            log_info "$title: $copied copied (incl. $downloaded downloaded), $missing missing"
        else
            log_info "$title: $copied copied, $missing missing"
        fi
        if [ "$SHARED_COPY" != "yes" ]; then
            : # report-only — no completeness cross-check
        else
            if [ "$missing" -gt 0 ]; then
                note_incomplete "$_PHOTOS_DIR" "Shared album \"$title\"" \
                    "$missing asset(s) in this shared album could not be exported — not available locally and Photos.app could not download them (cloud-only members, symlinked, or Finder-alias sources). Re-run after opening the album in Photos.app so it caches the assets."
            fi
        fi
        if [ "$SHARED_COPY" = "yes" ] && [ -n "$_apple_count" ] && [ "$_apple_count" -gt 0 ]; then
            local _accounted=$(( copied + missing ))
            if [ "$_accounted" -lt "$_apple_count" ]; then
                local _trashed_members=0
                case "$apk" in
                    ''|*[!0-9]*) ;;
                    *) _trashed_members="$(sqlite3 -readonly "$snap" \
                            "SELECT COUNT(*) FROM ZASSET WHERE ZCOLLECTIONSHARE = $apk AND COALESCE(ZTRASHEDSTATE,0) != 0;" 2>/dev/null)"
                       case "$_trashed_members" in ''|*[!0-9]*) _trashed_members=0 ;; esac ;;
                esac
                _accounted=$(( _accounted + _trashed_members ))
            fi
            if [ "$_accounted" -lt "$_apple_count" ]; then
                local _short=$(( _apple_count - _accounted ))
                log_warn "$title: Apple reports $_apple_count $(_pluralize "$_apple_count" asset) in this shared album but only $_accounted were accounted for ($_short unaccounted)"
                note_incomplete "$_PHOTOS_DIR" "Shared album \"$title\"" \
                    "Apple reports $_apple_count assets in this shared album but downpour.sh only accounted for $_accounted ($copied copied + $missing missing + recently-deleted members) — $_short asset(s) were not discovered. They may be cloud-only members not yet indexed locally; re-run after opening the album in Photos.app so it syncs."
            fi
        fi
        if [ "$SHARED_REPORT" = "yes" ]; then
            local _origs_n _missing_n
            _origs_n="$(awk 'END{print NR+0}' <"$_album_report_originals" 2>/dev/null)"
            _missing_n="$(awk 'END{print NR+0}' <"$_album_report_missing" 2>/dev/null)"
            if [ "${_origs_n:-0}" -gt 0 ]; then
                local _sa_md5_lk _sa_filled
                _sa_md5_lk="$(mktemp "$SCRATCH_DIR/sa_md5.XXXXXX" 2>/dev/null)" \
                    || _sa_md5_lk="$SCRATCH_DIR/sa_md5.$$.$RANDOM"
                _sa_filled="$_album_report_originals.h"
                awk -F'\t' '{ print $5 }' "$_album_report_originals" 2>/dev/null \
                    | tr '\n' '\0' \
                    | xargs -0 -n 100 md5 2>/dev/null \
                    | _photos_parse_md5_lines > "$_sa_md5_lk"
                if LC_ALL=C awk -F'\t' -v OFS='\t' -v lk="$_sa_md5_lk" '
                        BEGIN { while ((getline _l < lk) > 0) { _i = index(_l, "\t"); if (_i) m[substr(_l, 1, _i-1)] = substr(_l, _i+1) } }
                        { $5 = (($5 in m) ? m[$5] : ""); print }
                    ' "$_album_report_originals" > "$_sa_filled" 2>/dev/null; then
                    mv -f -- "$_sa_filled" "$_album_report_originals"
                else
                    LC_ALL=C awk -F'\t' -v OFS='\t' '{ $5 = ""; print }' \
                        "$_album_report_originals" > "$_sa_filled" 2>/dev/null \
                        && mv -f -- "$_sa_filled" "$_album_report_originals"
                fi
                rm -f -- "$_sa_md5_lk" "$_sa_filled" 2>/dev/null
            fi
            if [ "${_origs_n:-0}" -gt 0 ] || [ "${_missing_n:-0}" -gt 0 ]; then
                local _album_rel="${dst#"$out_root/"}"
                local _album_pfx="$_album_rel/"
                local _au="${_sa_uuid:-shared-${source}-${apk}}"
                local _bucket
                case "$parent" in
                    */"Shared by Me") _bucket="shared-by-me" ;;
                    *)                _bucket="shared-with-you" ;;
                esac
                printf '%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n' \
                    "$_au" "$title" "$_bucket" "$owner_name" \
                    "$_expiry_iso" "$_public_str" "$_zm_url" "${_apple_count:-}" \
                    "${_lib_master_n:-0}" >> "$_SA_RPT_META"
                if [ "${_origs_n:-0}" -gt 0 ]; then
                    LC_ALL=C awk -F'\t' -v OFS='\t' -v pfx="$_album_pfx" '{
                        comp=$8
                        if (comp != "") {
                            n=split(comp, c, ";"); out=""
                            for (k=1;k<=n;k++) { split(c[k], g, "|"); out=out (k>1?";":"") pfx g[1] "|" g[2] "|" g[3] }
                            comp=out
                        }
                        if ($5 !~ /^[0-9a-f]*$/) $5=""
                        print $1, $6, "on-disk", pfx $2, $3, $5, $7, comp
                    }' "$_album_report_originals" >> "$_SA_RPT_ASSETS"
                    LC_ALL=C awk -F'\t' -v OFS='\t' -v au="$_au" -v an="$title" -v pfx="$_album_pfx" '{
                        print au, an, $1
                    }' "$_album_report_originals" >> "$_SA_RPT_ALBUMS"
                fi
                if [ "${_missing_n:-0}" -gt 0 ]; then
                    LC_ALL=C awk -F'\t' -v OFS='\t' -v pfx="$_album_pfx" '{
                        print $1, $2, "not-on-disk", pfx $3, "", "", "", ""
                    }' "$_album_report_missing" >> "$_SA_RPT_ASSETS"
                    LC_ALL=C awk -F'\t' -v OFS='\t' -v au="$_au" -v an="$title" -v pfx="$_album_pfx" '{
                        print au, an, $1
                    }' "$_album_report_missing" >> "$_SA_RPT_ALBUMS"
                fi
                [ -s "$_contrib_tsv" ]     && LC_ALL=C awk -F'\t' -v OFS='\t' -v a="$_au" '{print a, $0}' "$_contrib_tsv"     >> "$_SA_RPT_CONTRIB"
                [ -s "$_captions_tsv" ]    && LC_ALL=C awk -F'\t' -v OFS='\t' -v a="$_au" '{print a, $0}' "$_captions_tsv"    >> "$_SA_RPT_CAPTIONS"
                [ -s "$_comments_tsv" ]    && LC_ALL=C awk -F'\t' -v OFS='\t' -v a="$_au" '{print a, $0}' "$_comments_tsv"    >> "$_SA_RPT_COMMENTS"
                [ -s "$_lib_masters_tsv" ] && LC_ALL=C awk -F'\t' -v OFS='\t' -v a="$_au" '{print a, $0}' "$_lib_masters_tsv" >> "$_SA_RPT_LIBMASTERS"
            fi
            rm -f -- "$_album_report_originals" "$_album_report_missing" 2>/dev/null
        fi
        local _album_kept=0
        [ "$SHARED_COPY" = "yes" ] && [ "$copied" -gt 0 ] && _album_kept=1
        if [ "$_album_kept" = "0" ]; then
            rm -f -- "$_contrib_tsv" "$_comments_tsv" "$_captions_tsv" "$_lib_masters_tsv" 2>/dev/null
            rmdir "$_album_dir" 2>/dev/null || true
        else
            [ "$contributed" -eq 0 ] && rm -f -- "$_contrib_tsv" 2>/dev/null
            [ "$commented" -eq 0 ]   && rm -f -- "$_comments_tsv" 2>/dev/null
            [ "$captioned" -eq 0 ]   && rm -f -- "$_captions_tsv" 2>/dev/null
            if [ "$_lib_masters_active" = "1" ]; then
                if [ "$_lib_master_n" -eq 0 ]; then
                    rm -f -- "$_lib_masters_tsv" 2>/dev/null
                else
                    log_info "$title: $_lib_master_n shared-by-me album member(s) also appear in your library (Shared by Me/) — the report lists each match so you can spot duplicates."
                fi
            fi
            if [ -n "$_end_iso" ]; then
                local _u; _u="$(_cd_ts_to_unix "$end_raw")"
                if [ -n "$_u" ]; then
                    _apply_touch_t "$(_format_touch_t "$_u")" "$dst"
                fi
            fi
        fi
        TOTAL_COPIED=$((TOTAL_COPIED + copied))
        TOTAL_DOWNLOADED=$((TOTAL_DOWNLOADED + downloaded))
        TOTAL_MISSING=$((TOTAL_MISSING + missing))
    }
    local TOTAL_COPIED=0 TOTAL_DOWNLOADED=0 TOTAL_MISSING=0
    local _n_albums_total=$(( ${#bm_pk[@]} + ${#wm_pk[@]} ))
    if [ "${#bm_pk[@]}" -gt 0 ]; then
        sqlite3 -readonly -separator $'\x1f' "$snap" "
            SELECT $(_sql_tsv_safe aa.ZORIGINALFILENAME), COUNT(*),
                   MIN(a.ZUUID), MIN(a.ZFILENAME)
              FROM ZASSET a
              JOIN ZADDITIONALASSETATTRIBUTES aa ON aa.ZASSET = a.Z_PK
             WHERE a.ZSAVEDASSETTYPE = 6
               AND COALESCE(a.ZTRASHEDSTATE, 0) = 0
               AND aa.ZORIGINALFILENAME IS NOT NULL
               AND aa.ZORIGINALFILENAME <> ''
             GROUP BY aa.ZORIGINALFILENAME;
        " > "$SCRATCH_DIR/lib_masters.tsv" 2>/dev/null \
            || : > "$SCRATCH_DIR/lib_masters.tsv"
        local _lm_line _lm_fn _lm_key
        while IFS= read -r _lm_line; do
            _lm_fn="${_lm_line%%$'\x1f'*}"
            [ -n "$_lm_fn" ] || continue
            _lm_key="${_lm_fn//[!A-Za-z0-9_]/_}"
            printf -v "_libmaster_${_lm_key}" '%s' "$_lm_line"
        done < "$SCRATCH_DIR/lib_masters.tsv"
    fi
    if [ "$SHARED_COPY" = "yes" ] && [ "$_n_albums_total" -gt 0 ]; then
        local _est_local_count=0 _est_local_bytes=0 _est_cloud=0
        local _slice _apk _asset_pk _aa_data _zuuid _zdir _zfilename _rest
        local _cand _cand_size
        local _loc_keys=()
        for _slice in "$SCRATCH_DIR/members_by_album/junction"/* \
                      "$SCRATCH_DIR/members_by_album/share"/*; do
            [ -f "$_slice" ] || continue
            while IFS=$'\x1f' read -r _apk _asset_pk; do
                case "$_asset_pk" in ''|*[!0-9]*) continue ;; esac
                local _aa_ref="_aa_${_asset_pk}"
                _aa_data="${!_aa_ref:-}"
                if [ -z "$_aa_data" ]; then
                    _est_cloud=$((_est_cloud + 1))
                    continue
                fi
                _zuuid=""; _zdir=""; _zfilename=""
                IFS=$'\x1f' read -r _apk _zuuid _zdir _zfilename _rest <<< "$_aa_data"
                local _loc_ref="_loc_${_asset_pk}"
                _cand="${!_loc_ref-$'\x1e'}"
                if [ "$_cand" = $'\x1e' ]; then
                    _cand="$(_resolve_cached_master "$_zuuid" 2>/dev/null)"
                    printf -v "_loc_${_asset_pk}" '%s' "$_cand"
                    _loc_keys+=( "$_loc_ref" )
                fi
                if [ -n "$_cand" ] && [ -f "$_cand" ]; then
                    _cand_size="$(stat -f %z "$_cand" 2>/dev/null)"
                    case "${_cand_size:-0}" in ''|*[!0-9]*) _cand_size=0 ;; esac
                    _est_local_count=$((_est_local_count + 1))
                    _est_local_bytes=$((_est_local_bytes + _cand_size))
                else
                    _est_cloud=$((_est_cloud + 1))
                fi
            done < "$_slice"
        done
        local _gvar
        for _gvar in "${_loc_keys[@]+"${_loc_keys[@]}"}"; do
            unset "$_gvar"
        done
        if [ "$_est_local_count" -gt 0 ]; then
            local _est_local_mb _est_disp
            _est_local_mb=$((_est_local_bytes / 1048576))
            if [ "$_est_local_mb" -ge 1024 ]; then
                _est_disp="$((_est_local_mb / 1024)) GB"
            else
                _est_disp="${_est_local_mb} MB"
            fi
            if [ "$_est_cloud" -gt 0 ]; then
                log_info "Disk estimate: ~${_est_disp} across ${_est_local_count} locally-cached $(_pluralize "$_est_local_count" "asset"); ${_est_cloud} cloud-only $(_pluralize "$_est_cloud" "asset") (sizes unknown until Photos.app fetches them)."
            else
                log_info "Disk estimate: ~${_est_disp} across ${_est_local_count} locally-cached $(_pluralize "$_est_local_count" "asset")."
            fi
        elif [ "$_est_cloud" -gt 0 ]; then
            log_info "Disk estimate: 0 locally-cached assets; ${_est_cloud} cloud-only $(_pluralize "$_est_cloud" "asset") (sizes unknown until Photos.app fetches them)."
        else
            log_info "Disk estimate: no member assets across the $_n_albums_total $(_pluralize "$_n_albums_total" album) — nothing to size."
        fi
        local _df_out _avail_kb
        _df_out="$(df -P -k "$out_root" 2>/dev/null)"
        if [ -n "$_df_out" ]; then
            _avail_kb="$(printf '%s\n' "$_df_out" | awk 'END{print $4}')"
            case "$_avail_kb" in ''|*[!0-9]*) _avail_kb=0 ;; esac
            if [ "$_avail_kb" -ge 1048576 ]; then
                log_info "Export volume: ~$((_avail_kb / 1048576)) GB free."
            else
                log_info "Export volume: ~$((_avail_kb / 1024)) MB free."
            fi
        else
            log_info "Export volume: free space could not be determined (df failed)."
        fi
    fi
    log_info "Downloading + copying members for $_n_albums_total $(_pluralize "$_n_albums_total" album)..."
    if ( : </dev/tty >/dev/tty ) 2>/dev/null; then
        log_info "(press 's' to skip the current shared album)"
    fi
    local _SA_RPT_META="$SCRATCH_DIR/sa_rpt_meta.tsv"
    local _SA_RPT_ASSETS="$SCRATCH_DIR/sa_rpt_assets.tsv"
    local _SA_RPT_ALBUMS="$SCRATCH_DIR/sa_rpt_albums.tsv"
    local _SA_RPT_CONTRIB="$SCRATCH_DIR/sa_rpt_contributors.tsv"
    local _SA_RPT_CAPTIONS="$SCRATCH_DIR/sa_rpt_captions.tsv"
    local _SA_RPT_COMMENTS="$SCRATCH_DIR/sa_rpt_comments.tsv"
    local _SA_RPT_LIBMASTERS="$SCRATCH_DIR/sa_rpt_libmasters.tsv"
    : > "$_SA_RPT_META"; : > "$_SA_RPT_ASSETS"; : > "$_SA_RPT_ALBUMS"
    : > "$_SA_RPT_CONTRIB"; : > "$_SA_RPT_CAPTIONS"; : > "$_SA_RPT_COMMENTS"; : > "$_SA_RPT_LIBMASTERS"
    _heartbeat_start 30 "... per-album download loop still running"
    if [ "${_SKIP_REQUESTED:-0}" = "1" ]; then
        _SKIP_REQUESTED=0
        log_info "  ('s' during setup ignored — nothing to skip yet.)"
    fi
    local i
    for (( i=0; i<${#bm_pk[@]}; i++ )); do
        _copy_album_members "${bm_src[$i]}" "${bm_pk[$i]}" "$out_root/Shared by Me" "${bm_title[$i]}" \
            "${bm_owner[$i]}" "${bm_created[$i]}" "${bm_start[$i]}" "${bm_end[$i]}" "${bm_uuid[$i]}"
    done
    for (( i=0; i<${#wm_pk[@]}; i++ )); do
        _copy_album_members "${wm_src[$i]}" "${wm_pk[$i]}" "$out_root/Shared with You" "${wm_title[$i]}" \
            "${wm_owner[$i]}" "${wm_created[$i]}" "${wm_start[$i]}" "${wm_end[$i]}" "${wm_uuid[$i]}"
    done
    _heartbeat_stop
    if [ "$SHARED_REPORT" = "yes" ] && [ -s "$_SA_RPT_ASSETS" ]; then
        mkdir -p "$out_root" 2>/dev/null
        local _sa_report="$out_root/Shared Albums.report"
        local _sa_rpt_tmp; _sa_rpt_tmp="$(mktemp "$_sa_report.tmp.XXXXXX" 2>/dev/null)" || _sa_rpt_tmp="$SCRATCH_DIR/shared_albums_report.tmp"
        track_output_path "$_sa_rpt_tmp"
        {
            _photos_report_header "$_LIB_PATH_G"
            if [ -s "$_SA_RPT_META" ]; then
                printf '\n[shared_albums]\n'
                printf '# album_uuid\talbum_name\tbucket\towner\texpires\tpublic\tshare_url\tasset_count_reported_by_apple\tmembers_with_full_res_copy\n'
                printf '# One row per shared album. bucket: shared-by-me | shared-with-you. Empty owner = your own album.\n'
                LC_ALL=C sort "$_SA_RPT_META"
            fi
            printf '\n[assets]\n'
            printf '# asset_uuid\toriginal_filename\tstatus\trel_path\tsize\thash\tflags\tcompanions\n'
            printf '# One row per shared-album member across ALL albums. status: on-disk | not-on-disk.\n'
            printf '# rel_path is relative to this Shared Albums/ folder: <bucket>/<album>/<file>.\n'
            printf '# flags: only `downloaded` (bytes fetched from iCloud via Photos.app) or empty.\n'
            printf '# companions: extra on-disk files (Live Photo motion video, shared-video master), each rel_path|size|md5, ;-separated.\n'
            LC_ALL=C sort "$_SA_RPT_ASSETS"
            if [ -s "$_SA_RPT_ALBUMS" ]; then
                printf '\n[albums]\n'
                printf '# album_uuid\talbum_name\tasset_uuid\n'
                printf '# Album membership: which asset belongs to which shared album.\n'
                LC_ALL=C sort "$_SA_RPT_ALBUMS"
            fi
            if [ -s "$_SA_RPT_CONTRIB" ]; then
                printf '\n[contributors]\n'
                printf '# album_uuid\tasset_uuid\tcontributor_name\n'
                printf '# Who posted each asset into its shared album.\n'
                LC_ALL=C sort "$_SA_RPT_CONTRIB"
            fi
            if [ -s "$_SA_RPT_CAPTIONS" ]; then
                printf '\n[captions]\n'
                printf '# album_uuid\tasset_uuid\tcaption\n'
                printf '# Per-asset user-supplied caption.\n'
                LC_ALL=C sort "$_SA_RPT_CAPTIONS"
            fi
            if [ -s "$_SA_RPT_COMMENTS" ]; then
                printf '\n[comments]\n'
                printf '# album_uuid\tasset_uuid\tdatetime\tcommenter\tkind\ttext\tmine\n'
                printf '# Comments + likes. kind = comment | like; mine = 1 when the local user authored it.\n'
                LC_ALL=C sort "$_SA_RPT_COMMENTS"
            fi
            if [ -s "$_SA_RPT_LIBMASTERS" ]; then
                printf '\n[library_full_res]\n'
                printf '# album_uuid\tlow_quality_uuid\tfull_quality_uuid\n'
                printf '# Shared-by-me members whose full-res master is in the library export.\n'
                LC_ALL=C sort "$_SA_RPT_LIBMASTERS"
            fi
            :
        } > "$_sa_rpt_tmp" 2>/dev/null \
            && mv -f -- "$_sa_rpt_tmp" "$_sa_report" 2>/dev/null \
            || { rm -f -- "$_sa_rpt_tmp" 2>/dev/null
                 log_warn "failed to write Shared Albums.report"
                 note_incomplete "$_PHOTOS_DIR" "Shared Albums.report" \
                     "the consolidated shared-albums catalog could not be written (disk-full or torn write) — the per-album asset list is not in this export"; }
        _untrack_output_path "$_sa_rpt_tmp"
        if [ -f "$_sa_report" ]; then
            local _exp_assets _got_assets
            _exp_assets="$(awk 'END{print NR+0}' <"$_SA_RPT_ASSETS" 2>/dev/null)"
            _got_assets="$(awk '/^\[assets\]$/{f=1;next} /^\[/{f=0} f&&NF&&$0!~/^#/{n++} END{print n+0}' "$_sa_report" 2>/dev/null)"
            case "$_got_assets" in ''|*[!0-9]*) _got_assets=0 ;; esac
            if [ "$_got_assets" -lt "$_exp_assets" ]; then
                log_warn "Shared Albums.report is short — wrote $_got_assets of $_exp_assets asset row(s); the file may be truncated."
                note_incomplete "$_PHOTOS_DIR" "Shared Albums.report" \
                    "the consolidated report write was truncated ($_got_assets of $_exp_assets asset rows) — disk-full or torn write"
            fi
            : # Shared Albums report folded into the consolidated Photos/Libraries/<stem>.report
        fi
    fi
    log_info "Finalising: pruning empty buckets + counting companion files..."
    find "$out_root" -mindepth 1 -type d -empty -delete 2>/dev/null || true
    if [ "$TOTAL_COPIED" -eq 0 ] && [ "$TOTAL_DOWNLOADED" -eq 0 ]; then
        rmdir "$out_root" 2>/dev/null || true
        rmdir "$(dirname "$out_root")" 2>/dev/null || true
    fi
    rmdir "$photos_dir" 2>/dev/null || true
    local _n_albums=$((${#bm_pk[@]} + ${#wm_pk[@]}))
    local _stat
    _stat="$_n_albums $(_pluralize "$_n_albums" album) — ${#bm_pk[@]} by me, ${#wm_pk[@]} with me; $TOTAL_COPIED $(_pluralize "$TOTAL_COPIED" file) copied"
    [ "$TOTAL_DOWNLOADED" -gt 0 ] && _stat="$_stat (incl. $TOTAL_DOWNLOADED downloaded)"
    [ "$TOTAL_MISSING" -gt 0 ] && _stat="$_stat, $TOTAL_MISSING missing"
    local _n_contrib _n_comments _n_captions
    _n_contrib="$(find "$out_root" -maxdepth 2 -type f -name '*.report' -exec grep -lF '[contributors]' {} + 2>/dev/null | LC_ALL=C wc -l | tr -d '[:space:]')"
    _n_comments="$(find "$out_root" -maxdepth 2 -type f -name '*.report' -exec grep -lF '[comments]' {} + 2>/dev/null | LC_ALL=C wc -l | tr -d '[:space:]')"
    _n_captions="$(find "$out_root" -maxdepth 2 -type f -name '*.report' -exec grep -lF '[captions]' {} + 2>/dev/null | LC_ALL=C wc -l | tr -d '[:space:]')"
    case "$_n_contrib" in    ''|*[!0-9]*) _n_contrib=0 ;; esac
    case "$_n_comments" in   ''|*[!0-9]*) _n_comments=0 ;; esac
    case "$_n_captions" in   ''|*[!0-9]*) _n_captions=0 ;; esac
    local _n_folded=$((_n_contrib + _n_comments + _n_captions))
    [ "$_n_folded" -gt 0 ] && _stat="$_stat, $_n_folded folded metadata $(_pluralize "$_n_folded" section)"
    _stat="$_stat, $(_dir_size_human "$out_root")"
    local _sa_disp_stem; _sa_disp_stem="$(basename "$(dirname "$out_root")")"
    if [ -d "$out_root" ]; then
        log_ok "Wrote Photos/Libraries/$_sa_disp_stem/Shared Albums/ ($_stat)"
    else
        log_info "Shared albums: nothing to write for $_sa_disp_stem ($_stat)"
    fi
    if [ "$_sib_copy_failed_count" -gt 0 ]; then
        log_warn "$_sib_copy_failed_count Live Photo / shared-video sibling $(_pluralize "$_sib_copy_failed_count" copy copies) failed — the main asset landed but the companion motion clip or video master did not. The asset's [assets] row will be missing that companion; re-run with the source library re-mounted to capture it."
        note_incomplete "$_PHOTOS_DIR" "Shared-album companion files" \
            "$_sib_copy_failed_count Live Photo / shared-video companion file(s) could not be copied — the main asset landed but its motion clip / video master did not, so those assets are incomplete. Re-run with the source library available to capture them."
    fi
    if [ "$ERR_COUNT" -gt "$_sa_err0" ]; then return 1; fi
    return 0
}

_cd_ts_to_human() {
    local u; u="$(_cd_ts_to_unix "$1")"; [ -z "$u" ] && return 0
    date -r "$u" "+%Y-%m-%d %H:%M" 2>/dev/null
}

_cd_ts_to_date() {
    local u; u="$(_cd_ts_to_unix "$1")"; [ -z "$u" ] && return 0
    date -r "$u" +%Y%m%d 2>/dev/null
}

_build_rrule() {
    local _packed="$1"
    local _allday="${2:-0}"
    local _freq _interval _count _until _wk _md
    _freq="${_packed%%|*}"; _packed="${_packed#*|}"
    _interval="${_packed%%|*}"; _packed="${_packed#*|}"
    _count="${_packed%%|*}"; _packed="${_packed#*|}"
    _until="${_packed%%|*}"; _packed="${_packed#*|}"
    _wk="${_packed%%|*}"; _packed="${_packed#*|}"
    _md="${_packed}"
    _wk="${_wk%%.*}"
    _md="${_md%%.*}"
    _freq="${_freq%%.*}"
    local _freq_name=""
    case "$_freq" in
        0|DAILY|daily)   _freq_name="DAILY" ;;
        1|WEEKLY|weekly) _freq_name="WEEKLY" ;;
        2|MONTHLY|monthly) _freq_name="MONTHLY" ;;
        3|YEARLY|yearly) _freq_name="YEARLY" ;;
        *) return 0 ;;
    esac
    local _rrule="FREQ=$_freq_name"
    _interval="${_interval%%.*}"
    case "$_interval" in
        ''|0|1) : ;;
        *[!0-9]*) : ;;
        *) _rrule="$_rrule;INTERVAL=$_interval" ;;
    esac
    _count="${_count%%.*}"
    local _have_count=0
    case "$_count" in
        ''|0) : ;;
        *[!0-9]*) : ;;
        *) _rrule="$_rrule;COUNT=$_count"; _have_count=1 ;;
    esac
    if [ "$_have_count" -eq 0 ] && [ -n "$_until" ]; then
        local _until_ics
        if [ "$_allday" = "1" ]; then
            _until_ics="$(_cd_ts_to_date "$_until")"
        else
            _until_ics="$(_cd_ts_to_utc "$_until")"
        fi
        [ -n "$_until_ics" ] && _rrule="$_rrule;UNTIL=$_until_ics"
    fi
    if [ -n "$_wk" ]; then
        local _byday=""
        case "$_wk" in
            *[!0-9]*)
                _byday="$(printf '%s' "$_wk" | tr ' ' ',' | tr -s ',' \
                    | LC_ALL=C tr -cd 'A-Z0-9,+-')"
                ;;
            ''|0) : ;;
            *)
                local _wkmask=$(( 10#$_wk & 127 ))
                local _days="SU MO TU WE TH FR SA" _bit=0 _tok
                local _IFS_save="$IFS"; IFS=' '
                for _tok in $_days; do
                    if [ $(( (_wkmask >> _bit) & 1 )) -eq 1 ]; then
                        _byday="${_byday:+$_byday,}$_tok"
                    fi
                    _bit=$((_bit + 1))
                done
                IFS="$_IFS_save"
                ;;
        esac
        _rrule="$_rrule$(_rrule_by_fragment BYDAY "$_byday" 'A-Z0-9,+-' '[A-Z]')"
    fi
    if [ -n "$_md" ]; then
        local _bymd=""
        case "$_md" in
            *[!0-9,\ -]*) : ;;
            ''|0) : ;;
            *) # Normalise separators and pre-restrict to the BYMONTHDAY
               _bymd="$(printf '%s' "$_md" | tr ' ' ',' | tr -s ',' \
                   | LC_ALL=C tr -cd '0-9,-')" ;;
        esac
        _rrule="$_rrule$(_rrule_by_fragment BYMONTHDAY "$_bymd" '0-9,-' '[0-9]')"
    fi
    printf '%s' "$_rrule"
}

REM_DIR="$HOME/Library/Group Containers/group.com.apple.reminders/Container_v1/Stores"

reminders_main() {
    maybe_show_help "$@"
    _announce_step "Reminders export"
    check_dependencies
    local out_arg out_dir
    out_arg="$(_parse_output_folder_arg "$@")" || exit 1
    out_dir="$(resolve_output_dir "$out_arg")" || exit 1
    _announce_output_dir "Reminders"
    require_full_disk_access
    warn_if_app_running Reminders
    [ -d "$REM_DIR" ] || die "Reminders store not found: $REM_DIR
  Open Reminders.app once to initialise it, then re-run."
    local out_root="$out_dir/Reminders"
    local ics_file="$out_root/Reminders.ics"
    local csv_file="$out_root/Reminders.csv"
    require_no_collision "$out_root"
    ensure_scratch
    log_info "Discovering Reminder stores..."
    local -a stores=()
    local f
    while IFS= read -r -d '' f; do
        stores+=( "$f" )
    done < <(find "$REM_DIR" -maxdepth 1 -type f -name 'Data-*.sqlite' -print0 2>/dev/null)
    [ "${#stores[@]}" -eq 0 ] && die "No Reminders store databases found"
    local merged_lists="$SCRATCH_DIR/lists.tsv"
    local merged_rems="$SCRATCH_DIR/rems.tsv"
    local rem_uidmap="$SCRATCH_DIR/rem_uidmap.tsv"
    local rem_recurmap="$SCRATCH_DIR/rem_recurmap.tsv"
    local rem_tagmap="$SCRATCH_DIR/rem_tagmap.tsv"
    local rem_sectionmap="$SCRATCH_DIR/rem_sectionmap.tsv"
    : > "$merged_lists"
    : > "$merged_rems"
    : > "$rem_uidmap"
    : > "$rem_recurmap"
    : > "$rem_tagmap"
    : > "$rem_sectionmap"
    local smart_filtered=0
    local list_deleted_filtered=0
    local soft_deleted=0
    local discovered_rems=0
    local discovered_lists=0
    local rems_census_failures=0 lists_census_failures=0 rems_census_attempted=0 lists_census_attempted=0
    local _smart_col_chosen=""
    log_info "Snapshotting ${#stores[@]} $(_pluralize "${#stores[@]}" store) and dumping list/reminder tables..."
    log_info "Stores dir: $REM_DIR/"
    local store snap entN_list _source_store_basename
    local rcol_title rcol_completed rcol_priority \
          rcol_due rcol_notes rcol_list rcol_completed_date \
          rcol_creation rcol_allday rcol_deleted \
          rcol_start rcol_flagged rcol_url rcol_parent rcol_recurrence \
          list_table uid_expr_rem
    local rstart_expr rflagged_expr rurl_expr rparent_expr rrecur_fk_expr
    local _has_parent_data=0
    local _parent_col_seen=0 _stores_probed=0
    local _has_recurrence_data=0 _has_tag_data=0
    local _rem_incomplete=()
    _build_aliased_name_expr() {  # $1 = alias prefix (l / g)
        local _out="" _gc _first=1 _IFS_save="$IFS"
        if [ -n "$_zname_list" ]; then
            _out="COALESCE("
            IFS=','
            for _gc in $_zname_list; do
                _gc="${_gc# }"
                if [ "$_first" -eq 1 ]; then _first=0; else _out="$_out, "; fi
                _out="${_out}${1}.$_gc"
            done
            IFS="$_IFS_save"
            _out="$_out, '')"
        else
            _out="COALESCE(${1}.ZNAME, '')"
        fi
        printf '%s' "$_out"
    }
    for store in "${stores[@]}"; do
        _source_store_basename="$(basename "$store")"
        _source_store_basename="$(printf '%s' "$_source_store_basename" \
            | tr -c 'A-Za-z0-9._-' '-')"
        log_info "  • ${store##*/}"
        if ! snap="$(snapshot_db "$store")"; then
            log_warn "Could not snapshot $store."
            _incomplete_push _rem_incomplete "Reminders account \"${store##*/}\"" "the account's store database could not be snapshotted for reading — none of this account's lists or reminders were exported"
            continue
        fi
        if ! sqlite3 -readonly "$snap" "SELECT 1 FROM ZREMCDREMINDER LIMIT 1;" >/dev/null 2>&1; then
            local _avail
            _avail="$(sqlite3 -readonly "$snap" \
                "SELECT GROUP_CONCAT(name, ', ') FROM sqlite_master \
                  WHERE type='table' AND name LIKE 'ZREMCD%';" 2>/dev/null)"
            log_warn "Skipping $(basename "$store" .sqlite): ZREMCDREMINDER not queryable (available: ${_avail:-none})"
            _incomplete_push _rem_incomplete "Reminders account \"$(basename "$store" .sqlite)\"" "the ZREMCDREMINDER table is not queryable (corrupt store or unrecognised schema; tables present: ${_avail:-none}) — none of this account's reminders were exported"
            continue
        fi
        local _entN_rc=0
        entN_list="$(_resolve_entity_number "$snap" REMCDList)" || _entN_rc=1
        if [ "$_entN_rc" -ne 0 ]; then
            log_warn "Skipping $(basename "$store" .sqlite): REMCDList entity number not resolvable from Z_PRIMARYKEY (corrupt store or unrecognised schema)"
            _incomplete_push _rem_incomplete "Reminders account \"$(basename "$store" .sqlite)\"" "the REMCDList Core Data entity number could not be resolved from Z_PRIMARYKEY (corrupt store or unrecognised schema) — none of this account's lists or reminders were exported"
            continue
        fi
        local _rcols _lcols _zname_cols _zc _uid_col _uid_candidate _db_tag
        _rcols="$(sqlite3 -readonly "$snap" "SELECT name FROM pragma_table_info('ZREMCDREMINDER');" 2>/dev/null)"
        rcol_title="$(_pick_first_col     "$snap" ZREMCDREMINDER ZTITLE ZTITLE1 ZTITLE2     || printf 'ZTITLE')"
        rcol_completed="$(_pick_first_col "$snap" ZREMCDREMINDER ZCOMPLETED                 || printf 'ZCOMPLETED')"
        rcol_priority="$(_pick_first_col  "$snap" ZREMCDREMINDER ZPRIORITY                  || printf 'ZPRIORITY')"
        rcol_due="$(_pick_first_col       "$snap" ZREMCDREMINDER ZDUEDATE                   || printf 'ZDUEDATE')"
        rcol_notes="$(_pick_first_col     "$snap" ZREMCDREMINDER ZNOTES ZNOTES1 ZNOTES2     || printf 'ZNOTES')"
        rcol_list="$(_pick_first_col      "$snap" ZREMCDREMINDER ZLIST                      || printf 'ZLIST')"
        rcol_completed_date="$(_pick_first_col "$snap" ZREMCDREMINDER ZCOMPLETIONDATE     || true)"
        rcol_creation="$(_pick_first_col       "$snap" ZREMCDREMINDER ZCREATIONDATE       || true)"
        rcol_allday="$(_pick_first_col         "$snap" ZREMCDREMINDER ZALLDAY             || true)"
        rcol_deleted="$(_pick_first_col        "$snap" ZREMCDREMINDER ZMARKEDFORDELETION  || true)"
        case "$rcol_completed_date" in ''|*[!A-Za-z0-9_]*) rcol_completed_date="NULL" ;; esac
        case "$rcol_creation"       in ''|*[!A-Za-z0-9_]*) rcol_creation="NULL" ;; esac
        case "$rcol_allday"         in ''|*[!A-Za-z0-9_]*) rcol_allday="NULL" ;; esac
        case "$rcol_deleted"        in ''|*[!A-Za-z0-9_]*) rcol_deleted="NULL" ;; esac
        local _ldel _rdel _ldel_col
        _rdel="1=1"
        case "$rcol_title"          in *[!A-Za-z0-9_]*) rcol_title="ZTITLE" ;; esac
        case "$rcol_completed"      in *[!A-Za-z0-9_]*) rcol_completed="ZCOMPLETED" ;; esac
        case "$rcol_priority"       in *[!A-Za-z0-9_]*) rcol_priority="ZPRIORITY" ;; esac
        case "$rcol_due"            in *[!A-Za-z0-9_]*) rcol_due="ZDUEDATE" ;; esac
        case "$rcol_notes"          in *[!A-Za-z0-9_]*) rcol_notes="ZNOTES" ;; esac
        case "$rcol_list"           in *[!A-Za-z0-9_]*) rcol_list="ZLIST" ;; esac
        rcol_start="$(_pick_first_col "$snap" ZREMCDREMINDER ZSTARTDATE || true)"
        case "$rcol_start" in
            ''|*[!A-Za-z0-9_]*) rstart_expr="NULL" ;;
            *) rstart_expr="$rcol_start" ;;
        esac
        rcol_flagged="$(_pick_first_col "$snap" ZREMCDREMINDER ZFLAGGED || true)"
        case "$rcol_flagged" in
            ''|*[!A-Za-z0-9_]*) rflagged_expr="NULL" ;;
            *) rflagged_expr="$rcol_flagged" ;;
        esac
        rurl_expr="NULL"
        local _url_ent _url_fk_cols _url_or="" _url_fk
        _url_ent="$(_resolve_entity_number "$snap" REMCDURLAttachment || true)"
        if [ -n "$_url_ent" ] && sqlite3 -readonly "$snap" \
                "SELECT 1 FROM pragma_table_info('ZREMCDOBJECT') WHERE name='ZURL' LIMIT 1;" \
                2>/dev/null | grep -q '^1$'; then
            _url_fk_cols="$(sqlite3 -readonly "$snap" \
                "SELECT name FROM pragma_table_info('ZREMCDOBJECT') \
                  WHERE name = 'ZREMINDER' OR name GLOB 'ZREMINDER[0-9]';" 2>/dev/null)"
            for _url_fk in $_url_fk_cols; do
                case "$_url_fk" in *[!A-Za-z0-9_]*) continue ;; esac
                if [ -z "$_url_or" ]; then
                    _url_or="o.$_url_fk = ZREMCDREMINDER.Z_PK"
                else
                    _url_or="$_url_or OR o.$_url_fk = ZREMCDREMINDER.Z_PK"
                fi
            done
            if [ -n "$_url_or" ]; then
                rurl_expr="(SELECT o.ZURL FROM ZREMCDOBJECT o
                    WHERE o.Z_ENT = $_url_ent
                      AND COALESCE(o.ZMARKEDFORDELETION, 0) = 0
                      AND o.ZURL IS NOT NULL AND o.ZURL <> ''
                      AND ($_url_or)
                    ORDER BY o.Z_PK LIMIT 1)"
            fi
        fi
        if [ "$rurl_expr" = "NULL" ]; then
            rcol_url="$(_pick_first_col "$snap" ZREMCDREMINDER ZREMINDERURL ZURL)"
            case "$rcol_url" in
                '') rurl_expr="NULL" ;;
                *)  rurl_expr="$rcol_url" ;;
            esac
        fi
        rcol_parent="$(_pick_first_col "$snap" ZREMCDREMINDER ZPARENTREMINDER || true)"
        case "$rcol_parent" in
            ''|*[!A-Za-z0-9_]*) rparent_expr="NULL" ;;
            *) rparent_expr="$rcol_parent"; _parent_col_seen=1 ;;
        esac
        _stores_probed=$((_stores_probed + 1))
        rcol_recurrence="$(_pick_first_col "$snap" ZREMCDREMINDER ZRECURRENCERULE ZRECURRENCE)"
        case "$rcol_recurrence" in
            '') rrecur_fk_expr="NULL" ;;
            *)  rrecur_fk_expr="$rcol_recurrence" ;;
        esac
        list_table=""
        local _has_lists
        for _zc in ZREMCDBASELIST ZREMCDOBJECT; do
            _lcols="$(sqlite3 -readonly "$snap" \
                "SELECT name FROM pragma_table_info('$_zc');" 2>/dev/null)"
            [ -z "$_lcols" ] && continue
            _has_lists="$(sqlite3 -readonly "$snap" \
                "SELECT COUNT(*) FROM $_zc WHERE Z_ENT=$entN_list;" 2>/dev/null)"
            case "${_has_lists:-0}" in ''|0) continue ;; esac
            list_table="$_zc"
            break
        done
        [ -z "$list_table" ] && list_table="ZREMCDBASELIST"
        _lcols="$(sqlite3 -readonly "$snap" \
            "SELECT name FROM pragma_table_info('$list_table');" 2>/dev/null)"
        _ldel_col="$(_pick_first_col "$snap" "$list_table" ZMARKEDFORDELETION || true)"
        case "$_ldel_col" in ''|*[!A-Za-z0-9_]*) _ldel_col="NULL" ;; esac
        if [ "$_ldel_col" = "NULL" ]; then
            _ldel="1=1"
        else
            _ldel="(l.$_ldel_col IS NULL OR l.$_ldel_col = 0)"
        fi
        _zname_cols="$(printf '%s\n' "$_lcols" | grep -E '^ZNAME([0-9]+)?$' | sort -V)"
        local _zname_list=""
        while IFS= read -r _zc; do
            [ -z "$_zc" ] && continue
            case "$_zc" in *[!A-Za-z0-9_]*) continue ;; esac
            _zname_list="${_zname_list:+${_zname_list}, }$_zc"
        done <<< "$_zname_cols"
        _uid_col=""
        for _uid_candidate in ZUNIQUEIDENTIFIER ZIDENTIFIER ZLOCALUUID ZCKIDENTIFIER; do
            if printf '%s\n' "$_rcols" | grep -qx "$_uid_candidate"; then
                _uid_col="$_uid_candidate"
                break
            fi
        done
        _db_tag="$(basename "$store" .sqlite)"
        _db_tag="$(printf '%s' "$_db_tag" | tr -c 'A-Za-z0-9._-' '-')"
        if [ -n "$_uid_col" ]; then
            if [ "$_uid_col" = "ZUNIQUEIDENTIFIER" ]; then
                uid_expr_rem="CASE
                    WHEN typeof($_uid_col) = 'blob' THEN lower(hex($_uid_col))
                    WHEN $_uid_col IS NULL OR $_uid_col = '' THEN '${_db_tag}-' || Z_PK
                    ELSE $_uid_col
                END"
            else
                uid_expr_rem="CASE
                    WHEN typeof($_uid_col) = 'blob' THEN '${_db_tag}-' || lower(hex($_uid_col))
                    WHEN $_uid_col IS NULL OR $_uid_col = '' THEN '${_db_tag}-' || Z_PK
                    ELSE '${_db_tag}-' || $_uid_col
                END"
            fi
        else
            uid_expr_rem="'${_db_tag}-' || Z_PK"
        fi
        local _smart_predicate="" _sc _smart_col=""
        for _sc in ZSMARTLISTTYPE ZISSMARTLIST ZSMARTLIST ZISSMART; do
            if sqlite3 -readonly "$snap" \
                "SELECT 1 FROM pragma_table_info('$list_table') WHERE name='$_sc' LIMIT 1;" \
                2>/dev/null | grep -q '^1$'; then
                _smart_predicate=" AND COALESCE(l.$_sc, 0) = 0"
                _smart_col="$_sc"
                break
            fi
        done
        [ -z "$_smart_col_chosen" ] && _smart_col_chosen="$_smart_col"
        if [ -n "$_smart_col" ]; then
            local _n_smart
            _n_smart="$(sqlite3 -readonly "$snap" \
                "SELECT COUNT(*) FROM $list_table \
                  WHERE Z_ENT = $entN_list \
                    AND ($_ldel_col IS NULL OR $_ldel_col = 0) \
                    AND COALESCE($_smart_col, 0) != 0;" 2>/dev/null)"
            case "${_n_smart:-0}" in
                ''|*[!0-9]*) : ;;
                *) smart_filtered=$((smart_filtered + _n_smart)) ;;
            esac
        fi
        if [ "$_ldel_col" != "NULL" ]; then
            local _n_ldel _ldel_smart_excl=""
            [ -n "$_smart_col" ] && _ldel_smart_excl=" AND COALESCE($_smart_col, 0) = 0"
            _n_ldel="$(sqlite3 -readonly "$snap" \
                "SELECT COUNT(*) FROM $list_table \
                  WHERE Z_ENT = $entN_list \
                    AND COALESCE($_ldel_col, 0) != 0$_ldel_smart_excl;" 2>/dev/null)"
            case "${_n_ldel:-0}" in
                ''|*[!0-9]*) : ;;
                *) list_deleted_filtered=$((list_deleted_filtered + _n_ldel)) ;;
            esac
        fi
        local _grp_fk _grp_fk_e="NULL" _color_col _color_e="NULL"
        _grp_fk="$(_pick_first_col "$snap" "$list_table" ZPARENTGROUP ZGROUP ZPARENTLIST)"
        case "$_grp_fk" in '') : ;; *) _grp_fk_e="$_grp_fk" ;; esac
        _color_col="$(_pick_first_col "$snap" "$list_table" ZCOLOR ZCOLORDATA ZCOLORSTRING)"
        case "$_color_col" in '') : ;; *) _color_e="l.$_color_col" ;; esac
        local _l_name_expr _list_name_select
        _l_name_expr="$(_build_aliased_name_expr l)"
        if [ "$_grp_fk_e" != "NULL" ]; then
            local _g_name_expr
            _g_name_expr="$(_build_aliased_name_expr g)"
            _list_name_select="CASE WHEN $_g_name_expr != '' \
                THEN $_g_name_expr || '/' || ($_l_name_expr) \
                ELSE ($_l_name_expr) END"
        else
            _list_name_select="$_l_name_expr"
        fi
        local _list_join=""
        [ "$_grp_fk_e" != "NULL" ] && \
            _list_join=" LEFT JOIN $list_table g ON l.$_grp_fk_e = g.Z_PK"
        local _color_select="''"
        if [ "$_color_e" != "NULL" ]; then
            _color_select="CASE WHEN typeof($_color_e)='blob' \
                THEN lower(hex($_color_e)) ELSE COALESCE($_color_e, '') END"
        fi
        sqlite3 -readonly -separator $'\x1f' "$snap" "
            SELECT '$_source_store_basename', l.Z_PK,
                   $(_sql_tsv_safe "$_list_name_select"),
                   $(_sql_tsv_safe "$_color_select")
              FROM $list_table l$_list_join
             WHERE l.Z_ENT = $entN_list
               AND $_ldel$_smart_predicate;
        " >> "$merged_lists" || {
            log_warn "Reminders SELECT failed for $store."
            _incomplete_push _rem_incomplete "Lists from Reminders account \"${store##*/}\"" "the list query (SELECT against $list_table) failed — this account's lists may be missing or partial in the export"
        }
        local _list_census
        _list_census="$(sqlite3 -readonly "$snap" \
            "SELECT COUNT(*) FROM $list_table l \
              WHERE l.Z_ENT = $entN_list \
                AND $_ldel$_smart_predicate;" \
            2>/dev/null)"
        lists_census_attempted=$((lists_census_attempted + 1))
        case "${_list_census:-0}" in
            ''|*[!0-9]*) lists_census_failures=$((lists_census_failures + 1)) ;;
            *) discovered_lists=$((discovered_lists + _list_census)) ;;
        esac
        local _rem_census _n_soft=0 _n_live=0
        _rem_census="$(sqlite3 -readonly -separator $'\x1f' "$snap" \
            "SELECT SUM(CASE WHEN $rcol_deleted IS NOT NULL AND $rcol_deleted != 0 THEN 1 ELSE 0 END), \
                    SUM(CASE WHEN $rcol_deleted IS NULL OR $rcol_deleted = 0 THEN 1 ELSE 0 END) \
               FROM ZREMCDREMINDER;" 2>/dev/null)"
        rems_census_attempted=$((rems_census_attempted + 1))
        if [ -z "$_rem_census" ]; then
            rems_census_failures=$((rems_census_failures + 1))
        else
            IFS=$'\x1f' read -r _n_soft _n_live <<< "$_rem_census"
            case "${_n_soft:-0}" in ''|*[!0-9]*) _n_soft=0 ;; esac
            case "${_n_live:-0}" in ''|*[!0-9]*) _n_live=0 ;; esac
            soft_deleted=$((soft_deleted + _n_soft))
            discovered_rems=$((discovered_rems + _n_soft + _n_live))
        fi
        sqlite3 -readonly -separator $'\x1f' "$snap" "
            SELECT '$_source_store_basename', Z_PK, COALESCE($rcol_list, ''),
                   $(_sql_tsv_bsafe "$rcol_title"), $(_sql_tsv_bsafe "$rcol_notes"),
                   CAST(COALESCE($rcol_completed, 0) AS INTEGER),
                   CAST(COALESCE($rcol_priority, 0) AS INTEGER),
                   COALESCE($rcol_due, ''), COALESCE($rcol_completed_date, ''),
                   COALESCE($rcol_creation, ''),
                   CAST(COALESCE($rcol_allday, 0) AS INTEGER),
                   $(_sql_tsv_safe "$uid_expr_rem"),
                   COALESCE($rstart_expr, ''),
                   CAST(COALESCE($rflagged_expr, 0) AS INTEGER),
                   $(_sql_tsv_bsafe "COALESCE($rurl_expr, '')"),
                   COALESCE($rparent_expr, ''),
                   CAST(COALESCE($rcol_deleted, 0) AS INTEGER)
              FROM ZREMCDREMINDER
             ORDER BY Z_PK;
        " >> "$merged_rems" || {
            log_warn "Reminders SELECT failed for $store."
            _incomplete_push _rem_incomplete "Reminders from account \"${store##*/}\"" "the reminder query (SELECT against ZREMCDREMINDER) failed — this account's reminders may be missing or partial in the export"
        }
        if [ "$rparent_expr" != "NULL" ]; then
            local _pcount
            _pcount="$(sqlite3 -readonly "$snap" \
                "SELECT COUNT(*) FROM ZREMCDREMINDER \
                  WHERE $rparent_expr IS NOT NULL;" 2>/dev/null)"
            case "${_pcount:-0}" in ''|0) : ;; *) _has_parent_data=1 ;; esac
            if ! sqlite3 -readonly -separator $'\x1f' "$snap" "
                SELECT '$_source_store_basename', Z_PK, $(_sql_tsv_safe "$uid_expr_rem")
                  FROM ZREMCDREMINDER;
            " >> "$rem_uidmap" 2>/dev/null; then
                log_warn "Failed to dump UID map for store $_source_store_basename — RELATED-TO links may be incomplete"
                _incomplete_push _rem_incomplete "Reminders UID map ($_source_store_basename)" "the UID map extract from ZREMCDREMINDER failed for this store — subtask RELATED-TO links for reminders in this store are missing in the VTODO output"
            fi
        fi
        if [ "$rrecur_fk_expr" != "NULL" ]; then
            local _rrtable="" _rrt
            for _rrt in ZREMCDRECURRENCERULE ZRECURRENCERULE ZREMCDRECURRENCE; do
                case "$_rrt" in *[!A-Za-z0-9_]*) continue ;; esac
                if sqlite3 -readonly "$snap" \
                    "SELECT 1 FROM sqlite_master \
                       WHERE type='table' AND name='$_rrt' LIMIT 1;" \
                    2>/dev/null | grep -q '^1$'; then
                    _rrtable="$_rrt"; break
                fi
            done
            if [ -n "$_rrtable" ]; then
                local _rr_freq _rr_interval _rr_count _rr_until \
                      _rr_wkdays _rr_monthdays
                _rr_freq="$(_pick_first_col "$snap" "$_rrtable" \
                              ZFREQUENCY ZRECURRENCEFREQUENCY ZTYPE)"
                _rr_interval="$(_pick_first_col "$snap" "$_rrtable" \
                                   ZINTERVAL ZRECURRENCEINTERVAL)"
                _rr_count="$(_pick_first_col "$snap" "$_rrtable" \
                                ZRECURRENCECOUNT ZCOUNT ZOCCURRENCECOUNT)"
                _rr_until="$(_pick_first_col "$snap" "$_rrtable" \
                                ZRECURRENCEEND ZENDDATE ZUNTILDATE ZEND)"
                _rr_wkdays="$(_pick_first_col "$snap" "$_rrtable" \
                                 ZDAYSOFTHEWEEK ZWEEKDAYS ZDAYSOFWEEK)"
                _rr_monthdays="$(_pick_first_col "$snap" "$_rrtable" \
                                    ZDAYSOFTHEMONTH ZMONTHDAYS ZDAYSOFMONTH)"
                local _rr_freq_sel="''" _rr_interval_sel="''" _rr_count_sel="''" \
                      _rr_until_sel="''" _rr_wkdays_sel="''" _rr_monthdays_sel="''"
                [ -n "$_rr_freq" ]      && _rr_freq_sel="COALESCE(rr.$_rr_freq, '')"
                [ -n "$_rr_interval" ]  && _rr_interval_sel="COALESCE(rr.$_rr_interval, '')"
                [ -n "$_rr_count" ]     && _rr_count_sel="COALESCE(rr.$_rr_count, '')"
                [ -n "$_rr_until" ]     && _rr_until_sel="COALESCE(rr.$_rr_until, '')"
                [ -n "$_rr_wkdays" ]    && _rr_wkdays_sel="$(_sql_tsv_safe "COALESCE(rr.$_rr_wkdays, '')")"
                [ -n "$_rr_monthdays" ] && _rr_monthdays_sel="$(_sql_tsv_safe "COALESCE(rr.$_rr_monthdays, '')")"
                local _rcount
                _rcount="$(sqlite3 -readonly "$snap" \
                    "SELECT COUNT(*) FROM ZREMCDREMINDER r \
                       JOIN $_rrtable rr ON r.$rrecur_fk_expr = rr.Z_PK \
                      WHERE $_rdel;" 2>/dev/null)"
                case "${_rcount:-0}" in ''|0) : ;; *) _has_recurrence_data=1 ;; esac
                if ! sqlite3 -readonly -separator $'\x1f' "$snap" "
                    SELECT '$_source_store_basename', r.Z_PK,
                           $_rr_freq_sel,
                           $_rr_interval_sel,
                           $_rr_count_sel,
                           $_rr_until_sel,
                           $_rr_wkdays_sel,
                           $_rr_monthdays_sel
                      FROM ZREMCDREMINDER r
                      JOIN $_rrtable rr ON r.$rrecur_fk_expr = rr.Z_PK
                     WHERE $_rdel;
                " >> "$rem_recurmap" 2>/dev/null; then
                    log_warn "Failed to dump recurrence map for store $_source_store_basename — RRULE output may be incomplete"
                    _incomplete_push _rem_incomplete "Reminders recurrence map ($_source_store_basename)" "the recurrence-rule extract failed for this store — RRULE properties for recurring reminders in this store are missing"
                fi
            fi
        fi
        local _tagtable="" _tt
        for _tt in ZREMCDHASHTAG ZREMCDTAG ZHASHTAG; do
            case "$_tt" in *[!A-Za-z0-9_]*) continue ;; esac
            if sqlite3 -readonly "$snap" \
                "SELECT 1 FROM sqlite_master \
                   WHERE type='table' AND name='$_tt' LIMIT 1;" \
                2>/dev/null | grep -q '^1$'; then
                _tagtable="$_tt"; break
            fi
        done
        if [ -n "$_tagtable" ]; then
            local _tag_name_col
            _tag_name_col="$(_pick_first_col "$snap" "$_tagtable" \
                                ZNAME ZTITLE ZNAME1 ZTITLE1 ZDISPLAYNAME)"
            local _tagjoin
            _tagjoin="$(sqlite3 -readonly "$snap" \
                "SELECT name FROM sqlite_master \
                   WHERE type='table' AND name GLOB 'Z_[0-9]*HASHTAGS' \
                   ORDER BY name LIMIT 1;" 2>/dev/null)"
            case "$_tagjoin" in
                Z_*HASHTAGS) : ;;
                *) _tagjoin="" ;;
            esac
            case "$_tagjoin" in *[!A-Za-z0-9_]*) _tagjoin="" ;; esac
            local _tj_tag_col="" _tj_rem_col=""
            if [ -n "$_tagjoin" ]; then
                _tj_tag_col="$(sqlite3 -readonly "$snap" \
                    "SELECT name FROM pragma_table_info('$_tagjoin') \
                       WHERE name GLOB 'Z_[0-9]*HASHTAGS' LIMIT 1;" 2>/dev/null)"
                _tj_rem_col="$(sqlite3 -readonly "$snap" \
                    "SELECT name FROM pragma_table_info('$_tagjoin') \
                       WHERE name GLOB 'Z_[0-9]*REMINDERS' LIMIT 1;" 2>/dev/null)"
                case "$_tj_tag_col" in *[!A-Za-z0-9_]*) _tj_tag_col="" ;; esac
                case "$_tj_rem_col" in *[!A-Za-z0-9_]*) _tj_rem_col="" ;; esac
            fi
            if [ -n "$_tag_name_col" ] && [ -n "$_tagjoin" ] \
               && [ -n "$_tj_tag_col" ] && [ -n "$_tj_rem_col" ]; then
                local _tcount _tcount_rc=0
                _tcount="$(sqlite3 -readonly "$snap" \
                    "SELECT COUNT(*) FROM $_tagjoin j \
                       JOIN ZREMCDREMINDER r ON j.$_tj_rem_col = r.Z_PK \
                      WHERE $_rdel;" \
                    2>/dev/null)" || _tcount_rc=$?
                if [ "$_tcount_rc" -ne 0 ]; then
                    log_warn "Reminders: tag-data probe failed for store $_source_store_basename — tags missing from this account's CATEGORIES"
                    _incomplete_push _rem_incomplete "Reminders tag data ($_source_store_basename)" "the tag-table probe failed (likely a Tahoe-era schema change to the tag-junction table), so reminders in this account's VTODO + CSV are exported WITHOUT their tags in the CATEGORIES field"
                fi
                case "${_tcount:-0}" in ''|0) : ;; *) _has_tag_data=1 ;; esac
                if [ "$_tcount_rc" -eq 0 ] && ! sqlite3 -readonly -separator $'\x1f' "$snap" "
                    SELECT '$_source_store_basename', r.Z_PK,
                           $(_sql_tsv_safe "COALESCE(t.$_tag_name_col, '')")
                      FROM $_tagjoin j
                      JOIN ZREMCDREMINDER r ON j.$_tj_rem_col = r.Z_PK
                      JOIN $_tagtable t ON j.$_tj_tag_col = t.Z_PK
                     WHERE $_rdel;
                " >> "$rem_tagmap" 2>/dev/null; then
                    log_warn "Reminders: tag-pair dump failed for store $_source_store_basename — tags missing from this account's CATEGORIES"
                    _incomplete_push _rem_incomplete "Reminders tag data ($_source_store_basename)" "the tag-pair join query failed after the tag probe succeeded — reminders in this account's VTODO + CSV are exported WITHOUT their tags in the CATEGORIES field"
                fi
            fi
        fi
        local _sec_have_tbl _sec_have_col _sec_have_seccols _sec_have_remck
        _sec_have_tbl="$(sqlite3 -readonly "$snap" \
            "SELECT 1 FROM sqlite_master WHERE type='table' AND name='ZREMCDBASESECTION' LIMIT 1;" 2>/dev/null)"
        _sec_have_col="$(sqlite3 -readonly "$snap" \
            "SELECT 1 FROM pragma_table_info('ZREMCDBASELIST') WHERE name='ZMEMBERSHIPSOFREMINDERSINSECTIONSASDATA' LIMIT 1;" 2>/dev/null)"
        _sec_have_seccols="$(sqlite3 -readonly "$snap" \
            "SELECT CASE WHEN COUNT(DISTINCT name)=3 THEN 1 ELSE 0 END FROM pragma_table_info('ZREMCDBASESECTION') WHERE name IN ('ZCKIDENTIFIER','ZDISPLAYNAME','ZMARKEDFORDELETION');" 2>/dev/null)"
        _sec_have_remck="$(sqlite3 -readonly "$snap" \
            "SELECT 1 FROM pragma_table_info('ZREMCDREMINDER') WHERE name='ZCKIDENTIFIER' LIMIT 1;" 2>/dev/null)"
        if [ "$_sec_have_tbl" = "1" ] && [ "$_sec_have_col" = "1" ] \
           && [ "$_sec_have_seccols" = "1" ] && [ "$_sec_have_remck" = "1" ]; then
            if ! sqlite3 -readonly -separator $'\x1f' "$snap" "
                SELECT '$_source_store_basename', r.Z_PK,
                       $(_sql_tsv_safe "COALESCE(s.ZDISPLAYNAME, '')")
                  FROM ZREMCDBASELIST l
                  JOIN json_each(CAST(l.ZMEMBERSHIPSOFREMINDERSINSECTIONSASDATA AS TEXT),
                                 '\$.memberships') je
                  JOIN ZREMCDBASESECTION s
                    ON s.ZCKIDENTIFIER = json_extract(je.value, '\$.groupID')
                   AND COALESCE(s.ZMARKEDFORDELETION, 0) = 0
                  JOIN ZREMCDREMINDER r
                    ON r.ZCKIDENTIFIER = json_extract(je.value, '\$.memberID')
                 WHERE l.ZMEMBERSHIPSOFREMINDERSINSECTIONSASDATA IS NOT NULL
                   AND $_rdel;
            " >> "$rem_sectionmap" 2>/dev/null; then
                log_warn "Reminders: section-membership dump failed for store $_source_store_basename — Section column blank for this account"
                _incomplete_push _rem_incomplete "Reminders sections ($_source_store_basename)" "the section-membership query (json_each over ZREMCDBASELIST.ZMEMBERSHIPSOFREMINDERSINSECTIONSASDATA) failed — reminders in this account are exported WITHOUT their Section value in the CSV"
            fi
        fi
    done
    local list_count rem_count
    list_count="$(LC_ALL=C awk 'END{print NR}' "$merged_lists" 2>/dev/null)"
    rem_count="$(LC_ALL=C awk 'END{print NR}' "$merged_rems" 2>/dev/null)"
    case "$list_count" in ''|*[!0-9]*) list_count=0 ;; esac
    case "$rem_count"  in ''|*[!0-9]*) rem_count=0 ;; esac
    log_info "Found $list_count $(_pluralize "$list_count" list), $rem_count $(_pluralize "$rem_count" reminder)"
    [ "$smart_filtered" -gt 0 ] && _disclose_excluded "$smart_filtered smart $(_pluralize "$smart_filtered" list)" "saved-query rows that own no reminders — these are searches, not reminders"
    [ "$list_deleted_filtered" -gt 0 ] && _disclose_excluded "$list_deleted_filtered deleted $(_pluralize "$list_deleted_filtered" list) in Recently Deleted" "the reminders they held were still exported; restore the $(_pluralize "$list_deleted_filtered" list) from Reminders' Recently Deleted if you want $(_pluralize "$list_deleted_filtered" it them) back"
    [ "$soft_deleted" -gt 0 ] && \
        log_info "$soft_deleted of $rem_count exported $(_pluralize "$rem_count" reminder) $(_pluralize "$soft_deleted" was were) in Recently Deleted (kept in the export and marked deleted) — check Reminders' Recently Deleted to review or restore."
    if [ -n "$_smart_col_chosen" ] && [ "$_smart_col_chosen" != "ZSMARTLISTTYPE" ]; then
        log_info "Schema: smart-list flag = $_smart_col_chosen (legacy)"
    fi
    if [ -z "$_smart_col_chosen" ]; then
        log_info "Schema: no smart-list flag column found on any Reminders store (probed: ZSMARTLISTTYPE / ZISSMARTLIST / ZSMARTLIST / ZISSMART). Smart-list rows, if present in the schema, will not be filtered from the export."
    fi
    [ "$_has_recurrence_data" -eq 1 ] && \
        log_info "Recurring reminders detected — emitting RRULE in their VTODOs."
    [ "$_has_parent_data" -eq 1 ] && \
        log_info "Subtasks detected — emitting RELATED-TO parent links."
    if [ "$_parent_col_seen" -eq 0 ] && [ "$_stores_probed" -gt 0 ]; then
        log_info "Subtask parent column (ZPARENTREMINDER) absent on this schema — RELATED-TO links not emitted."
    fi
    [ "$_has_tag_data" -eq 1 ] && \
        log_info "Reminder tags detected — appending them to CATEGORIES."
    if [ "$rem_count" -eq 0 ]; then
        if [ "${#_rem_incomplete[@]}" -gt 0 ]; then
            _create_output_dir "$out_root" "permission denied / disk full?"
            _incomplete_drain "$out_root" "${_rem_incomplete[@]+"${_rem_incomplete[@]}"}"
            log_warn "All ${#_rem_incomplete[@]} reminder $(_pluralize "${#_rem_incomplete[@]}" store) failed to snapshot or query$(_disclosure_pointer)."
            mark_success
            print_summary
            exit 0
        fi
        if [ "${discovered_rems:-0}" -gt 0 ]; then
            _create_output_dir "$out_root" "merge produced no rows"
            note_incomplete "$out_root" "Reminders" \
                "the reminder census counted $discovered_rems reminder(s) across the source stores but the merged export produced none — reminders exist on this Mac but were not exported. Re-run after confirming the databases are intact."
            mark_success
            print_summary
            exit 0
        fi
        report_empty_source "reminders" "Reminders"
    fi
    log_info "Emitting per-reminder VTODO + CSV rows..."
    _store_md5() {
        local _key _ref _h
        _key="$(printf '%s' "$1" | LC_ALL=C tr -c 'A-Za-z0-9_' '_')"
        _ref="_smd5_$_key"
        _h="${!_ref:-}"
        if [ -n "$_h" ]; then
            printf '%s' "$_h"
            return 0
        fi
        _h="$(printf '%s' "$1" | md5 -q)"
        printf -v "$_ref" '%s' "$_h"
        printf '%s' "$_h"
    }
    while IFS=$'\x1f' read -r _lst_store _lst_pk _lst_name _lst_color; do
        [ -z "$_lst_pk" ] && continue
        case "$_lst_pk" in *[!0-9]*) continue ;; esac
        local _lst_key
        _lst_key="$(_store_md5 "$_lst_store")_${_lst_pk}"
        printf -v "_lst_$_lst_key" '%s' "$_lst_name"
        [ -n "${_lst_color:-}" ] && printf -v "_lcl_$_lst_key" '%s' "$_lst_color"
    done < "$merged_lists"
    _list_name_for() {
        local _lst_key _ref out
        _lst_key="$(_store_md5 "$1")_${2}"
        _ref="_lst_$_lst_key"
        out="${!_ref:-}"
        [ -z "$out" ] && out="(unknown list)"
        printf '%s' "$out"
    }
    _list_color_for() {
        local _lst_key _ref
        _lst_key="$(_store_md5 "$1")_${2}"
        _ref="_lcl_$_lst_key"
        printf '%s' "${!_ref:-}"
    }
    _canon_uid() {
        local _u="$1"
        case "$_u" in
            [0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f])
                printf '%s' "${_u:0:8}-${_u:8:4}-${_u:12:4}-${_u:16:4}-${_u:20:12}" ;;
            *) printf '%s' "$_u" ;;
        esac
    }
    while IFS=$'\x1f' read -r _um_store _um_pk _um_uid; do
        [ -z "$_um_pk" ] && continue
        case "$_um_pk" in *[!0-9]*) continue ;; esac
        local _um_key
        _um_key="$(_store_md5 "$_um_store")_${_um_pk}"
        printf -v "_uid_$_um_key" '%s' "$(_canon_uid "$_um_uid")"
    done < "$rem_uidmap"
    _uid_for_pk() {
        local _ref="_uid_$(_store_md5 "$1")_${2}"
        printf '%s' "${!_ref:-}"
    }
    while IFS=$'\x1f' read -r _rm_store _rm_pk _rm_freq _rm_int _rm_cnt _rm_until _rm_wk _rm_md; do
        [ -z "$_rm_pk" ] && continue
        case "$_rm_pk" in *[!0-9]*) continue ;; esac
        local _rm_key
        _rm_key="$(_store_md5 "$_rm_store")_${_rm_pk}"
        printf -v "_rec_$_rm_key" '%s' "${_rm_freq}|${_rm_int}|${_rm_cnt}|${_rm_until}|${_rm_wk}|${_rm_md}"
    done < "$rem_recurmap"
    _recur_for_pk() {
        local _ref="_rec_$(_store_md5 "$1")_${2}"
        printf '%s' "${!_ref:-}"
    }
    while IFS=$'\x1f' read -r _tg_store _tg_pk _tg_name; do
        [ -z "$_tg_pk" ] && continue
        case "$_tg_pk" in *[!0-9]*) continue ;; esac
        _tg_name="${_tg_name//\\n/ }"
        [ -z "$_tg_name" ] && continue
        local _tg_key _tg_ref _tg_prev
        _tg_key="$(_store_md5 "$_tg_store")_${_tg_pk}"
        _tg_ref="_tag_$_tg_key"
        _tg_prev="${!_tg_ref:-}"
        if [ -z "$_tg_prev" ]; then
            printf -v "_tag_$_tg_key" '%s' "$_tg_name"
        else
            printf -v "_tag_$_tg_key" '%s' "${_tg_prev},${_tg_name}"
        fi
    done < "$rem_tagmap"
    _tags_for_pk() {
        local _ref="_tag_$(_store_md5 "$1")_${2}"
        printf '%s' "${!_ref:-}"
    }
    while IFS=$'\x1f' read -r _sc_store _sc_pk _sc_name; do
        [ -z "$_sc_pk" ] && continue
        case "$_sc_pk" in *[!0-9]*) continue ;; esac
        _sc_name="${_sc_name//\\n/ }"
        [ -z "$_sc_name" ] && continue
        local _sc_key
        _sc_key="$(_store_md5 "$_sc_store")_${_sc_pk}"
        printf -v "_sec_$_sc_key" '%s' "$_sc_name"
    done < "$rem_sectionmap"
    _section_name_for() {
        local _ref="_sec_$(_store_md5 "$1")_${2}"
        printf '%s' "${!_ref:-}"
    }
    _create_output_dir "$out_root"
    _incomplete_drain "$out_root" "${_rem_incomplete[@]+"${_rem_incomplete[@]}"}"
    local raw_stream="$SCRATCH_DIR/Reminders.unfolded.ics"
    {
        printf 'BEGIN:VCALENDAR\n'
        printf 'VERSION:2.0\n'
        printf 'PRODID:-//Unknown//Unknown//EN\n'
        printf 'CALSCALE:GREGORIAN\n'
    } > "$raw_stream"
    {
        printf 'List,List Color,Section,Title,Completed,Deleted,Priority,Flagged,Due Date,Start Date,Completed Date,Notes,URL,Parent,Created\r\n'
    } > "$SCRATCH_DIR/Reminders.csv"
    local emitted_rems=0 skipped_rems=0
    local _pt_last=0 _pt_inline=0
    local store_path pk listpk title notes completed priority due \
          completed_at created allday ckid start flagged url parentpk \
          deleted
    while IFS=$'\x1f' read -r store_path pk listpk title notes completed \
            priority due completed_at created allday ckid \
            start flagged url parentpk deleted; do
        case "$pk" in
            ''|*[!0-9]*)
                skipped_rems=$((skipped_rems + 1))
                continue ;;
        esac
        local list_name list_color section_name notes_real title_real url_real
        list_name="$(_list_name_for "$store_path" "$listpk")"
        list_name="${list_name//\\n/ }"
        list_color="$(_list_color_for "$store_path" "$listpk")"
        section_name="$(_section_name_for "$store_path" "$pk")"
        notes_real="$(_unescape_bsafe "$notes")"
        title_real="$(_unescape_bsafe "$title")"
        url_real="$(_unescape_bsafe "$url")"
        local due_human created_human due_ics completed_str \
              start_human comp_human flagged_str deleted_str
        due_human="$(_cd_ts_to_human "$due")"
        created_human="$(_cd_ts_to_human "$created")"
        start_human="$(_cd_ts_to_human "$start")"
        comp_human="$(_cd_ts_to_human "$completed_at")"
        due_ics="$(_cd_ts_to_utc "$due")"
        if [ "$completed" = "1" ]; then completed_str="yes"; else completed_str="no"; fi
        local due_date_only start_date_only
        if [ "${allday:-0}" = "1" ]; then
            due_date_only="$(_cd_ts_to_date "$due")"
            start_date_only="$(_cd_ts_to_date "$start")"
            due_human="${due_human%% *}"
            start_human="${start_human%% *}"
        else
            due_date_only=""
            start_date_only=""
        fi
        if [ "${flagged:-0}" = "1" ]; then flagged_str="yes"; else flagged_str="no"; fi
        if [ "${deleted:-0}" = "1" ]; then deleted_str="yes"; else deleted_str="no"; fi
        local priority_label
        case "${priority:-0}" in
            0|'') priority_label="None" ;;
            1|2|3|4) priority_label="High" ;;
            5|6) priority_label="Medium" ;;
            7|8|9) priority_label="Low" ;;
            *) priority_label="Medium" ;;
        esac
        local parent_uid=""
        if [ -n "${parentpk:-}" ]; then
            case "$parentpk" in
                *[!0-9]*) : ;;
                *) parent_uid="$(_uid_for_pk "$store_path" "$parentpk")" ;;
            esac
        fi
        {
            csv_field "$list_name";       printf ','
            csv_field "$list_color";      printf ','
            csv_field "$section_name";    printf ','
            csv_field "$title_real";      printf ','
            csv_field "$completed_str";   printf ','
            csv_field "$deleted_str";     printf ','
            csv_field "$priority_label";  printf ','
            csv_field "$flagged_str";     printf ','
            csv_field "$due_human";       printf ','
            csv_field "$start_human";     printf ','
            csv_field "$comp_human";      printf ','
            csv_field "$notes_real";      printf ','
            csv_field "$url_real";        printf ','
            csv_field "$parent_uid";      printf ','
            csv_field "$created_human";   printf '\r\n'
        } >> "$SCRATCH_DIR/Reminders.csv"
        {
            printf 'BEGIN:VTODO\n'
            local uid="$ckid"
            uid="$(_canon_uid "$uid")"
            printf 'UID:%s\n' "$(ics_escape "$uid")"
            printf 'DTSTAMP:19700101T000000Z\n'
            if [ -n "$title_real" ]; then
                printf 'SUMMARY:%s\n' "$(ics_escape "$title_real")"
            else
                printf 'SUMMARY:Untitled\n'
            fi
            [ -n "$notes_real" ] && printf 'DESCRIPTION:%s\n' "$(ics_escape "$notes_real")"
            local _cats _tags _tg_one _tg_rest
            _cats=""
            [ -n "$list_name" ] && _cats="$(ics_escape "$list_name")"
            _tags="$(_tags_for_pk "$store_path" "$pk")"
            if [ -n "$_tags" ]; then
                _tg_rest="$_tags"
                while [ -n "$_tg_rest" ]; do
                    case "$_tg_rest" in
                        *,*) _tg_one="${_tg_rest%%,*}"; _tg_rest="${_tg_rest#*,}" ;;
                        *)   _tg_one="$_tg_rest";       _tg_rest="" ;;
                    esac
                    [ -z "$_tg_one" ] && continue
                    if [ -n "$_cats" ]; then
                        _cats="$_cats,$(ics_escape "$_tg_one")"
                    else
                        _cats="$(ics_escape "$_tg_one")"
                    fi
                done
            fi
            printf 'CATEGORIES:%s\n' "$_cats"
            if [ -n "$start_date_only" ]; then
                printf 'DTSTART;VALUE=DATE:%s\n' "$start_date_only"
            else
                local start_ics
                start_ics="$(_cd_ts_to_utc "$start")"
                [ -n "$start_ics" ] && printf 'DTSTART:%s\n' "$start_ics"
            fi
            if [ -n "$due_date_only" ]; then
                printf 'DUE;VALUE=DATE:%s\n' "$due_date_only"
            elif [ -n "$due_ics" ]; then
                printf 'DUE:%s\n' "$due_ics"
            fi
            [ -n "$url_real" ] && printf 'URL:%s\n' "$(ics_escape "$url_real")"
            [ -n "$parent_uid" ] && \
                printf 'RELATED-TO;RELTYPE=PARENT:%s\n' "$(ics_escape "$parent_uid")"
            if [ "${deleted:-0}" = "1" ]; then
                printf 'STATUS:CANCELLED\n'
            elif [ "$completed" = "1" ]; then
                printf 'STATUS:COMPLETED\n'
                local comp_ics
                comp_ics="$(_cd_ts_to_utc "$completed_at")"
                [ -n "$comp_ics" ] && printf 'COMPLETED:%s\n' "$comp_ics"
                printf 'PERCENT-COMPLETE:100\n'
            else
                printf 'STATUS:NEEDS-ACTION\n'
            fi
            if [ -n "$priority" ] && [ "$priority" != "0" ]; then
                printf 'PRIORITY:%s\n' "$priority"
            fi
            local _recur
            _recur="$(_recur_for_pk "$store_path" "$pk")"
            if [ -n "$_recur" ]; then
                local _rrule
                _rrule="$(_build_rrule "$_recur" "${allday:-0}")"
                [ -n "$_rrule" ] && printf 'RRULE:%s\n' "$_rrule"
            fi
            printf 'END:VTODO\n'
        } >> "$raw_stream"
        emitted_rems=$((emitted_rems + 1))
        _progress_tick "$emitted_rems" "$rem_count" \
            "$(_pluralize "$rem_count" reminder) emitted"
    done < "$merged_rems"
    _progress_end
    printf 'END:VCALENDAR\n' >> "$raw_stream"
    log_info "Folding ICS, validating CSV, finalising outputs..."
    local _vcp_rems="$discovered_rems"
    if [ "$rems_census_failures" -gt 0 ]; then
        _vcp_rems=""
        log_warn "Reminders: per-store census failed on $rems_census_failures of $rems_census_attempted store(s) — drift check will surface as verification gap."
    fi
    validate_count_parity "$_vcp_rems" $((emitted_rems + skipped_rems)) \
        "Reminder" "$out_root"
    local _vcp_lists="$discovered_lists"
    if [ "$lists_census_failures" -gt 0 ]; then
        _vcp_lists=""
        log_warn "Reminders: per-store list-census failed on $lists_census_failures of $lists_census_attempted store(s) — drift check will surface as verification gap."
    fi
    validate_count_parity "$_vcp_lists" "$list_count" \
        "Reminder list" "$out_root"
    local ics_tmp csv_tmp
    ics_tmp="$(mktemp "$ics_file.tmp.XXXXXX")" || die "Cannot create ICS temp file"
    track_output_path "$ics_tmp"
    csv_tmp="$(mktemp "$csv_file.tmp.XXXXXX")" || die "Cannot create CSV temp file"
    track_output_path "$csv_tmp"
    if ! _fold_75_octets < "$raw_stream" > "$ics_tmp"; then
        die "ICS folding failed"
    fi
    mv -- "$SCRATCH_DIR/Reminders.csv" "$csv_tmp" || die "CSV move failed"
    grep -q 'BEGIN:VCALENDAR' "$ics_tmp" || die "ICS output missing VCALENDAR"
    mv -f -- "$ics_tmp" "$ics_file" || die "Cannot finalise $ics_file"
    _untrack_output_path "$ics_tmp"
    mv -f -- "$csv_tmp" "$csv_file" || die "Cannot finalise $csv_file"
    _untrack_output_path "$csv_tmp"
    clean_ics_file "$ics_file" || \
        log_warn "iCal post-clean pass failed for Reminders.ics; output preserved"
    validate_csv_rfc4180 "$csv_file" || true
    if [ "$list_count" -gt 0 ]; then
        log_ok "Wrote Reminders/ ($rem_count $(_pluralize "$rem_count" reminder) across $list_count $(_pluralize "$list_count" list), .ics + .csv, $(_dir_size_human "$out_root"))"
    else
        log_ok "Wrote Reminders/ ($rem_count $(_pluralize "$rem_count" reminder), .ics + .csv, $(_dir_size_human "$out_root"))"
    fi
    mark_success
    sweep_junk_files "$out_root"
    print_summary
    if [ "$ERR_COUNT" -gt 0 ]; then exit 1; fi
    exit 0
}

_discover_bookmarks_plists() {
    local pf
    [ -f "$HOME/Library/Safari/Bookmarks.plist" ] \
        && printf '%s\n' "$HOME/Library/Safari/Bookmarks.plist"
    if [ -d "$HOME/Library/Safari/Profiles" ]; then
        for pf in "$HOME/Library/Safari/Profiles"/*/Bookmarks.plist; do
            [ -f "$pf" ] && printf '%s\n' "$pf"
        done
    fi
}

_emit_netscape_html_from_xml_plist() {
    local xml_file="$1"
    local mode="${2:-bookmarks}"
    LC_ALL=C awk '
        function _close_tag(t,    e) {
            e = "</" t ">"
            return (index(buf, e) != 0)
        }
        {
            if (pend == "") {
                t = ""
                if (match($0, /<string>/) && !match($0, /<\/string>/)) t = "string"
                else if (match($0, /<key>/) && !match($0, /<\/key>/)) t = "key"
                if (t != "") {
                    pend = t
                    buf = $0
                    next
                }
                print
                next
            }
            buf = buf " " $0
            if (_close_tag(pend)) {
                print buf
                pend = ""
                buf = ""
            }
        }
        END {
            if (pend != "") print buf
        }
    ' "$xml_file" | LC_ALL=C awk -v MODE="$mode" '
        function extract_tag(line, tag,    s, e, p) {
            s = "<" tag ">"
            e = "</" tag ">"
            p = index(line, s)
            if (p == 0) return ""
            line = substr(line, p + length(s))
            p = index(line, e)
            if (p == 0) return ""
            return substr(line, 1, p - 1)
        }
        function attr_quote(t, r) {
            r = t
            gsub(/"/, "\\&quot;", r)
            return r
        }
        function indent(d,    s, i) {
            s = ""
            for (i = 0; i < d; i++) s = s "    "
            return s
        }
        BEGIN {
            _hdr = (MODE == "readinglist") ? "Reading List" : "Bookmarks"
            print "<!DOCTYPE NETSCAPE-Bookmark-file-1>"
            print "<META HTTP-EQUIV=\"Content-Type\" CONTENT=\"text/html; charset=UTF-8\">"
            print "<TITLE>" _hdr "</TITLE>"
            print "<H1>" _hdr "</H1>"
            print "<DL><p>"
            n_dicts = 0
            stack_depth = 0
            stack[0] = 0          # parent of top-level dicts is root sentinel 0
            root_count = 0
            cur_key = ""
            cur_key_id = 0
        }
        /^[[:space:]]*<dict>[[:space:]]*$/ {
            n_dicts++
            parent[n_dicts] = stack[stack_depth]
            if (parent[n_dicts] == 0) {
                root_count++
                root_children[root_count] = n_dicts
            } else {
                child_count[parent[n_dicts]]++
                children[parent[n_dicts], child_count[parent[n_dicts]]] = n_dicts
            }
            stack_depth++
            stack[stack_depth] = n_dicts
            d_openkey[n_dicts] = cur_key
            cur_key = ""
            next
        }
        /^[[:space:]]*<dict\/>[[:space:]]*$/ {
            n_dicts++
            parent[n_dicts] = stack[stack_depth]
            if (parent[n_dicts] == 0) {
                root_count++
                root_children[root_count] = n_dicts
            } else {
                child_count[parent[n_dicts]]++
                children[parent[n_dicts], child_count[parent[n_dicts]]] = n_dicts
            }
            d_openkey[n_dicts] = cur_key
            cur_key = ""
            next
        }
        /^[[:space:]]*<\/dict>[[:space:]]*$/ {
            _closing = stack[stack_depth]
            _p = parent[_closing]
            if (_p != 0) {
                if (d_title[_closing] != "" && d_title[_p] == "") {
                    d_title[_p] = d_title[_closing]
                }
                if (d_openkey[_closing] == "URIDictionary") {
                    if (d_lastvisit[_closing] != "" && d_lastvisit[_p] == "") {
                        d_lastvisit[_p] = d_lastvisit[_closing]
                    }
                }
                if (d_openkey[_closing] == "ReadingList") {
                    if (d_adddate[_closing] != "" && d_adddate[_p] == "") {
                        d_adddate[_p] = d_adddate[_closing]
                    }
                    if (d_preview[_closing] != "" && d_preview[_p] == "") {
                        d_preview[_p] = d_preview[_closing]
                    }
                }
            }
            stack_depth--
            cur_key = ""
            next
        }
        /^[[:space:]]*<array>[[:space:]]*$/ { cur_key = ""; next }
        /^[[:space:]]*<\/array>[[:space:]]*$/ { cur_key = ""; next }
        /^[[:space:]]*<array\/>[[:space:]]*$/ { cur_key = ""; next }
        /^[[:space:]]*<key>/ {
            _v = extract_tag($0, "key")
            if (_v != "") {
                cur_key = _v
                cur_key_id = stack[stack_depth]
            }
            next
        }
        /^[[:space:]]*<string>/ || /^[[:space:]]*<string\/>[[:space:]]*$/ {
            if (cur_key != "" && stack_depth > 0 && cur_key_id == stack[stack_depth]) {
                _val = extract_tag($0, "string")
                _id = stack[stack_depth]
                if (cur_key == "title") {
                    d_title[_id] = _val
                } else if (cur_key == "Title") {
                    d_folder_title[_id] = _val
                } else if (cur_key == "URLString") {
                    d_url[_id] = _val
                } else if (cur_key == "WebBookmarkType") {
                    d_type[_id] = _val
                } else if (cur_key == "WebBookmarkUUID") {
                    d_uuid[_id] = _val
                } else if (cur_key == "PreviewText") {
                    d_preview[_id] = _val
                }
            }
            cur_key = ""
            next
        }
        /^[[:space:]]*<date>/ || /^[[:space:]]*<integer>/ {
            if (cur_key != "" && stack_depth > 0 && cur_key_id == stack[stack_depth]) {
                _id = stack[stack_depth]
                if ($0 ~ /<date>/) {
                    _dv = extract_tag($0, "date")
                } else {
                    _dv = extract_tag($0, "integer")
                }
                if (_dv != "") {
                    if (cur_key == "DateAdded" || cur_key == "addDate") {
                        if (d_adddate[_id] == "") d_adddate[_id] = _dv
                    } else if (cur_key == "lastVisitedDate") {
                        d_lastvisit[_id] = _dv
                    }
                }
            }
            cur_key = ""
            next
        }
        /^[[:space:]]*</ {
            cur_key = ""
            next
        }
        function display_folder_title(t) {
            if (t == "BookmarksBar") return "Favorites"
            if (t == "BookmarksMenu") return "Bookmarks Menu"
            return t
        }
        END {
            _root_emit = (MODE == "readinglist") ? 0 : 1
            sp = 0
            for (_i = root_count; _i >= 1; _i--) {
                sp++
                wstack_id[sp] = root_children[_i]
                wstack_phase[sp] = 0
                wstack_depth[sp] = 1
                wstack_emit[sp] = _root_emit
            }
            while (sp > 0) {
                _id = wstack_id[sp]
                _phase = wstack_phase[sp]
                _d = wstack_depth[sp]
                _emit = wstack_emit[sp]
                sp--
                _type = d_type[_id]
                if (_phase == 1) {
                    printf "%s</DL><p>\n", indent(_d)
                    continue
                }
                if (_type == "WebBookmarkTypeLeaf") {
                    if (!_emit) continue
                    _url = d_url[_id]
                    if (_url != "") {
                        _t = d_title[_id]
                        if (_t == "") _t = _url
                        _attrs = ""
                        if (d_adddate[_id] != "")
                            _attrs = _attrs " ADD_DATE=\"" d_adddate[_id] "\""
                        if (d_lastvisit[_id] != "")
                            _attrs = _attrs " LAST_VISIT=\"" d_lastvisit[_id] "\""
                        if (d_uuid[_id] != "")
                            _attrs = _attrs " WEB_BOOKMARK_UUID=\"" attr_quote(d_uuid[_id]) "\""
                        printf "%s<DT><A HREF=\"%s\"%s>%s</A>\n", \
                            indent(_d), attr_quote(_url), _attrs, _t
                        if (d_preview[_id] != "")
                            printf "%s<DD>%s\n", indent(_d), d_preview[_id]
                    }
                    continue
                }
                if (_type == "WebBookmarkTypeList") {
                    _is_rl = (d_folder_title[_id] == "com.apple.ReadingList")
                    if (MODE == "readinglist") {
                        if (_is_rl) {
                            _n = child_count[_id]
                            for (_i = _n; _i >= 1; _i--) {
                                sp++
                                wstack_id[sp] = children[_id, _i]
                                wstack_phase[sp] = 0
                                wstack_depth[sp] = _d
                                wstack_emit[sp] = 1
                            }
                            continue
                        }
                    } else {
                        if (_is_rl) continue
                    }
                    _ft = d_folder_title[_id]
                    if (parent[_id] == 0 && _ft == "") {
                        _n = child_count[_id]
                        for (_i = _n; _i >= 1; _i--) {
                            sp++
                            wstack_id[sp] = children[_id, _i]
                            wstack_phase[sp] = 0
                            wstack_depth[sp] = _d
                            wstack_emit[sp] = _emit
                        }
                        continue
                    }
                    if (_ft != "") {
                        if (_emit) {
                            _hattr = ""
                            if (_ft == "BookmarksBar")
                                _hattr = _hattr " PERSONAL_TOOLBAR_FOLDER=\"true\""
                            if (d_adddate[_id] != "")
                                _hattr = _hattr " ADD_DATE=\"" d_adddate[_id] "\""
                            printf "%s<DT><H3%s>%s</H3>\n", indent(_d), \
                                _hattr, display_folder_title(_ft)
                            printf "%s<DL><p>\n", indent(_d)
                            sp++
                            wstack_id[sp] = _id
                            wstack_phase[sp] = 1
                            wstack_depth[sp] = _d
                            wstack_emit[sp] = 1
                        }
                        _n = child_count[_id]
                        for (_i = _n; _i >= 1; _i--) {
                            sp++
                            wstack_id[sp] = children[_id, _i]
                            wstack_phase[sp] = 0
                            wstack_depth[sp] = _emit ? (_d + 1) : _d
                            wstack_emit[sp] = _emit
                        }
                        continue
                    }
                    _n = child_count[_id]
                    for (_i = _n; _i >= 1; _i--) {
                        sp++
                        wstack_id[sp] = children[_id, _i]
                        wstack_phase[sp] = 0
                        wstack_depth[sp] = _d
                        wstack_emit[sp] = _emit
                    }
                    continue
                }
                _n = child_count[_id]
                for (_i = _n; _i >= 1; _i--) {
                    sp++
                    wstack_id[sp] = children[_id, _i]
                    wstack_phase[sp] = 0
                    wstack_depth[sp] = _d
                    wstack_emit[sp] = _emit
                }
            }
            print "</DL><p>"
        }
    '
}

_convert_date_attrs_to_epoch() {
    local line rest attr val epoch out
    while IFS= read -r line; do
        case "$line" in
            *ADD_DATE=\"*|*LAST_VISIT=\"*) ;;
            *) printf '%s\n' "$line"; continue ;;
        esac
        out="$line"
        for attr in ADD_DATE LAST_VISIT; do
            rest="$out"
            case "$rest" in
                *"$attr=\""*)
                    val="${rest#*$attr=\"}"
                    val="${val%%\"*}"
                    case "$val" in
                        ''|*[!0-9]*)
                            epoch="$(LC_ALL=C TZ=UTC date -j -f '%Y-%m-%dT%H:%M:%SZ' "$val" +%s 2>/dev/null)"
                            if [ -z "$epoch" ]; then
                                case "$val" in
                                    *.*Z)
                                        epoch="$(LC_ALL=C TZ=UTC date -j -f '%Y-%m-%dT%H:%M:%SZ' "${val%.*}Z" +%s 2>/dev/null)"
                                        ;;
                                esac
                            fi
                            if [ -z "$epoch" ]; then
                                local _ov _head _off
                                _ov="$val"
                                _off=""
                                case "$_ov" in
                                    *[+-][0-9][0-9][0-9][0-9])
                                        _off="${_ov: -5}"
                                        _head="${_ov%?????}"
                                        ;;
                                    *)
                                        _head="$_ov"
                                        ;;
                                esac
                                case "$_head" in
                                    *.*) _head="${_head%.*}" ;;
                                esac
                                if [ -n "$_off" ]; then
                                    epoch="$(LC_ALL=C TZ=UTC date -j -f '%Y-%m-%dT%H:%M:%S%z' "${_head}${_off}" +%s 2>/dev/null)"
                                fi
                            fi
                            local _gval="$val"
                            _gval="${_gval//\\/\\\\}"
                            _gval="${_gval//\*/\\*}"
                            _gval="${_gval//\?/\\?}"
                            _gval="${_gval//\[/\\[}"
                            if [ -n "$epoch" ]; then
                                out="${out//$attr=\"$_gval\"/$attr=\"$epoch\"}"
                            else
                                out="${out// $attr=\"$_gval\"/}"
                                out="${out//$attr=\"$_gval\"/}"
                            fi
                            ;;
                        *)
                            : # all-digit value is already epoch
                            ;;
                    esac
                    ;;
            esac
        done
        printf '%s\n' "$out"
    done
}

_rl_leaf_count() {
    local _n
    _n="$(_emit_netscape_html_from_xml_plist "$1" readinglist 2>/dev/null \
        | awk '/^[[:space:]]*<DT><A /{a++} END{print a+0}')"
    case "$_n" in ''|*[!0-9]*) _n=0 ;; esac
    printf '%s' "$_n"
}

safari_bookmarks_main() {
    maybe_show_help "$@"
    _announce_step "Safari bookmarks export"
    check_dependencies
    local out_arg out_dir
    out_arg="$(_parse_output_folder_arg "$@")" || exit 1
    out_dir="$(resolve_output_dir "$out_arg")" || exit 1
    _announce_output_dir "Safari"
    log_info "Discovering Safari Bookmarks plists..."
    require_full_disk_access
    log_info "Discovery root: ~/Library/Safari (default + Profiles/*)"
    warn_if_app_running "Safari"
    local plists=()
    local _pl
    while IFS= read -r _pl; do
        [ -n "$_pl" ] && plists+=( "$_pl" )
    done < <(_discover_bookmarks_plists)
    if [ "${#plists[@]}" -eq 0 ]; then
        report_no_source "Safari bookmarks" "not present" \
            "$HOME/Library/Safari/Bookmarks.plist (and Profiles/*/Bookmarks.plist on Safari 17+)" \
            "Safari"
        return 0
    fi
    local out_root="$out_dir/Safari"
    require_no_collision "$out_root"
    _create_output_dir "$out_root" "permission denied / disk full?"
    ensure_scratch
    log_info "Converting ${#plists[@]} $(_pluralize "${#plists[@]}" plist) to Netscape HTML..."
    local total_bookmarks=0 total_folders=0 plists_with_data=0
    local total_readinglist=0
    local plists_rl_only=0
    local _idx _plist _bm_filebase _rl_filebase _xml _tmp _of _profile_uuid
    local _bm _fl _cnt
    local _rl_tmp _rl_of _rl_cnt
    for (( _idx=0; _idx<${#plists[@]}; _idx++ )); do
        _plist="${plists[$_idx]}"
        log_info "Source: $_plist"
        case "$_plist" in
            */Profiles/*/Bookmarks.plist)
                _profile_uuid="$(_sanitize_name "$(basename "$(dirname "$_plist")")")"
                _bm_filebase="Safari Bookmarks ($_profile_uuid)"
                _rl_filebase="Safari Reading List ($_profile_uuid)"
                ;;
            *)
                _bm_filebase="Safari Bookmarks"
                _rl_filebase="Safari Reading List"
                ;;
        esac
        _xml="$SCRATCH_DIR/Bookmarks.xml.${_idx}.plist"
        if ! plutil -convert xml1 -o "$_xml" -- "$_plist" 2>/dev/null; then
            log_warn "Cannot convert $_plist to XML (plutil failed); skipping."
            note_incomplete "$out_root" "$_bm_filebase (from $_plist)" \
                "the Safari bookmarks file could not be read (it may be corrupt or in an unrecognised format) — this profile's bookmarks were not exported"
            continue
        fi
        if [ ! -s "$_xml" ]; then
            log_warn "Empty XML conversion for $_plist; skipping."
            note_incomplete "$out_root" "$_bm_filebase (from $_plist)" \
                "reading the Safari bookmarks file produced no usable data — this profile's bookmarks were not exported"
            continue
        fi
        _of="$(_unique_path "$out_root/${_bm_filebase}.html")"
        _tmp="$(mktemp "$_of.tmp.XXXXXX")" || die "Cannot create temp output file"
        if ! _emit_netscape_html_from_xml_plist "$_xml" bookmarks \
             | _convert_date_attrs_to_epoch > "$_tmp"; then
            log_warn "Bookmark HTML generation failed for $_plist; skipping."
            note_incomplete "$out_root" "$_bm_filebase (from $_plist)" \
                "generating the bookmarks export file from the Safari bookmarks failed — this profile's bookmarks were not exported"
            rm -f -- "$_tmp" 2>/dev/null
            continue
        fi
        _cnt=$(awk '/^[[:space:]]*<DT><A /{a++} /^[[:space:]]*<DT><H3/{h++} END{printf "%d\t%d", a+0, h+0}' "$_tmp" 2>/dev/null)
        _bm="${_cnt%$'\t'*}"
        _fl="${_cnt##*$'\t'}"
        case "$_bm" in ''|*[!0-9]*) _bm=0 ;; esac
        case "$_fl" in ''|*[!0-9]*) _fl=0 ;; esac
        local _src_leaves
        _src_leaves=$(awk '
            f { if ($0 ~ /<string>.+<\/string>/) n++; f=0 }
            /<key>URLString<\/key>/ { f=1 }
            END { print n+0 }
        ' "$_xml" 2>/dev/null)
        case "$_src_leaves" in ''|*[!0-9]*) _src_leaves=0 ;; esac
        local _bm_ok=0
        if [ "$_bm" -eq 0 ] && [ "$_fl" -eq 0 ]; then
            local _rl_in_src
            _rl_in_src="$(_rl_leaf_count "$_xml")"
            local _nonrl_leaves=$((_src_leaves - _rl_in_src))
            [ "$_nonrl_leaves" -lt 0 ] && _nonrl_leaves=0
            if [ "$_nonrl_leaves" -gt 0 ]; then
                log_warn "Bookmark parser produced 0 entries for $_bm_filebase but the source has $_nonrl_leaves non-Reading-List bookmark $(_pluralize "$_nonrl_leaves" entry entries) — parser desync."
                note_incomplete "$out_root" "$_bm_filebase (from $_plist)" \
                    "the Safari bookmarks file lists $_nonrl_leaves bookmark entry/entries but none could be read out (the file was in a format this export didn't recognise) — this profile's bookmarks were not exported"
            else
                log_info "No bookmarks in $_bm_filebase — skipping."
            fi
            rm -f -- "$_tmp" 2>/dev/null
        elif ! mv -f -- "$_tmp" "$_of"; then
            log_warn "Cannot finalise $_of."
            note_incomplete "$out_root" "$_bm_filebase (from $_plist)" \
                "the Netscape-HTML output was generated successfully but moving it from scratch into place failed (target volume full, transient permission issue, or vanished mount) — this profile's bookmarks were not exported"
            rm -f -- "$_tmp" 2>/dev/null
        else
            if [ "${#plists[@]}" -eq 1 ]; then
                log_info "Wrote $_bm_filebase.html ($_bm $(_pluralize "$_bm" bookmark), $_fl $(_pluralize "$_fl" folder))"
            else
                log_info "  • $_bm_filebase.html ($_bm $(_pluralize "$_bm" bookmark), $_fl $(_pluralize "$_fl" folder))"
            fi
            total_bookmarks=$((total_bookmarks + _bm))
            total_folders=$((total_folders + _fl))
            plists_with_data=$((plists_with_data + 1))
            _bm_ok=1
        fi
        _rl_of="$(_unique_path "$out_root/${_rl_filebase}.html")"
        _rl_tmp="$(mktemp "$_rl_of.tmp.XXXXXX")" || die "Cannot create temp output file"
        if ! _emit_netscape_html_from_xml_plist "$_xml" readinglist \
             | _convert_date_attrs_to_epoch > "$_rl_tmp"; then
            log_warn "Reading List HTML generation failed for $_plist."
            note_incomplete "$out_root" "$_rl_filebase (from $_plist)" \
                "generating the export file for the Safari Reading List failed — this profile's Reading List was not exported"
            rm -f -- "$_rl_tmp" 2>/dev/null
            _rl_cnt="$(_rl_leaf_count "$_xml")"
        else
            _rl_cnt=$(awk '/^[[:space:]]*<DT><A /{a++} END{printf "%d", a+0}' "$_rl_tmp" 2>/dev/null)
            case "$_rl_cnt" in ''|*[!0-9]*) _rl_cnt=0 ;; esac
            if [ "$_rl_cnt" -eq 0 ]; then
                rm -f -- "$_rl_tmp" 2>/dev/null
            elif ! mv -f -- "$_rl_tmp" "$_rl_of"; then
                log_warn "Cannot finalise $_rl_of."
                note_incomplete "$out_root" "$_rl_filebase (from $_plist)" \
                    "the Reading List HTML output was generated successfully but moving it from scratch into place failed (target volume full, transient permission issue, or vanished mount) — this profile's Reading List was not exported"
                rm -f -- "$_rl_tmp" 2>/dev/null
            else
                if [ "${#plists[@]}" -eq 1 ]; then
                    log_info "Wrote $_rl_filebase.html ($_rl_cnt $(_pluralize "$_rl_cnt" "Reading List item"))"
                else
                    log_info "  • $_rl_filebase.html ($_rl_cnt $(_pluralize "$_rl_cnt" "Reading List item"))"
                fi
                total_readinglist=$((total_readinglist + _rl_cnt))
                [ "$_bm" -eq 0 ] && [ "$_fl" -eq 0 ] && \
                    plists_rl_only=$((plists_rl_only + 1))
            fi
        fi
        if [ "$_bm_ok" -eq 1 ] && [ "$_src_leaves" -gt 0 ] && [ "$_bm" -lt "$_src_leaves" ]; then
            local _diff=$((_src_leaves - _bm))
            local _rl_slack="$_rl_cnt"
            if [ "$_diff" -gt "$_rl_slack" ]; then
                log_warn "Read only $_bm of $_src_leaves bookmarks for $_bm_filebase (short by $((_diff - _rl_slack))) — some entries couldn't be parsed."
                note_incomplete "$out_root" "$_bm_filebase (from $_plist)" \
                    "the Safari bookmarks file lists $_src_leaves bookmark entry/entries but only $_bm could be read out (some entries were in a format this export didn't recognise) — some bookmarks were not exported"
            fi
        fi
    done
    if [ "$plists_with_data" -eq 0 ] && [ "$total_readinglist" -eq 0 ]; then
        if report_have_incomplete "$out_root"; then
            log_warn "All Safari profiles failed to convert$(_disclosure_pointer "Safari/_incomplete.txt")."
            mark_success
            print_summary
            exit 0
        fi
        rmdir "$out_root" 2>/dev/null || true
        report_empty_source "bookmarks" "Safari"
    fi
    log_info "Finalising Safari/ output..."
    local _rl_phrase=""
    if [ "$total_readinglist" -gt 0 ]; then
        _rl_phrase=", $total_readinglist $(_pluralize "$total_readinglist" "saved article")"
    fi
    local _plists_contributing=$((plists_with_data + plists_rl_only))
    if [ "$plists_with_data" -eq 0 ] && [ "$total_readinglist" -gt 0 ]; then
        log_ok "Wrote Safari/ (Reading List only: $total_readinglist $(_pluralize "$total_readinglist" "saved article"), $(_dir_size_human "$out_root"))"
    elif [ "$_plists_contributing" -eq 1 ]; then
        log_ok "Wrote Safari/ ($total_bookmarks $(_pluralize "$total_bookmarks" bookmark), $total_folders $(_pluralize "$total_folders" folder)${_rl_phrase}, $(_dir_size_human "$out_root"))"
    else
        log_ok "Wrote Safari/ ($_plists_contributing $(_pluralize "$_plists_contributing" profile), $total_bookmarks $(_pluralize "$total_bookmarks" bookmark), $total_folders $(_pluralize "$total_folders" folder)${_rl_phrase}, $(_dir_size_human "$out_root"))"
    fi
    if [ "$total_readinglist" -gt 0 ]; then
        log_info "Reading List exported separately: $total_readinglist $(_pluralize "$total_readinglist" "saved article") (Safari Reading List.html)"
    fi
    mark_success
    sweep_junk_files "$out_root"
    print_summary
    if [ "$ERR_COUNT" -gt 0 ]; then exit 1; fi
    exit 0
}

_clamp_env_int STICKIES_RTF_MAX_MB 50 10000 >/dev/null

_sticky_meta_load() {
    [ -s "$SCRATCH_DIR/sticky-meta.usv" ] || return 0
    local _line _k _hex _rest _var
    while IFS= read -r _line; do
        _k="${_line%%$'\x1f'*}"
        _rest="${_line#*$'\x1f'}"
        [ -z "$_k" ] && continue
        _hex="$(printf '%s' "$_k" | od -An -tx1 | tr -d ' \n')"
        _var="_smeta_${_hex}"
        printf -v "$_var" '%s' "$_rest"
    done < "$SCRATCH_DIR/sticky-meta.usv"
    _STICKY_META_LOADED=1
}

_sticky_meta_for() {
    local _u="$1"
    [ "${_STICKY_META_LOADED:-0}" = "1" ] || _sticky_meta_load
    local _hex _var
    _hex="$(printf '%s' "$_u" | od -An -tx1 | tr -d ' \n')"
    _var="_smeta_${_hex}"
    [ -n "${!_var+x}" ] && printf '%s' "${!_var}"
}

_rgb_to_hex() {
    local _r="$1" _g="$2" _b="$3"
    if [ -z "$_r" ] || [ -z "$_g" ] || [ -z "$_b" ]; then printf ''; return; fi
    case "$_r$_g$_b" in
        *[!0-9.eE+-]*) printf ''; return ;;
    esac
    LC_ALL=C awk -v r="$_r" -v g="$_g" -v b="$_b" \
        'BEGIN {
            if (r+0!=r || g+0!=g || b+0!=b) exit 1
            printf "#%02X%02X%02X", int(r*255+0.5), int(g*255+0.5), int(b*255+0.5)
        }'
}

_rgba_to_rgba_css() {
    local _r="$1" _g="$2" _b="$3" _a="${4:-1.0}"
    if [ -z "$_r" ] || [ -z "$_g" ] || [ -z "$_b" ]; then printf ''; return; fi
    [ -z "$_a" ] && _a="1.0"
    case "$_r$_g$_b" in
        *[!0-9.eE+-]*) printf ''; return ;;
    esac
    case "$_a" in
        *[!0-9.eE+-]*) printf ''; return ;;
    esac
    LC_ALL=C awk -v r="$_r" -v g="$_g" -v b="$_b" -v a="$_a" \
        'BEGIN {
            if (r+0!=r || g+0!=g || b+0!=b || a+0!=a) exit 1
            printf "rgba(%d, %d, %d, %s)", int(r*255+0.5), int(g*255+0.5), int(b*255+0.5), a
        }'
}

_stickies_slug() {
    local _s
    _s=$(printf '%s' "$1" | \
        LC_ALL=C tr -c 'A-Za-z0-9 ' ' ' | \
        LC_ALL=C tr -s ' ' | \
        sed -E 's/^ //; s/ $//' | \
        cut -c1-40 | \
        LC_ALL=C tr -s ' ' '-' | \
        sed -E 's/-+$//; s/^-+//')
    [ -z "$_s" ] && _s="untitled"
    printf '%s' "$_s"
}

_stickies_friendly_title() {
    if [ -z "$1" ]; then
        printf 'Sticky #%03d' "$2"
    else
        printf '%s' "$1"
    fi
}

_stickies_envelope_css() {
    local _bg_hex="$1" _bg_rgba="$2" _spine="$3" _highlight="$4"
    printf '<style>\n'
    printf 'html{background:#ececec;margin:0;padding:2em 1em;min-height:100vh;font-family:-apple-system,BlinkMacSystemFont,"Helvetica Neue",sans-serif;}\n'
    printf 'body{box-sizing:border-box;margin:0 auto;padding:1.4em 1.5em;max-width:640px;border-radius:6px;box-shadow:0 4px 14px rgba(0,0,0,0.18),0 1px 3px rgba(0,0,0,0.08);'
    [ -n "$_bg_hex" ]  && printf 'background-color:%s;' "$_bg_hex"
    [ -n "$_bg_rgba" ] && printf 'background-color:%s;' "$_bg_rgba"
    printf '}\n'
    if [ -n "$_spine" ]; then
        printf 'body::before{content:"";display:block;height:8px;background-color:%s;margin:-1.4em -1.5em 1em -1.5em;border-radius:6px 6px 0 0;}\n' "$_spine"
    fi
    [ -n "$_highlight" ] && printf '::selection{background-color:%s;}\n' "$_highlight"
    printf 'img{max-width:100%%;height:auto;}\n'
    printf '</style>\n'
}

_stickies_iso_to_epoch() {
    local _iso="$1"
    [ -z "$_iso" ] && { printf ''; return; }
    LC_ALL=C TZ=UTC date -j -f '%Y-%m-%dT%H:%M:%SZ' "$_iso" '+%s' 2>/dev/null
}

_stickies_emit_index() {
    local _mf="$1" _nc="$2" _root="$3"
    local _idx_tmp
    _idx_tmp="$(mktemp "$_root/index.html.tmp.XXXXXX" 2>/dev/null)" \
        || _idx_tmp="$_root/index.html.tmp.$$"
    track_output_path "$_idx_tmp"
    {
        printf '<!DOCTYPE html>\n<html>\n<head>\n'
        printf '<meta charset="UTF-8">\n'
        printf '<title>Stickies (%d)</title>\n' "$_nc"
        printf '<style>\n'
        printf 'html{background:#ececec;margin:0;padding:2em 1em;min-height:100vh;}\n'
        printf 'body{font-family:-apple-system,BlinkMacSystemFont,"Helvetica Neue",sans-serif;max-width:640px;margin:0 auto;color:#222;}\n'
        printf 'h1{font-size:1.3em;font-weight:600;margin:0 0 1em;}\n'
        printf '.list{display:flex;flex-direction:column;gap:0.4em;}\n'
        printf '.row{display:flex;align-items:center;gap:0.7em;padding:0.6em 0.9em;background:#fff;border-radius:6px;text-decoration:none;color:inherit;box-shadow:0 1px 3px rgba(0,0,0,0.08);transition:box-shadow 0.15s ease;}\n'
        printf '.row:hover{box-shadow:0 2px 8px rgba(0,0,0,0.15);}\n'
        printf '.swatch{width:1.2em;height:1.2em;border-radius:3px;border:1px solid rgba(0,0,0,0.12);flex:0 0 auto;}\n'
        printf '.title{flex:1 1 auto;font-weight:500;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;}\n'
        printf 'footer{margin-top:1.5em;color:#999;font-size:0.8em;}\n'
        printf '</style>\n</head>\n<body>\n'
        printf '<h1>Stickies — %d %s</h1>\n' "$_nc" "$(_pluralize "$_nc" sticky stickies)"
        printf '<div class="list">\n'
        local _i _u _td _fn _hx _zo _fr _e1 _e2 _e3
        local _idx_pipe_rc=0
        LC_ALL=C sort -t $'\x1f' -k6,6nr "$_mf" | \
            while IFS=$'\x1f' read -r _i _u _td _fn _hx _zo _fr; do
            html_escape "$_fn" _e1
            printf '<a class="row" href="%s">\n' "$_e1"
            html_escape "${_hx:-#cccccc}" _e2
            printf '  <span class="swatch" style="background:%s"></span>\n' "$_e2"
            html_escape "$_td" _e3
            printf '  <span class="title">%s</span>\n' "$_e3"
            printf '</a>\n'
        done
        _idx_pipe_rc=$?
        printf '</div>\n'
        printf '<footer>Exported %s.</footer>\n' "$(_utc_now_iso8601)"
        printf '</body>\n</html>\n'
    } > "$_idx_tmp"
    local _idx_group_rc=$?
    { [ "$_idx_pipe_rc" -eq 0 ] && [ "$_idx_group_rc" -eq 0 ]; }
    _atomic_commit_tmp $? "$_idx_tmp" "$_root/index.html" "Stickies/index.html"
    _untrack_output_path "$_idx_tmp"
}

export_stickies() {
    local out_root="$1"
    local _stick_root="$out_root/Stickies"
    local _stick_tahoe_dir="$HOME/Library/Containers/com.apple.Stickies/Data/Library/Stickies"
    local _sticky_img_fail_count=0
    local _src=""
    if [ -d "$_stick_tahoe_dir" ]; then
        local _stick_first_rtfd
        if IFS= read -r -d '' _stick_first_rtfd < <(find "$_stick_tahoe_dir" -maxdepth 1 -name '*.rtfd' -type d -print0 -quit 2>/dev/null); then
            _src="$_stick_tahoe_dir"
        fi
    fi
    if [ -z "$_src" ]; then
        report_no_source "Stickies" "not configured" \
            "~/Library/Containers/com.apple.Stickies/Data/Library/Stickies/*.rtfd" \
            "Stickies"
        return 0
    fi
    require_no_collision "$_stick_root"
    _create_output_dir "$_stick_root" "permission denied / disk full?"
    log_info "Source: $_src"
    local _html_validated=0
        ensure_scratch
        local _state="$_src/.SavedStickiesState"
        local _meta_usv="$SCRATCH_DIR/sticky-meta.usv"
        : > "$_meta_usv"
        if [ -f "$_state" ]; then
            local _state_xml="$SCRATCH_DIR/sticky-state.xml"
            if plutil -convert xml1 -o "$_state_xml" -- "$_state" 2>/dev/null; then
                LC_ALL=C awk '
                    function reset_row() {
                        uuid=""; sr=""; sg=""; sb=""; sa=""
                        hr=""; hg=""; hb=""
                        pr=""; pg=""; pb=""; frame=""; zorder=""
                        floating=""; translucent=""; expandedsize=""
                        cur_color=""; state=""
                    }
                    BEGIN { depth=0; reset_row() }
                    /<dict>/ { depth++; if (depth==1) reset_row(); state=""; next }
                    /<\/dict>/ {
                        if (depth==2) { cur_color=""; state="" }
                        if (depth==1) {
                            print uuid"\x1f"sr"\x1f"sg"\x1f"sb"\x1f"hr"\x1f"hg"\x1f"hb"\x1f"pr"\x1f"pg"\x1f"pb"\x1f"sa"\x1f"frame"\x1f"zorder"\x1f"floating"\x1f"translucent"\x1f"expandedsize
                        }
                        depth--; state=""; next
                    }
                    /<dict\/>/ { state=""; next }
                    depth==1 && /<key>UUID<\/key>/        { state="uuid"; next }
                    depth==1 && /<key>Frame<\/key>/       { state="frame"; next }
                    depth==1 && /<key>ExpandedSize<\/key>/ { state="expandedsize"; next }
                    depth==1 && /<key>ZOrder<\/key>/      { state="zorder"; next }
                    depth==1 && /<key>Floating<\/key>/    { state="floating"; next }
                    depth==1 && /<key>Translucent<\/key>/ { state="translucent"; next }
                    depth==1 && /<key>StickyColor<\/key>/    { cur_color="s"; state=""; next }
                    depth==1 && /<key>HighlightColor<\/key>/ { cur_color="h"; state=""; next }
                    depth==1 && /<key>SpineColor<\/key>/     { cur_color="p"; state=""; next }
                    depth==1 && /<key>ControlColor<\/key>/   { cur_color="ctrl"; state=""; next }
                    depth==2 && /<key>Red<\/key>/   { state="r"; next }
                    depth==2 && /<key>Green<\/key>/ { state="g"; next }
                    depth==2 && /<key>Blue<\/key>/  { state="b"; next }
                    depth==2 && /<key>Alpha<\/key>/ { state="a"; next }
                    state=="uuid" && /<string>/ {
                        s=$0; sub(/.*<string>/, "", s); sub(/<\/string>.*/, "", s)
                        uuid=s; state=""; next
                    }
                    state=="frame" && /<string>/ {
                        s=$0; sub(/.*<string>/, "", s); sub(/<\/string>.*/, "", s)
                        frame=s; state=""; next
                    }
                    state=="expandedsize" && /<string>/ {
                        s=$0; sub(/.*<string>/, "", s); sub(/<\/string>.*/, "", s)
                        expandedsize=s; state=""; next
                    }
                    state=="zorder" && /<integer>/ {
                        s=$0; sub(/.*<integer>/, "", s); sub(/<\/integer>.*/, "", s)
                        zorder=s; state=""; next
                    }
                    state=="zorder" && /<real>/ {
                        s=$0; sub(/.*<real>/, "", s); sub(/<\/real>.*/, "", s)
                        sub(/\..*$/, "", s); zorder=s; state=""; next
                    }
                    state=="floating" {
                        if ($0 ~ /<true *\/>/)  { floating="true";  state=""; next }
                        if ($0 ~ /<false *\/>/) { floating="false"; state=""; next }
                    }
                    state=="translucent" {
                        if ($0 ~ /<true *\/>/)  { translucent="true";  state=""; next }
                        if ($0 ~ /<false *\/>/) { translucent="false"; state=""; next }
                    }
                    state ~ /^[rgb]$/ && cur_color != "ctrl" && /<real>/ {
                        s=$0; sub(/.*<real>/, "", s); sub(/<\/real>.*/, "", s)
                        if      (cur_color=="s" && state=="r") sr=s
                        else if (cur_color=="s" && state=="g") sg=s
                        else if (cur_color=="s" && state=="b") sb=s
                        else if (cur_color=="h" && state=="r") hr=s
                        else if (cur_color=="h" && state=="g") hg=s
                        else if (cur_color=="h" && state=="b") hb=s
                        else if (cur_color=="p" && state=="r") pr=s
                        else if (cur_color=="p" && state=="g") pg=s
                        else if (cur_color=="p" && state=="b") pb=s
                        state=""; next
                    }
                    state=="a" && /<real>/ {
                        s=$0; sub(/.*<real>/, "", s); sub(/<\/real>.*/, "", s)
                        if (cur_color=="s") sa=s
                        state=""; next
                    }
                    state != "" && (/<string>/ || /<data>/ || /<integer>/ || /<real>/ || /<dict>/ || /<array>/ || /<true *\/>/ || /<false *\/>/) {
                        state = ""
                    }
                ' "$_state_xml" > "$_meta_usv" 2>/dev/null
            fi
        fi
        local _manifest="$SCRATCH_DIR/sticky-manifest.usv"
        : > "$_manifest"
        _sticky_meta_load
        local _idx=0 _note_count=0 _rtfd_discovered=0
        local _rtfd _uuid _txt_rtf _html_tmp _meta_line
        local _sr _sg _sb _sa _hr _hg _hb _pr _pg _pb _frame _zorder _floating _translucent _expandedsize
        local _sticky_hex _sticky_rgba _highlight_hex _spine_hex
        local _title_raw _title_disp _slug _of _files_dir _files_basename
        local _style _body _mtime _rtf_size _created _touch_epoch _touch_str
        while IFS= read -r -d '' _rtfd; do
            [ -d "$_rtfd" ] || continue
            _rtfd_discovered=$((_rtfd_discovered + 1))
            _txt_rtf="$_rtfd/TXT.rtf"
            if [ ! -f "$_txt_rtf" ]; then
                log_warn "Stickies: .rtfd package $(basename -- "$_rtfd" .rtfd) has no TXT.rtf — skipping."
                note_incomplete "$_stick_root" "Sticky $(basename -- "$_rtfd" .rtfd)" \
                    "its .rtfd package contains no TXT.rtf body file — this sticky is not in the export"
                continue
            fi
            _rtf_size=$(find "$_rtfd" -type f -print0 2>/dev/null \
                | xargs -0 stat -f '%z' 2>/dev/null \
                | LC_ALL=C awk '{s+=$1} END{print s+0}')
            case "$_rtf_size" in ''|*[!0-9]*) _rtf_size=0 ;; esac
            if [ "$_rtf_size" -gt $((STICKIES_RTF_MAX_MB * 1024 * 1024)) ]; then
                log_warn "Stickies: .rtfd bundle for $(basename -- "$_rtfd" .rtfd) exceeds ${STICKIES_RTF_MAX_MB} MB ($_rtf_size bytes) — skipping textutil to avoid wedge."
                note_incomplete "$_stick_root" "Sticky $(basename -- "$_rtfd" .rtfd)" \
                    "its .rtfd bundle ($_rtf_size bytes, including embedded attachments) exceeds the ${STICKIES_RTF_MAX_MB} MB safety cap — not rendered to HTML. Raise STICKIES_RTF_MAX_MB and re-run if this is a genuine sticky"
                continue
            fi
            _idx=$((_idx + 1))
            _uuid=$(basename -- "$_rtfd" .rtfd)
            _meta_line=$(_sticky_meta_for "$_uuid")
            _sr=""; _sg=""; _sb=""; _hr=""; _hg=""; _hb=""
            _pr=""; _pg=""; _pb=""; _sa=""
            _frame=""; _zorder=""; _floating=""; _translucent=""; _expandedsize=""
            IFS=$'\x1f' read -r _sr _sg _sb _hr _hg _hb _pr _pg _pb _sa _frame _zorder _floating _translucent _expandedsize <<< "$_meta_line"
            _sticky_hex=$(_rgb_to_hex "$_sr" "$_sg" "$_sb" 2>/dev/null)
            _sticky_rgba=""
            if [ -n "$_sa" ]; then
                local _is_translucent
                _is_translucent=$(LC_ALL=C awk -v v="$_sa" 'BEGIN{print (v+0 < 1.0) ? "1" : "0"}')
                if [ "$_is_translucent" = "1" ]; then
                    _sticky_rgba=$(_rgba_to_rgba_css "$_sr" "$_sg" "$_sb" "$_sa")
                fi
            fi
            _highlight_hex=$(_rgb_to_hex "$_hr" "$_hg" "$_hb" 2>/dev/null)
            _spine_hex=$(_rgb_to_hex "$_pr" "$_pg" "$_pb" 2>/dev/null)
            _html_tmp="$SCRATCH_DIR/sticky-tahoe-$_idx.html"
            textutil -convert html -stdout "$_rtfd" > "$_html_tmp" 2>/dev/null || {
                log_warn "Stickies: textutil failed on $_uuid — skipping."
                note_incomplete "$_stick_root" "Sticky $_uuid" \
                    "textutil could not convert its RTF body to HTML — this sticky is not in the export"
                rm -f -- "$_html_tmp"
                continue
            }
            if [ ! -s "$_html_tmp" ]; then
                log_warn "Stickies: textutil produced empty output for $_uuid — skipping."
                note_incomplete "$_stick_root" "Sticky $_uuid" \
                    "textutil exited cleanly but produced no HTML output — this sticky is not in the export"
                rm -f -- "$_html_tmp"
                continue
            fi
            _title_raw=$(textutil -convert txt -stdout "$_rtfd" 2>/dev/null | \
                LC_ALL=C tr -d '\r' | awk 'NF{print; exit}' | \
                sed -E 's/^[[:space:]]*[•·▸▶▾▿◦‣⦿⁕*-]+[[:space:]]*//' | \
                sed -E 's/[[:space:]]+$//')
            _title_disp=$(printf '%s' "$_title_raw" | LC_ALL=C cut -c1-60 | iconv -c -f UTF-8 -t UTF-8)
            _slug="$(_stickies_slug "$_title_raw")"
            _title_disp="$(_stickies_friendly_title "$_title_disp" "$_idx")"
            _slug="$(_sanitize_name "$_slug")"
            _of="$(_unique_path "$(printf '%s/Sticky-%03d-%s.html' "$_stick_root" "$_idx" "$_slug")")"
            if grep -q 'src="file://' "$_html_tmp" 2>/dev/null; then
                _files_dir="${_of%.html}.files"
                _files_basename="${_files_dir##*/}"
                if mkdir -p "$_files_dir" 2>/dev/null; then
                    find "$_rtfd" -maxdepth 1 -type f \
                        ! -name 'TXT.rtf' ! -name '.*' \
                        -exec ditto -- {} "$_files_dir/" \; 2>/dev/null
                    if [ -z "$(find "$_files_dir" -maxdepth 1 -type f 2>/dev/null)" ]; then
                        rmdir "$_files_dir" 2>/dev/null
                        _files_dir=""
                    fi
                    if [ -n "$_files_dir" ]; then
                        local _img _img_jpg
                        while IFS= read -r -d '' _img; do
                            _img_jpg="${_img%.*}.jpg"
                            [ -e "$_img_jpg" ] && continue
                            if ! _sips_to_jpeg "$_img" "$_img_jpg" best; then
                                _sticky_img_fail_count=$((_sticky_img_fail_count + 1))
                                log_warn "Image→JPEG conversion failed for ${_img##*/} in sticky '${_title_disp:-?}' — browsers may show a broken image."
                            fi
                        done < <(find "$_files_dir" -maxdepth 1 -type f \
                            \( -iname '*.heic' -o -iname '*.heif' \
                               -o -iname '*.tif' -o -iname '*.tiff' \) -print0 2>/dev/null)
                    fi
                else
                    log_warn "Cannot create $_files_dir — sticky image attachments not extracted."
                    _files_dir=""
                fi
                if [ -n "$_files_dir" ]; then
                    local _fb_sed _fb_sed_re
                    _fb_sed=$(printf '%s' "$_files_basename" | sed 's/[&|\\]/\\&/g')
                    _fb_sed_re=$(printf '%s' "$_files_basename" | sed 's/[].[*&|\\^$(){}+?]/\\&/g')
                    sed -E "s|src=\"file://[^\"]*/([^/\"]*)\"|src=\"${_fb_sed}/\1\"|g" \
                        "$_html_tmp" > "${_html_tmp}.fixed" 2>/dev/null && \
                        mv "${_html_tmp}.fixed" "$_html_tmp" || \
                        rm -f "${_html_tmp}.fixed" 2>/dev/null
                    local _img2 _img2_jpg _src_sed _dst_sed
                    while IFS= read -r -d '' _img2_jpg; do
                        _img2="${_img2_jpg%.jpg}"
                        local _so_orig=0 _so_cand
                        for _so_cand in "$_img2".*; do
                            [ -e "$_so_cand" ] || continue
                            case "$(printf '%s' "${_so_cand##*.}" | tr 'A-Z' 'a-z')" in
                                heic|heif|tif|tiff) _so_orig=1; break ;;
                            esac
                        done
                        [ "$_so_orig" = "1" ] || continue
                        _src_sed=$(printf '%s' "${_img2##*/}" | sed 's/[].[*&|\\^$(){}+?]/\\&/g')
                        _dst_sed=$(printf '%s' "${_img2_jpg##*/}" | sed 's/[&|\\]/\\&/g')
                        sed -E "s|src=\"(${_fb_sed_re}/)${_src_sed}\.[Hh][Ee][Ii][CcFf]\"|src=\"\1${_dst_sed}\"|g" \
                            "$_html_tmp" > "${_html_tmp}.imgfix" 2>/dev/null && \
                            mv "${_html_tmp}.imgfix" "$_html_tmp" || \
                            rm -f "${_html_tmp}.imgfix" 2>/dev/null
                        sed -E "s|src=\"(${_fb_sed_re}/)${_src_sed}\.[Tt][Ii][Ff][Ff]?\"|src=\"\1${_dst_sed}\"|g" \
                            "$_html_tmp" > "${_html_tmp}.imgfix" 2>/dev/null && \
                            mv "${_html_tmp}.imgfix" "$_html_tmp" || \
                            rm -f "${_html_tmp}.imgfix" 2>/dev/null
                    done < <(find "$_files_dir" -maxdepth 1 -type f -name '*.jpg' -print0 2>/dev/null)
                fi
            fi
            _style=$(sed -n '/<style[^>]*>/,/<\/style>/p' "$_html_tmp" 2>/dev/null)
            _body=$(sed -n '/<body[^>]*>/,/<\/body>/p' "$_html_tmp" 2>/dev/null | \
                sed -e '1s/<body[^>]*>//' -e '$s/<\/body>//')
            _mtime=$(TZ=UTC stat -f '%Sm' -t '%Y-%m-%dT%H:%M:%SZ' "$_rtfd" 2>/dev/null)
            _created=$(TZ=UTC stat -f '%SB' -t '%Y-%m-%dT%H:%M:%SZ' "$_rtfd" 2>/dev/null)
            local _of_tmp
            _of_tmp="$(mktemp "$_of.tmp.XXXXXX" 2>/dev/null)" || _of_tmp="$_of.tmp.$$"
            track_output_path "$_of_tmp"
            {
                printf '<!DOCTYPE html>\n'
                printf '<html>\n<head>\n'
                printf '<meta charset="UTF-8">\n'
                printf '<title>Sticky %03d — %s</title>\n' "$_idx" "$(html_escape "$_title_disp")"
                [ -n "$_sticky_hex" ]    && printf '<meta name="apple-stickies-color" content="%s">\n'      "$(html_escape "$_sticky_hex")"
                [ -n "$_highlight_hex" ] && printf '<meta name="apple-stickies-highlight" content="%s">\n'  "$(html_escape "$_highlight_hex")"
                [ -n "$_spine_hex" ]     && printf '<meta name="apple-stickies-spine" content="%s">\n'      "$(html_escape "$_spine_hex")"
                [ -n "$_frame" ]         && printf '<meta name="apple-stickies-window" content="%s">\n'     "$(html_escape "$_frame")"
                [ -n "$_expandedsize" ]  && printf '<meta name="apple-stickies-expanded-size" content="%s">\n' "$(html_escape "$_expandedsize")"
                [ -n "$_zorder" ]        && printf '<meta name="apple-stickies-zorder" content="%s">\n'     "$(html_escape "$_zorder")"
                [ -n "$_floating" ]      && printf '<meta name="apple-stickies-floating" content="%s">\n'   "$(html_escape "$_floating")"
                [ -n "$_translucent" ]   && printf '<meta name="apple-stickies-translucent" content="%s">\n' "$(html_escape "$_translucent")"
                [ -n "$_created" ]       && printf '<meta name="apple-stickies-created" content="%s">\n'    "$(html_escape "$_created")"
                [ -n "$_mtime" ]         && printf '<meta name="apple-stickies-modified" content="%s">\n'   "$(html_escape "$_mtime")"
                printf '<meta name="apple-stickies-uuid" content="%s">\n' "$(html_escape "$_uuid")"
                [ -n "$_style" ] && printf '%s\n' "$_style"
                _stickies_envelope_css "$_sticky_hex" "$_sticky_rgba" "$_spine_hex" "$_highlight_hex"
                printf '</head>\n<body>\n'
                printf '%s\n' "$_body"
                printf '</body>\n</html>\n'
            } > "$_of_tmp"
            if ! _atomic_commit_tmp $? "$_of_tmp" "$_of"; then
                _untrack_output_path "$_of_tmp"
                note_incomplete "$_stick_root" "Sticky $_uuid" \
                    "the per-sticky HTML write failed (mv into place) — disk-full or read-only volume"
                rm -f -- "$_html_tmp"
                [ -n "$_files_dir" ] && rm -rf -- "$_files_dir"
                continue
            fi
            _untrack_output_path "$_of_tmp"
            _note_count=$((_note_count + 1))
            _touch_epoch=$(_stickies_iso_to_epoch "$_mtime")
            _touch_str=$(_format_touch_t "$_touch_epoch")
            _apply_touch_t "$_touch_str" "$_of"
            if [ "$_html_validated" != "1" ]; then
                validate_html_structure "$_of"
                _html_validated=1
            fi
            local _zo_sort="-1"
            if [ -n "$_zorder" ]; then
                _zo_sort="$_zorder"
            fi
            printf '%03d\x1f%s\x1f%s\x1f%s\x1f%s\x1f%s\x1f%s\n' \
                "$_idx" "$(tsv_escape "$_uuid")" "$(tsv_escape "$_title_disp")" "${_of##*/}" \
                "$_sticky_hex" "$_zo_sort" "$(tsv_escape "$_frame")" >> "$_manifest"
            rm -f -- "$_html_tmp"
        done < <(find "$_src" -maxdepth 1 -name '*.rtfd' -type d -print0 2>/dev/null | LC_ALL=C sort -z)
        if [ "$_rtfd_discovered" -gt "$_note_count" ]; then
            log_warn "Stickies: discovered $_rtfd_discovered .rtfd $(_pluralize "$_rtfd_discovered" package) but only $_note_count $(_pluralize "$_note_count" sticky stickies) exported."
            note_incomplete "$_stick_root" "Stickies — discovery and emit counts disagree" \
                "found $_rtfd_discovered .rtfd package(s) on disk but only $_note_count sticky/stickies landed in the export — $((_rtfd_discovered - _note_count)) were dropped"
        fi
        if [ "$_note_count" -gt 0 ]; then
            _stickies_emit_index "$_manifest" "$_note_count" "$_stick_root"
            validate_html_structure "$_stick_root/index.html"
            log_ok "Wrote Stickies/ ($_note_count $(_pluralize "$_note_count" sticky stickies) + index.html, $(_dir_size_human "$_stick_root"))"
            if [ "$_sticky_img_fail_count" -gt 0 ]; then
                log_warn "$_sticky_img_fail_count embedded $(_pluralize "$_sticky_img_fail_count" image) failed to convert to JPEG — the original (HEIC/HEIF/TIFF) is still in the .files/ subdir but the per-sticky .html won't render those images inline in most browsers."
            fi
        elif report_have_incomplete "$_stick_root"; then
            log_warn "Stickies: an earlier step could not complete$(_disclosure_pointer "Stickies/_incomplete.txt")."
        else
            rmdir "$_stick_root" 2>/dev/null || true
            report_empty_source "stickies" "Stickies"
        fi
        return 0
}

stickies_main() {
    maybe_show_help "$@"
    _announce_step "Stickies export"
    check_dependencies
    local out_arg out_dir
    out_arg="$(_parse_output_folder_arg "$@")" || exit 1
    out_dir="$(resolve_output_dir "$out_arg")" || exit 1
    _announce_output_dir "Stickies"
    require_full_disk_access
    warn_if_app_running Stickies
    export_stickies "$out_dir"
    mark_success
    sweep_junk_files "$out_dir"
    print_summary
    if [ "$ERR_COUNT" -gt 0 ]; then exit 1; fi
    exit 0
}

export_text_replacements() {
    local out_root="$1"
    local _tr_root="$out_root/Text Replacements"
    local _db="$HOME/Library/KeyboardServices/TextReplacements.db"
    if [ ! -f "$_db" ]; then
        report_no_source "Text Replacements" "not configured" \
            "~/Library/KeyboardServices/TextReplacements.db" "Text Replacements"
        return 0
    fi
    require_no_collision "$_tr_root"
    _create_output_dir "$_tr_root"
    log_info "Source: $_db"
    log_info "Snapshotting TextReplacements.db and querying ZTEXTREPLACEMENTENTRY..."
    ensure_scratch
    local _snap=""
    _snap=$(snapshot_db "$_db" 2>/dev/null) || _snap=""
    if [ -z "$_snap" ]; then
        log_warn "Text Replacements: could not snapshot TextReplacements.db for read-only querying."
        note_incomplete "$_tr_root" "All text replacements" \
            "TextReplacements.db is present but could not be snapshotted for read-only querying — the source DB may be corrupt or an unrecognised macOS schema variant, or scratch space may be exhausted / the temp directory unwritable — nothing could be exported"
        rmdir "$_tr_root" 2>/dev/null || true
        return 0
    fi
    if ! sqlite3 -readonly "$_snap" "SELECT Z_PK, ZSHORTCUT, ZPHRASE, ZWASDELETED FROM ZTEXTREPLACEMENTENTRY LIMIT 1;" >/dev/null 2>&1; then
        log_warn "Text Replacements: TextReplacements.db schema not readable."
        note_incomplete "$_tr_root" "All text replacements" \
            "TextReplacements.db is present but its schema could not be read (corrupt DB, or an unrecognised macOS schema variant) — nothing could be exported"
        rmdir "$_tr_root" 2>/dev/null || true
        return 0
    fi
    local _ts_col="" _ts_label="" _icloud_del_col="" _sync_col="" _sync_sel=""
    _ts_col="$(_pick_first_col "$_snap" ZTEXTREPLACEMENTENTRY \
                  ZTIMESTAMP ZCREATIONDATE ZCREATEDDATE ZDATECREATED \
                  ZMODIFICATIONDATE ZMODIFIEDDATE ZDATEMODIFIED ZDATE)"
    if [ -n "$_ts_col" ]; then
        case "$_ts_col" in
            *MODIF*) _ts_label="Modified" ;;
            *)       _ts_label="Created" ;;
        esac
    fi
    _icloud_del_col="$(_pick_first_col "$_snap" ZTEXTREPLACEMENTENTRY \
                   ZWASDELETEDFROMICLOUD ZICLOUDWASDELETED ZWASDELETEDONICLOUD)"
    _sync_col="$(_pick_first_col "$_snap" ZTEXTREPLACEMENTENTRY \
                    ZSYNCSTATE ZSYNCED ZCLOUDSYNCSTATE ZISSYNCED)"
    if [ -n "$_sync_col" ]; then
        _sync_sel="$(_sql_tsv_safe "CAST($_sync_col AS TEXT)")"
    elif _col_present "$_snap" ZTEXTREPLACEMENTENTRY ZNEEDSSAVETOCLOUD; then
        _sync_col="ZNEEDSSAVETOCLOUD"
        _sync_sel="$(_sql_tsv_safe "CASE WHEN COALESCE(ZNEEDSSAVETOCLOUD, 0) = 0 THEN 'yes' ELSE 'no' END")"
    fi
    local _where="COALESCE(ZWASDELETED, 0) = 0"
    if [ -n "$_icloud_del_col" ]; then
        _where="$_where AND COALESCE($_icloud_del_col, 0) = 0"
    fi
    if [ -n "$_ts_col" ] && [ "$_ts_col" != "ZTIMESTAMP" ]; then
        log_info "Schema: timestamp = $_ts_col ($_ts_label, legacy)"
    fi
    if [ -n "$_icloud_del_col" ]; then
        log_info "Schema: iCloud tombstone = $_icloud_del_col (folded into Deleted column)"
    fi
    if [ -n "$_sync_col" ] && [ "$_sync_col" != "ZNEEDSSAVETOCLOUD" ]; then
        log_info "Schema: sync state = $_sync_col (Synced column)"
    fi
    local _disc
    local _count _count_q _active
    _count_q=$(sqlite3 -readonly "$_snap" -separator $'\x1f' \
        "SELECT (SELECT COUNT(*) FROM ZTEXTREPLACEMENTENTRY),
                (SELECT COUNT(*) FROM ZTEXTREPLACEMENTENTRY WHERE $_where);" 2>/dev/null)
    if [ -z "$_count_q" ]; then
        log_warn "Text Replacements: entry count query failed."
        note_incomplete "$_tr_root" "All text replacements" \
            "the count query against ZTEXTREPLACEMENTENTRY failed — the database is present but not reliably queryable, so no CSV was written"
        rmdir "$_tr_root" 2>/dev/null || true
        return 0
    fi
    _count="${_count_q%%$'\x1f'*}"
    _active="${_count_q#*$'\x1f'}"
    case "$_count"  in ''|*[!0-9]*) _count=0 ;; esac
    case "$_active" in ''|*[!0-9]*) _active=0 ;; esac
    _disc="$_count"
    if [ "$_count" = "0" ]; then
        if report_have_incomplete "$_tr_root"; then
            log_warn "Text Replacements: an earlier step could not complete$(_disclosure_pointer)."
            rmdir "$_tr_root" 2>/dev/null || true   # don't leave a bare empty category dir (parity with the branches above)
            return 0
        fi
        rmdir "$_tr_root" 2>/dev/null || true
        report_empty_source "text replacements" "Text Replacements"
        return 0
    fi
    local _csv="$_tr_root/TextReplacements.csv"
    local _hdr="Shortcut,Phrase,Deleted"
    local _sel="$(_sql_tsv_safe "ZSHORTCUT"), $(_sql_tsv_safe "ZPHRASE"),
                   CASE WHEN $_where THEN 'no' ELSE 'yes' END"
    if [ -n "$_ts_col" ]; then
        _hdr="$_hdr,$_ts_label"
        _sel="$_sel,
                   CASE
                     WHEN $_ts_col IS NULL OR $_ts_col = 0 THEN ''
                     WHEN $_ts_col > 4000000000
                       THEN datetime($_ts_col / 1e9 + 978307200, 'unixepoch', 'localtime')
                     ELSE datetime($_ts_col + 978307200, 'unixepoch', 'localtime')
                   END"
    fi
    if [ -n "$_sync_col" ]; then
        _hdr="$_hdr,Synced"
        _sel="$_sel, $_sync_sel"
    fi
    local _tr_query_failed=""
    local _tr_tmp
    _tr_tmp="$(mktemp "$_csv.tmp.XXXXXX" 2>/dev/null)" || _tr_tmp="$_csv.tmp.$$"
    track_output_path "$_tr_tmp"
    {
        printf '%s\r\n' "$_hdr"
        sqlite3 -readonly "$_snap" "
            SELECT $_sel
            FROM ZTEXTREPLACEMENTENTRY
            ORDER BY ZSHORTCUT, Z_PK;
        " -separator $'\x1f' > "$SCRATCH_DIR/textrepl_rows.$$" 2>/dev/null \
            || _tr_query_failed=1
        local _sc _ph _del _x1 _x2
        while IFS=$'\x1f' read -r _sc _ph _del _x1 _x2; do
            local _row="$(csv_field "$_sc"),$(csv_field "$_ph"),$(csv_field "$_del")"
            if [ -n "$_ts_col" ]; then
                _row="$_row,$(csv_field "$_x1")"
                if [ -n "$_sync_col" ]; then
                    _row="$_row,$(csv_field "$_x2")"
                fi
            elif [ -n "$_sync_col" ]; then
                _row="$_row,$(csv_field "$_x1")"
            fi
            printf '%s\r\n' "$_row"
        done < "$SCRATCH_DIR/textrepl_rows.$$"
    } > "$_tr_tmp"
    _atomic_commit_tmp $? "$_tr_tmp" "$_csv"; local _commit_ok=$?
    _untrack_output_path "$_tr_tmp"
    rm -f -- "$SCRATCH_DIR/textrepl_rows.$$" 2>/dev/null
    [ "$_commit_ok" -eq 0 ] || note_incomplete "$_tr_root" "TextReplacements.csv" \
            "the atomic CSV write failed (disk-full / read-only output volume / permission error) — the user's text replacements were not exported"
    [ -n "$_tr_query_failed" ] && { log_warn "Text Replacements: row query failed — the CSV may be incomplete."; note_incomplete "$_tr_root" "TextReplacements.csv" "reading the rows from the Text Replacements database failed partway through (it may be corrupt or have an unexpected layout); the CSV may be truncated"; }
    local _emit=0 _deleted
    _deleted=$((_count - _active))
    if [ "$_deleted" -gt 0 ]; then
        log_info "Exported $_deleted deleted text replacement(s) (marked Deleted=yes) — review and discard if not needed."
    fi
    if [ "$_commit_ok" -eq 0 ]; then
        _emit=$(_count_csv_rows "$_csv")
        validate_count_parity "$_disc" "$_emit" "TextReplacements.csv" "$_tr_root" || true
        validate_csv_rfc4180 "$_csv" || true
        log_ok "Wrote Text Replacements/ ($_emit $(_pluralize "$_emit" replacement), $(_dir_size_human "$_tr_root"))"
    else
        log_warn "Text Replacements/ was not written — the CSV commit failed$(_disclosure_pointer)."
    fi
    return 0
}

text_replacements_main() {
    maybe_show_help "$@"
    _announce_step "Text Replacements export"
    check_dependencies
    local out_arg out_dir
    out_arg="$(_parse_output_folder_arg "$@")" || exit 1
    out_dir="$(resolve_output_dir "$out_arg")" || exit 1
    _announce_output_dir "Text Replacements"
    require_full_disk_access
    export_text_replacements "$out_dir"
    mark_success
    sweep_junk_files "$out_dir"
    print_summary
    if [ "$ERR_COUNT" -gt 0 ]; then exit 1; fi
    exit 0
}

_VM_HAS_FOLDERS=0
_VM_RECORDINGS_DIR="$HOME/Library/Group Containers/group.com.apple.VoiceMemos.shared/Recordings"

_format_cd_date_prefix() {
    local unix
    unix="$(_cd_ts_to_unix "$1")"
    [ -n "$unix" ] && [ "$unix" -gt 0 ] || { printf ''; return; }
    LC_ALL=C date -r "$unix" '+%Y-%m-%d_%H%M%S' 2>/dev/null
}

_vm_idx_rows() {
    local _rel _rec _folder _dur _tr _fav _disp _durfmt _e1 _e2 _e3 _e4
    LC_ALL=C sort -t "$(printf '\x1f')" -k1,1 "$_mf" | \
        while IFS="$(printf '\x1f')" read -r _rel _rec _folder _dur _tr _fav; do
        _disp="${_rel##*/}"
        _durfmt=""
        case "$_dur" in
            ''|*[!0-9.]*) _durfmt="" ;;
            *)            _durfmt="$(_fmt_duration "${_dur%%.*}")" ;;
        esac
        printf '<tr>'
        html_escape "$_disp" _e1
        printf '<td><a href="%s">%s</a></td>' "$(_url_encode_path "$_rel")" "$_e1"
        html_escape "${_folder:-—}" _e2
        printf '<td>%s</td>' "$_e2"
        html_escape "$_rec" _e3
        printf '<td>%s</td>' "$_e3"
        html_escape "$_durfmt" _e4
        printf '<td class="num">%s</td>' "$_e4"
        local _trmark='' _favmark=''
        case "$_tr" in yes) _trmark='✓' ;; esac
        case "$_fav" in yes) _favmark='★' ;; esac
        printf '<td class="c">%s</td>' "$_trmark"
        printf '<td class="c">%s</td>' "$_favmark"
        printf '</tr>\n'
    done
}

_vm_emit_index() {
    local _mf="$1" _nc="$2" _root="$3"
    local _idx_title _idx_h1 _idx_extra_css _idx_thead _idx_rows_fn
    _idx_title="Voice Memos ($_nc)"
    _idx_h1="Voice Memos — $_nc $(_pluralize "$_nc" recording recordings)"
    _idx_extra_css='td.num{text-align:right;font-variant-numeric:tabular-nums;color:#555;}
td.c{text-align:center;}'
    _idx_thead='<tr><th>Recording</th><th>Folder</th><th>Recorded</th><th>Duration</th><th>Transcript</th><th>Favorite</th></tr>'
    _idx_rows_fn=_vm_idx_rows
    _emit_html_index "$_root/index.html" "Voice Memos/index.html"
}

_bulk_copy_fallback() {
    local src="$1" dst="$2"
    local copied=0 _f _rel _tdir _orig _bc_src_sz _bc_dst_sz
    _BULK_COPY_N=0
    if [ ! -d "$src" ]; then
        log_warn "Voice Memos bulk-copy fallback: source directory does not exist or is unreadable: $src"
        return 1
    fi
    mkdir -p "$dst" || { log_warn "Cannot create $dst"; return 1; }
    local _stubs_file=""
    if [ -n "${SCRATCH_DIR:-}" ]; then
        _stubs_file="$SCRATCH_DIR/vm_fallback_stubs.tsv"
        : > "$_stubs_file" 2>/dev/null || _stubs_file=""
    fi
    local _fails_file=""
    if [ -n "${SCRATCH_DIR:-}" ]; then
        _fails_file="$SCRATCH_DIR/vm_fallback_fails.tsv"
        : > "$_fails_file" 2>/dev/null || _fails_file=""
    fi
    local _pt_last=0 _pt_inline=0
    while IFS= read -r -d '' _f; do
        _rel="${_f#"$src"/}"
        if is_icloud_stub "$_f" || is_dataless "$_f"; then
            if [ -n "$_stubs_file" ]; then
                _orig="$(_strip_icloud_stub_name "${_f##*/}")"
                printf '%s\n' "$_orig" >> "$_stubs_file"
            fi
            continue
        fi
        should_skip_copy "$_f" "$_rel" && continue
        _tdir="$(dirname "$dst/$_rel")"
        [ -d "$_tdir" ] || mkdir -p "$_tdir" 2>/dev/null
        if ditto -- "$_f" "$dst/$_rel" 2>/dev/null && [ -e "$dst/$_rel" ]; then
            _bc_src_sz=$(stat -f%z "$_f" 2>/dev/null || printf 0)
            _bc_dst_sz=$(stat -f%z "$dst/$_rel" 2>/dev/null || printf 0)
            case "$_bc_src_sz" in ''|*[!0-9]*) _bc_src_sz=0 ;; esac
            case "$_bc_dst_sz" in ''|*[!0-9]*) _bc_dst_sz=0 ;; esac
            if [ "$_bc_src_sz" = "$_bc_dst_sz" ]; then
                copied=$((copied + 1))
            else
                rm -f -- "$dst/$_rel" 2>/dev/null || true
                [ -n "$_fails_file" ] && printf '%s\n' "$_rel" >> "$_fails_file"
            fi
        else
            [ -n "$_fails_file" ] && printf '%s\n' "$_rel" >> "$_fails_file"
        fi
        _progress_tick "$copied" 0 "recordings copied (fallback)"
    done < <(find "$src" -type f ! -type l ! -name 'CloudRecordings.db*' ! -name '*.plist' ! -name '*.storedata*' -print0 2>/dev/null)
    _progress_end
    _BULK_COPY_N="$copied"
}

voice_memos_main() {
    maybe_show_help "$@"
    _announce_step "Voice memos export"
    check_dependencies
    local out_arg out_dir
    out_arg="$(_parse_output_folder_arg "$@")" || exit 1
    out_dir="$(resolve_output_dir "$out_arg")" || exit 1
    _announce_output_dir "Voice Memos"
    require_full_disk_access
    _VM_DB_PATH="$_VM_RECORDINGS_DIR/CloudRecordings.db"
    if [ ! -f "$_VM_DB_PATH" ] && \
       [ -f "$HOME/Library/Application Support/com.apple.voicememos/Recordings/CloudRecordings.db" ]; then
        _VM_DB_PATH="$HOME/Library/Application Support/com.apple.voicememos/Recordings/CloudRecordings.db"
    fi
    if [ ! -d "$_VM_RECORDINGS_DIR" ]; then
        report_no_source "Voice Memos" "not configured" "$_VM_RECORDINGS_DIR" "Voice Memos"
        return 0
    fi
    warn_if_app_running "Voice Memos"
    local out_root="$out_dir/Voice Memos"
    require_no_collision "$out_root"
    _create_output_dir "$out_root"
    log_info "Snapshotting CloudRecordings.db..."
    [ -f "$_VM_DB_PATH" ] && log_info "Source: $_VM_DB_PATH"
    local snap=""
    local _vm_db_ok=0
    local _vm_db_unreadable=0
    if [ -f "$_VM_DB_PATH" ]; then
        ensure_scratch
        if snap="$(snapshot_db "$_VM_DB_PATH")" && [ -n "$snap" ]; then
            if sqlite3 -readonly "$snap" \
                   "SELECT Z_PK FROM ZCLOUDRECORDING LIMIT 1;" >/dev/null 2>&1; then
                _vm_db_ok=1
            else
                log_warn "CloudRecordings.db schema not readable — falling back to bulk copy."
                _vm_db_unreadable=1
            fi
        else
            log_warn "Could not snapshot CloudRecordings.db — falling back to bulk copy."
            _vm_db_unreadable=1
        fi
    else
        log_warn "CloudRecordings.db not present — falling back to bulk copy."
    fi
    if [ "$_vm_db_ok" -eq 0 ]; then
        ensure_scratch
        if [ "$_vm_db_unreadable" -eq 1 ]; then
            note_incomplete "$out_root" "Voice Memos metadata" \
                "exported via bulk-copy fallback — recording dates / labels / folders / transcripts unavailable; the database was present but unreadable"
        fi
        local fallback_n _fb_rc
        _bulk_copy_fallback "$_VM_RECORDINGS_DIR" "$out_root"
        _fb_rc=$?
        fallback_n="$_BULK_COPY_N"
        case "$fallback_n" in ''|*[!0-9]*) fallback_n=0 ;; esac
        if [ "$_fb_rc" -ne 0 ]; then
            note_incomplete "$out_root" "Voice Memos recordings" \
                "the bulk-copy fallback could not create the output directory — no recordings were exported"
            die "Cannot create $out_root — Voice Memos bulk-copy fallback failed."
        fi
        local _vm_fb_fails="$SCRATCH_DIR/vm_fallback_fails.tsv"
        local _vm_fb_fail_count=0
        if [ -s "$_vm_fb_fails" ]; then
            _vm_fb_fail_count="$(_count_lines "$_vm_fb_fails")"
            if [ "$_vm_fb_fail_count" -gt 0 ]; then
                log_warn "$_vm_fb_fail_count $(_pluralize "$_vm_fb_fail_count" recording) failed to copy"
                note_incomplete "$out_root" "$_vm_fb_fail_count voice $(_pluralize "$_vm_fb_fail_count" recording) failed to copy" \
                    "cp failed during the bulk-copy fallback walk — the recording audio was not exported"
            fi
        fi
        local _vm_fb_stubs="$SCRATCH_DIR/vm_fallback_stubs.tsv"
        local _vm_fb_stub_count=0
        if [ -s "$_vm_fb_stubs" ]; then
            _vm_fb_stub_count="$(_count_lines "$_vm_fb_stubs")"
            if [ "$_vm_fb_stub_count" -gt 0 ]; then
                {
                    printf '# Schema-unreadable fallback: recovered filenames listed below.\n\n'
                    printf '[Recordings]\n'
                    LC_ALL=C sort -u "$_vm_fb_stubs"
                } | _write_skipped_report "$out_root" "Voice Memos recordings"
            fi
        fi
        if [ "$fallback_n" -eq 0 ] && [ "$_vm_fb_stub_count" -eq 0 ]; then
            cleanup_empty_dirs "$out_root"
            report_empty_source "recordings" "Voice Memos"
        fi
        local _vm_fb_stat="$fallback_n $(_pluralize "$fallback_n" recording)"
        [ "$_vm_fb_stub_count" -gt 0 ] && \
            _vm_fb_stat="$_vm_fb_stat, $_vm_fb_stub_count cloud-only$(_disclosure_pointer "Voice Memos/_skipped.txt")"
        _vm_fb_stat="$_vm_fb_stat, $(_dir_size_human "$out_root")"
        log_ok "Wrote Voice Memos/ ($_vm_fb_stat)"
        mark_success
        sweep_junk_files "$out_root"
        print_summary
        if [ "$ERR_COUNT" -gt 0 ]; then exit 1; fi
        exit 0
    fi
    log_info "Probing schema (folders, transcript, parent)..."
    local folder_lookup=""
    local _vm_parent_folder_col=""
    local _vm_fname_qual="''"
    if sqlite3 -readonly "$snap" "SELECT Z_PK FROM ZFOLDER LIMIT 1;" \
            >/dev/null 2>&1; then
        _VM_HAS_FOLDERS=1
        folder_lookup="$SCRATCH_DIR/vm_folders.tsv"
        _vm_parent_folder_col="$(_pick_first_col "$snap" ZFOLDER \
                                    ZPARENTFOLDER ZPARENT ZSUPERFOLDER)"
        :
        local _vm_folder_name_col _vm_fname_bare="''"
        _vm_folder_name_col="$(_pick_first_col "$snap" ZFOLDER \
                                  ZENCRYPTEDNAME ZNAME)"
        if [ -n "$_vm_folder_name_col" ]; then
            _vm_fname_bare="$_vm_folder_name_col"
            _vm_fname_qual="f.$_vm_folder_name_col"
            [ "$_vm_folder_name_col" != "ZENCRYPTEDNAME" ] && \
                log_info "Schema: folder-name = $_vm_folder_name_col (legacy)"
        fi
        if [ -n "$_vm_parent_folder_col" ]; then
            local _folder_walk_max_depth=10
            sqlite3 -readonly -separator $'\t' "$snap" \
                "SELECT Z_PK, $(_sql_tsv_safe "$_vm_fname_bare"), COALESCE($_vm_parent_folder_col, 0) FROM ZFOLDER;" \
                > "$SCRATCH_DIR/vm_folders_raw.tsv" 2>/dev/null || true
            LC_ALL=C awk -F'\t' -v MAX_DEPTH="$_folder_walk_max_depth" '
                { name[$1] = $2; parent[$1] = $3 }
                END {
                    for (pk in name) {
                        path = ""
                        cur = pk
                        for (i = 0; i < MAX_DEPTH && cur != 0 && cur != ""; i++) {
                            if (visited[cur]) break
                            visited[cur] = 1
                            n = name[cur]
                            if (n == "") break
                            if (path == "") path = n
                            else            path = n "/" path
                            cur = parent[cur]
                        }
                        delete visited
                        print pk "\t" path
                    }
                }
            ' "$SCRATCH_DIR/vm_folders_raw.tsv" \
                > "$SCRATCH_DIR/vm_folder_paths.tsv"
            sqlite3 -readonly -separator $'\t' "$snap" \
                "SELECT Z_PK, ZFOLDER FROM ZCLOUDRECORDING WHERE ZFOLDER IS NOT NULL;" \
                > "$SCRATCH_DIR/vm_membership.tsv" 2>/dev/null || true
            LC_ALL=C awk -F'\t' '
                FNR == NR { path[$1] = $2; next }
                ($2 in path) { print $1 "\t" path[$2] }
            ' "$SCRATCH_DIR/vm_folder_paths.tsv" \
              "$SCRATCH_DIR/vm_membership.tsv" \
                > "$folder_lookup"
        else
            sqlite3 -readonly -separator $'\t' "$snap" \
                "SELECT r.Z_PK, $(_sql_tsv_safe "$_vm_fname_qual")
                 FROM ZCLOUDRECORDING r
                 JOIN ZFOLDER f ON f.Z_PK = r.ZFOLDER;" \
                > "$folder_lookup" 2>/dev/null || true
        fi
    fi
    if [ "$_VM_HAS_FOLDERS" -eq 1 ] && [ -s "$folder_lookup" ]; then
        local _vf_pk _vf_name
        while IFS=$'\t' read -r _vf_pk _vf_name; do
            case "$_vf_pk" in ''|*[!0-9]*) continue ;; esac
            printf -v "_vf_${_vf_pk}" '%s' "$_vf_name"
        done < "$folder_lookup"
    fi
    local _cloudonly_file="$SCRATCH_DIR/vm_cloudonly.tsv"
    : > "$_cloudonly_file" || die "Cannot create scratch cloud-only list"
    local _vm_transcript_col="" _vm_parent_col=""
    local _vm_trim_start_col="" _vm_trim_end_col=""
    local _vm_duration_col="" _vm_autotitle_col="" _vm_mdate_col="" _vm_favorite_col="" _vm_deleted_col=""
    _vm_transcript_col="$(_pick_first_col "$snap" ZCLOUDRECORDING \
                            ZTRANSCRIPTION ZTRANSCRIPT ZTRANSCRIPTSTRING)"
    _vm_parent_col="$(_pick_first_col "$snap" ZCLOUDRECORDING \
                         ZRECORDING_PARENT ZPARENT ZTRIMMEDFROM ZPARENTRECORDING)"
    _vm_trim_start_col="$(_pick_first_col "$snap" ZCLOUDRECORDING \
                             ZTRIMSTARTOFFSET ZTRIMSTART)"
    _vm_trim_end_col="$(_pick_first_col "$snap" ZCLOUDRECORDING \
                           ZTRIMENDOFFSET ZTRIMEND)"
    _vm_duration_col="$(_pick_first_col "$snap" ZCLOUDRECORDING \
                           ZDURATION ZRECORDINGDURATION)"
    _vm_autotitle_col="$(_pick_first_col "$snap" ZCLOUDRECORDING \
                            ZENCRYPTEDTITLE ZTITLE ZDISPLAYNAME ZGENERATEDTITLE)"
    _vm_mdate_col="$(_pick_first_col "$snap" ZCLOUDRECORDING \
                        ZMODIFIEDDATE ZMODIFICATIONDATE ZLASTMODIFIED \
                        ZDATEMODIFIED ZLASTMODIFIEDDATE)"
    _vm_favorite_col="$(_pick_first_col "$snap" ZCLOUDRECORDING \
                          ZISFAVORITE ZFAVORITE ZFLAGGED ZISFLAGGED)"
    _vm_deleted_col="$(_pick_first_col "$snap" ZCLOUDRECORDING \
                          ZLOCALDELETEDDATE ZDELETEDDATE ZRECENTLYDELETEDDATE)"
    [ -n "$_vm_parent_folder_col" ] && [ "$_vm_parent_folder_col" != "ZPARENTFOLDER" ] && \
        log_info "Schema: parent-folder = $_vm_parent_folder_col (legacy)"
    [ -n "$_vm_transcript_col" ] && [ "$_vm_transcript_col" != "ZTRANSCRIPTION" ] && \
        log_info "Schema: transcript = $_vm_transcript_col (legacy)"
    [ -n "$_vm_parent_col" ] && [ "$_vm_parent_col" != "ZRECORDING_PARENT" ] && \
        log_info "Schema: trim-parent = $_vm_parent_col (legacy)"
    [ -n "$_vm_trim_start_col" ] && [ "$_vm_trim_start_col" != "ZTRIMSTARTOFFSET" ] && \
        log_info "Schema: trim-start = $_vm_trim_start_col (legacy)"
    [ -n "$_vm_trim_end_col" ] && [ "$_vm_trim_end_col" != "ZTRIMENDOFFSET" ] && \
        log_info "Schema: trim-end = $_vm_trim_end_col (legacy)"
    [ -n "$_vm_duration_col" ] && [ "$_vm_duration_col" != "ZDURATION" ] && \
        log_info "Schema: duration = $_vm_duration_col (legacy)"
    [ -n "$_vm_autotitle_col" ] && [ "$_vm_autotitle_col" != "ZENCRYPTEDTITLE" ] && \
        log_info "Schema: auto-title = $_vm_autotitle_col (legacy)"
    [ -n "$_vm_mdate_col" ] && [ "$_vm_mdate_col" != "ZMODIFIEDDATE" ] && \
        log_info "Schema: modification-date = $_vm_mdate_col (legacy)"
    [ -n "$_vm_favorite_col" ] && [ "$_vm_favorite_col" != "ZISFAVORITE" ] && \
        log_info "Schema: favorite = $_vm_favorite_col (legacy)"
    [ -n "$_vm_deleted_col" ] && [ "$_vm_deleted_col" != "ZLOCALDELETEDDATE" ] && \
        log_info "Schema: recently-deleted = $_vm_deleted_col (legacy)"
    local _vm_transcript_sel="''" _vm_parent_sel="0"
    local _vm_trim_start_sel="''" _vm_trim_end_sel="''"
    [ -n "$_vm_transcript_col" ] && \
        _vm_transcript_sel="replace(replace(replace(replace(replace(COALESCE($_vm_transcript_col, ''), x'09', ' '), x'0A', ' '), x'0D', ' '), x'1F', ' '), x'00', '')"
    [ -n "$_vm_parent_col" ]     && _vm_parent_sel="COALESCE($_vm_parent_col, 0)"
    [ -n "$_vm_trim_start_col" ] && _vm_trim_start_sel="COALESCE($_vm_trim_start_col, '')"
    [ -n "$_vm_trim_end_col" ]   && _vm_trim_end_sel="COALESCE($_vm_trim_end_col, '')"
    local _vm_duration_sel="''" _vm_autotitle_sel="''"
    local _vm_mdate_sel="''" _vm_favorite_sel="''"
    [ -n "$_vm_duration_col" ]  && _vm_duration_sel="COALESCE($_vm_duration_col, '')"
    [ -n "$_vm_autotitle_col" ] && _vm_autotitle_sel="$(_sql_tsv_safe "COALESCE($_vm_autotitle_col, '')")"
    [ -n "$_vm_mdate_col" ]     && _vm_mdate_sel="COALESCE($_vm_mdate_col, '')"
    [ -n "$_vm_favorite_col" ]  && _vm_favorite_sel="COALESCE($_vm_favorite_col, 0)"
    local _vm_deleted_sel="0"
    [ -n "$_vm_deleted_col" ] && _vm_deleted_sel="CASE WHEN $_vm_deleted_col IS NOT NULL THEN 1 ELSE 0 END"
    local n_live=0 n_live_discovery_ok=1
    local _n_live_raw
    _n_live_raw="$(sqlite3 -readonly "$snap" \
        "SELECT COUNT(*) FROM ZCLOUDRECORDING;" 2>/dev/null)"
    case "${_n_live_raw:-}" in
        ''|*[!0-9]*) n_live=0; n_live_discovery_ok=0 ;;
        *) n_live=$_n_live_raw ;;
    esac
    [ "$n_live_discovery_ok" = "0" ] && \
        log_warn "Voice Memos live-recording count query failed — the drift check will surface this as a verification gap."
    local _disc_msg="Found $n_live $(_pluralize "$n_live" recording)"
    local _disc_extras=""
    if [ -n "$_vm_transcript_col" ]; then
        local _n_transcribed
        _n_transcribed="$(sqlite3 -readonly "$snap" \
            "SELECT COUNT(*) FROM ZCLOUDRECORDING
             WHERE COALESCE($_vm_transcript_col, '') != '';" 2>/dev/null)"
        case "${_n_transcribed:-0}" in
            ''|*[!0-9]*) : ;;
            *) [ "$_n_transcribed" -gt 0 ] && {
                   [ -n "$_disc_extras" ] && _disc_extras="$_disc_extras, "
                   _disc_extras="${_disc_extras}${_n_transcribed} transcribed"
               } ;;
        esac
    fi
    if [ "${_VM_HAS_FOLDERS:-0}" = "1" ]; then
        local _n_folders
        _n_folders="$(sqlite3 -readonly "$snap" \
            "SELECT COUNT(*) FROM ZFOLDER;" 2>/dev/null)"
        case "${_n_folders:-0}" in
            ''|*[!0-9]*) : ;;
            *) [ "$_n_folders" -gt 0 ] && {
                   [ -n "$_disc_extras" ] && _disc_extras="$_disc_extras, "
                   _disc_extras="${_disc_extras}${_n_folders} $(_pluralize "$_n_folders" folder)"
               } ;;
        esac
    fi
    [ -n "$_disc_extras" ] && _disc_msg="$_disc_msg ($_disc_extras)"
    log_info "$_disc_msg, starting main extraction..."
    local _vm_manifest="$out_root/Voice Memos.csv"
    {
        printf '%s,%s,%s,%s,%s,%s' \
            "$(csv_field "Filename")" \
            "$(csv_field "Folder")" \
            "$(csv_field "Created")" \
            "$(csv_field "Duration (s)")" \
            "$(csv_field "Trimmed")" \
            "$(csv_field "Transcribed")"
        [ -n "$_vm_favorite_col" ] && printf ',%s' "$(csv_field "Favorite")"
        printf ',%s\r\n' "$(csv_field "UUID")"
    } > "$_vm_manifest" 2>/dev/null || note_incomplete "$out_root" "Voice Memos.csv header" \
        "writing the Voice Memos.csv header row failed (disk full / read-only output volume) — the manifest may be missing its header"
    local _vm_index="$SCRATCH_DIR/vm_index.tsv"
    : > "$_vm_index" 2>/dev/null || true
    local _pt_last=0 _pt_inline=0
    local n_total=0 n_written=0 n_rd=0 n_skipped_null_path=0 n_skipped_missing_file=0 n_copy_failed=0 _pk _zdate _label _zpath _transcript _parent _ext _bn _datepfx _name _folder _outsub _dst _touch_t _src_sz _dst_sz
    local _autotitle _duration _mdate _favorite _uuid _row_folder _row_trimmed _row_transcribed _row_dur _row_fav _row_fav_int _trim_start _trim_end _deleted
    while IFS=$'\x1f' read -r _pk _zdate _label _zpath _transcript _parent _trim_start _trim_end \
                            _autotitle _duration _mdate _favorite _uuid _deleted; do
        n_total=$((n_total + 1))
        _progress_tick "$n_total" "$n_live" "recordings processed"
        if [ -z "$_zpath" ]; then
            n_skipped_null_path=$((n_skipped_null_path + 1))
            continue
        fi
        case "$_zpath" in
            /*) : ;;
            *)  _zpath="$_VM_RECORDINGS_DIR/$_zpath" ;;
        esac
        if [ ! -f "$_zpath" ] || is_dataless "$_zpath"; then
            n_skipped_missing_file=$((n_skipped_missing_file + 1))
            printf '%s\x1f%s\x1f%s\n' "$_label" "$_zdate" "$_uuid" >> "$_cloudonly_file"
            continue
        fi
        _bn="${_zpath##*/}"
        _ext="${_bn##*.}"
        case "$_ext" in *\ *|''|"$_bn") _ext="m4a" ;; esac
        if [ -n "$_label" ]; then
            _name="$(_sanitize_name "$_label")"
            [ -z "$_name" ] && _name="Recording"
        elif [ -n "${_autotitle:-}" ]; then
            _name="$(_sanitize_name "$_autotitle")"
            [ -z "$_name" ] && _name="Recording"
        else
            _name="Recording"
        fi
        _datepfx="$(_format_cd_date_prefix "$_zdate")"
        if [ -n "$_datepfx" ]; then
            _name="${_datepfx}_${_name}"
        fi
        _folder=""
        if [ "$_VM_HAS_FOLDERS" -eq 1 ]; then
            local _vf_ref="_vf_${_pk}"
            _folder="${!_vf_ref:-}"
        fi
        local _vm_path_safe="" _vm_comp _vm_safe_comp _vm_old_ifs _vm_had_f
        if [ -n "$_folder" ]; then
            _vm_old_ifs="$IFS"
            case $- in *f*) _vm_had_f=1 ;; *) _vm_had_f=0 ;; esac
            IFS='/'
            set -f
            for _vm_comp in $_folder; do
                set +f
                _vm_safe_comp="$(_sanitize_name "$_vm_comp")"
                if [ -z "$_vm_safe_comp" ]; then
                    _vm_safe_comp="_unnamed_"
                fi
                if [ -z "$_vm_path_safe" ]; then
                    _vm_path_safe="$_vm_safe_comp"
                else
                    _vm_path_safe="$_vm_path_safe/$_vm_safe_comp"
                fi
                set -f
            done
            [ "$_vm_had_f" -eq 0 ] && set +f
            IFS="$_vm_old_ifs"
            case "$_vm_path_safe" in
                "Recently Deleted"|"Recently Deleted/"*)
                    _vm_path_safe="Recently Deleted (folder)${_vm_path_safe#Recently Deleted}" ;;
            esac
            if [ -n "$_vm_path_safe" ]; then
                _outsub="$out_root/$_vm_path_safe"
                [ -d "$_outsub" ] || mkdir -p "$_outsub" 2>/dev/null
            else
                _outsub="$out_root"
            fi
        else
            _outsub="$out_root"
        fi
        if [ -n "$_vm_deleted_col" ] && [ "${_deleted:-0}" = "1" ]; then
            _outsub="$out_root/Recently Deleted"
            _vm_path_safe="Recently Deleted"
            [ -d "$_outsub" ] || mkdir -p "$_outsub" 2>/dev/null
        fi
        _dst="$(_unique_path "$_outsub/$_name.$_ext")"
        if ditto -- "$_zpath" "$_dst" 2>/dev/null; then
            _src_sz=$(stat -f%z "$_zpath" 2>/dev/null || printf 0)
            _dst_sz=$(stat -f%z "$_dst" 2>/dev/null || printf 0)
            case "$_src_sz" in ''|*[!0-9]*) _src_sz=0 ;; esac
            case "$_dst_sz" in ''|*[!0-9]*) _dst_sz=0 ;; esac
            if [ "$_src_sz" = "$_dst_sz" ]; then
                local _vm_mtime_src="$_zdate"
                if [ -n "$_vm_mdate_col" ] && [ -n "${_mdate:-}" ] \
                   && [ "$_mdate" != "0" ]; then
                    _vm_mtime_src="$_mdate"
                fi
                _touch_t="$(_format_touch_t "$(_cd_ts_to_unix "$_vm_mtime_src")")"
                _apply_touch_t "$_touch_t" "$_dst"
                if [ -n "$_vm_parent_col" ] && [ -n "${_parent:-}" ] \
                   && [ "$_parent" != "0" ] && [ "$_parent" != "" ]; then
                    local _trim_dst="${_dst%.*}_trimmed.${_dst##*.}"
                    _trim_dst="$(_unique_path "$_trim_dst")"
                    if mv -- "$_dst" "$_trim_dst" 2>/dev/null; then
                        _dst="$_trim_dst"
                    else
                        log_warn "Could not add the _trimmed marker to ${_dst##*/} (rename failed) — exported under its original name."
                    fi
                fi
                local _trim_header=""
                if [ -n "$_vm_trim_start_col" ] && [ -n "$_vm_trim_end_col" ] \
                   && [ -n "$_vm_parent_col" ] && [ -n "${_parent:-}" ] \
                   && [ "$_parent" != "0" ] && [ "$_parent" != "" ] \
                   && [ -n "${_trim_start:-}" ] && [ -n "${_trim_end:-}" ]; then
                    case "$_trim_start" in
                        ''|*[!0-9.]*) : ;;
                        *)
                            case "$_trim_end" in
                                ''|*[!0-9.]*) : ;;
                                *) _trim_header="[Trimmed: ${_trim_start}s - ${_trim_end}s]" ;;
                            esac
                        ;;
                    esac
                fi
                if [ -n "$_vm_transcript_col" ] && [ -n "${_transcript:-}" ]; then
                    local _txt="${_dst%.*}.txt"
                    {
                        [ -n "$_trim_header" ] && printf '%s\n\n' "$_trim_header"
                        printf '%s\n' "$_transcript"
                    } > "$_txt" 2>/dev/null || true
                    _apply_touch_t "$_touch_t" "$_txt"
                elif [ -n "$_trim_header" ]; then
                    local _txt="${_dst%.*}.txt"
                    printf '%s\n' "$_trim_header" > "$_txt" 2>/dev/null || true
                    _apply_touch_t "$_touch_t" "$_txt"
                fi
                n_written=$((n_written + 1))
                [ -n "$_vm_deleted_col" ] && [ "${_deleted:-0}" = "1" ] && \
                    n_rd=$((n_rd + 1))
                _row_folder="${_vm_path_safe:-}"
                _row_trimmed="no"
                if [ -n "$_vm_parent_col" ] && [ -n "${_parent:-}" ] \
                   && [ "$_parent" != "0" ] && [ "$_parent" != "" ]; then
                    _row_trimmed="yes"
                fi
                _row_transcribed="no"
                [ -n "$_vm_transcript_col" ] && [ -n "${_transcript:-}" ] && \
                    _row_transcribed="yes"
                _row_dur=""
                if [ -n "$_vm_duration_col" ] && [ -n "${_duration:-}" ]; then
                    case "$_duration" in
                        ''|*[!0-9.]*) _row_dur="" ;;
                        *) _row_dur="$_duration" ;;
                    esac
                fi
                _row_fav="no"
                case "${_favorite:-0}" in
                    *[!0-9.]*) _row_fav="no" ;;
                    *)
                        _row_fav_int="${_favorite%%.*}"
                        local _row_fav_frac=""
                        case "$_favorite" in
                            *.*) _row_fav_frac="${_favorite#*.}" ;;
                        esac
                        case "${_row_fav_int}${_row_fav_frac}" in
                            *[!0]*) _row_fav="yes" ;;
                            *)      _row_fav="no" ;;
                        esac
                        ;;
                esac
                {
                    printf '%s,%s,%s,%s,%s,%s' \
                        "$(csv_field "${_dst##*/}")" \
                        "$(csv_field "$_row_folder")" \
                        "$(csv_field "$_datepfx")" \
                        "$(csv_field "$_row_dur")" \
                        "$(csv_field "$_row_trimmed")" \
                        "$(csv_field "$_row_transcribed")"
                    [ -n "$_vm_favorite_col" ] && printf ',%s' "$(csv_field "$_row_fav")"
                    printf ',%s\r\n' "$(csv_field "${_uuid:-}")"
                } >> "$_vm_manifest" 2>/dev/null || true
                printf '%s\x1f%s\x1f%s\x1f%s\x1f%s\x1f%s\n' \
                    "${_dst#"$out_root/"}" "$_datepfx" "$_row_folder" \
                    "$_row_dur" "$_row_transcribed" "$_row_fav" \
                    >> "$_vm_index" 2>/dev/null || true
            else
                rm -f -- "$_dst" 2>/dev/null   # reap the torn partial (matches the bulk-copy fallback's reap)
                log_warn "Partial copy (size mismatch — truncated write / unreadable source): ${_zpath##*/} → ${_dst##*/}"
                n_copy_failed=$((n_copy_failed + 1))
            fi
        else
            rm -f -- "$_dst" 2>/dev/null   # reap any torn partial
            log_warn "copy failed: ${_zpath##*/}"
            n_copy_failed=$((n_copy_failed + 1))
        fi
    done < <(sqlite3 -readonly -separator $'\x1f' "$snap" \
        "SELECT Z_PK,
                COALESCE(ZDATE, ''),
                $(_sql_tsv_safe "ZCUSTOMLABEL"),
                $(_sql_tsv_safe "ZPATH"),
                $_vm_transcript_sel,
                $_vm_parent_sel,
                $_vm_trim_start_sel,
                $_vm_trim_end_sel,
                $_vm_autotitle_sel,
                $_vm_duration_sel,
                $_vm_mdate_sel,
                $_vm_favorite_sel,
                $(_sql_tsv_safe "COALESCE(ZUNIQUEID, '')"),
                $_vm_deleted_sel
         FROM ZCLOUDRECORDING
         ORDER BY ZDATE, Z_PK;" 2>/dev/null)
    _progress_end
    if [ "$n_total" -eq 0 ]; then
        if [ "$n_live_discovery_ok" = "1" ] && [ "${n_live:-0}" -eq 0 ]; then
            rm -f -- "$_vm_manifest" 2>/dev/null || true
            cleanup_empty_dirs "$out_root"
            report_empty_source "recordings" "Voice Memos"
        else
            log_warn "Voice Memos: no recordings were exported but completeness is unverifiable (discovery COUNT failed, or reported recordings the per-recording query could not read) — marking INCOMPLETE."
            note_incomplete "$out_root" "Voice Memos discovery" \
                "no per-recording rows were exported, but the recording count could not be confirmed zero (the discovery COUNT(*) query failed, or it reported N>0 while the per-recording SELECT produced nothing). Recordings may exist on this Mac but were not exported. Re-run after confirming the database is intact."
        fi
    fi
    log_info "Cloud-only recordings report..."
    if [ "$n_skipped_missing_file" -gt 0 ]; then
        local _co_label _co_created _co_uuid _co_created_h _co_line
        {
            printf '# Sections below list recovered recording labels with\n'
            printf '# their UUID and creation date so same-labeled\n'
            printf '# recordings remain distinguishable.\n\n'
            printf '[Recordings]\n'
            while IFS=$'\x1f' read -r _co_label _co_created _co_uuid; do
                [ -z "$_co_label" ] && _co_label="Recording"
                _co_created_h="$(_format_cd_date_prefix "$_co_created")"
                _co_line="$_co_label"
                [ -n "$_co_created_h" ] && _co_line="$_co_line | created: $_co_created_h"
                [ -n "$_co_uuid" ]      && _co_line="$_co_line | uuid: $_co_uuid"
                printf '%s\n' "$_co_line"
            done < "$_cloudonly_file" | LC_ALL=C sort -u
        } | _write_skipped_report "$out_root" "Voice Memos recordings" \
                "$n_skipped_missing_file" "$n_total" \
                "open Voice Memos.app and right-click each cloud-only recording > Download Now"
    fi
    if [ "$n_skipped_null_path" -gt 0 ]; then
        log_warn "$n_skipped_null_path $(_pluralize "$n_skipped_null_path" recording) had no ZPATH in the database"
        note_incomplete "$out_root" "$n_skipped_null_path voice $(_pluralize "$n_skipped_null_path" recording)" \
            "these recordings have a database row but no file path (ZPATH) — they could not be located and are not in the export"
    fi
    if [ "$n_copy_failed" -gt 0 ]; then
        log_warn "$n_copy_failed $(_pluralize "$n_copy_failed" recording) failed to copy"
        note_incomplete "$out_root" "$n_copy_failed voice $(_pluralize "$n_copy_failed" recording) failed to copy" \
            "the recording exists in the database and on disk but the file copy failed (permission denied, ENOSPC, collision, or an unreadable source) — these recordings are not in the export"
    fi
    [ "$n_rd" -gt 0 ] && \
        log_info "Exported $n_rd recently-deleted $(_pluralize "$n_rd" recording) to Recently Deleted/ — review and discard if not needed."
    log_info "Cleanup and sanity check..."
    local _vcp_n_live="$n_live"
    [ "$n_live_discovery_ok" = "0" ] && _vcp_n_live=""
    validate_count_parity "$_vcp_n_live" \
        $((n_written + n_skipped_null_path + n_skipped_missing_file + n_copy_failed)) \
        "Recording" "$out_root"
    if [ "$n_written" -gt 0 ]; then
        validate_csv_rfc4180 "$_vm_manifest"
    else
        rm -f -- "$_vm_manifest" 2>/dev/null || true
    fi
    if [ "$n_written" -eq 0 ]; then
        if ! report_have_skipped "$out_root"; then
            cleanup_empty_dirs "$out_root"
            log_warn "No recordings could be exported"
            log_info "If Voice Memos is in use on another Apple device, this may be an iCloud-sync gap — open Voice Memos.app once to trigger sync, then re-run."
        elif report_have_incomplete "$out_root"; then
            find "$out_root" -mindepth 1 -type d -empty -delete 2>/dev/null || true
            log_warn "Voice Memos: nothing exported — $n_skipped_missing_file $(_pluralize "$n_skipped_missing_file" recording) cloud-only and an earlier step could not complete$(_disclosure_pointer "Voice Memos/_incomplete.txt")."
        else
            find "$out_root" -mindepth 1 -type d -empty -delete 2>/dev/null || true
            log_ok "Wrote Voice Memos/ (0 $(_pluralize 0 recording) — all $n_skipped_missing_file $(_pluralize "$n_skipped_missing_file" recording) are cloud-only)$(_disclosure_pointer "Voice Memos/_skipped.txt")"
        fi
    else
        find "$out_root" -mindepth 1 -type d -empty -delete 2>/dev/null || true
        local _vm_have_index=0
        if [ -s "$_vm_index" ]; then
            _vm_emit_index "$_vm_index" "$n_written" "$out_root"
            validate_html_structure "$out_root/index.html"
            [ -s "$out_root/index.html" ] && _vm_have_index=1
        fi
        local _vm_stat="$n_written $(_pluralize "$n_written" recording)"
        [ "$_vm_have_index" -eq 1 ] && _vm_stat="$_vm_stat + index.html"
        if [ "$n_skipped_missing_file" -gt 0 ]; then
            _vm_stat="$_vm_stat, $n_skipped_missing_file cloud-only$(_disclosure_pointer "Voice Memos/_skipped.txt")"
        fi
        _vm_stat="$_vm_stat, $(_dir_size_human "$out_root")"
        log_ok "Wrote Voice Memos/ ($_vm_stat)"
    fi
    mark_success
    sweep_junk_files "$out_root"
    print_summary
    if [ "$ERR_COUNT" -gt 0 ]; then exit 1; fi
    exit 0
}

declare -F wrapper_leaf_cleanup_hook >/dev/null 2>&1 \
    && eval 'leaf_cleanup_hook() { wrapper_leaf_cleanup_hook; }'
declare -F wrapper_info_handler_hook >/dev/null 2>&1 \
    && eval 'info_handler_hook() { wrapper_info_handler_hook; }'
wrapper_main "$@"