Evaluate offline full-text search backends and record the decision #20

New issue

Open

opened 2026-07-24 19:38:19 -04:00 by JackFrostbyte · 0 comments

JackFrostbyte commented

2026-07-24 19:38:19 -04:00

Owner

Goal

    Evaluate suitable lightweight lexical search backends against the pilot corpus and retrieval fixtures, then record the selected backend in an architecture decision record.

    ## Why

    Arkive needs a backend chosen from measured project requirements: offline operation, deterministic builds, Unicode behavior, citation metadata, constrained resources, and long-term maintainability.

    ## Scope

    - Identify a small set of plausible offline full-text search backends.

Build minimal throwaway evaluations against the actual five-document corpus and M2-01 fixtures.
Measure or compare deterministic build behavior, Python integration, CPU use, RAM use, index size, query latency, Unicode handling, filters, portability, citation metadata support, and maintenance burden.
Document licensing and redistribution implications of each candidate dependency.
Record the selected backend and rejected alternatives in a new ADR.
Define the architectural boundary between the search core and presentation.
Delete or clearly isolate disposable evaluation code that is not part of the selected implementation.
```
  ## Out of scope

  - Production index-builder implementation.
```
Vector or hybrid retrieval.
LLM evaluation.
A user interface.

Premature optimization for a large corpus.

  ## Dependencies

  - #19 — Define retrieval evaluation fixtures and success criteria

  ## Acceptance criteria

  - At least two credible backends are compared against the same fixtures.

The decision is supported by recorded evidence rather than popularity alone.
The ADR covers offline use, determinism, resources, Unicode, citation support, portability, licensing, and maintenance.
The selected backend can preserve Arkive source, document, and chunk identifiers.

No vector or LLM dependency is introduced.

  ## Validation

  - Run the M2-01 fixture set against each evaluated backend.

Record reproducible evaluation commands and environment details.
Verify the selected backend operates with networking disabled.

Review and approve the ADR.

  ## Suggested branch

  `feature/issue-20-search-backend-adr`

  <!-- arkive-planning-automation:2026-07-24-v3:M2-02 -->

## Goal Evaluate suitable lightweight lexical search backends against the pilot corpus and retrieval fixtures, then record the selected backend in an architecture decision record. ## Why Arkive needs a backend chosen from measured project requirements: offline operation, deterministic builds, Unicode behavior, citation metadata, constrained resources, and long-term maintainability. ## Scope - Identify a small set of plausible offline full-text search backends. - Build minimal throwaway evaluations against the actual five-document corpus and M2-01 fixtures. - Measure or compare deterministic build behavior, Python integration, CPU use, RAM use, index size, query latency, Unicode handling, filters, portability, citation metadata support, and maintenance burden. - Document licensing and redistribution implications of each candidate dependency. - Record the selected backend and rejected alternatives in a new ADR. - Define the architectural boundary between the search core and presentation. - Delete or clearly isolate disposable evaluation code that is not part of the selected implementation. ## Out of scope - Production index-builder implementation. - Vector or hybrid retrieval. - LLM evaluation. - A user interface. - Premature optimization for a large corpus. ## Dependencies - #19 — Define retrieval evaluation fixtures and success criteria ## Acceptance criteria - At least two credible backends are compared against the same fixtures. - The decision is supported by recorded evidence rather than popularity alone. - The ADR covers offline use, determinism, resources, Unicode, citation support, portability, licensing, and maintenance. - The selected backend can preserve Arkive source, document, and chunk identifiers. - No vector or LLM dependency is introduced. ## Validation - Run the M2-01 fixture set against each evaluated backend. - Record reproducible evaluation commands and environment details. - Verify the selected backend operates with networking disabled. - Review and approve the ADR. ## Suggested branch `feature/issue-20-search-backend-adr`

JackFrostbyte added this to the Offline Search Proof Loop v0.1 milestone

2026-07-24 19:38:19 -04:00

JackFrostbyte added the

type/design

area/search

labels

2026-07-24 19:38:19 -04:00

JackFrostbyte added a new dependency

2026-07-24 20:10:49 -04:00

#19 Define retrieval evaluation fixtures and success criteria

JackFrostbyte added a new dependency

2026-07-24 20:10:50 -04:00