=begin rakudoc

=TITLE Adjusting Transformers

=SUBTITLE Extending mold execution, copying, rewriting, and transformer behavior

=head1 Overview

Transformers apply molds to data.

Use this extension point when changing how transformation is performed rather
than how data is walked, parsed, rendered, sourced, or stored.

To adjust transformer behavior:

=item 1. B<Setup>: decide whether the extension changes mold execution, copying, rewriting, wrappers, or validation.

=item 2. B<Molds>: preserve mold ordering and mold control behavior.

=item 3. B<Copying>: use Qwiratry's copy service for copy semantics.

=item 4. B<Rewriting>: use C<TreeRewrite> only for intentional input mutation.

=item 5. B<Wrappers>: add cross-cutting behavior around transformer or mold execution.

=item 6. B<Testing>: test callable transformers, ordering, wrappers, copying, rewriting, and type checks.

=head1 Setup

Use transformer extensions when the extension changes transformation behavior.
Do not use transformer extensions to support a new external data representation;
use a format. Do not use transformer extensions to traverse a new data model;
use a walker. Do not use transformer extensions to connect to a database or API;
use a source/destination extension.

=head1 Molds

=head2 Mold Ordering

Molds are ordered by priority, specificity, and tie-breaker. Transformer
extensions that add ordering metadata or produce molds programmatically must
preserve deterministic ordering.

If ordering cannot be made deterministic, Qwiratry throws
C<X::Qwiratry::MoldOrderingConflict>. This usually means two or more
molds have equal priority, specificity, and tie-breaker values. Extensions
that generate molds or add ordering metadata should preserve this failure
mode.

=head2 Mold Control

C<Qwiratry::Mold::NextMold> lets a mold decline the current match and
continue with the next matching mold.

=head1 Copying

Use C<Qwiratry::Transformer::Copy> when an extension needs to clone input before
rewriting or needs a standard way to copy positional and associative structures.

=begin code :lang<raku>
my $copy-service = Qwiratry::Transformer::Copy.instance;
my $clone = $copy-service.deepcopy($node);
=end code

=head1 Rewriting

C<TreeRewrite> marks a transformer as able to mutate or replace nodes during
transformation. Use this only when the extension intentionally changes the input
tree or node graph.

=begin code :lang<raku>
use Qwiratry::Transformer::TreeRewrite;

transformer MyRewrite does TreeRewrite {
    mold TOP do {
        make $_;
    }
}
=end code

=head1 Wrappers

Transformer slang supports wrappers for transformer execution, mold
matching, and mold actions. Use wrappers when the extension needs to add
cross-cutting behavior around existing molds rather than replacing the
mold system.

=head1 Testing

Add tests that prove:

=item Callable transformers still work.

=item Mold ordering remains deterministic.

=item Wrapper behavior applies at the intended layer.

=item Copy and rewrite behavior does not mutate data accidentally.

=item C<X::Qwiratry::MoldOrderingConflict> is thrown for unresolved ordering conflicts.

=item C<X::Qwiratry::TypeCheck> is thrown for result type constraint failures.

=head1 Reference Material

=head2 Main Types

=item C<Transformer>

Base class for transformer objects and the runtime behavior behind the
C<transformer> declarator.

=item C<Qwiratry::Mold::Mold>

Runtime representation of one mold rule: match logic, action logic, and
ordering metadata.

=item C<Qwiratry::Mold::NextMold>

Control tool for declining the current mold and continuing with the next
matching mold.

=item C<Qwiratry::Transformer::Copy>

Copy service for shallow and deep copying transformable nodes.

=item C<Qwiratry::Transformer::TreeRewrite::TreeRewrite>

Marker role for transformers that rewrite input structures in place.

=item C<X::Qwiratry::MoldOrderingConflict>

Thrown when mold order cannot be made deterministic.

=item C<X::Qwiratry::TypeCheck>

Thrown when a transformer or mold result does not match a declared return
type constraint.

=end rakudoc
