discord_bot/specs/SPEC-014-codex.md

SPEC-014 — Codex Mechanicus search

Luma is an Adeptus Mechanicus tech-priest; her lore has a real home — the priest's own Codex Mechanicus at binaric.tech (an Astro/MDX archive, five tongues). A codex_search function tool lets her consult that archive and answer from sourced inscriptions instead of inventing lore. The index is public but still untrusted by the time it reaches a prompt: the fetch is SSRF-guarded (SPEC-011 shares guard_url), size-bounded, and every returned field is sanitized (SAF-03). Luma-only; active only when enable-codex = true.

CDX-01 — codex_search is offered as a tool (coverage: test)

When enable-codex is true, the chat call's tools list includes a codex_search function (query string, optional lang) next to any IGDB / fetch_url tools. When false, it is absent.

CDX-02 — The index is fetched safely and cached (coverage: test)

The index URL (codex-index-url, default https://binaric.tech/search-index.json) passes the SSRF guard before any network call, is read under a byte cap (codex-max-bytes, default 4 MB) with a download timeout, and is cached in memory for codex-cache-ttl (default 3600 s) so repeated searches do not re-fetch.

CDX-03 — Ranking weights title over summary over body (coverage: test)

The query is tokenized (stopwords dropped); each inscription is scored by term hits weighted title (8) > summary (3) > body (1). Results are returned highest-score first, each as {title, summary, collection, url}, with url absolute against the site origin.

CDX-04 — Language is preferred, with fallback (coverage: test)

Results are filtered to the requested lang (en, de, eo, no, uk; default en; unknown codes fall back to en) by the language segment in each inscription URL. If no inscription in that tongue matches, the search falls back to all tongues rather than returning nothing.

CDX-05 — Results are sanitized and failure is reported (coverage: test)

Each title and summary is passed through sanitize_external_text and length-capped (codex-summary-chars, default 500). An index that cannot be fetched or parsed returns an {error: ...} dict the model can relay — search never raises.

CDX-06 — Searches are metered per user (coverage: test)

Each codex_search increments a per-user daily counter; over codex-daily-per-user (default 50) the tool refuses with an error result without touching the index. The budget gate (SAF-04) still applies to the surrounding model calls.

CDX-07 — Luma cites the codex, not invention (coverage: manual)

With the persona grounding line, when a pilgrim asks Cult Mechanicus lore Luma consults codex_search and answers from it, offering the binaric.tech link to read the full inscription rather than hallucinating. Verified live on ggg.