=begin rakudoc

=TITLE Developing Qwiratry

=SUBTITLE Notes for contributors and people working on Qwiratry itself

=head1 Overview

This document collects the README material that is mainly useful when developing
Qwiratry rather than simply using it.

=head1 Source Installation

Install from a checkout when working on Qwiratry itself:

=begin code :lang<shell>
git clone <repository-url>
cd raku-Qwiratry
zef install .
=end code

Qwiratry currently needs RakuAST support when running:

=begin code :lang<shell>
export RAKUDO_RAKUAST=1
=end code

=head1 Architecture

Qwiratry is built around five core architectural groups:

=item B<Query group>: declarative, immutable query specifications; this is what to find.

=item B<Walker group>: traversal strategies and execution plans; this is how to walk the data.

=item B<Strategy group>: element-level behavior and reusable processing logic.

=item B<Transformer group>: declarative data transformations using molds.

=item B<Per-traversal group>: mutable state management with C<Context> and incremental result streaming with C<QueryIterator>.

The architecture enables:

=item Multiple traversal strategies for the same query.

=item Query optimization before execution.

=item Streaming results via lazy iterators.

=item Composite execution across multiple domains.

=item Pluggable strategies for element processing.

=head1 Requirements

=item Raku 6.e or later.

=item C<Slangify> (Mold slang and L<Qwiratry::Query::Slang::Topic>).

=item C<Implementation::Loader> v0.0.7 or later.

=item C<RAKUDO_RAKUAST=1> in the environment (RakuAST-only; legacy grammar unsupported for query/Topic slang).

=head1 Testing

Run the test suite with C<zef> from the repository root:

=begin code :lang<shell>
zef test .
=end code

=head1 Developer Documentation

=item L<Specification|Specification>: complete architecture specification.

=item L<Operators|../Operators>: query operator reference.

=item C<kitty-specs/>: detailed feature specifications and design documents.

=item C<t/examples/>: example code and usage patterns.

=item L<Extending Qwiratry|../Extending/index>: extension guides for formats, locations, walkers, strategies, transformers, and other extension points.

=item L<Required Raku Modifications|Required-Raku-Modifications>: possible Raku language and runtime changes that would better support data-oriented programming.

=item L<Streaming Qwiratry Proposal|Streaming-Qwiratry-Proposal>: proposed interfaces for streaming-capable parsers, renderers, sources, and destinations.

=item L<Qwiratry TOP Plan|Qwiratry-TOP-Plan>: design note for rebuilding Raku TOP on Qwiratry.

=item L<Qwiratry TOP Prerequisites|Qwiratry-TOP-Prerequisites>: normative spec for streaming-shaped Location I/O and C<TypedIterator> (core foundations before TOP).

=item L<Qwiratry TOP Basics|Qwiratry-TOP-Basics>: Relation, Memory, Postgres, and Tables (TOP layer; plan §4.1–4.2).

=item L<Changelog|Changelog>: user-visible changes by release.

=item L<Release Process|Release-Process>: prep, fez publishing, and GitHub release steps.

=end rakudoc
