docs: add initial array adr

[neilcampbell]

Collaboration with @daniel-makerx to create an Array ADR based on the discussions we've had thus far.

[github-actions]

Coverage Report

File	Stmts	Miss	Cover	Missing
src/puya_lib
arc4.py	126	126	0%	1–332
bytes.py	9	9	0%	1–15
util.py	16	16	0%	1–33
src/puya
__main__.py	34	34	0%	1–57
arc32.py	71	2	97%	78, 104
arc56.py	78	2	97%	279, 285
artifact_sorter.py	53	1	98%	84
compile.py	160	8	95%	91–92, 134–137, 157–160, 316, 364
context.py	31	1	97%	35
errors.py	35	8	77%	40–42, 44–46, 50–51
log.py	235	61	74%	26–29, 45–48, 82, 92–93, 98–105, 120–128, 150, 184–185, 227–229, 232–234, 236, 249–258, 283, 289, 294, 363–364, 373, 401–403, 416–430
main.py	36	36	0%	1–49
parse.py	87	5	94%	31, 40, 50, 56, 87
utils.py	201	18	91%	50, 67–68, 77–78, 86–87, 177, 195–197, 204, 212, 226, 249, 251, 274, 309
src/puya/awst
function_traverser.py	292	3	99%	76, 372, 378
nodes.py	995	40	96%	100, 104–107, 147, 151–154, 365, 561, 577, 611, 652, 681–682, 732, 759–760, 908, 930, 962, 988, 993, 1148, 1233, 1249, 1298, 1375, 1456, 1510, 1514, 1637, 1782, 1787, 1792, 1800, 1805, 1810
serialize.py	68	11	84%	24, 84–89, 95–98
to_code_visitor.py	434	12	97%	131, 242, 279, 325, 579, 586–589, 619, 647, 651
txn_fields.py	98	1	99%	48
wtypes.py	330	18	95%	174, 178–181, 195–196, 200, 230, 243, 254, 259–260, 294, 332, 346, 396, 519
src/puya/awst/validation
arc4_copy.py	113	1	99%	38
base_invoker.py	47	4	91%	55, 62, 72–76
immutable.py	31	2	94%	26, 34
inner_transactions.py	187	1	99%	161
labels.py	30	8	73%	25–27, 32, 36–41
scratch_slots.py	38	4	89%	18, 32, 47, 49
src/puya/ir
arc4_router.py	281	19	93%	100, 163, 219, 299, 347, 419, 432, 490–491, 503, 508, 513, 518, 523, 528, 548–552, 685, 722
avm_ops.py	323	1	99%	46
avm_ops_models.py	50	3	94%	21, 30, 38
context.py	101	8	92%	68, 75, 78, 80, 118–119, 129, 135
main.py	392	14	96%	77–83, 93–99, 125, 138, 166, 544, 777–781
models.py	531	22	96%	74, 182, 189, 338, 409–410, 415, 421–425, 438, 482, 511, 567, 613, 693, 709, 750, 753, 760, 763, 852–853
ssa.py	130	3	98%	51–52, 150
to_text_visitor.py	152	7	95%	123, 212, 219–224
types_.py	101	10	90%	50, 57, 91–95, 116, 152, 157–159
visitor.py	129	17	87%	145, 193, 205, 220, 223, 236, 239, 245, 248, 259, 262, 265, 268, 271, 274, 277, 280
visitor_mutator.py	105	2	98%	174–175
vla.py	72	1	99%	87
src/puya/ir/builder
_utils.py	136	5	96%	229–231, 293–300
arc4.py	500	21	96%	175–180, 479, 482, 540–543, 815–816, 1062, 1086, 1167, 1174, 1210, 1258, 1268, 1323, 1368, 1387, 1407
assignment.py	94	7	93%	100, 115, 189, 208, 225–226, 271
blocks.py	140	7	95%	55, 92–96, 158, 166, 231
bytes.py	64	14	78%	13–45, 129
callsub.py	81	5	94%	32–33, 58, 108–109
flow_control.py	95	1	99%	56
iteration.py	198	5	97%	91–92, 107, 144, 206
itxn.py	323	37	89%	139–140, 142, 156, 164–169, 197, 204, 226–227, 560, 579–597, 666, 670, 684, 693–706
main.py	598	70	88%	127, 267, 271, 276–295, 300–319, 374, 398, 419, 437–438, 440, 448, 490, 577–578, 690, 722, 735–736, 784, 809, 846–848, 859, 924, 1002, 1015, 1056, 1121, 1124, 1132, 1135, 1143, 1174, 1200, 1209, 1333, 1350, 1393–1403
storage.py	83	2	98%	101, 154
src/puya/ir/destructure
coalesce_locals.py	101	19	81%	119, 128–129, 132–135, 138–147, 163–166
parcopy.py	84	2	98%	47, 83
src/puya/ir/optimize
collapse_blocks.py	92	5	95%	65–69
compiled_reference.py	79	5	94%	53, 87, 158–163
control_op_simplification.py	104	7	93%	47–48, 177, 253–260
inner_txn.py	36	1	97%	38
intrinsic_simplification.py	483	31	94%	76, 168–170, 175, 257, 269, 304, 315–316, 340–341, 365, 434, 621, 623, 638, 678, 701, 731, 737, 739, 741, 746, 748, 750, 752, 754, 806–807, 814
main.py	87	2	98%	118–119
src/puya/ir/validation
_base.py	30	1	97%	28
compile_reference_validator.py	20	2	90%	24, 30
min_avm_version_validator.py	15	4	73%	16–20
op_run_mode_validator.py	19	5	74%	19–29
src/puya/mir
aligned_writer.py	63	3	95%	21, 61, 80
builder.py	157	13	92%	71–73, 155, 267–268, 321, 324, 327, 330, 333, 336, 339
models.py	433	6	99%	97, 206, 250, 316, 333, 403
src/puya/mir/stack_allocation
f_stack.py	89	2	98%	23, 70
peephole.py	48	2	96%	47, 49
x_stack.py	205	3	99%	32, 336–340
src/puya/teal
models.py	369	2	99%	383, 444
src/puya/teal/optimize
constant_block.py	104	4	96%	63, 152, 189, 206
peephole.py	127	3	98%	162, 168, 251
repeated_rotations.py	51	1	98%	16
repeated_rotations_search.py	90	6	93%	35, 41–42, 58, 68–69
src/puya/ussemble
assemble.py	171	5	97%	134, 202, 219–220, 260
models.py	25	1	96%	16
op_spec_models.py	22	1	95%	20
src/puyapy
__main__.py	64	17	73%	177, 189–203, 207
client_gen.py	118	11	91%	65–66, 84–88, 92, 205, 212–213, 233
compile.py	150	22	85%	59–68, 82, 164–165, 176, 183–184, 201–211, 221–223, 228, 244
models.py	99	4	96%	65, 77–79
parse.py	180	13	93%	50–51, 87, 159–164, 168, 268, 272–273, 321, 333, 358
template.py	32	8	75%	10–11, 18–19, 27–28, 34, 37
utils.py	21	5	76%	16–17, 25–28
src/puyapy/awst_build
arc4_client.py	104	24	77%	46–50, 58, 70, 76, 80, 109, 115–116, 122, 125, 128, 134, 137, 145, 148, 151, 154, 157, 160, 163, 166, 169, 172
arc4_client_gen.py	132	8	94%	32, 91–92, 102, 104, 119–120, 187
arc4_utils.py	288	47	84%	42, 45–46, 48, 53–60, 78, 89–93, 109, 111, 114–115, 138, 181–183, 192, 197, 202–203, 229, 233, 245, 252, 254, 268–269, 272–276, 281–282, 288–291, 299, 307, 324, 336, 344, 446, 451, 470
base_mypy_visitor.py	127	39	69%	70–76, 94, 102–115, 129, 131, 133, 145, 150, 154, 157, 160, 166, 188, 191, 194, 201, 205, 208, 211, 215, 233, 237, 241, 245, 249, 253, 257, 261, 265, 269, 273, 277, 281
context.py	218	47	78%	55, 58, 68–69, 87–88, 128, 188, 193, 199–203, 207, 210, 219, 221, 224–226, 228, 235, 237, 248–249, 254–256, 259, 274, 286–287, 299, 313, 316–328
contract.py	319	33	90%	128, 179, 192–196, 236, 238, 242, 246, 254, 262, 264, 284, 339, 342, 354, 362, 365, 368, 371, 374, 377, 380, 383, 386, 389, 449–453, 502–506, 586–590, 661, 684
intrinsic_models.py	49	1	98%	55
main.py	36	1	97%	30
module.py	429	59	86%	118, 138, 144–148, 163–164, 171, 180–181, 189–193, 215, 244, 264–265, 276, 298–301, 311–313, 319, 336–339, 352, 386, 393, 415–416, 439–444, 498–499, 527, 538, 541, 547, 553, 563, 569, 572, 584, 587, 610, 630, 635, 639, 648–652, 744, 752, 754
pytypes.py	594	60	90%	87, 97–99, 104, 111, 116–118, 122–124, 151–152, 192, 210–216, 239, 259, 301, 339–341, 370, 436, 445, 464, 484, 506–507, 648–650, 664–665, 732–733, 837, 848–849, 898–899, 904, 957–958, 981–982, 1133–1134, 1158, 1186, 1222–1224, 1264, 1274–1275
subroutine.py	602	52	91%	136, 246, 252, 310–313, 319, 370, 375, 378–384, 475, 495, 650, 652–653, 671, 673, 683–684, 693–694, 698, 719, 785, 792, 812–813, 899, 925–926, 943, 959, 983, 991, 1002, 1028–1031, 1137–1138, 1158, 1168, 1170, 1179, 1197, 1205, 1219, 1222, 1225, 1228, 1231
utils.py	161	24	85%	30, 47–51, 69, 104–105, 107, 151–152, 203, 211, 216, 229–233, 238–241, 250, 254, 262
src/puyapy/awst_build/eb
_base.py	128	18	86%	52, 57–59, 64, 71, 76, 81–83, 142, 153, 183, 188, 193, 198, 209, 223–225
_bytes_backed.py	48	2	96%	30–31
_expect.py	122	21	83%	25, 36, 85–88, 100–103, 106, 158–159, 217–220, 230–233
_literals.py	144	29	80%	43, 72, 91, 120, 137, 151, 155, 159–165, 175–189, 194
_type_registry.py	40	4	90%	251–252, 264–265
utils.py	47	3	94%	28–30, 100
array.py	26	9	65%	23, 28–33, 43, 47
biguint.py	101	6	94%	56, 100, 139, 155–156, 158
binary_bool_op.py	105	3	97%	153, 161, 171
bool.py	55	9	84%	39–43, 59, 70, 83, 97
bytes.py	168	18	89%	103–104, 131–132, 137–138, 144–145, 148, 156, 199, 234, 266, 270, 287–288, 303–304
compiled.py	70	9	87%	86–90, 127–131, 154
conditional_literal.py	134	34	75%	98, 102, 162, 166–169, 178–180, 203–206, 215, 219, 223–226, 241–253, 262–263, 274–277
contracts.py	77	8	90%	55, 61, 63, 73, 99, 109, 111, 116
dict.py	27	5	81%	24, 32–34, 38
ensure_budget.py	31	1	97%	47
interface.py	90	3	97%	314–316, 320
intrinsics.py	97	6	94%	43, 62, 69, 82, 89, 160
log.py	43	4	91%	46–47, 52, 61
logicsig.py	15	1	93%	26
none.py	27	1	96%	38
string.py	144	13	91%	72, 116–117, 136, 141, 184, 191, 195, 207, 281–283, 303
struct.py	16	5	69%	14–16, 25, 29
subroutine.py	80	16	80%	47, 51–54, 69, 72–79, 94, 102–103, 105–108, 113
template_variables.py	37	2	95%	30, 58
tuple.py	339	13	96%	86, 134, 150, 240–241, 253, 346–347, 466, 535, 546–547, 610
uint64.py	108	6	94%	57, 118–119, 167–168, 200
uint64_enums.py	40	2	95%	41, 46
unsigned_builtins.py	155	22	86%	74, 81, 105, 129, 133, 137, 141, 149, 153, 157, 161, 165, 175, 179, 185, 196, 202, 208, 247, 279, 291, 303
src/puyapy/awst_build/eb/arc4
_base.py	92	3	97%	185–188, 199
_utils.py	141	7	95%	119, 127, 138, 178–181, 252, 256
abi_call.py	317	19	94%	118, 124, 145, 215, 228–229, 310, 322, 380, 403, 434, 453–454, 513, 549, 623, 708–709, 726
address.py	73	2	97%	57, 116
bool.py	58	3	95%	42, 87–88
dynamic_array.py	120	9	92%	56, 123–124, 145, 221, 241–242, 245–248
dynamic_bytes.py	68	3	96%	99–101
emit.py	34	1	97%	36
static_array.py	62	1	98%	44
string.py	98	7	93%	54–55, 103, 124, 129–132
struct.py	49	1	98%	49
tuple.py	93	16	83%	45–47, 70, 88–91, 94–95, 134–137, 142, 146–147, 157, 167
ufixed.py	70	2	97%	43, 102
src/puyapy/awst_build/eb/reference_types
account.py	79	2	97%	65, 175
application.py	45	1	98%	40
asset.py	65	1	98%	48
src/puyapy/awst_build/eb/storage
_common.py	69	3	96%	107, 120–121
_storage.py	108	20	81%	58, 66, 70, 74, 78, 82, 86, 90, 94, 104, 108, 112, 116, 122, 133, 139, 145, 157–159
_value_proxy.py	55	7	87%	38, 42, 50, 54, 91, 99, 103
box_map.py	147	1	99%	194
global_state.py	127	6	95%	104–105, 114–115, 164–165
local_state.py	137	11	92%	99–100, 104, 151, 155, 159, 169, 173, 197, 254, 278
src/puyapy/awst_build/eb/transaction
base.py	39	2	95%	23, 43
group.py	53	1	98%	48
inner.py	48	2	96%	91–92
inner_params.py	77	5	94%	64, 74, 78, 138, 140
itxn_args.py	60	1	98%	72
TOTAL	22772	1734	92%

Tests	Skipped	Failures	Errors	Time
834	2 💤	0 ❌	0 🔥	5m 48s ⏱️

[joe-p]

LGTM. Think this is a great encapsulation of the conversation! I have a small suggestion to capture the fact that this decision was made with front-end support in mind.

[SilentRhetoric]

Should this be arr2 = someFunctionThatMutates(arr); if arr is immutable?

[daniel-makerx]

The value assigned to arr is immutable, but the variable arr is not defined as const so can be reassigned like this

[tristanmenzel]

arr is correct here. Being immutable does not prevent reassignment. For example strings and numbers are already immutable. It doesn't prevent you from writing a = a + b to update a.