a3d065dd8d* fix(release): repair package repo publish
Arch repo metadata and R2 uploads need to be reproducible from CI, with retry hardening for transient Cloudflare failures.
* fix(daemon): stop shutdown log storm
Init waiter must treat ShuttingDown as terminal so daemon shutdown tests do not flood Meson logs while the daemon is stopping.
* refactor(cli): delegate serve to MCP binary
Keep yams serve UX while removing MCP server linkage from yams-cli. The standalone MCP binary owns stdio serving and exits on stdin EOF.
* refactor(cli): move daemon path helpers
Keep CLI path resolution out of YamsDaemon so later link cuts can separate CLI and daemon internals. Full yams_daemon removal still needs a socket-only daemon-client split.
* refactor(daemon): split embedded client
* perf(search): add lean-guided benchmark gates
Add Lean topology/search models, ingestion ablation docs, and focused regression tests for topology and compression threshold behavior.
Extract search observability, keep benchmark-only ablation controls, and make retrieval quality benchmarks default to Simeon while preserving explicit ONNX opt-in.
* refactor(config): move daemon policies
* refactor(daemon): extract plugin runtime
* refactor(daemon): untangle service coordinators
Untangle CLI/MCP from daemon service coordinators and the daemon static lib.
- MetadataRepository uses a daemon-neutral tree-diff callback. The
GraphComponent wrapper moves to src/daemon/components/metadata_graph_bridge.cpp,
owned by the daemon library.
- WriteCoordinator moves to a dedicated build-only yams_write_coordinator
static lib. Drop ResourceGovernor coupling inside the writer loop; batch
sizing still respects config.maxBatchSize.
- AppContext gains enqueuePostIngest callback. ServiceManager wires it to
its own enqueuePostIngest; app services no longer call ServiceManager
directly.
- Embedding repair uses BulkIngestLease/BeginBulkIngestCallback instead of
concrete VectorIndexCoordinator::BulkScope. Daemon dispatchers provide a
lease factory backed by the real coordinator.
- CLI daemon_command uses config helpers instead of YamsDaemon::getXDGRuntimeDir.
- Remove explicit dependency('yams_daemon') from src/cli and tools/yams-mcp.
- Declare missing yams_extraction/yams_ingest deps on yams_app_services so
app services link cleanly without daemon.
Validated:
meson compile -C build/release -j4 yams-daemon yams-cli yams-mcp-server
ninja -C build/release -t commands tools/yams-cli/yams-cli tools/yams-mcp/yams-mcp-server | grep -c libyams_daemon.a -> 0
yams-cli --version, yams-mcp-server init, yams serve --help smoke tests
Size drop on macOS release: yams-cli 41M -> 32M, yams-mcp-server 37M -> 22M.
* fix(cli): keep stdin add local fallback
No embedded daemon now. When yams add - buffers stdin and daemon IPC is missing, store via local app services instead of failing socket_missing.
Validated:
meson compile -C build/debug -j4 yams-cli catch2_cli_commands
MESON_BUILD_ROOT=/Users/trevon/work/tools/yams/build/debug build/debug/tests/catch2_cli_commands 'AddCommand - reads from piped stdin and stores content'
MESON_BUILD_ROOT=/Users/trevon/work/tools/yams/build/debug build/debug/tests/catch2_cli_commands
meson compile -C build/release -j4 yams-cli yams-mcp-server
meson compile -C build/asan-api -j2 yams-cli catch2_cli_commands
MESON_BUILD_ROOT=/Users/trevon/work/tools/yams/build/asan-api ASAN_OPTIONS=halt_on_error=1:abort_on_error=1:print_summary=1 build/asan-api/tests/catch2_cli_commands 'AddCommand - reads from piped stdin and stores content'
ninja -C build/release -t commands tools/yams-cli/yams-cli tools/yams-mcp/yams-mcp-server | grep libyams_daemon.a -> no output
* feat(bench): add xplan multi-arm experiment harness
Unified plan runner, ablation axes, REPORT/ablation docs, and
KPI snapshot so optimization loops stop living in shell matrices.
* feat(formal): expand topology/search Lean contracts
Boundary models for search provenance, construction gates,
and cluster/route objectives so Lean guides correctness while
xplan ranks performance levers.
* feat(search,topology): construction purity + graph expansion path
Raise topology build defaults (min edge 0.25, max component 64) and
split oversized CC pieces so hybrid assist is quality-positive on
scifact. Add GraphNeighbors expansion with medoid-anchor fallback,
structured helpers instead of nested session logic, and BEIR-default
xplan plans. Search engine extraction (fanout/classic pipeline) rides
along as the integration surface for routing.
* feat(topology): add KMeans engine and SGC identity contracts
Register kmeans in the factory with deterministic spherical k-means
over embeddings, and enforce SGC document-identity invariants in
debug builds with matching unit coverage.
* feat(daemon): topology readiness gates and selectable reranker
Drive topologyReady from published epoch/freshness/rebuild/dirty
ingest state (not just KG drain), surface those fields in search
stats, and wire onnx|simeon|auto|none cross-reranker selection.
* chore(search): drop meta_path tuner knobs
Meta-path routing is gone; remove dead TunedParams fields and the
ConfigResolver test for [search.meta_path].
* feat(bench): add topology_purity_validate plan
Repeats=3 validation matrix for construction-purity winners vs
topo_off so MRR deltas can clear run-to-run noise.
* chore: format add_command and config include order
Mechanical clang-format / include reorder only; no behavior change.
* feat(bench): decision-grade xplan loop for search engine
Document search-engine measurement in AGENTS; harden xplan with
repeats=3 plans, quality×latency primaries, mechanism metrics from
debug.jsonl, multi-rep log promotion, and archive superseded topology
plans.
* feat(graph): denser product semantic_neighbor topK
Raise default YAMS_GRAPH_SEMANTIC_TOPK fallback from 4 to 8 so product
graphs leave fewer degree-0 docs for GraphNeighbors expansion.
* feat(search): extract topology assist and cross-rerank seams
Pull topology assist into search_topology_stage (seed merge, skip
reasons, optional vector seed probe default 0). Extract cross_rerank
compute from search_engine. Wire probe via typed config/ConfigResolver.
* feat(bench): product-path search engine ablation plans
Add topology-off component, vector-weight, and tiered-execution xplan
plans (repeats=3) and wire them into the AGENTS measurement loop table.
* fix(ci): repair pre-push fallbacks
* feat(bench): lock-free mid-run builds + multi-corpus gates
xplan skips meson rebuild when the quality binary exists (flock +
YAMS_BENCH_FORCE_BUILD override) to stop multi-arm link races. Add
graph_vector weight and nfcorpus transfer-gate plans; document in AGENTS.
* fix(daemon): keep SearchEngine alive via shared_ptr cache
getCachedEngine previously published a raw pointer that metrics polling
used through rebuild, racing destructor of SearchEngine::Impl (TSAN).
Store and return a shared_ptr snapshot so diagnostic readers pin the
engine for the duration of getConfig/health checks.
Also adds the cautious vectorWeight 0.30→0.20 multi-corpus xplan plan.
* feat(search): route vectors through cached topology
Build and reuse validated topology snapshots, rank routed members by query similarity, and narrow the vector leg to the accepted document set with explicit work diagnostics.
Remove the retired HDBSCAN engine and vendor dependency, preserve typed topology policy through search tuning, and cover the runtime/configuration contracts.
* feat(bench): consolidate search decision plans
Enforce deterministic experiment identity and declared baselines, expose routed/global vector work metrics, and register the focused benchmark contracts.
Promote the compact repeats=3 routing-budget gate, archive superseded topology mechanism screens, and add multi-corpus product calibration plans.
* feat(search): refine topology vector routing
* fix(search): propagate daemon readiness
* feat(bench): measure generalized memory health
* fix(cli): honor in-process fallbacks
* ci: harden smolvm debug builds
* perf(search): route topology through filtered ANN
* feat(bench): measure read-write pressure
* perf(metadata): index symbol lookups on read pool
* fix(daemon): isolate startup reads and maintenance
* feat(bench): replay isolated generalized corpora
* feat(search): add evidence routing pipeline
Replace the blocking smolvm pre-push path with host ASan/TSan validation, harden sanitizer-sensitive smoke tests, and add recovery cleanup for malformed SQLite WAL sidecars.
* refactor(search): unify topology evidence path
Remove classic and sidecar fusion lanes so topology augments the recall-preserving ANN and lexical candidate pool through one product path.
* refactor(bench): prune superseded search lanes
Measure the topology-plus-ANN product path with stable experiment identity and remove obsolete sidecar and tiered controls.
* docs(search): retire stale experiment notes
Keep the benchmark handoff focused on the topology-plus-ANN product lane and its active decision plans.
* refactor(search): prune dead search surfaces
Remove unused fusion, reranker, policy, and router abstractions.
Bound topology materialization and keep document trace payloads opt-in.
* fix(cli): clear build warnings
* fix(xplan): reject stale run identity
* refactor(search)!: remove legacy query stack
Replace the unused AST/ranker/post-processor surface with focused facet aggregation used by product search.
BREAKING CHANGE: removes query parser, result ranker, search filter, and SearchResults container APIs from yams_search.
* refactor(search): type value stage traces
Remove synthetic ComponentResult markers for embedding and concept stages. Preserve failure and timeout states instead of overwriting them with fake successful results.
* refactor(search): isolate benchmark env overlays
Move test-only search environment parsing behind an injectable internal adapter. Keep all existing overlay keys and tuner pin semantics while restoring SearchEngineBuilder to composition.
* refactor(search): unify topology routing options
Snapshot topology policy once at the assist boundary and pass it through routing sessions and diagnostics. Remove repeated scalar copying without changing routing behavior or metric keys.
* fix(search): unify tuner config ownership
Use one complete config-to-params overlay for runtime seeding and no-tuner policy resolution. Reseed attached tuners on setConfig so reported and executed configuration cannot diverge.
* fix(search): snapshot tuner state per query
Read tuned config, params, and state under one lock before routing. Add a TSAN correlation test so adaptive observation cannot produce a torn logical query snapshot.
* fix(search): enforce topology routing contract
Generated configs must preserve hybrid-assist shadow routing, while daemon-backed search must abstain when published topology artifacts are stale. Keep standalone validation and global ANN recall intact.
* fix(daemon): let SQLite reclaim its file
Directly resizing a live database from sampled page counts can truncate pages allocated by concurrent writers. VACUUM must remain the only file-reclamation mechanism.
* fix(metadata): tolerate missing symbol FTS
Readiness lookups can race an unavailable optional FTS migration. Retain the indexed fast path, but retry against the base table when prepare or cached-statement execution proves the capability absent.
* build(fuzz): drop removed query parser target
The optional AFL build still referenced the deleted legacy query parser API and could no longer compile.
* fix(bench): include writes in drain oracle
A zero post-ingest queue is not durable drain while coordinated writes remain queued or in flight.
* fix(daemon): vacuum padded WAL databases safely
|
||
|---|---|---|
| .. | ||
| plans | ||
| schema | ||
| workers | ||
| __init__.py | ||
| analyze_query_class.py | ||
| artifacts.py | ||
| model.py | ||
| README.md | ||
| report.py | ||
| runner.py | ||
| summarize.py | ||
| test_xplan_contracts.py | ||
| validate.py | ||
xplan (engineering)
Unified multi-arm experiment runner for daemon KPI work. Not a product surface.
Commands
python3 tests/benchmarks/xplan/runner.py self-test
python3 tests/benchmarks/xplan/runner.py list-plans
python3 tests/benchmarks/xplan/runner.py list-workers
# BEIR corpora for quality/topology plans (auto-fetched on first run too)
python3 tests/benchmarks/xplan/runner.py download-beir # scifact + nfcorpus
python3 tests/benchmarks/xplan/runner.py download-beir scifact
python3 tests/benchmarks/xplan/runner.py download-beir --list
# Run a plan (writes artifacts under build/benchmarks/)
python3 tests/benchmarks/xplan/runner.py run <plan> --build-dir build/release
python3 tests/benchmarks/xplan/runner.py run <plan> --dry-run
python3 tests/benchmarks/xplan/runner.py run <plan> --arm baseline --arm no_kg
# Regenerate docs for an existing artifact directory
python3 tests/benchmarks/xplan/runner.py report build/benchmarks/<plan>/<stamp>
# Compare two stamps
python3 tests/benchmarks/xplan/runner.py compare \
build/benchmarks/ingest_pipeline/<stampA> \
build/benchmarks/ingest_pipeline/<stampB>
Generated report files (per run)
| File | Contents |
|---|---|
REPORT.md |
Full engineering report: host/git, primary + all metrics, factors, per-arm detail |
ablation.md |
Baseline vs other arms, relative deltas, ranking hints |
metrics.csv |
Flat table for spreadsheets |
report.json |
Machine-readable full report |
summary.md / summary.json |
Compact overview |
arms/<arm>/metrics.json |
Per-arm KPIs + ablation attributes |
All under build/benchmarks/<plan>/<stamp>/ (gitignored).
Layout
tests/benchmarks/xplan/
runner.py # CLI
plans/*.json # experiment definitions
workers/ # measurement adapters + ablation.py
report.py # REPORT.md / ablation.md / csv
summarize.py # compact summary + report hook
schema/ # plan schema
Ablation
workers/ablation.py maps plan factors → env (one-factor-off):
- Search components:
YAMS_SEARCH_*_WEIGHT=0+YAMS_ENABLE_ENV_OVERRIDES=1 - Ingest:
YAMS_BENCH_DISABLE_KG,YAMS_DISABLE_VECTORS, GLiNER - Topology mode / expansion presets (
full64,medoid64,cap8,cap2) inretrieval_quality
Plans (engineering)
| Plan | Focus |
|---|---|
search_component_ablation / subsystem_overhead |
Search engine component one-factor-off (BEIR scifact) |
leg_stage_ablation / simeon_rerank* |
Search pipeline / rerank arms |
ingest_pipeline |
Ingest kg/vectors/gliner (synthetic — throughput, not ranking) |
retrieval_load / repair_ability / ops_timeline / daemon_ops_core |
Daemon KPIs 2–5 |
read_write_pressure |
Equal-budget write-heavy/balanced/read-heavy/read-only daemon load; per-op latency, DB pools, WriteCoordinator pressure, WAL growth, drain, and recovery (repeats=3) |
topology_purity_validate / topology_routing_budget_ablation |
Topology construction purity and routed-vs-global ANN budget gate (repeats=3) |
search_generalized_memory_topology_gate |
SciFact + NF-Corpus in one index; per-source quality, cross-source interference, and topology-vs-global cost (repeats=3) |
search_simeon_ann_attribution_multicorp |
Mixed-corpus text/current-PQ/exact-vec0 attribution over identical Simeon embeddings (repeats=3) |
plans/archive/* |
Superseded plans (historical only) |
Agent measurement loop and plan selection: repo AGENTS.md (Benchmarks & Experiments).
Corpora
| Kind | Used by | Notes |
|---|---|---|
| BEIR scifact (default for quality) | search_component_*, topology_*, simeon_rerank*, leg_stage_* |
~/.cache/yams/benchmarks/scifact; auto-download on run |
| BEIR nfcorpus | optional plan override dataset=nfcorpus |
same cache layout |
| Mixed BEIR memory | search_generalized_memory_topology_gate |
one daemon/index containing namespaced SciFact + NF-Corpus documents and queries |
| synthetic | ingest/load/ops throughput only | not for ranking ablations — opt-in via "dataset": "synthetic" |
Default quality params: dataset=scifact, corpus_size=2000, num_queries=50.
Plans with separate SciFact and NF-Corpus arms test transfer between isolated indexes; they do
not model generalized memory. A retrieval-quality plan can set datasets to two or more BEIR
names to materialize one content-deduplicated local-manifest for the entire run. The worker
namespaces document/query IDs, remaps duplicate-content qrels, and reports per-source MRR/recall
plus mixed_cross_source_result_rate and mixed_cross_source_top1_rate from the shared ranking.
The benchmark also exports topology_clusters.json and derives mixed_cluster_overlap.json, which
shows source counts, entropy, and purity for every cluster. Aggregate metrics distinguish the
fraction of cross-source clusters from the fraction of documents exposed to those clusters;
content duplicated across corpora is reported separately and excluded from partition purity.
For state-sensitive search ablations, shared_warm_cache primes one immutable YAMS store and clones
it into each measured arm/repeat. This fixes corpus, vector index, tuner state, and persisted
topology without letting one workload mutate the next workload's input. Topology plans can also set
require_topology_construction_identity=true; the worker pins the first construction fingerprint
and fails on within-workload, cross-repeat, or cross-arm drift. Do not point multiple measured arms
at one live warm directory: that preserves topology but carries mutable query/tuner state forward.
Evaluate ingestion changes in two lanes at the same code revision. Use
search_generalized_memory_topology_gate after the index settles for mixed-memory quality and
route purity. Use retrieval_load for concurrent adds/searches through the daemon; it reports
post-ingest backlog plus WriteCoordinator queue depth, in-flight work, apply time, queue wait, and
excess queue wait. Do not combine these into one score: promote an ingestion change only when it
preserves the per-source quality floor and improves or holds the read-under-write pressure KPIs.
Use read_write_pressure when the question is contention rather than search-component attribution.
Its arms execute the same operation budget per client, vary only the read/write mix, and subtract a
post-warmup infrastructure baseline from cumulative queue/WAL counters. Point-in-time queue depth
and the workload high-water delta are both retained so short bursts are not hidden by sampling.
Set harness-only YAMS_BENCH_CORPUS_SEED_DIR to a frozen YAMS data directory to give every
arm/repeat an isolated copy-on-write corpus; YAMS_BENCH_SEARCH_QUERY can select a representative
symbol or concept. The source directory is never opened by the daemon and remains unchanged.
Rules
- No new multi-arm shell scripts. Wrappers under
scripts/only. - Prefer typed config for product knobs;
YAMS_BENCH_*is harness-only. - Do not rank search levers on synthetic — BEIR only (or another labeled hard corpus).
- Topology claims need
debug.jsonlcounters / certificates. - Multi-client plans need a Catch2-enabled builddir.
- Published numbers:
docs/benchmarks/README.md(default system only).
Known infrastructure debt
yams graph --explorecan fail with a local indexSQL logic errorfor valid readiness symbols (observed onSearchEngineManager::getSnapshot/rebuildNow). The fallback is a targeted local read after YAMS retrieval identifies the files. Follow-up: captureyams doctordiagnostics, verify graph/index schema integrity, and add a regression fixture before changing graph-query behavior.