This document defines what a conforming pocket-es implementation must do, not how. An agent reading this spec should be able to build a compatible system in any language and verify it against the same test fixtures.

pocket-es has exactly two wire contracts, each independently versioned:

The index schema describes data at rest; the search request schema describes the query in flight. They version separately because they change for different reasons: the index schema changes when the indexer emits new fields, the request schema when search() accepts a new query shape. A conforming deployment documents and validates both.

The index is a single JSON file. A conforming index has this shape:

{
  "_cluster": {
    "name":       string,     // index identity
    "version":    integer,    // index-schema version (currently 2)
    "built_at":   string,     // ISO 8601 timestamp
    "git_sha":    string,     // source commit
    "doc_count":  integer,    // total documents
    "vocab_size": integer,    // unique terms after stopword removal
    "avg_dl":     float       // average document length in tokens
  },
  "idf": {                   // term → IDF score (precomputed)
    "<term>": float,
    ...
  },
  "docs": [                   // one entry per indexed org file
    {
      "_id":         string,  // relative path without .org or /index
      "_dir":        boolean, // true if source was index.org (dir-form)
      "title":       string,
      "date":        string,  // YYYY-MM-DD or partial
      "keywords":    [string],
      "description": string,
      "headings":    [string],  // first 15 section headings
      "terms":       {"<term>": integer},  // top 50 term frequencies
      "doc_len":     integer  // total token count
    }
  ],
  "suggest_corpus": [string]  // prefix completion candidates
}

The _id and _dir fields determine the live URL:

Tokenization is the shared contract between the indexer and every client. A conforming tokenizer satisfies these invariants:

Parameters: k1 = 1.2, b = 0.75.

For a single term t against document d:

tf    = doc.terms[t] or 0
dl    = doc.doc_len
idf_v = idf[t] or 0
numer = tf * (k1 + 1)
denom = tf + k1 * (1 - b + b * dl / avg_dl)
score = idf_v * numer / denom   (0 if denom == 0)

Multi-term queries sum per-term scores. Field boosts multiply the sum.

The second wire contract: what search() accepts. Every input surface (free text, JSON, and the phase-B simple/lucene producers) terminates in one IR; this schema is that IR written down. Authoritative source is the malli schema pocket-es.dsl/SearchRequest (see query-surface-spec); this is its language-neutral description.

{
  "$schema_version": 1,          // request-schema version (optional; defaults to 1)
  "query": <Query>,              // required -- exactly one query container
  "size":  integer,              // optional, 1..100
  "from":  integer               // optional, >= 0
}

A <Query> is an object with exactly one of these keys:

A conforming implementation must support these query types:

The browser UI manages six atoms and a URL with four parameters:

A conforming index supports these access patterns:

All consumers must produce identical ranking for the same query against the same index. The BM25 parameters (k1, b) and the tokenizer (stopwords, normalization) are the shared contract.

A conforming deployment passes these checks:

1. Index integrity. doc_count = length(docs)=, all IDF terms present
2. URL resolution. Every _id resolves to HTTP 200 using the _dir rule
3. Tokenization contract. Property tests pass (4 invariants, 300+ iterations)
4. Scoring determinism. Same query returns same results across consumers
5. State round-trip. URL with q, d, p params restores identical view
6. No stopwords in index. No term in any doc's terms map is a stopword
7. Date sanity. No doc has date matching the AI review date (2024-08-11)
8. Description tone. No description contains slop markers (delve, comprehensive, explore, etc.)
9. Index schema version. _cluster.version is present, integer, and recognized
10. Request schema conformance. Every IR the JSON surface forwards to search() is valid per the Search Request Schema, or search() is never called and an inline error is shown instead
11. Producer/consumer agreement (refutation hook). dsl/explain (free-mode-IR s) is nil for all s (the free producer never emits an IR the schema rejects)