psf-memo/docs/reviews/thread-query-bounds-summary.md

Review summary: thread-query-bounds

Architect review of the refactorer handoff for task thread-query-bounds.

Commits reviewed

• 9db1137 (specifier): Add thread query performance specification (psf-memo-db/specs/thread-query-performance.feature) and record both implementation parts in the backlog.
• 3c4de9c (coder): Implement bounded thread query for /posts/:txid/thread — per-thread like counting via countLikesForTxids instead of the whole-DB buildLikeCountMap, and a prefix-scan of postChildren per node instead of a full-store walk.
• 386fea9 (refactorer): Add property tests for the thread query and cover GetPostThread edge cases.

Merged onto the architect worktree (swarmforge-architect) as d422db0. The merge also fast-forwarded the architect branch to master's client worktree changes (new-post txid display, nav menu, tooltip, Dockerfile cleanup); those were already on master and are outside this task, but their suites were run as part of merge hardening.

Architectural findings and fixes applied

The core optimization is correct and worth keeping: thread work is now proportional to the thread, not the database. The review found and fixed three structural issues the handoff left behind.

1. Information hiding / dependency direction (the key fix). The refactorer moved the postChildren key format (${parentTxid}:, :\uffff) into the GetPostThread use case, which also reached into postQuery.postChildrenDb.iterator(...) and postQuery.postsDb.get(...) directly. That couples a high-level use case to the LevelDB representation. I added PostQuery.listChildTxids(txid) (adapter owns the key format and the prefix bounds), made GetPostThread call listChildTxids and the existing PostQuery.getPostOrNull, and made countRepliesForTxids delegate to listChildTxids (removing the duplicated prefix-scan). GetPostThread now depends only on the PostQuery interface.

2. Dead full-scan method removed (cohesion). PostQuery.buildLikeCountMap was the exact whole-database like scan this task eliminated; after the change it was referenced only by tests. Removed it and its tests, consistent with the feed-query-performance review precedent. postTxidFromPostLike and postLikeKey were kept (still pinned by the key round-trip property test).

3. Uncovered guards now covered + property tests realigned. The prefix-scan guards (child?.parentTxid !== txid, !child?.childTxid) and the buildThreadNode cycle guard were uncovered by the handoff tests. I moved the prefix-bound assertions into PostQuery unit/property tests, added unit cases for the parent-mismatch and missing-child guards, added a cycle test, and repurposed the like-count property test to the live countLikesForTxids path.

The only production behavior change is the removal of the dead method; thread results, ordering, and like counts are unchanged.

Verification results

Language mutation (mutate4javascript, full mutation, --max-workers 8)

• psf-memo-db/src/adapters/post-query.js: 37 killed, 0 survived, 0 uncovered.
• psf-memo-db/src/use-cases/get-post-thread.js: 10 killed, 0 survived, 0 uncovered.
• The differential/default run only selected 1 changed site after the manifest refresh, so both files were re-run with --mutate-all to guarantee the new listChildTxids and removed method were actually mutated. Manifests were refreshed by the tool (no hand edits).

DRY (dry4javascript)

• Changed files (post-query.js, get-post-thread.js): no duplicate candidates. The postChildren prefix-scan is now single-sourced in PostQuery.listChildTxids.

CRAP / cyclomatic complexity (crap4javascript)

All changed functions are well below the 8.0 threshold and 100% covered. Highest: PostQuery.scanRecentPostTxidsAndCount (CC 6, CRAP 6.0, pre-existing), GetPostThread.buildThreadNode (CC 5, CRAP 5.0), PostQuery.likeTxidFromPostLike / scanFollowingFeedTxidsAndCount / scanPostsByAddrTxidsAndCount (CC 5, CRAP 5.0). PostQuery.listChildTxids is CC 4, CRAP 4.0; countRepliesForTxids is CC 2, CRAP 2.0.

Soft Gherkin acceptance mutation (gherkin-mutator --level soft)

• thread-query-performance.feature: 8 executed, 6 killed, 2 survived. Both survivors are max_entries upper-bound mutations (1 -> 3 and 0 -> 7). The assertion is reads <= max_entries, so raising the bound can never fail: the fixture performs 1 and 0 postChildren reads respectively, still below the larger bound. These are intrinsic equivalents / weak example-to-assertion connections (the same class documented for feed-query-performance), not implementation gaps; no change warranted. The feature stamp is correctly withheld because survivors remain.

Suite status

• psf-memo-db: unit 357 passing, property 44 passing, acceptance 11/11 generated files pass (including thread-query-performance), lint pass.
• psf-memo-client (merge hardening): unit 309 passing, lint pass, build pass.
• psf-memo-indexer (merge hardening): unit 85 passing, lint pass.

Handoffs sent

• git_handoff to coder and refactorer (priority: 00) with the review commit (adapter encapsulation, dead-code removal, test hardening, refreshed mutation manifests, Gherkin acceptance-mutation manifest).
• No specifier handoff: no functional or spec change in the review commit (structural refactor, tests, and tool-generated manifests only).

By architect.