Document full-text boosts and optional scoring by kylebernhardy · Pull Request #778 · HarperFast/documentation

kylebernhardy · 2026-10-31T19:39:51Z

Animated felt-art reading nook with Kyle and Kato, gently swaying felt stars, drifting wool steam and a wagging dark tail

⊙ Problem

Full-text references still name engine 0.7.0 and omit query-policy settings. Developers also need the v5.4 boost/optional-scoring contract alongside its permission and eligibility rules.

💡 Solution

Align upgrade and recovery guidance with published fulltext 0.9.0. Document v5.4 fuzzy/query-policy controls and boost/should: optional clauses add scores without admitting records that fail the required condition.

🤔 What is available?

Kyle confirmed Harper 5.4 as the shipping release. The reference now carries a v5.4.0 badge and the 5.4 notes describe scoring and reserved-key compatibility. Publish alongside Add full-text boosts and optional scoring conditions. Wrapper companion: Add query boosts and optional full-text scoring.

🔧 Changes

Reference changes

Reference	Reader-facing change
Full-text querying	Documents v5.4 fuzzy and scoring controls; defines types, source permissions, reserved keys, limits and HTTP/operations examples.
Resource API and Operations API	Expose condition properties and consistent availability; operations restart guidance includes the captured query policy.
Overview and index configuration	Target engine 0.9.0; distinguish 0.5/0.6 rebuilds from compatible 0.7/0.8 checkpoints and document recovery without qualifying rollback.
Query optimization and REST querying	Separate work budgets from query ceilings, link current native limits and direct scoring to structured requests.
Configuration options and Configuration operations	Define term/clause/distance policy, defaults and ranges; require a full process restart, with exact operations parameter names.
v5.4 release notes	Add the v5.4 scoring release entry and align engine, checkpoint, query-policy, restart and alpha configuration guidance.

✅ Verification

Full-tree formatting, production site build and diff checks passed. All three full-text JSON examples parse. Contract checks used Harper 9ab796aed: its native-plane suite passed 51 tests and deployed HTTP/operations suite passed 20. Those tests cover the documented controls; the page snippets were not separately executed against a released Harper build.

🤔 Final review response

Claude and Composer reviewed 023f6a9d; an independent source review checked 91b33a02 without new findings. The subsequent 5.4 assignment and overlap reconciliation were self-reviewed against fulltext v0.9.0. Final formatting, production build and diff checks passed. Runtime behavior is unchanged.

Merge coordination

Merged current main and resolved both content conflicts, preserving RocksDB upgrade warnings and the full-text process-restart requirement. Reconciled the fuzzy eligibility, preview and host-capacity guidance from Document fulltext 0.8 query policy and fuzzy controls against released wrapper 0.9.0. Shared engine/checkpoint guidance agrees with Document opt-in full-text analytics and the 0.9 engine; its new analytics feature remains in that PR.

Assemble the v5 reference and open release notes from harper and harper-pro deletes these source pages and imports them from code repositories. Its companion Move the v5 reference and 5.4 release notes into docs/ must carry this reconciled content before the site migration lands. The complete content is now ported into Add full-text boosts and optional scoring conditions at 6c252ed00, stacked on the Harper migration branch. Its assembled site build and independent nine-page/three-fragment parity check passed. Keep this PR open as the fallback until the migration and replacement are safely included; do not merge this duplicate after the site migration. Other open branches still need their own conflict resolution.

Comment generated by kAIle (GPT-6)

Release target: main — v5.4 engine, query policy and scoring documentation
Related PRs: #777 overlaps (query policy and fuzzy references), #789 overlaps (engine upgrade and recovery), #788 overlaps (v5 reference assembly)
Complexity: medium

_{Review-Coverage: authored=codex; ran=cursor-composer,claude; adjudicated=domain,domain(claude); blocked=gemini(auth); declined=cursor-grok,muse; rounds=6; full=5 @ 8375a29}

_{Review-Attention: skim ~2m (decisions: pending-contract-in-current-reference, alpha-rollback-partial-steps, absorb-777-scope, conditional-ranking-prose) @ 8375a29}

gemini-code-assist

Code Review

This pull request updates the documentation across several files to describe the pending-release query-time relevance controls, including the new should and boost parameters for full-text search. The review feedback highlights several instances where critical limitations, security warnings, or validation failure conditions are combined with other concepts in a single sentence. To comply with documentation style guidelines, these warnings and limitations—such as those regarding incompatible builds, fuzzy controls, invalid boost values, and unbounded query failures—should be split into separate, distinct sentences.

github-actions · 2026-10-31T19:43:37Z