# Implementation review record

The stopping rule is two consecutive adversarial passes with no new verified findings. A finding resets that count. Reviews run against the compiled executable, synthetic Algolia responses, and isolated files; they do not claim live IndieHackers data access.

| Pass | Scope | Verified findings | Verification after repairs | Consecutive clean passes |
| --- | --- | --- | --- | --- |
| Baseline | Existing implementation | Not counted as a review | Strict checks and 75 end-to-end scenarios passed | 0 |
| 1 | Response grammar, pagination, configuration, export integrity | 9 groups below | Strict checks and 95 end-to-end scenarios passed | 0 |
| 2 | Process and filesystem lifecycle, concurrent publication, configuration bounds | 4 groups below; one apparent finding withdrawn | Strict checks and 114 end-to-end scenarios passed | 0 |
| 3 | Encoding fidelity and API origin validation | 2 groups below | Strict checks and 123 end-to-end scenarios passed | 0 |
| 4 | Independent JSON corpus, TLS, transfer limits, commit-boundary signals, memory instrumentation | 0 | 132 scenarios passed; 64 valid and 88 invalid corpus bodies; AddressSanitizer run: 108 tests passed with no reports | 1 |
| 5 | File ownership, namespace changes, and cleanup review | 1 group below | Strict checks and 136 end-to-end scenarios passed | 0 |
| 6 | Post-repair ownership, callback/arena lifetime, cancellation, and crash recovery | 0 | AddressSanitizer: 108 tests passed without reports; 24 filesystem/cancellation scenarios passed, including SIGKILL recovery | 1 |
| 7 | Final CLI/API contract, publication/error paths, documentation, and fresh optimized build | 0 | Strict checks and fresh build passed; 137 scenarios / 139 runner tests passed; real Algolia HTTPS rejection preserved the prior export | 2 |

Pass 1 findings and repairs:

- Malformed JSON was accepted: trailing commas in objects and arrays, duplicate empty keys, and malformed Unicode could become successful exports. A strict decoder now uses the standard tokenizer and string unquoting with checked grammar, decoded-key uniqueness, Unicode scalar validation, numeric limits, depth limits, and a token budget. Valid surrogate pairs and empty keys have positive regressions.
- Replacing an export changed mode `0600` to `0644`. Staging files are now created privately from the first open; new exports use `0600` and replacements preserve permission bits.
- A symlink output was silently replaced. Nonregular destinations are now rejected before making requests, preserving links and targets.
- `--output --no-code` treated the flag as a filename, leaving the founder filter enabled. Missing option values now fail before collection; explicit `--output=VALUE` remains available for names beginning with a dash.
- Index `..` changed `/1/indexes/../query` into `/1/query` through URL normalization. Dot path segments are now rejected as index names.
- Product IDs containing `/`, `?`, `#`, or non-ASCII characters produced misleading URLs. IDs are now encoded as one path segment.
- Duplicate products were counted as separate results. Repeated nonempty IDs within or across pages now abort the collection. Responses containing more than the requested 100 hits also fail.
- HTTP `206 Partial Content` was accepted as a complete search response. Search requests now require the API's documented `200` status.
- A dotenv assignment containing only an inline comment used the comment as a credential or index. Comment-only values now decode as empty values.

Transport resource ownership, response decoding, and export staging now live in separate modules. Pagination logs also distinguish the requested limit from the end of the index. All regressions exercise the actual executable.

Primary references checked during review: [Algolia search contract](https://www.algolia.com/doc/rest-api/search/search-single-index), [JSON specification](https://www.rfc-editor.org/rfc/rfc8259), [libcurl path normalization](https://curl.se/libcurl/c/CURLOPT_PATH_AS_IS.html), and [private temporary-file creation](https://man7.org/linux/man-pages/man3/mkstemp.3.html).

Pass 2 findings and repairs:

- A destination edited while the HTTP request was in flight was overwritten. Export operations now use an open directory descriptor, a kernel advisory directory lock, and checked destination identity/timestamps before publication. New destinations use an atomic no-replace rename. Directory replacement cannot redirect staging cleanup or publication.
- SIGINT/SIGTERM terminated the process without discarding its staging file. A lock-free signal flag now cancels active transfers, response decoding, and the inter-page pause, then runs normal cleanup and returns 130/143. Publication finishes as one protected critical section.
- A FIFO `.env` blocked startup, and arbitrarily large files were read into memory. Configuration reads are nonblocking, require a regular file, and enforce a 64 KiB limit, including file growth during reading.
- Publication synced file contents without syncing the directory entry. Both are now synced; failure after the rename explicitly reports that the export was published, rather than claiming the old destination was preserved.

The apparent short-write finding was withdrawn. A `strace` positive-return substitution skips the syscall without writing its reported prefix. Inspection of `core:os` and the retry trace confirmed that the existing writer handles real partial writes. This invalid probe is excluded from the regression suite. Buffered CSV output is retained to reduce filesystem calls, with its flush checked before publication.

Filesystem verification uses `strace` to inject actual error returns into identified staging-file writes, fsync, close, fchmod, renameat2, and unlinkat. Tests assert the fault reached the intended syscall and distinguish failures before publication from directory-sync failure after publication. A kernel file-size limit, signals, concurrent collectors, and changed output directories are also exercised.

Pass 3 findings and repairs:

- A dotenv index ending in byte `ff` was queried as a different index containing U+FFFD, then reported as a successful export. The bounded dotenv reader and index validation now reject invalid UTF-8 before any request.
- Missing hosts, nested schemes, invalid ports, and malformed IPv6 API origins passed CLI validation. Origin parsing now requires one explicit HTTP(S) scheme and an authority validated by libcurl's URL parser. Valid IPv6 and a trailing root slash have positive coverage.

Pass 5 finding and repair:

- Replacing the staging pathname while HTTP was in flight caused the replacement's contents to be published with a success message. Staging identity is now captured from its open descriptor and verified against the pathname and completed file metadata before rename. The completed file cursor must match its size, preventing unexpected trailing data. Cleanup only removes a path still referring to the inode created by this process; a replacement or symlink is reported and left untouched. Regressions cover replacement files, symlinks, disappearance, and inserted trailing bytes.

Pass 6 found no new issues. Source review followed callback pointers, per-page allocations, persistent ID ownership, directory/file descriptors, and the publication boundary through success, failure, and cancellation. The current sources were rebuilt with AddressSanitizer and passed the executable/JSON corpus suites without reports. A SIGKILL/restart regression confirmed that the kernel releases the directory lock, the previous export survives, and the abandoned private staging inode is retained rather than swept by the next run.

Pass 7 found no new issues. The final source/contract review checked argument validation and help, credential precedence, resource limits, response schema, row defaults, file permissions, descriptor ownership, signal exit status, and each side of the publication boundary. `make --always-make check test` rebuilt the optimized executable and passed all 139 reported tests (137 scenarios, including two generated corpus checks). The final code also passed the separate AddressSanitizer run: 108 tests, including the 64 valid and 88 malformed corpus inputs, with no sanitizer reports.

The final executable reached the default Algolia HTTPS endpoint using a deliberately invalid search key, returned HTTP 403 and status 1, preserved the existing CSV, and removed its staging file. This proves production transport and the rejection path; a successful live IndieHackers export still requires valid credentials and has not been claimed.

Review stopped after passes 6 and 7 produced two consecutive passes with no new findings. The prior clean count from pass 4 was reset when pass 5 found the staging replacement bug. The withdrawn positive-return write probe is excluded from the finding count.

Final optimized executable: `build/collector`, SHA-256 `ae8a5393d9426a13fd6e6bb389dde7f6661589bb312f889755cbebfd3b74f291`.