Run commands from facilitator/. The service uses tsx for maintenance
commands and writes durable state to the configured PostgreSQL database.
Build and service
npm run build builds the published Bazaar SDK first and then compiles the
facilitator. npm run dev watches src/server.ts; npm start runs the
compiled service from dist/.
Database and keys
The key CLI accepts rotate-sponsor, add-channel, or disable-channel, then
the network and optional channel address. Key material is encrypted before insertion into managed_keys; the
encryption key is supplied through the configured environment variable. Never
put a Stellar secret in YAML, a command history, or a client payload.
Search index
status reports active generation, provider/vector health, queue depth, and
dead-letter jobs. backfill enqueues missing vectors. reindex creates or
activates a new generation according to the configured model identity.
revive requeues dead-lettered jobs after an operator fixes the underlying
provider or document problem.
Indexing jobs are safe across replicas because claims use PostgreSQL row locks,
leases, and fencing tokens. Payment requests do not wait for embedding work.
Fast search checks
The first command runs the small checked-in search evaluator. The model report
describes the local embedding runtime. test:live-model loads a pinned model,
checks dimension, normalization, determinism, mismatch rejection, and artifact
checksum. Set FACILITATOR_LIVE_MODEL_REPO=Xenova/bge-m3 and
FACILITATOR_LIVE_MODEL_DIM=1024 to exercise the shipped BGE-M3 path.
Benchmark lifecycle
Controlled dataset
The CDP fetch and candidate-generation steps are optional development inputs.
The judge reads OPENROUTER_API_KEY only from the environment and defaults to
deepseek/deepseek-v4-flash-0731. Human calibration is a separate import; a
model response is never relabeled as human review.
Production retrieval evaluation
The release evaluator creates an isolated PostgreSQL schema, proves its table
ownership, seeds the frozen corpus, runs lexical/semantic/hybrid/reranked
profiles through SearchService, and drops the schema after the run. It never
truncates an operator’s catalog.
Handwritten evaluation v2
These commands operate on the versioned handwritten-evals/ artifacts and
report status without silently converting provisional labels into release
evidence. See evaluation workflow.
Ecosystem cohort
The source-diverse benchmark has separate commands so its provenance cannot be
confused with the controlled Stellar fixture corpus:
Foreign snapshots are not automatically redistributed under this repository’s
Apache-2.0 license. The fetch manifest, hashes, transformed .example fixtures,
and provenance metadata are the reproducible boundary.
Tests and release checks
test:live submits real testnet transactions and requires funded accounts and
the configured facilitator. Integration tests require PostgreSQL. License
checks cover the locked dependency tree; the OpenZeppelin Relayer/AGPL path is
not a base dependency.
For the full release gate, run the benchmark validation, human calibration,
model/index completeness, latency thresholds, adversarial checks, and final
report together. A green unit suite alone is not a search-quality or pubnet
conformance claim. Last modified on August 10, 2026
