psf-memo/docs/reviews/topic-metadata-summary.md

Topic Metadata Columns — Architect Review

By architect.

Task and commits reviewed

• Task: topic-metadata (refactorer handoff merge_and_process refactorer dd11964174).
• Merged swarmforge-refactorer (fast-forward). Topic-metadata commits:
  • a599b34 Spec topic metadata columns
  • 8da0f09 Implement topic metadata columns (coder)
  • dd11964 Refactor topic metadata: cut CRAP, share test doubles, harden property tests (refactorer)
• Architect review commit: 3f05488 (survivor-killing tests + tool-written mutation manifests/stamps). Verification record git_sha: 3f05488da0.
• Records/summary commit: (this commit).

The feature adds lastSeen (epoch-ms of the newest topic post, 0 for follow-only rooms) and followerCount to each topicSummaries record; exposes them from GET /topics; rebuilds them in the backfill utility; and renders four topic columns (name, relative time, post count, follower count) on the client topics page.

Architectural findings

• UI/Core separation (good). The React Topics component stays thin: it delegates load/pagination to the testable TopicDiscoveryPage controller and formats labels with the pure relative-time.js service (own unit tests). The controller also exposes getLastSeenLabel for the acceptance/unit seam. The component calls relativeTime(topic.lastSeen, …) directly rather than that wrapper, but both share the same pure function, so the exercised logic is the tested logic. Accepted as-is.
• Dependency direction (good). Indexer metadata maintenance is isolated in topic-indexing.js; topic-follow.js/topic-message.js only decide when to call recordTopicFollow/recordTopicPost. backfill-topic-indexes.js takes injected LevelDB handles and holds no file-system concerns; the CLI wrapper opens the real stores. TopicQuery.listTopics reads metadata from topicSummaries and ordering/pagination from topicRecency with limit: offset + limit, never iterating rooms.
• Information hiding (good). getIfPresent/isNotFound hide not-found handling; listTopics defaults missing metadata fields to 0 for legacy summaries. The topicSummaries record shape and topicRecencyKey are duplicated between the indexer and the DB — unavoidable cross-deployable protocol constants (the components share no module); both are pinned by exact-key/field tests so they cannot drift silently.
• Local quality (good). The refactorer replaced the ternary follower delta with Number(isActive) - Number(wasActive), dropping recordTopicFollow from CC 8 to CC 6. The indexer and DB share in-memory store doubles (test/support/memory-db.js, test/support/level-double.js) instead of re-creating them per test.
• Observation (not changed). recordTopicFollow recomputes followerCount from summary.followerCount ?? 0. If a room's roomsDb record survives but its topicSummaryDb summary is lost, an idempotent replay (delta 0) would report 0 rather than the true active-follow count. This only arises from a degraded store state that the backfill repairs, and no runtime path reaches it, so it was left unchanged.

Fixes applied (kill language-mutation survivors)

Added DB unit tests only; no production behavior changed.

• psf-memo-db/test/unit/adapters/topic-query.unit.js
  • listTopics() called with no arguments defaults limit 100 / offset 0 (killed offset = 0 -> 1).
  • A legacy summary without postCount reports 0 (killed ?? 0 -> 1).
  • A post without blockHeight orders after a height-1 post, pinning the zero default (killed blockHeight ?? 0 -> 1).
• psf-memo-db/test/unit/lib/backfill-topic-indexes.unit.js
  • A post without blockHeight summarizes at lastHeight 0 and recency height 0 (killed value.blockHeight ?? 0 -> 1).
  • topicRecencyKey(undefined|null, room) equals topicRecencyKey(0, room) (killed blockHeight ?? 0 -> 1).

These five survivors were the only real mutation gaps; all remaining survivors are documented intrinsic equivalents.

Verification

Records (git_sha 3f05488da024895005786de0b8dd6973045d7b46):

File	Component
docs/reviews/topic-metadata-verification.json	psf-memo-indexer (canonical)
docs/reviews/topic-metadata-db-verification.json	psf-memo-db
docs/reviews/topic-metadata-client-verification.json	psf-memo-client

Suite status (all pass):

• psf-memo-indexer: 113 unit, 12 property, 7 acceptance suites, lint ok.
• psf-memo-db: 392 unit (was 387; +5 review tests), 57 property, 16 acceptance suites, lint ok.
• psf-memo-client: 441 unit, 90 property, 33 acceptance suites, lint ok, build ok.

Language mutation (mutate4javascript, --max-workers 8; --mutate-all where the differential run under-selected the changed DB files):

• Indexer: topic-indexing.js 26/26 killed; topic-follow.js 3/3 killed; topic-message.js 3 killed / 1 survived.
• DB: topic-query.js 29/29 killed (after hardening); backfill-topic-indexes.js 11 killed / 2 survived.
• Client: relative-time.js 8/8 killed; topic-discovery-page.js 2/2 killed.

Total 82 killed, 3 survived.

Documented mutation equivalents:

• psf-memo-indexer/src/use-cases/action-types/topic-message.js line 30 pushDatas[0] -> pushDatas[1]: handlePost normalizes a two-push payload and always reads the text at index 1; index 0 is never inspected, so the action prefix and the room are interchangeable there.
• psf-memo-db/src/lib/backfill-topic-indexes.js lines 43/45 > -> >=: on equality the guard assigns the value it already holds, so the summary is unchanged.

DRY (dry4javascript, scoped to changed files): no candidates in the changed production files. One candidate in tests — the identical topicRecencyKey ordering property test in psf-memo-db and psf-memo-indexer — is cross-component duplication mirroring the duplicated key function; not reducible without a shared test package, consistent with the accepted protocol constant. No change.

CRAP (crap4javascript): every changed function is 100% covered and below the 8.0 threshold; highest CRAP/CC 6.0 (recordTopicFollow, collectSummaries, TopicQuery.getTopicPostTxids, relativeTime).

Soft Gherkin acceptance mutation (gherkin-mutator --level soft --workers 8):

• DB topic-metadata.feature: 30 total, 30 killed, 0 survived → the tool wrote a # mutation-stamp plus the per-scenario manifest.
• Indexer topic-metadata-indexing.feature: 62 total, 14 killed, 48 survived.
• Client topic-metadata-columns.feature: 28 total, 16 killed, 12 survived.

All survivors are intrinsic equivalents, not implementation gaps: single-character case mutations of example values (room, addr, txid, text) are resolved consistently on both the setup and assertion sides of their scenario; the height/firstHeight/secondHeight mutations feed scenarios that do not assert height; the firstSeen/secondSeen mutations do not cross the asserted max(seen) (the killed mutations are the ones that do); and the client lastSeen mutations stay inside the same relative-time bucket. These are specifier-side feature-quality items (weak write/read connection), consistent with prior reviews. The mutator wrote manifests into the indexer and client features; those tool-written changes are committed as-is.

Handoffs

• End-of-chain git_handoff to specifier (priority 50) to merge swarmforge-architect into master, using the records/summary commit.
• No coder/refactorer follow-up: the review adds tests and tool-written metadata only, with no production behavior change.