Three Ways to Group: A Design Study of Phase 2's Compute Kernel

Three Ways to Group: A Design Study of Phase 2's Compute Kernel

I designed a weekly-time-summary tool in an earlier piece of work. Its second phase — Compute — takes a flat list of resolved time entries and produces a nested structure of week→day→project→entries with per-group totals plus a project rollup. The design gave Phase 2 a clear contract but deliberately left its internal shape unspecified. Before I build it, I owe myself the practice of weighing how that transformation could be shaped. The choice of shape determines what is easy to verify, what is easy to extend, and where the bugs will hide.

I hold three alternative shapes in my mind. Each is a complete, runnable way to turn the flat list into the nested structure. I will describe each, trace a small concrete input through it, state what it makes easy and what it makes hard, and then judge which best serves the purpose.

---

The Input I Will Trace

Before comparing shapes, I need a concrete input small enough to hold in my head but varied enough to exercise every code path. Here is a flat list of five entries, already resolved by Phase 1 — dates normalised, durations in minutes, projects and tags extracted:

```

E1: 2026-07-13, 45, "client-work", ["meeting"]

E2: 2026-07-13, 30, "client-work", ["email"]

E3: 2026-07-13, 90, "deep-think", ["design"]

E4: 2026-07-14, 60, "client-work", ["meeting"]

E5: 2026-07-14, 25, "admin", []

```

That is two days (Monday and Tuesday of the week starting 2026-07-13), three projects, and one untagged entry. The expected output structure — the contract Phase 3 will read — looks like this, in a rough notation rather than the final data format which Phase 3 owns:

```

week(2026-07-13) {

total_minutes: 250

project_rollup: {

"client-work": 135,

"deep-think": 90,

"admin": 25

}

days: [

day(2026-07-13) {

total_minutes: 165

projects: {

"client-work": { total: 75, entries: [E1, E2] },

"deep-think": { total: 90, entries: [E3] }

}

},

day(2026-07-14) {

total_minutes: 85

projects: {

"client-work": { total: 60, entries: [E4] },

"admin": { total: 25, entries: [E5] }

}

}

]

}

```

The week total of 250 and the project rollup figures are derivable from the day structure, but the design contract asks Phase 2 to compute them explicitly so Phase 3 never has to re-aggregate. That is the output I hold each alternative against.

---

Alternative A: The Single-Pass Builder

Structure. One function receives the flat list. It initialises an empty accumulator — a mutable structure with slots for the week total, the project rollup map, and a list of day buckets. It iterates the entries exactly once. For each entry, it updates the week total, upserts into the project rollup, finds or creates the right day bucket by date, finds or creates the right project bucket within that day, appends the entry, and updates the day and project subtotals. At the end, it returns the fully populated structure.

Trace on the concrete input.

```

Start: acc = { week_total: 0, project_rollup: {}, days: [] }

E1 (client-work, 45, 2026-07-13):

week_total += 45 → 45

project_rollup["client-work"] += 45 → 45

find day 2026-07-13 → not found, create { date: 2026-07-13, total: 0, projects: {} }

within that day, find project "client-work" → not found, create { total: 0, entries: [] }

append E1, day.project["client-work"].total += 45 → 45, day.total += 45 → 45

E2 (client-work, 30, 2026-07-13):

week_total += 30 → 75

project_rollup["client-work"] += 30 → 75

find day 2026-07-13 → found

find project "client-work" → found

append E2, project.total += 30 → 75, day.total += 30 → 75

E3 (deep-think, 90, 2026-07-13):

week_total += 90 → 165

project_rollup["deep-think"] += 90 → 90

find day 2026-07-13 → found

find project "deep-think" → not found, create { total: 0, entries: [] }

append E3, project.total += 90 → 90, day.total += 90 → 165

E4 (client-work, 60, 2026-07-14):

week_total += 60 → 225

project_rollup["client-work"] += 60 → 135

find day 2026-07-14 → not found, create { date: 2026-07-14, total: 0, projects: {} }

find project "client-work" → not found, create { total: 0, entries: [] }

append E4, project.total += 60 → 60, day.total += 60 → 60

E5 (admin, 25, 2026-07-14):

week_total += 25 → 250

project_rollup["admin"] += 25 → 25

find day 2026-07-14 → found

find project "admin" → not found, create { total: 0, entries: [] }

append E5, project.total += 25 → 25, day.total += 25 → 85

Return acc.

```

What it makes easy. The implementation is a single loop with no intermediate structures. All the grouping logic lives in one place — the "find or create" pattern for days and projects. The cost is linear in the number of entries, and the memory overhead is only the output structure itself. Verifying correctness reduces to checking that each entry's contribution appears in the right buckets and that the running totals add up — a single pass through the trace.

What it makes hard. The single loop does five distinct things per entry: update week total, update project rollup, find-or-create day, find-or-create project, append and update subtotals. Those five concerns are braided together. If I later need to add tag-based grouping, I must thread a sixth concern into the same loop. If the grouping logic grows a bug — say the project rollup double-counts an entry — the bug lives in the middle of a dense knot, and isolating it requires teasing apart updates that happen on the same line of thought. Testing the compute phase in isolation means feeding it entries and inspecting the whole nested output; there is no intermediate state I can assert on before the loop finishes. The shape is correct but monolithic.

---

Alternative B: The Pipeline of Small Transformations

Structure. The computation is broken into a sequence of pure functions, each producing an intermediate structure consumed by the next. Step 1: group_by_date — partitions the flat list into a map of date→entries, preserving order. Step 2: for each date group, build_day_block — groups entries within that date by project, computes project subtotals and the day total, and returns a day block. Step 3: build_week — takes the list of day blocks, computes the week total by summing day totals, and builds the project rollup by merging project totals across days. Each step is a function from one immutable value to another; nothing is mutated in place.

Trace on the concrete input.

```

Step 1: group_by_date(entries)

→ {

"2026-07-13": [E1, E2, E3],

"2026-07-14": [E4, E5]

}

Step 2: build_day_block for "2026-07-13"

sub-group by project:

"client-work": [E1, E2] → total 75

"deep-think": [E3] → total 90

day total: 75 + 90 = 165

→ { date: "2026-07-13", total: 165, projects: { ... } }

build_day_block for "2026-07-14"

sub-group by project:

"client-work": [E4] → total 60

"admin": [E5] → total 25

day total: 60 + 25 = 85

→ { date: "2026-07-14", total: 85, projects: { ... } }

day_blocks = [block_13, block_14]

Step 3: build_week(day_blocks)

week total: 165 + 85 = 250

project rollup: merge project totals from both days

client-work: 75 + 60 = 135

deep-think: 90 + 0 = 90

admin: 0 + 25 = 25

→ { week_start: "2026-07-13", total: 250, project_rollup: { ... }, days: day_blocks }

```

What it makes easy. Each step has exactly one responsibility. group_by_date only cares about partitioning; it knows nothing of projects or totals. build_day_block only cares about one day's entries; it does not need to know how many days there are or what the week total will be. build_week only aggregates what the day blocks already computed; it does not touch individual entries. This separation means I can test each function independently: I can feed build_day_block a single day's entries and assert the day total, without constructing a whole week. If a bug causes the project rollup to be wrong, the fault is confined to build_week's merge logic — or possibly to build_day_block producing wrong project totals, which its own tests would catch. Extending with tag grouping means adding a new step in the pipeline without touching the existing functions.

What it makes hard. The pipeline creates intermediate structures that the single-pass approach does not. The date-grouped map and the list of day blocks both consume memory proportional to the input. With five entries this is invisible; with fifty thousand entries across several years, it might matter. More subtly, the pipeline's separation forces decisions about what each intermediate structure contains. build_day_block computes a day total; build_week recomputes the week total by summing those day totals rather than by summing entries directly. That is correct but redundant — the same information exists in two places. If a future maintainer changes build_day_block's total computation but forgets that build_week assumes day totals are accurate, the week total could drift from the sum of entries. The pipeline's clarity comes at the cost of denormalisation: the same fact is computed at multiple stages and must be kept consistent.

---

Alternative C: The Relational Core with Views

Structure. The entries are loaded into a minimal in-memory table — a list of uniform records, each a flat map of fields. Two grouping operations are defined as declarative queries over that table. The first query groups by date, then by project, and produces the nested day→project structure with subtotals. The second query groups by project across all dates and produces the project rollup. The week total is a third query — a simple sum over the duration field with no grouping. All three queries read from the same underlying table; none mutate it. The compute phase is the execution of these queries and the assembly of their results into the output shape.

Trace on the concrete input.

```

Table (entries as uniform records):

{ date: "2026-07-13", duration: 45, project: "client-work", tags: ["meeting"] }

{ date: "2026-07-13", duration: 30, project: "client-work", tags: ["email"] }

{ date: "2026-07-13", duration: 90, project: "deep-think", tags: ["design"] }

{ date: "2026-07-14", duration: 60, project: "client-work", tags: ["meeting"] }

{ date: "2026-07-14", duration: 25, project: "admin", tags: [] }

Query 1: GROUP BY date, project → SUM(duration), COLLECT(entries)

Result:

("2026-07-13", "client-work") → { total: 75, entries: [E1, E2] }

("2026-07-13", "deep-think") → { total: 90, entries: [E3] }

("2026-07-14", "client-work") → { total: 60, entries: [E4] }

("2026-07-14", "admin") → { total: 25, entries: [E5] }

Then nested: group those results by date to form day blocks.

"2026-07-13" → day total = 75+90 = 165, projects = { ... }

"2026-07-14" → day total = 60+25 = 85, projects = { ... }

Query 2: GROUP BY project → SUM(duration)

Result:

"client-work" → 135

"deep-think" → 90

"admin" → 25

Query 3: SUM(duration) — no grouping

Result: 250

Assemble output from Query 1 days, Query 2 rollup, Query 3 total.

```

What it makes easy. The grouping logic is declarative. I do not write loops that update accumulators; I state what I want grouped and what aggregation to apply. This makes the intent of the computation legible at a glance — "group by date and project, sum duration" is closer to the design brief's language than any loop. Adding a new grouping is another query over the same table, independent of the existing ones. The table is a stable, shared source of truth: if a bug causes the project rollup to disagree with the sum of day project totals, I know both queries read the same entries, so the bug is in one of the query definitions, not in a mutation order or an intermediate structure's staleness. Testing can assert each query's output directly against the input table.

What it makes hard. The approach requires a query engine, even if a minimal one. In a language with built-in group-by on collections this is nearly free; in a language without it, I must either bring in a library or write the grouping machinery myself — at which point I have built a worse version of the pipeline. The three queries also duplicate work: Query 1 and Query 2 both scan the full table and compute sums by project, just at different granularities. The single-pass approach computes those totals together in one scan; the relational approach trades CPU cycles for clarity. For five entries this is irrelevant; for a large log the trade-off becomes real. And the assembly step at the end — taking the flat query results and nesting them into the output contract — is a small but real piece of glue code that couples the query outputs to Phase 3's expected shape. If that shape changes, the assembly changes too, even if the queries remain correct.

---

Judgment: Which Shape Best Serves the Purpose?

The purpose of Phase 2 is to transform the flat list into the nested structure correctly and verifiably, without concerning itself with presentation. My own design work on this tool drew a sharp line between pure transformation logic and display surface precisely so that correctness can be verified without a screen. That means the overriding virtue of any Phase 2 implementation is verifiability — the ease with which I can convince myself, and later a reader of the code, that the output is exactly what the input demands.

Alternative A, the single-pass builder, is the most efficient in time and memory. But its verifiability is the weakest of the three. The single loop braids five updates together; tracing a single entry's contribution requires following it through five accumulator mutations that happen in rapid succession. A bug in the week total update might be on a different line than a bug in the day total update, but both execute in the same loop body, and reasoning about them requires holding the entire accumulator state in mind at once. This shape works — many programs are built exactly this way — but it asks the reader to trust the loop rather than to see the structure.

Alternative C, the relational core with views, is the most declarative and the closest to the language of the design brief. But it introduces a query abstraction that, in a small program, may be heavier than the problem warrants. The three queries scan the table independently, and the assembly step that follows is an extra translation layer that does not exist in the other two shapes. For a system that would grow many different groupings and cross-sections, this shape would shine. For a system whose output contract is two specific structures, it feels like bringing a database to a five-entry list.

Alternative B, the pipeline of small transformations, lands in the middle. It is not as terse as the single pass, nor as declarative as the queries. But each step has exactly one responsibility, and the intermediate structures make the data's journey visible: first it is grouped by date, then each date is shaped into a day block, then the day blocks are assembled into the week. I can test group_by_date with a handful of entries and see the partition. I can test build_day_block with one day's entries and assert its total. I can test build_week with two made-up day blocks and assert the week total and project rollup without involving real entries at all. That testability — the ability to isolate each transformation and verify it against a small, constructed input — is what verifiable without a screen means in practice.

Alternative B gives each step a boundary narrow enough to test alone. Alternative A gives the whole Phase 2 a single boundary, which is too wide. Alternative C gives each query a boundary, but the queries overlap in the table they scan, and the assembly step is a boundary that exists only to marry two shapes — it has no computational logic of its own.

If the design brief's purpose were raw speed on large logs, I would choose Alternative A and accept the verifiability cost. If the design brief's purpose were a general-purpose reporting engine that would grow many cross-cutting views, I would choose Alternative C. But the design brief's stated purpose is correctness in a pure transformation, with a fixed output contract, built by a maker who wants to verify each piece before trusting the whole. For that purpose, Alternative B is the right shape.

I choose the pipeline.