8. Data Structures (pocket version)

TL;DR (5 lines)

Data structures are architectural choices.
Use cases matter more than names.
Aggregation flows are better teaching units than isolated declarations.
Broken examples should show a mismatched shape.
Container choice should remain visible in the code story.

Concrete Problem

Readers often see containers as names only, not as data-shape decisions embedded in a complete flow.

Coherent example

space demo/collections

form Metrics {
  count: int
  total: int
}

proc absorb(values: list[int]) -> Metrics {
  let count: int = 0
  let total: int = 0
  for value in values {
    set count = count + 1
    set total = total + value
  }
  give Metrics(count, total)
}

Global explanation

Collections pages are useful only when they explain why a shape exists. The example shows aggregation as a real need for a container-like surface instead of presenting structures as vocabulary alone.

Short exercise

Replace the single summary form with two grouped buckets and explain why the new shape is justified.

Next best action

Keep the example small, reproduce it locally, then continue to the full chapter if you need the broader context.