Preserve query-local BFCL date arguments

[SonAIengine]

Summary

• add query-local ISO date guidance for BFCL date-like tool arguments and bump the BFCL model cache version
• add repeatable BFCL milestone gates: bfcl-027-gate, bfcl-027-gate-check, bfcl-028-gate, and bfcl-028-gate-check
• add saved-artifact gate checks for XGEN scale acceptance, including schema-context reduction metrics
• add XGEN OpenAPI snapshot capture/check/reuse support with sha256 provenance and the stricter xgen-scale-0.28 gate
• record the X2BEE snapshot-provenance sweep: 15 specs, 2,173 operations, 1,084 unique tools, 8,579 edges, 1.00 hit/recall/selector, 99.78% avg schema reduction
• document the XGEN API Collection build/runtime integration path in docs/integrations/xgen-api-collection.md
• document the full qwen3.6-27B BFCL xgen-0.28 result as a research failure target, not a README/public headline
• add requested-depth deterministic BFCL metrics (recall_at_k, all_tools_found_at_k, argument_schema_coverage_at_k) so selector/rerank upper bounds can be checked before another full model run

Latest BFCL 0.28 Full Result

• artifact: /tmp/gtc-bfcl-028-gate-full-qwen.json
• model/evaluator: qwen3.6-27b, local BFCL-compatible evaluator
• scope: 4 categories, 1000 cases per repeat, row+retrieved, top-k=5, 3 repeats
• gate: fail
• retrieved exact@5: 0.865 vs threshold 0.87
• retrieval@5: 0.953 vs threshold 0.96
• row-source upper-bound preservation: 0.904497 vs threshold 0.96
• parallel_multiple exact@5: 0.730 vs threshold 0.78
• failure inspect: /tmp/gtc-bfcl-028-failure-inspect.json
• deterministic failure-subset upper bound: top_k=30 gives all_tools_found_at_k=0.901099, recall_at_k=0.937729, while fixed top-5 all-tools-found is 0.274725
• main next targets: top-5 rank compression, multi-tool set preservation, sibling ambiguity, optional embedding/rerank ablation

Verification

• git diff --check
• poetry run ruff check .
• poetry run ruff format --check .
• poetry run pytest tests/ -q
• make research-check-unit
• make research-check
• make -n bfcl-027-gate
• make -n bfcl-028-gate
• make bfcl-027-gate-check REPORT=/tmp/gtc-bfcl-date-guidance-limit25-repeat3-row-retrieved-qwen.json pass
• make bfcl-028-gate-check REPORT=/tmp/gtc-bfcl-date-guidance-limit25-repeat3-row-retrieved-qwen.json fails as expected for partial scope
• OUT_DIR=/tmp/gtc-x2bee-openapi-snapshot-028 make xgen-scale-snapshot
• MANIFEST=/tmp/gtc-x2bee-openapi-snapshot-028/manifest.json make xgen-scale-snapshot-check
• MANIFEST=/tmp/gtc-x2bee-openapi-snapshot-028/manifest.json GATE_PROFILE=xgen-scale-0.28 OUT=/tmp/gtc-x2bee-scale-snapshot-sweep-028.json TOP_KS=3,5,10 make xgen-scale-sweep
• make xgen-scale-028-gate-check REPORT=/tmp/gtc-x2bee-scale-snapshot-sweep-028.json pass
• LIMIT=1 REPEATS=1 TOOL_SOURCES=retrieved FAIL_ON_GATE=0 OUT=/tmp/gtc-bfcl-028-endpoint-smoke.json CACHE_DIR=/tmp/gtc-bfcl-028-endpoint-smoke-cache make bfcl-028-gate pass over partial smoke cases
• FAIL_ON_GATE=0 CACHE_DIR=/tmp/gtc-bfcl-date-guidance-limit25-repeat3-row-retrieved-cache-v19 OUT=/tmp/gtc-bfcl-028-gate-full-qwen.json CONCURRENCY=6 PROGRESS_EVERY=50 make bfcl-028-gate completed, gate fail as documented
• make bfcl-028-gate-check REPORT=/tmp/gtc-bfcl-028-gate-full-qwen.json fail as documented
• make bfcl-failure-subset REPORT=/tmp/gtc-bfcl-028-gate-full-qwen.json OUT=/tmp/gtc-bfcl-028-failure-case-ids.txt
• make bfcl-inspect-failures REPORT=/tmp/gtc-bfcl-028-gate-full-qwen.json OUT=/tmp/gtc-bfcl-028-failure-inspect.json TOP_K=5 INSPECT_DEPTH=30 TOOL_SOURCES=retrieved REPORT_TOP_KS=5
• poetry run pytest tests/test_bfcl_tool_selection_benchmark.py tests/test_bfcl_tool_selection_failures.py tests/test_bfcl_tool_selection_hard_cases.py -q
• poetry run python -m benchmarks.bfcl_tool_selection.run --categories simple_python,multiple,parallel,parallel_multiple --top-k 30 --case-ids-file /tmp/gtc-bfcl-028-failure-case-ids.txt

Docs-only commit fd126fb: no additional code tests were required after that commit; git diff --check was run. Commit fdbcbda adds benchmark metrics and was verified with targeted ruff/pytest plus the deterministic failure-subset run above.

[SonAIengine]

Closing this internal stacked PR as superseded by the current main branch. The branch is preserved for history.