Skip to content

Add the @harperfast/fulltext native package scaffold - #19

Merged
kylebernhardy merged 9 commits into
mainfrom
codex/issue-9-scaffold
Sep 5, 2026
Merged

Add the @harperfast/fulltext native package scaffold#19
kylebernhardy merged 9 commits into
mainfrom
codex/issue-9-scaffold

Conversation

@kylebernhardy

@kylebernhardy kylebernhardy commented Sep 5, 2026

Copy link
Copy Markdown
Member

Scaffolds @harperfast/fulltext as a pinned Rust/Tantivy Node-API package with a public native façade, stable native error boundaries, platform packaging, and a backend-neutral Tantivy Directory qualification harness. The Rocks façade remains intentionally unexported until Phase 0 proves its caller-owned rocksdb-js lease.

Closes #9.

For the human reviewer

  1. Tantivy Directory will be implemented directly over caller-owned RocksDB instead of materializing filesystem segments. Reversing this remains affordable before the Rocks façade ships; approving it commits Phase 0 to validating durability and read amplification.
  2. Native and Rocks façades will share one native addon rather than separate backend artifacts. A different choice would increase package and ABI complexity and becomes expensive after publication.
  3. This scaffold exports only ./native; ./rocks is added after its lease is proven instead of exposing a placeholder contract. Rejecting this choice delays merging the scaffold or requires committing to an untested ABI.
  4. A caught native panic terminally poisons only the affected handle. The owning executor must serialize mutations; the poison boundary is deliberately not a general synchronization primitive.
  5. runtimeInfo() is Promise-shaped even though its initial addon load is currently synchronous. Changing this after consumers adopt it would be costly.
  6. Directory qualification requires concurrent atomic metadata reads to return either the old or new value without transient failures. This can still change before the Rocks adapter is implemented.
  7. Watch qualification proves content correlation, not strict causal attribution to one notification. The callback performs no directory I/O, avoiding backend lock re-entry.
  8. Test-only panic probes use private ID-keyed functions excluded from generated public declarations. This is inexpensive to revisit if later stateful test APIs need a different shape.

Verification

  • npm run check: formatting, TypeScript, Clippy, 6 Rust tests, 7 Node tests, and the packed-package consumer test passed.
  • cargo deny check: advisories, bans, licenses, and sources passed.
  • Generated declarations remained release-clean, and the native dependency tree and built artifact contained no RocksDB linkage.
  • End-to-end route: the package was installed from npm pack output with consumer lifecycle scripts disabled and its public native entry point loaded successfully. Indexing and search are intentionally not observable in this scaffold.
  • Independent read-only review: Claude returned LGTM with no surviving findings; the native Gemini CLI returned no actionable findings after evidence-based reconsideration. The Gemini run is additional to, and not represented by, the machine-derived pre-push receipt.

Complexity: complicated

Review-Coverage: authored=codex; ran=claude; adjudicated=domain; declined=gemini,cursor-grok,cursor-composer; rounds=9 @ fd89c05

Human-Review-Need: 4 @ fd89c05

@kylebernhardy kylebernhardy added this to the v5.3 milestone Sep 5, 2026
@kylebernhardy
kylebernhardy marked this pull request as ready for review September 5, 2026 20:29
@kylebernhardy
kylebernhardy merged commit 89df005 into main Sep 5, 2026
5 checks passed
@kylebernhardy
kylebernhardy deleted the codex/issue-9-scaffold branch September 5, 2026 20:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Scaffold the Rust and Node-API package architecture

1 participant