psf-memo/docs/reviews/txid-wire-encoding-summary.md

txid-wire-encoding — Architect Review

Task: txid-wire-encoding Components: psf-memo-client, psf-memo-db Base: bf7edd5 (last merged architect review); inbound refactorer commit a76fcee

What was reviewed

Inbound refactorer batch (priority 10), merged onto swarmforge-architect by fast-forwarding to a76fcee. The linear chain reviewed:

• bb0c9ab — specifier: Spec txid wire encoding and database repair. Adds psf-memo-client/specs/txid-wire-encoding.feature (4 scenario outlines pinning the like, reply, poll-option, and poll-vote wire order) and psf-memo-db/specs/repair-txid-encoding.feature (6 scenario outlines for the byte-reversed-reference repair utility).
• dedb7a1 — coder: Fix txid wire encoding and add txid repair utility. Adds txidToWireBytes and reverses the txid in buildTxidTextPayload, so likes, replies, poll options, and poll votes now embed the referenced txid little-endian; adds the repair-txid-encoding library (correctReference, repairTxidEncoding), the util/txid CLI wrapper, unit tests, the DB acceptance fixture/handlers, and decodes the wire txid in the client acceptance handlers.
• a76fcee — refactorer: Refactor txid wire encoding and repair library. Generalizes the four near-identical repair loops into repairStore plus a txidIndex key/value adapter, replaces the reply-only buildReplyPayload with the shared buildTxidTextPayload(txid, text, label), and adds client and DB property tests (round trip, involution, idempotence, conservation, resolution, index rebuild).

Architect review commit: a2229f7dd4 — the mutate4javascript footer manifests (client hex.js, memo-like.js, memo-reply.js; DB src/lib/repair-txid-encoding.js), the soft gherkin-mutator acceptance-mutation manifests on both touched feature files, the hardening tests below, and the extracted shared test double. The summary and verification records are committed on top, so git diff a2229f7dd4 HEAD touches only docs/. The records' git_sha is a2229f7dd4, the commit that contains the verified source state.

Architectural findings and fixes applied

The refactorer's structure is sound and required no further boundary change. The hardening work was mutation- and duplication-driven.

1. UI/Core separation. src/services/hex.js is a pure leaf (byte decode, reverse, payload assembly) with no React, DOM, wallet, or IO. memo-like.js and memo-reply.js are core services that receive the wallet/feed/thread behind injected adapter doubles. src/lib/repair-txid-encoding.js is a pure async core that receives the LevelDB handles; only util/txid/repair-txid-encoding.js opens real stores. Every piece of core behavior is exercised without a browser, network, or database file.
2. Dependency rule. The client services depend inward on hex.js; the DB CLI wrapper depends inward on src/lib. Nothing in the pure modules reaches out to React, the router, LevelDB, or the file system.
3. Information hiding. The little-endian wire order now has exactly one definition (txidToWireBytes), and the txid+text payload shape has one definition (buildTxidTextPayload). The refactorer's repairStore + txidIndex hide the per-store field/key/value differences behind a small adapter, and correctReference hides the "keep / reverse / leave" decision. No persistence structure leaks into callers.
4. Minor coupling, accepted. buildTxidTextPayload defaults its label to 'Poll txid', a residue of its poll-only origin. It is now generic and the reply caller passes 'Parent txid' explicitly; the poll callers rely on the default. A fully neutral default was not worth churning the poll call sites.
5. Test boundaries. The task-local FakeDb/makeLevel double was duplicated verbatim across the new unit and property tests, so it was extracted to psf-memo-db/test/support/level-double.js (a test helper, kept out of test/unit/** and test/property/*.test.js). The util CLI wrapper is an environmentally unsuitable adapter shell and is deliberately excluded from the tools that run tests/coverage/mutation.
6. Mutation hardening (see below). Six pre-existing boundary survivors in memo-like.js and one in memo-reply.js were killed with focused boundary assertions rather than design changes.

Verification results

Language mutation (mutate4javascript, --mutate-all where the wrapper

detected differential under-selection, --max-workers 8)

File	Sites	Killed	Survived	Uncovered
psf-memo-client/src/services/hex.js	7	7	0	0
psf-memo-client/src/services/memo-like.js	34	34	0	0
psf-memo-client/src/services/memo-reply.js	2	2	0	0
psf-memo-db/src/lib/repair-txid-encoding.js	6	6	0	0

The first memo-like.js run left 9 survivors (true -> false on the validate/validateTip return values, the validateTip tipSats > spendableSats boundary, the _validateTipAmount max-tip boundary, the getSpendableSats ?? 0 default, the _requireTipAddress <= 0 and .length > 0 boundaries, the _buildTipOutput tipSats > 0 boundary, and the _incrementPostCount || 0 default). memo-reply.js left the isTooLong > MAX_REPLY_BYTES boundary. Each was a missing boundary/default assertion, not a design fault; focused unit assertions were added and the re-runs report 34/0 and 2/0. hex.js and the DB repair library were clean on the first full run.

psf-memo-db/util/txid/repair-txid-encoding.js is not mutated: it is the file-system adapter shell (opens real LevelDB stores, no unit coverage by design), and the tool that runs tests is scoped to the testable core.

DRY (dry4javascript)

Scoped runs over the changed production files, tests, and adapters.

• DB. The verbatim FakeDb/makeLevel duplication across the two new test files was extracted to test/support/level-double.js; the scoped report dropped from 72 to 70 duplicate blocks. Every remaining block is pre-existing acceptance/lib/handlers.js step-handler boilerplate, except one structurally identical but semantically distinct pair in the unit test (like/postLikes vs reply/postChildren index-rebuild assertions), left as deliberate test boilerplate.
• Client. The task-local candidates are two makeWallet doubles (test/property/poll-services.property.test.js vs test/unit/memo-reply.test.js) and one structurally identical pair of like-rejection tests in memo-like.test.js. makeWallet appears in 28 client test files as an established per-suite fixture convention, so extracting it would be a broad cross-suite refactor beyond this task; both are recorded as documented pattern-boilerplate. The remaining blocks are pre-existing acceptance/lib/handlers.js boilerplate.

CRAP / cyclomatic complexity (crap4javascript)

• Client: every changed function at or below CRAP 6.0 with ~100% coverage — MemoLike._validateTipAmount (CC 6, 100%, 6.0), hexToBytes (CC 5, 5.0), MemoLike._incrementPostCount (CC 5, 5.0), MemoLike.getSpendableSats (CC 4, 4.0), the rest CC ≤ 3. MemoReply.reply is 90% covered but CRAP 2.0.
• DB: repairStore (CC 5, 100%, 5.0), correctReference (CC 4, 4.0), hasRecord (CC 4, 4.0), reverseTxid (CC 3, 3.0), repairTxidEncoding/ txidIndex (CC 1). All below the 8.0 threshold.

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

• txid-wire-encoding.feature (client): 14 executed, 8 killed, 6 survived, 0 errors. All six survivors are single-character case mutations of values that are never asserted: reply message (hello memo, a second one), poll option (yes, no), and poll-vote comment (yes, I choose this). Each scenario asserts the Memo prefix and the referenced txid, not the carried text, so the mutated text is an intrinsic equivalent / weak example-to-assertion link. The wire-order txid mutations (the point of the feature) were killed.
• repair-txid-encoding.feature (DB): 21 executed, 18 killed, 3 survived, 0 errors. All three survivors mutate the reversedPostTxid example value in scenarios 0, 1, and 5, which use it only in the negative assertion "the postLikes store contains 0 entry whose key starts with <reversedPostTxid>". Since the key is absent by construction, any mutated value still yields 0 entries — a genuine negative-assertion equivalent. All positive repair and index assertions killed their mutations.

These survivors are specifier-side feature-quality items (weak text assertions), not implementation gaps; no implementation change is warranted.

Suite status

Canonical records, both against review commit a2229f7dd4523e6397418e2bb8ac43800940b902:

• swarmforge/scripts/verify.sh client --record docs/reviews/txid-wire-encoding-verification.json --task txid-wire-encoding -> pass (5/5): unit 417 pass / 0 fail, property 80 pass / 0 fail, acceptance all 30 suites passed, lint ok, build ok.
• swarmforge/scripts/verify.sh db --record docs/reviews/txid-wire-encoding-db-verification.json --task txid-wire-encoding -> pass (4/4): unit 371 passing, property 54 pass / 0 fail, acceptance all 13 suites passed, lint ok.

This is the first recent task to touch two components, so the client record uses the canonical <task>-verification.json name and the DB record uses <task>-db-verification.json; both carry the same review git_sha.

Handoffs sent

• End-of-chain git_handoff to the specifier (task txid-wire-encoding) with the review commit a2229f7dd4 so it can merge swarmforge-architect into master.
• No coder/refactorer handoff: the review is mutation hardening plus a test-double extraction with no follow-up work for those roles.

By architect.