feat: Added "internals" MDBook

[RobertJacobsonCDC]

The PR adds an in-repo home for developer-oriented notes and documentation about ixa internals.

• I moved some content from the GitHub repo wiki and deleted obsolete wiki content.
• Organized as an MDBook
• Added a docs:internals mise task but left existing mise run docs behavior the same.

[RobertJacobsonCDC]

This is also a natural home for diagrams that aren't (yet) used in the Ixa Book itself.

[github-actions]

Benchmark Results

Hyperfine

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
large_sir::baseline	2.8 ± 0.0	2.8	3.0	1.00
large_sir::entities	6.1 ± 0.1	6.0	6.4	2.15 ± 0.05

Criterion

Regressions (slower)

Group	Bench	Param	Change	CI Lower	CI Upper
large_dataset	bench_query_population_property_entities		22.754%	20.617%	24.904%
large_dataset	bench_query_population_multi_unindexed_entities		13.975%	12.046%	15.892%
counts	concrete_plus_derived_unindexed_entities		11.445%	8.712%	14.302%
examples	example-births-deaths		8.162%	7.424%	8.930%
sampling	count_and_sampling_single_known_length_entities		6.260%	5.709%	6.710%
algorithm_benches	algorithm_sampling_multiple_known_length		4.209%	3.695%	4.780%
sample_entity	sample_entity_multi_property_indexed	1000	4.136%	3.864%	4.537%
sample_entity	sample_entity_multi_property_indexed	100000	3.776%	3.438%	4.144%
sample_entity	sample_entity_multi_property_indexed	10000	3.723%	3.535%	3.915%
counts	single_property_unindexed_entities		2.988%	1.421%	4.666%
algorithm_benches	algorithm_sampling_multiple_l_reservoir		2.195%	1.441%	2.926%
indexing	query_people_multiple_individually_indexed_properties_entities		1.767%	1.637%	1.906%

Improvements (faster)

Group	Bench	Param	Change	CI Lower	CI Upper
indexing	with_query_results_single_indexed_property_entities		-4.561%	-5.034%	-4.246%
indexing	query_people_count_single_indexed_property_entities		-3.640%	-4.067%	-3.295%
counts	reindex_after_adding_more_entities		-3.394%	-3.525%	-3.257%
large_dataset	bench_query_population_derived_property_entities		-3.113%	-4.062%	-2.093%
sampling	sampling_multiple_unindexed_entities		-2.082%	-3.075%	-1.066%
counts	index_after_adding_entities		-2.040%	-2.320%	-1.791%
indexing	with_query_results_indexed_multi-property_entities		-1.538%	-2.037%	-1.095%
sampling	sampling_single_known_length_entities		-1.470%	-1.761%	-1.162%

Unchanged / inconclusive (CI crosses 0%)

Group	Bench	Param	Change	CI Lower	CI Upper
examples	example-basic-infection		2.406%	-2.296%	10.216%
sampling	sampling_single_unindexed_concrete_plus_derived_entities		1.689%	0.116%	3.356%
large_dataset	bench_filter_unindexed_entity		1.348%	-3.302%	6.404%
sample_entity	sample_entity_single_property_unindexed	100000	-1.038%	-1.616%	-0.395%
sampling	sampling_multiple_l_reservoir_entities		1.027%	0.675%	1.594%
sampling	count_and_sampling_single_unindexed_concrete_plus_derived_entiti		0.982%	0.646%	1.332%
sampling	sampling_single_unindexed_entities		0.955%	0.242%	1.705%
large_dataset	bench_query_population_multi_indexed_entities		0.949%	0.580%	1.484%
indexing	query_people_count_multiple_individually_indexed_properties_enti		0.900%	0.578%	1.278%
algorithm_benches	algorithm_sampling_single_known_length		0.773%	-0.058%	1.858%
indexing	with_query_results_multiple_individually_indexed_properties_enti		0.729%	0.420%	1.004%
sample_entity	sample_entity_single_property_unindexed	10000	0.639%	0.141%	1.129%
sample_entity	sample_entity_single_property_indexed	1000	-0.582%	-0.956%	-0.240%
sampling	sampling_single_l_reservoir_entities		-0.501%	-1.131%	-0.102%
counts	multi_property_indexed_entities		-0.485%	-0.771%	-0.058%
sampling	sampling_multiple_known_length_entities		-0.464%	-0.807%	-0.020%
indexing	query_people_single_indexed_property_entities		-0.334%	-0.690%	-0.068%
sample_entity	sample_entity_whole_population	100000	-0.212%	-0.626%	0.079%
sample_entity	sample_entity_single_property_indexed	10000	-0.198%	-0.571%	0.194%
algorithm_benches	algorithm_sampling_single_rand_reservoir		0.194%	-0.040%	0.437%
sample_entity	sample_entity_whole_population	1000	0.191%	-0.470%	0.828%
sample_entity	sample_entity_single_property_indexed	100000	0.188%	-0.430%	1.010%
sample_entity	sample_entity_whole_population	10000	0.181%	-0.025%	0.389%
large_dataset	bench_query_population_indexed_property_entities		-0.167%	-0.601%	0.318%
sample_entity	sample_entity_single_property_unindexed	1000	0.157%	-0.652%	1.152%
indexing	query_people_indexed_multi-property_entities		-0.149%	-0.822%	0.591%
algorithm_benches	algorithm_sampling_single_l_reservoir		-0.127%	-0.342%	0.117%
large_dataset	bench_filter_indexed_entity		-0.122%	-12.338%	13.714%
large_dataset	bench_match_entity		0.119%	-0.291%	0.600%
indexing	query_people_count_indexed_multi-property_entities		-0.101%	-1.244%	0.904%
counts	single_property_indexed_entities		-0.082%	-0.535%	0.357%
counts	multi_property_unindexed_entities		0.075%	-0.220%	0.472%

[github-actions]

Benchmark Results

Hyperfine

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
large_sir::baseline	2.3 ± 0.1	2.3	2.7	1.00
large_sir::entities	4.5 ± 0.1	4.5	4.9	1.95 ± 0.06

Criterion

Regressions (slower)

Group	Bench	Param	Change	CI Lower	CI Upper
large_dataset	bench_query_population_derived_property_entities		3.629%	3.061%	4.181%
sampling	sampling_single_unindexed_entities		3.165%	2.845%	3.456%
sampling	sampling_multiple_unindexed_entities		2.276%	1.966%	2.622%
sampling	sampling_multiple_l_reservoir_entities		2.189%	1.724%	2.768%
algorithm_benches	algorithm_sampling_multiple_known_length		2.005%	1.358%	2.652%
large_dataset	bench_query_population_multi_indexed_entities		1.652%	1.356%	1.909%

Improvements (faster)

Group	Bench	Param	Change	CI Lower	CI Upper
sample_entity	sample_entity_single_property_unindexed	10000	-11.467%	-13.350%	-9.540%
indexing	query_people_indexed_multi-property_entities		-3.219%	-4.480%	-2.015%
indexing	query_people_multiple_individually_indexed_properties_entities		-2.862%	-3.322%	-2.520%
indexing	query_people_single_indexed_property_entities		-1.254%	-1.520%	-1.091%

Unchanged / inconclusive (CI crosses 0%)

Group	Bench	Param	Change	CI Lower	CI Upper
algorithm_benches	algorithm_sampling_single_known_length		-1.316%	-2.395%	-0.440%
sample_entity	sample_entity_multi_property_indexed	1000	1.220%	0.480%	2.285%
indexing	with_query_results_indexed_multi-property_entities		-1.208%	-1.835%	-0.697%
counts	multi_property_unindexed_entities		1.200%	0.402%	2.132%
counts	index_after_adding_entities		-1.101%	-1.242%	-0.932%
indexing	query_people_count_multiple_individually_indexed_properties_enti		-1.047%	-1.258%	-0.843%
sample_entity	sample_entity_single_property_unindexed	1000	-0.989%	-1.703%	-0.348%
sample_entity	sample_entity_single_property_indexed	10000	-0.883%	-1.259%	-0.330%
sampling	sampling_multiple_known_length_entities		0.875%	0.302%	1.482%
counts	reindex_after_adding_more_entities		-0.850%	-1.447%	-0.334%
large_dataset	bench_query_population_property_entities		0.822%	-0.112%	1.974%
indexing	with_query_results_multiple_individually_indexed_properties_enti		0.805%	0.410%	1.360%
sampling	count_and_sampling_single_known_length_entities		0.745%	0.157%	1.377%
counts	multi_property_indexed_entities		-0.669%	-0.915%	-0.336%
sample_entity	sample_entity_single_property_indexed	1000	-0.664%	-1.468%	0.105%
indexing	query_people_count_single_indexed_property_entities		-0.649%	-1.949%	1.291%
algorithm_benches	algorithm_sampling_multiple_l_reservoir		0.630%	0.271%	1.089%
sample_entity	sample_entity_whole_population	1000	-0.624%	-1.385%	0.086%
sample_entity	sample_entity_multi_property_indexed	100000	0.557%	0.051%	0.992%
sampling	sampling_single_known_length_entities		0.522%	0.079%	1.161%
sampling	sampling_single_l_reservoir_entities		0.501%	0.157%	0.789%
sampling	count_and_sampling_single_unindexed_concrete_plus_derived_entiti		-0.500%	-0.691%	-0.294%
large_dataset	bench_match_entity		0.477%	0.181%	0.879%
sample_entity	sample_entity_single_property_unindexed	100000	-0.476%	-1.046%	-0.024%
indexing	query_people_count_indexed_multi-property_entities		-0.429%	-1.057%	0.239%
sample_entity	sample_entity_single_property_indexed	100000	0.416%	-0.739%	1.642%
large_dataset	bench_filter_indexed_entity		-0.349%	-12.857%	13.553%
sample_entity	sample_entity_multi_property_indexed	10000	0.332%	-0.380%	0.972%
algorithm_benches	algorithm_sampling_single_l_reservoir		-0.304%	-0.638%	-0.055%
large_dataset	bench_query_population_multi_unindexed_entities		0.279%	-1.169%	1.763%
algorithm_benches	algorithm_sampling_single_rand_reservoir		0.257%	-0.142%	0.716%
large_dataset	bench_filter_unindexed_entity		-0.231%	-4.655%	4.655%
sample_entity	sample_entity_whole_population	100000	0.210%	-0.211%	0.800%
sampling	sampling_single_unindexed_concrete_plus_derived_entities		-0.174%	-0.502%	0.148%
sample_entity	sample_entity_whole_population	10000	-0.164%	-0.552%	0.370%
examples	example-basic-infection		-0.154%	-1.940%	2.223%
examples	example-births-deaths		0.090%	-0.103%	0.290%
indexing	with_query_results_single_indexed_property_entities		-0.087%	-0.430%	0.395%
counts	single_property_unindexed_entities		0.059%	-0.393%	0.663%
large_dataset	bench_query_population_indexed_property_entities		0.056%	-0.151%	0.309%
counts	single_property_indexed_entities		0.030%	-0.283%	0.472%
counts	concrete_plus_derived_unindexed_entities		0.005%	-0.364%	0.379%

[k88hudson-cfa]

Generally speaking, I think this kind of design documentation is difficult to keep up to date as code evolves but is useful to understand the original intent of the authors if somebody wants to go back in history and figure out why things were implemented a certain way. I'd recommend treating some of this as a series of snapshots (like an Architectural Decision Record or similar), which we could make a section for.

If you intend to keep this up to date, it's not particularly well-suited to being maintained in a collaborative way: breaking it up into sections and having it live closer to the code would be an improvement IMO.