Implement citation resolution and exact passage display #24

New issue

Open

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

JackFrostbyte commented

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

Owner

Goal

    Resolve every search result to the correct authoritative passage and display its provenance, location, offsets, and attribution information.

    ## Why

    Ranked identifiers are not sufficient for a trustworthy archive. Users must be able to inspect the exact source-backed passage, and the runtime must refuse broken citations rather than display the wrong text.

    ## Scope

    - Resolve chunk IDs through document and source records.

Load the exact chunk text and verify it against declared offsets in normalized text.
Expose source title, author or publisher when available, document path, and source/document/chunk IDs.
Expose page, section, heading, or equivalent citation location when available.
Expose exact half-open character offsets.
Expose license and attribution information appropriate for inspection.
Provide an exact-passage display through the search CLI or a reusable presentation layer.
Detect missing files, mismatched text, invalid offsets, broken lineage, and incorrect source locations.
Fail clearly rather than substituting nearby or stale content.
```
  ## Out of scope

  - Generated summaries or answers.
```
PDF visual rendering beyond opening or identifying the authoritative source passage.
Vector search.
Translation.

A graphical interface.

  ## Dependencies

  - #23 — Implement the offline search library and CLI

  ## Acceptance criteria

  - Every valid pilot search result resolves to its correct chunk and authoritative source passage.

Displayed text matches declared offsets exactly.
Provenance and available citation-location metadata are shown.
License or attribution information is available to the user.
Broken lineage, files, offsets, or text cause explicit errors.

The resolver never silently displays a different passage.

  ## Validation

  - Run the complete unit-test suite.

Resolve and manually inspect every expected citation in M2-01.
Exercise missing-file, wrong-text, invalid-offset, and broken-lineage fixtures.

Compare displayed text to the normalized document and original source location.

  ## Suggested branch

  `feature/issue-24-citation-resolution`

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

## Goal Resolve every search result to the correct authoritative passage and display its provenance, location, offsets, and attribution information. ## Why Ranked identifiers are not sufficient for a trustworthy archive. Users must be able to inspect the exact source-backed passage, and the runtime must refuse broken citations rather than display the wrong text. ## Scope - Resolve chunk IDs through document and source records. - Load the exact chunk text and verify it against declared offsets in normalized text. - Expose source title, author or publisher when available, document path, and source/document/chunk IDs. - Expose page, section, heading, or equivalent citation location when available. - Expose exact half-open character offsets. - Expose license and attribution information appropriate for inspection. - Provide an exact-passage display through the search CLI or a reusable presentation layer. - Detect missing files, mismatched text, invalid offsets, broken lineage, and incorrect source locations. - Fail clearly rather than substituting nearby or stale content. ## Out of scope - Generated summaries or answers. - PDF visual rendering beyond opening or identifying the authoritative source passage. - Vector search. - Translation. - A graphical interface. ## Dependencies - #23 — Implement the offline search library and CLI ## Acceptance criteria - Every valid pilot search result resolves to its correct chunk and authoritative source passage. - Displayed text matches declared offsets exactly. - Provenance and available citation-location metadata are shown. - License or attribution information is available to the user. - Broken lineage, files, offsets, or text cause explicit errors. - The resolver never silently displays a different passage. ## Validation - Run the complete unit-test suite. - Resolve and manually inspect every expected citation in M2-01. - Exercise missing-file, wrong-text, invalid-offset, and broken-lineage fixtures. - Compare displayed text to the normalized document and original source location. ## Suggested branch `feature/issue-24-citation-resolution`

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

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

JackFrostbyte added the

area/search

type/implementation

labels

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

JackFrostbyte referenced this issue

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

Detect stale, mismatched, missing, or corrupted indexes #25

JackFrostbyte referenced this issue

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