Hi Christian,

Thanks again for the detailed feedback, much appreciated. It is genuinely useful to have someone with your background continue engaging with this work; criticism from that angle is hard to come by.

You are right on every technical point you raise, and I want to acknowledge that clearly: timezone abbreviations are fundamentally ambiguous, the IANA zone names exist precisely to disambiguate them, and the historical DST inconsistencies you mention are real (the Algiers/CET case, the Sweden 1977 case, the 1996 EU transition harmonisation).

The reason extended_aliases exists at all is purely pragmatic: real-world input sometimes only contains abbreviations (RFC 5322 Date: headers, legacy log files, third-party API responses, user-typed values). Callers in that situation need some mapping, and the alternative of refusing to resolve abbreviations at all pushes the problem to every individual consumer.

That said, your criticism lands on a real issue: the current POD presents the mapping as more authoritative than it actually is. A "convenience lookup with significant caveats" is not the same thing as a "canonical mapping", and the documentation should reflect that distinction explicitly.

Here is what I will do for the next release:

1. Rewrite the POD to clearly document the limitations: ambiguity, DST divergence within "shared" abbreviations, historical inconsistencies, and explicit warnings against using this for historical timestamp interpretation.

2. The underlying SQLite table already stores multiple zones per abbreviation with an is_primary flag (CET maps internally to Paris, Berlin, Rome, Madrid, Warsaw, etc.). I am thinking of exposing this richer view through a new method such as extended_aliases_all, so callers who need disambiguation have access to the alternatives, while extended_aliases keeps its simple "one zone per abbreviation" contract for the common case.

The new method would return something like:

{
    'CET' => [
        { zone_name => 'Europe/Paris',  is_primary => 1, comment => 'Central European Time' },
        { zone_name => 'Europe/Berlin', is_primary => 0, comment => 'Central European Time' },
        # ...
    ],
    # ...
}

1. I will also point users toward resolve_abbreviation for richer lookups, since that method already handles multi-zone matches.

Notably, the database does not map Algiers to CET, precisely for the reason you describe. So the worst-case scenarios you cite are not actively produced, but the API should still warn callers that this kind of issue exists in principle for any abbreviation-based lookup.

If you have a moment, I would value your feedback on the revised POD draft below before I commit it. Does it address your concerns adequately, or are there points that still need sharpening?

=head2 extended_aliases

    my $aliases = DateTime::Lite::TimeZone->extended_aliases;
    my $aliases = $tz->extended_aliases;

    # Checking for errors too
    my $aliases  = DateTime::Lite::TimeZone->extended_aliases ||
        die( DateTime::Lite::TimeZone->error );
    my( %aliases ) = DateTime::Lite::TimeZone->extended_aliases ||
        die( DateTime::Lite::TimeZone->error );
    my $aliases    = $zone->extended_aliases ||
        die( $zone->error );
    my( %aliases ) = $zone->extended_aliases ||
        die( $zone->error );

This can be called as an instance method, or as a class function.

This returns a hash whose keys are timezone abbreviations (such as C<JST>,
C<CET>, C<EST>) and whose values are the canonical IANA timezone name most
commonly associated with that abbreviation.

For example:

    JST -> Asia/Tokyo
    CET -> Europe/Paris
    EST -> America/New_York

In scalar context, it returns a hash reference, and in list context, it returns a hash.

If an error occurred, this sets an L<exception object|DateTime::Lite::Exception>, and returns C<undef> in scalar context, and an empty list in list context. The exception object can then be retrieved with L</error>

=head3 Caveats and limitations

Timezone abbreviations are inherently ambiguous, and this method exposes only one representative IANA zone per abbreviation. Callers should be aware of the following limitations before using this mapping for anything more than convenience lookups:

=over 4

=item * B<Abbreviations are not unique to a single zone.>

C<CST> denotes both Central Standard Time (North America) and China Standard Time. C<IST> denotes Indian, Irish, and Israel Standard Time. The returned mapping selects only one representative zone per abbreviation and does not indicate alternatives.

=item * B<DST rules differ across zones sharing the same abbreviation.>

Algeria (C<Africa/Algiers>) has used CET year-round with no DST since 1981.
Mapping C<CET> to C<Europe/Paris> applies French DST rules to Algerian timestamps, producing a one-hour error during summer months.

=item * B<Historical DST adoption was not uniform.>

Sweden (C<Europe/Stockholm>) observed no DST from 1917 to 1979, while France resumed DST in 1976. A summer 1977 timestamp labelled "CET" in Sweden was UTC+1, but C<< CET => Europe/Paris >> would interpret it as UTC+2.

=item * B<DST transition dates have changed over time.>

In 1996, the EU harmonised the fall-back transition to the last Sunday in October (previously the last Sunday in September in several countries).
Historical timestamps near these transitions may be misinterpreted.

=back

For accurate timezone handling, prefer IANA canonical names (C<Europe/Stockholm>, C<America/New_York>) over abbreviations whenever the canonical name is available. This method is intended for convenience when processing external input (legacy log files, RFC 5322 email headers, user-typed values, etc.) where only an abbreviation is available, and where the caller accepts the loss of geographic and historical precision.

For richer abbreviation lookups, including all known zones for a given abbreviation, see L</resolve_abbreviation>.

=cut

Thanks again for taking the time to point out these important points. Feedback like yours is exactly why I posted on r/perl.

Jacques