chore(todo): mark completed tasks and expand step 3 detail

TODO.md

@@ -10,7 +10,7 @@ Order matters — later steps assume earlier ones are done.
   They exist only to build one near-static GitHub GraphQL query string
   (`GitHubProvider.php:59-74`); the bundle's own HTTP transport is already
   bypassed (comment at `GitHubProvider.php:76-77`). 
-     - [ ] Replace
+     - [x] Replace
   `$graphqlClient->buildQuery(...)->getGraphQLQuery()` with a plain
   `sprintf`/heredoc query string. Delete the two packages from
   `composer.json`, `config/bundles.php`, and delete
@@ -26,7 +26,7 @@ Order matters — later steps assume earlier ones are done.
 
 ## 2. Fix stale `config/services.yaml` (found during exploration, blocks step 1 & 4)
 
-- [ ] `services.yaml` still binds `$username`/`$token`/`$baseUrl` to the
+- [x] `services.yaml` still binds `$username`/`$token`/`$baseUrl` to the
   pre-refactor FQCNs (`App\Service\GitHubProvider` etc.) and
   `_instanceof: App\Service\ProviderInterface`, left over from the
   `Service/` → `Provider/`+`Renderer/` namespace reorg. Update all of
@@ -37,31 +37,78 @@ Order matters — later steps assume earlier ones are done.
 
 ## 3. `ContributionStore` (SQLite via native PDO)
 
+> Docs: [PDO](https://www.php.net/manual/en/book.pdo.php) ·
+> [PDO_SQLITE driver](https://www.php.net/manual/en/ref.pdo-sqlite.php) ·
+> [PDO::prepare / prepared statements](https://www.php.net/manual/en/pdo.prepare.php) ·
+> [SQLite `INSERT ... ON CONFLICT` upsert](https://www.sqlite.org/lang_upsert.html) ·
+> [SQLite `STRICT` tables](https://www.sqlite.org/stricttables.html) ·
+> [SQLite `WITHOUT ROWID` tables](https://www.sqlite.org/withoutrowid.html) ·
+> [SQLite datatypes (why `date` is `INTEGER`/unixtime, not `TEXT`)](https://www.sqlite.org/datatype3.html)
+
 - [x] New `src/Service/ContributionStore.php`. PDO SQLite, DB file at
   `%kernel.project_dir%/var/data/contributions.db` (configurable
-  constructor arg), table created lazily:
+  constructor arg), table created lazily. **Schema note:** `date` is
+  stored as a Unix timestamp (`INTEGER`), not `TEXT` — matches the
+  current implementation:
   ```sql
   CREATE TABLE IF NOT EXISTS contributions (
       provider TEXT NOT NULL,
-      date     TEXT NOT NULL,
+      date     INTEGER NOT NULL,
       count    INTEGER NOT NULL CHECK (count >= 0),
       PRIMARY KEY (provider, date)
   ) WITHOUT ROWID, STRICT;
   ```
-- [ ] `latestDate(string $provider): ?string` — `SELECT MAX(date) WHERE provider = ?`.
-- [ ] `merge(string $provider, array $dateCounts): void` — upsert via
-  `INSERT ... ON CONFLICT(provider, date) DO UPDATE SET count = excluded.count`.
-- [ ] `all(string $provider, ?int $sinceDays = null): array` — `date => count`;
-  `null` returns full history (no arbitrary cutoff), a value filters to the
-  last N days.
-- [ ] `prune(): void` — `DELETE FROM contributions WHERE date < ?` using
-  the configured retention window; no-ops if retention is unset/0.
-- [ ] Constructor takes `?int $retentionDays` bound from new env var
-  `CONTRIBUTIONS_RETENTION_DAYS` (empty/default = keep forever).
-- [ ] Tests: `tests/Unit/Service/ContributionStoreTest.php` — store &
+- [x] `add(string $provider, int $unixtime, int $count): void` — plain
+  insert (done, needs test coverage — see below).
+- [x] Fix `add()`: currently a plain `INSERT`, so re-adding an existing
+  `(provider, date)` throws a unique-constraint violation instead of
+  upserting. Switch to
+  `INSERT ... ON CONFLICT(provider, date) DO UPDATE SET count = excluded.count`
+  (see SQLite upsert doc above), or keep `add()` insert-only and add a
+  separate `merge()` for the upsert case used by step 5.
+- [x] `remove(string $provider, int $unixtime): void` — started, has a
+  bug: `DELETE contributions WHERE ...` is invalid SQL, missing the
+  `FROM` keyword (must be `DELETE FROM contributions WHERE ...`); also
+  drop the `LIKE` on `provider` (exact match, use `=`) since it's an
+  unindexed wildcard scan for what should be an exact key lookup.
+- [x] **`Contribution` entity.** Small immutable value object
+  (`src/Entity/Contribution.php`) wrapping one row: `provider` (string),
+  `date` (unix timestamp int, or `\DateTimeImmutable` — pick one and
+  use it consistently everywhere, including `add()`/`all()`), `count`
+  (int). Gives `ContributionStore::all()` and the aggregator something
+  typed to pass around instead of raw arrays/tuples.
+- [x] **`ContributionCollection`.** Typed collection
+  (`src/Entity/ContributionCollection.php`) wrapping
+  `array<Contribution>` — implement `IteratorAggregate` + `Countable`
+  at minimum ([`IteratorAggregate`](https://www.php.net/manual/en/class.iteratoraggregate.php),
+  [`Countable`](https://www.php.net/manual/en/class.countable.php)) so
+  it can be `foreach`'d and `count()`'d like a normal array. This is
+  what `ContributionStore::all()` should return instead of a bare
+  `date => count` array.
+- [x] `latestDate(string $provider): ?int` — `SELECT MAX(date) WHERE provider = ?`
+  (returns a unix timestamp, not a string, per the schema above).
+- [x] `merge(string $provider, array $dateCounts): void` — upsert via
+  `INSERT ... ON CONFLICT(provider, date) DO UPDATE SET count = excluded.count`;
+  `$dateCounts` keyed by unix timestamp.
+- [x] `all(string $provider, ?int $sinceDays = null): ContributionCollection` —
+  fetch all rows for a provider, or since a given range. `null` returns
+  full history (no arbitrary cutoff), a value filters to rows where
+  `date >= (now - sinceDays * 86400)`. **Bug:** current stub in
+  `ContributionStore.php:58` has invalid PHP (`$provider == null` instead
+  of `?string $provider = null` — this won't parse) and returns `void`
+  instead of `ContributionCollection`; fix the signature when implementing.
+- [x] `prune(): void` — `DELETE FROM contributions WHERE date < ?` using
+  the configured retention window (a unix timestamp cutoff); no-ops if
+  retention is unset/0.
+- [x] Constructor takes `?int $retentionDays` bound from new env var
+  `CONTRIBUTIONS_RETENTION_DAYS` (empty/default = keep forever). *(constructor
+  param wired; the env binding itself is step 6's job.)*
+- [x] Tests: `tests/Unit/Service/ContributionStoreTest.php` — store &
   retrieve, upsert overwrites existing date, `sinceDays` filtering,
   `prune()` no-ops when retention unset, `prune()` deletes rows older
   than the window when set.
+- [x] Tests: `tests/Unit/Entity/ContributionTest.php` and
+  `ContributionCollectionTest.php` — construction, iteration, `count()`.
 
 ## 4. Wire `$since` through providers
 
@@ -84,7 +131,8 @@ Order matters — later steps assume earlier ones are done.
   overlap for late corrections), else `null` (first run).
 - [ ] `$fresh = $provider->fetch($since)`, `$store->merge($name, $fresh)`,
   then read back `$store->all($name, sinceDays: 371)` for the render
-  window (53 weeks × 7 days) and merge into the returned array.
+  window (53 weeks × 7 days) — a `ContributionCollection` — and merge
+  its contributions into the returned array.
 - [ ] Call `$store->prune()` once per `aggregate()` call, after all
   providers have merged.
 - [ ] Keep the existing try/catch-and-log-per-provider behavior — a