limitations.md

Known limitations

• Compiled posting arrays remain JavaScript number[] rows. Stage 2C keeps token/lemma/set/position state in packed views instead of per-document object graphs, but compiled posting identity for Stage 2B is still those arrays. Mapped artifacts remain future work. Stage 3A may skip unread 1-of-k body ordinals using additive presence masks; it does not pack posting arrays.
• Complete searchDetailed() diagnostics still require a full ranking plan. Normal search()/Worker results use the exact representative-reduced final ranker. Stage 3A unread-block skipping applies only to the supported ordinary exact multi-token compiled search() class; searchDetailed() and other unsupported classes fail closed to exhaustive compiled retrieval. The canonical Stage 3A fail-closed list is in exact-pruning.md. Ordinary eligible search() may rank from packed ranking-evidence views; searchDetailed(), explain: true, exhaustive diagnostics, and complete-interpretation collection stay on the FeatureVector diagnostic path. Stage 1 still computes a full ordered plan when public diagnostics require candidate titles, cycle membership, conflict cardinality, absolute ranks, or explanation successors. A future implementation can derive these from signature cardinalities and ordered bucket streams without changing their semantics.
• High-DF posting work remains. The exact indexed retriever still walks competitive / conjunction posting regions. Stage 3A may skip unread 1-of-k body-only ordinals once stronger co-occurrence classes have filled the required representative stream. Stage 2B may skip a posting array only after this query has already decoded it. Prefix expansion and new lemma surfaces remain exhaustive. candidateLimit is not an exactness bound.
• Prefix expansion may remain expensive. Exact prefix search enumerates matching terms. There is no recall cap. A high-DF prefix on a small corpus can cost more than a rare exact title on a large corpus.
• Optimization eligibility is narrower than all indexed queries. Recall-heavy equivalent/topical/standalone queries, configured-prefix-recall queries, dotted/version queries, bound contextual completion, short-literal leads, custom retrievers or custom constraints, nonzero retrieval-score weight, and all-strong fail closed to the previous exact FeatureVector path. Fallback preserves correctness; it is not a ranking-quality degradation. See scaling.md.
• Competitive conjunction documents still require exact ranking evidence. Exact directClass and builtin constraint-signature membership can depend on body evidence (bodyLexicalMatch, body vs title phraseAdjacency, bodyPhraseCount). Stage 3A still evaluates conjunction and partial-conjunction documents, then may skip remaining 1-of-k body-only ordinals. Conjunction/partial-conjunction cardinality still scales with corpus size on the measured VPN-like workload (25k → 100k remaining work ≈ 4×). Eligible ordinary search() records that evidence during retrieval and ranks from packed views instead of constructing a FeatureVector per retrieved direct. searchDetailed() and ineligible shapes still extract FeatureVectors. There is no production lazy FeatureVector evaluator and no approximate top-K. A title-first remaining-score bound is investigation evidence only; see lazy-features.md. Absolute milliseconds live in scaling.md; they are not an SLA and not flat scaling.
• Practical range is workload-dependent. Indexed search has been validated through about 100k documents; roughly 50k–100k is the currently demonstrated practical range, subject to query mix, environment, artifact size (~54 MB lexical at 100k on the Stage 3A VPN-like machine), and latency needs. Browser and runtime memory matter. Million-document ordinary search under 50 ms is not achieved. That is not a quality cliff; see scaling.md and compact-runtime.md.
• Relationship channels can require deep representatives. Public direct and related rows expose absolute global rank; explain rows also expose constraintsVsNext. Preserving those values may require retaining the complete global prefix through the deepest requested channel row, so representativeDepth can exceed max(limit, relatedLimit).
• Analyzed document and ranking memory. RSS is process resident size, not retained heap. 0.3.1 removed the old Θ(C²) retained pair reports and packed the remaining constraint graph. 0.4.0 builtin ranking compares signatures (B) in the common case; worst case remains Θ(C²) when B = C or constraints are custom. Pass retriever: "full-scan" only as an explicit small-corpus/reference mode.
• No incremental updates. Artifact-omitted index() rebuilds from replacement documents. After a supplied artifact has been consumed, re-indexing the identical validated corpus reuses its hydrated state and incompatible replacement input rejects.
• No native Android package.
• No query-semantic retriever, vector DB, or ANN. Measured lexical retrieval did not justify them for v0.
• Hyphen aliases (wifi vs Wi-Fi) need corpus decisions.
• Adaptive threshold is corpus- and hardware-sensitive. 1500 is a default, not a guarantee.
• score is unstable. Constraints are the correctness model.
• Custom retrievers are experimental; they leak internal query/index shapes and use the FeatureVector fallback path.

Future work (not started)

Million-document ordinary low-latency search, exact prefix-range skipping without a recall cap, incremental updates, and native ports. Do not treat those as promised. 0.6.5 is the last planned constant-factor v1 performance release for now; further Stage 3A / WAND / compound-state productization is not the committed next slice. See scaling.md.

Ranking internals (behavior-preserving; not a ranking redesign):

• Builtin ranking groups candidates by constraint signature and compares O(B²) signature pairs. Exact indexed retrieval first keeps a proven per-signature prefix; custom constraint functions fail closed to all candidates. Cycle diagnosis for the pairwise path reuses that graph and its SCC result. Unordered pair objects are no longer retained. Directed edges use packed uint32 chunks rather than one JS array per edge. SCC adjacency is exact CSR; reverse CSR is not retained into ordering. DEFAULT_CANDIDATE_LIMIT remains an accepted compatibility constant, not an exact retrieval budget.
• Ready components are extracted with a binary heap keyed by best candidate score, then document.id. Incomparable buckets interleave; they are not concatenated.