psf-memo/docs/reviews/feed-total-cap-summary.md

# feed-total-cap — Architect Review

Task: `feed-total-cap`
Component: `psf-memo-db`
Base: `c2bfbc3` (last merged architect review)

## What was reviewed

Inbound refactorer batch (priority 10):

- **`c131b91`** — coder: *Raise recent-feed total scan cap to 500*. Changes
  `PostQuery.TOTAL_SCAN_CAP` from 10 to 500, adds two unit cases
  (exact-total-under-cap and default-cap read bound), and adds the
  `many-top-level-posts` acceptance fixture (510 top-level posts).
- **`10deb3e`** — refactorer: *Add recent-feed cap property tests*. Adds
  `test/property/recent-feed-cap.property.test.js` (capped total, newest-first
  pagination conservation, bounded raw scan, 500 default cap, reply exclusion).

Also in the linear chain (specifier-side): `a643820` (backlog entry) and
`28b34b5` (spec: new `feed-total-cap.feature`, `feed-query-performance`
scenario 2 renamed and totals raised to the exact-under-cap value).

Merged onto `swarmforge-architect` by fast-forwarding to `10deb3e`.

**Architect review commit: `b2c78fb651`** — tool-written manifests only (the
`mutate4javascript` manifest in `post-query.js` and the `gherkin-mutator`
acceptance stamps in the two touched feature files). This summary and the
verification record are committed directly on top of it, so
`git diff b2c78fb651 HEAD` touches only `docs/`. The record's `git_sha` is
`b2c78fb651`, the commit that contains the verified source state.

## Architectural findings and fixes applied

No structural change was warranted.

1. **Information hiding / dependency rule.** The cap remains a module-private
   constant (`TOTAL_SCAN_CAP = 500`) in `src/adapters/post-query.js`, exposed
   only through the existing optional `totalScanCap` parameter. The high-level
   `ListRecentPosts` use case does not learn any new index or IO detail; there
   is no new dependency from core toward LevelDB, and no new module boundary.
2. **Testability.** The new property tests drive `PostQuery` through in-memory
   doubles (`makePostHeightsDb` with a read counter, `makeParentsDb`,
   `makeQuery`) and never touch LevelDB or the network; the read bound is
   observable through the counter. Tests stay separate from the generators in
   `test/property/harness.js`.
3. **Duplication.** `dry4javascript` reported no duplicate candidate in the
   changed source (`post-query.js`) nor in the new property test. The 74
   duplicate blocks it did report are pre-existing `acceptance/lib/handlers.js`
   step-handler boilerplate and old `post-query.unit.js` mock shapes; none
   overlaps `loadManyTopLevelPosts`. Deferred as documented pre-existing
   pattern-boilerplate, consistent with prior reviews.
4. **Acceptance fixture.** `loadManyTopLevelPosts` lives in the acceptance
   handler library (test helper), separate from unit/property tests. It writes
   `posts`, `postHeights`, and `addrPostHeights`; the `addrPostHeights` writes
   are not read by the recent-feed path but are harmless and keep the fixture
   reusable for address queries.

## Verification results

### Language mutation (`mutate4javascript`, `--max-workers 8`)
- `psf-memo-db/src/adapters/post-query.js`: differential run selected 0 of 37
  covered sites (only a module-level constant changed), so `mutate-file.sh`
  auto-reran `--mutate-all`: **37 killed, 0 survived, 0 uncovered**.

### DRY (`dry4javascript`)
- Changed files (`src/adapters/post-query.js`,
  `test/property/recent-feed-cap.property.test.js`,
  `test/unit/adapters/post-query.unit.js`, `acceptance/lib/handlers.js`):
  **no new duplicate candidates**. The 74 reported blocks are all pre-existing
  handler/unit mock boilerplate.

### CRAP / cyclomatic complexity (`crap4javascript src/adapters/post-query.js`)
All functions below the 8.0 threshold. Highest:
`PostQuery.scanRecentPostTxidsAndCount` (CC 6, 100% covered, CRAP 6.0),
then `likeTxidFromPostLike` / `scanFollowingFeedTxidsAndCount` /
`scanPostsByAddrTxidsAndCount` (CC 5, CRAP 5.0). The cap change does not alter
cyclomatic complexity.

### Soft Gherkin acceptance mutation (`gherkin-mutator --level soft`)
- **`feed-total-cap.feature`**: 10 executed, **7 killed**, **3 survived**,
  0 errors.
  - `examples[1].limit 50 -> 43`: genuine equivalent — after `offset 499` only
    11 of the 510 posts remain, so the page length is `min(limit, 11) = 11` for
    both values and `total 500` / `hasMore false` are unchanged.
  - `examples[1].max_entries 510 -> 512`: intrinsic upper-bound equivalent — the
    `at most` bound mutated upward can never fail (actual reads 510); APS exposes
    no project mutation filter, documented precedent.
  - `examples[1].offset 499 -> 504`: weak example-to-assertion connection — the
    scenario asserts `total`, `hasMore`, and the read bound but not the returned
    page slice, so shifting the offset within the tail still passes. Specifier-side
    feature-quality item, not an implementation gap.
- **`feed-query-performance.feature`**: 25 executed, **18 killed**, **7
  survived**, 0 errors. All 7 are the same pre-existing class already documented
  in `feed-query-performance-summary.md` (5 survivors then): `limit` mutations
  wider than the page, `max_entries` upper-bound mutations, and one new
  `offset 0 -> 7` page-slice mutation exposed by the specifier's revised
  examples. Genuine equivalents / weak assertions; no implementation change
  warranted.

### Suite status
`swarmforge/scripts/verify.sh db --record
docs/reviews/feed-total-cap-verification.json --task feed-total-cap`
-> **pass (4/4)**:
unit **358 passing**, property **48 pass / 0 fail**, acceptance **all 12
acceptance suites passed** (including the new `feed-total-cap`), lint **pass**.
Record `git_sha` = `b2c78fb651`.

## Handoffs sent
- End-of-chain `git_handoff` to the specifier (`priority: 50`, task
  `feed-total-cap`) with the review commit so it can merge
  `swarmforge-architect` into `master`.
- No coder/refactorer handoff: the review is tool-written manifests only, with
  no follow-up work for them. The soft-mutation survivors are specifier-side
  feature-quality items, not implementation gaps.

By architect.