Define index manifest schema v0.1 #21

New issue

Closed

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

JackFrostbyte commented

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

Owner

Goal

    Define and validate an index manifest that records the lexical index format, build configuration, exact corpus inputs, compatibility, and integrity.

    ## Why

    The runtime must be able to prove which validated records produced an index and detect when the index no longer matches the archive.

    ## Scope

    - Define a narrowly scoped index manifest using the actual requirements of the selected backend.

Record index format and schema version.
Record build tool, backend, and relevant dependency versions.
Record deterministic build configuration.
Identify included and excluded source, document, and chunk records.
Record hashes or equivalent integrity identifiers for corpus inputs.
Record language and compatibility information needed by the runtime.
Define treatment of timestamps so reproducibility is preserved where required.
Record an integrity checksum for the built index artifact or artifact set.
Add schema documentation, positive examples, negative fixtures, and validation tests.
```
  ## Out of scope

  - A deployment-bundle manifest.
```
Vector, embedding, model, translation, speech, or public-release manifests.
Index-builder implementation.

A generalized artifact-signing system.

  ## Dependencies

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

  ## Acceptance criteria

  - The schema represents every input needed to determine whether an index is current and compatible.

Included and excluded records are explicit.
Input and index integrity information is verifiable.
Backend and build configuration are reproducible.
Timestamp behavior is documented and does not create unexplained nondeterminism.
Positive and negative validation tests pass.

The design remains limited to the lexical index.

  ## Validation

  - Validate the example manifest against the new schema.

Exercise missing, duplicate, stale, incompatible, and checksum-invalid negative fixtures.
Run the complete unit-test suite.

Review the schema against the selected backend ADR.

  ## Suggested branch

  `feature/issue-21-index-manifest`

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

## Goal Define and validate an index manifest that records the lexical index format, build configuration, exact corpus inputs, compatibility, and integrity. ## Why The runtime must be able to prove which validated records produced an index and detect when the index no longer matches the archive. ## Scope - Define a narrowly scoped index manifest using the actual requirements of the selected backend. - Record index format and schema version. - Record build tool, backend, and relevant dependency versions. - Record deterministic build configuration. - Identify included and excluded source, document, and chunk records. - Record hashes or equivalent integrity identifiers for corpus inputs. - Record language and compatibility information needed by the runtime. - Define treatment of timestamps so reproducibility is preserved where required. - Record an integrity checksum for the built index artifact or artifact set. - Add schema documentation, positive examples, negative fixtures, and validation tests. ## Out of scope - A deployment-bundle manifest. - Vector, embedding, model, translation, speech, or public-release manifests. - Index-builder implementation. - A generalized artifact-signing system. ## Dependencies - #20 — Evaluate offline full-text search backends and record the decision ## Acceptance criteria - The schema represents every input needed to determine whether an index is current and compatible. - Included and excluded records are explicit. - Input and index integrity information is verifiable. - Backend and build configuration are reproducible. - Timestamp behavior is documented and does not create unexplained nondeterminism. - Positive and negative validation tests pass. - The design remains limited to the lexical index. ## Validation - Validate the example manifest against the new schema. - Exercise missing, duplicate, stale, incompatible, and checksum-invalid negative fixtures. - Run the complete unit-test suite. - Review the schema against the selected backend ADR. ## Suggested branch `feature/issue-21-index-manifest`

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

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

JackFrostbyte added the

area/metadata

type/design

labels

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