• File encoding is UTF-8 (errors are replaced, not fatal).
• File lives under the site/ tree and matches glob **/*.org.
• File is not under any excluded subtree:
  • _drafts/
  • templates/
  • includes/
  • orgparse-examples/
• File contains at least one #+TITLE: header with a non-empty value. This is the sole hard gate; all other headers are optional.

A document is only emitted when:

1. #+TITLE is present and non-empty.
2. doc_len > 5= OR keywords is non-empty. (Stubs with fewer than 5 tokens and no keywords are silently dropped.)

• Only the first occurrence of each header key is kept.
• Org source blocks (#+begin_... / #+end_...) are stripped before tokenization; they do not contribute to term frequencies.
• Org drawers (:NAME:... / :END:) are stripped before tokenization.
• Org links [[target][text]] are replaced by their display text.
• Org markup characters ~=*/+_ are replaced by spaces before tokenization.

The index artifact version is _cluster.version. This should be specified in deps.edn (or a dedicated index-config.edn) rather than hard-coded in the indexer source, so that the contract document, the build config, and the runtime all agree on the schema version:

;; Proposed: deps.edn :index alias or standalone index-config.edn
{:index-schema-version 2
 :output-path "site/static/search-index.json"
 :bm25 {:k1 1.2 :b 0.75}
 :top-n-terms 50
 :min-doc-freq 2
 :idf-threshold 3.0}

Currently the version is a literal 2 in pocket-es.indexer. The loader (Contract 3) checks :version at parse time but has no way to reject a schema it does not understand – a version bump without a loader update will silently produce wrong results.

{
  "_cluster": { ... },
  "idf":      { "<term>": <float>, ... },
  "docs":     [ { ... }, ... ],
  "suggest_corpus": [ "<string>", ... ]
}

All four top-level keys are always present.

• Keys: vocabulary terms (strings). Values: floats rounded to 3 decimal places.
• Formula: round(log((N - df + 0.5) / (df + 0.5) + 1), 3) (BM25 IDF).
• Inclusion: doc_freq > 2= OR idf > 3.0.

• Sorted lexicographically. Sources: keyword tokens + title words after stripping non-word characters, lowercasing, filtering stopwords and pure digits.

The following invariants must hold for any valid artifact:

• No deep js->clj on the full blob. Each top-level key is accessed via unchecked-get and converted independently.
• :doc_len is snake_case (not kebab-case) – intentional, matches JSON.
• :avg-dl appears at both top-level and [:cluster :avg-dl]. Scoring uses top-level; cluster map is for display only.
• :terms values are raw JS numbers (shallow conversion).

1. <script data-index-url"…">= attribute – explicit override.
2. location.port == "8700"= → /search-index.json (dev server).
3. Default → /static/search-index.json (published site).

(search idx request) → JS {hits: {total: int, hits: [{_id, _score, _source}]}}

• _score is Math.round(raw_score * 100) – always non-negative integer.
• Results sorted descending by _score. Only score > 0 included.
• Default _source strips :terms and :doc_len.

BM25 parameters: k1=1.2, b=0.75 (constants).

(suggest idx {text: "prefix", size: 10}) → JS ["match1", "match2", ...]

Prefix match against sorted :suggest-corpus. Case-insensitive.

1. #pocket-es-root – standalone HTML
2. #content – org-published page
3. .outline-2 – fallback org layout
4. document.body – final fallback

• Input starts with { and parses as JSON → raw ES request.
• Otherwise → multi_match with ["title^3", "description", "headings^2", "terms"].

search(req), suggest(req), cluster.health(), cat.indices(), cat.count(), _idx.