8000 docs(facts): the /_facts wait loop stops on unavailable and not-enabled (#3021) by xerj-org · Pull Request #3028 · xerj-org/xerj · GitHub
[go: up one dir, main page]

Skip to content

docs(facts): the /_facts wait loop stops on unavailable and not-enabled (#3021) - #3028

Merged
xerj-org merged 1 commit into
mainfrom
fix/3021-facts-startup
Nov 7, 2026
Merged

xerj-org merged 1 commit into
mainfrom
fix/3021-facts-startup

Conversation

@xerj-org
@xerj-org xerj-org commented Nov 7, 2026
Copy link
Copy Markdown
Owner

Refs #3021 (docs half; the issue stays open for the start-up half).

Problem. landing/llms.txt and docs/MODEL_QUICKSTART.md poll GET /_facts until model.state == "loaded". A missing or broken bundle answers 200 with model.state: "unavailable"; a node without the flag answers 404 xerj_query_not_enabled. Neither becomes loaded, so the loop never ends.

Change. The loop reads .model.state // .error.type, keeps polling on empty output (node not up) and not_loaded, and stops and prints anything else. llms.txt and the quickstart say what unavailable and xerj_query_not_enabled mean 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:

start-up loop prints exit
--facts-model-dir <missing dir> unavailable 0
no flag xerj_query_not_enabled 0
--facts-model-dir real A_s47 bundle loaded 0

Test. scripts/seo/test_llms_facts_wait_loop.py runs both loops under bash with stub curl/sleep replaying rc.101 bodies and the real jq. Before: 6 failures (loop times out). After: 4/4 OK. Added to seo.yml.

No other open PR edits landing/llms.txt (checked all 58 open PRs).

🤖 Generated with Claude Code

…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.
@cla-bot cla-bot Bot added the cla-signed label Nov 7, 2026
@xerj-org
xerj-org merged commit dbe9498 into main Nov 7, 2026
29 checks passed
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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

0