Repository navigation
docs(facts): the /_facts wait loop stops on unavailable and not-enabled (#3021) - #3028
Merged
Merged
Conversation
…ed (#3021) Motivation. landing/llms.txt and docs/MODEL_QUICKSTART.md told agents to poll `GET /_facts` until `model.state == "loaded"`. A node started with `--facts-model-dir` pointing at a missing or broken bundle answers 200 with `model.state: "unavailable"`, and a node started without the flag answers `404 xerj_query_not_enabled`. Neither ever becomes `loaded`, so an agent following the docs polled forever (#3021). The prose said "stop polling", the command did not. Change. The loop now reads `.model.state // .error.type` and stops on any non-empty value other than `not_loaded`, then prints it: loaded success unavailable missing/broken bundle; `jq -r .model.error` names the file; point --facts-model-dir at the directory holding bundle.json, facts/, counting/ xerj_query_not_enabled started without --facts-model-dir Empty output (node not up yet) and `not_loaded` (preload running) keep polling. Verified against the v1.0.0-rc.101 x86_64-unknown-linux-gnu release binary on private ports with throwaway data dirs, loop extracted verbatim from llms.txt (timeout 60 s each): --facts-model-dir <missing dir> -> unavailable, rc=0 no flag -> xerj_query_not_enabled, rc=0 --facts-model-dir candidate_a_s47 bundle -> loaded, rc=0 The old loop on the first two states never returns. Test. scripts/seo/test_llms_facts_wait_loop.py extracts the loop from both files and runs it under bash with stub curl/sleep replaying rc.101 bodies and the real jq. Before: 6 failures (the loop times out on unavailable and on not-enabled in both files, plus the missing error text). After: 4/4 OK. Wired into the seo.yml workflow. Not in this change. The engine half of #3021 (fail start-up when the bundle is missing or broken) lives in the facts serving code, which is not in this repository; see the issue comment.
YYW0228
pushed a commit
to YYW0228/xerj
that referenced
this pull request
Nov 7, 2026
The public half of the v1.0.0-rc.102 cut. The release tag goes on this PR's merge commit, so the notes and the tree they describe are one commit. - CHANGELOG.md: [Unreleased] cut over to [1.0.0-rc.102] - 2026-11-06. Every PR merged since v1.0.0-rc.101 is cited (xerj-org#2969 xerj-org#2982 xerj-org#2983 xerj-org#2984 xerj-org#2985 xerj-org#2988 xerj-org#3023 xerj-org#3028 xerj-org#3029 xerj-org#3030) or exempted with its reason (site, blog and donation pages: xerj-org#2971 xerj-org#2972 xerj-org#2976 xerj-org#2978 xerj-org#2980 xerj-org#2990 xerj-org#3032; CI test-only: xerj-org#3031). The release-notes gate passes locally against origin/main 34a2f24. - The XERJ Query-1 numbers in the summary trace to the R8 evaluation (private harness, runs/r8_2026-11-06/R8_RESULT.md): Score v2 on the four development families, 1,600 items, seed 47 90.29 -> 94.69 (+4.40, 95% interval +3.32 to +5.64), seeds 11/29 +3.95/+4.17; stated as in-sample because R8 was chosen on those items; wrong answers 9 -> 10 of 1,600 (s47), 12 -> 15 (s11); held-out fresh_v1 Net 0.3333 -> 0.3481. The 1,600/1,600 engine-vs-Python parity was re-run on the merged rc.102 build tree. - Upgrade notes say plainly that the rc.101 promise to land the storage and ingest lanes on public main before rc.102 was not kept, and that the rc.102 bundle needs an rc.102 binary. - Fixed lists the rc.101 aarch64 Linux assets built with a 4 KiB jemalloc page (checked in the rc.101 build tree: "checking LG_PAGE... 12" for both aarch64 targets), which xerj-org#1663 had fixed in release.yml; rc.102's native aarch64 builds set JEMALLOC_SYS_WITH_LG_PAGE=16. - ROADMAP.md: review line names v1.0.0-rc.102 (the docs_capability_lists check); the open-defects shortlist re-verified live: xerj-org#1122 and xerj-org#1170 open. - engine/Cargo.toml workspace version 1.0.0-rc.102, Cargo.lock restamped (19 workspace packages, no dependency moved). - Landing footer stamps V1.0.0-RC.101 -> V1.0.0-RC.102 (59 pages) and the nav's fallback latest-tag label; landing-constants-guard passes.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Refs #3021 (docs half; the issue stays open for the start-up half).
Problem.
landing/llms.txtanddocs/MODEL_QUICKSTART.mdpollGET /_factsuntilmodel.state == "loaded". A missing or broken bundle answers 200 withmodel.state: "unavailable"; a node without the flag answers404 xerj_query_not_enabled. Neither becomesloaded, so the loop never ends.Change. The loop reads
.model.state // .error.type, keeps polling on empty output (node not up) andnot_loaded, and stops and prints anything else. llms.txt and the quickstart say whatunavailableandxerj_query_not_enabledmean and how to fix each.Verified against the v1.0.0-rc.101 x86_64 release binary, private ports, throwaway data dirs, loop extracted verbatim from llms.txt:
--facts-model-dir <missing dir>unavailablexerj_query_not_enabled--facts-model-dirreal A_s47 bundleloadedTest.
scripts/seo/test_llms_facts_wait_loop.pyruns both loops under bash with stubcurl/sleepreplaying rc.101 bodies and the realjq. Before: 6 failures (loop times out). After: 4/4 OK. Added toseo.yml.No other open PR edits
landing/llms.txt(checked all 58 open PRs).🤖 Generated with Claude Code