Skip to content

docs: show sidecar-backed manifest bundle verify/load pattern #198

@Fieldnote-Echo

Description

@Fieldnote-Echo

Context

ordvec-manifest already supports auxiliary artifact verification and VerifiedLoadPlan, which is the right boundary for downstream local database bundles. OrdinalDB should be able to document and implement a .odb directory bundle without duplicating manifest schema, path policy, SHA-256 checks, or probe logic.

The missing piece is a concrete docs example for a bundle that has one ordvec index artifact plus a required caller-owned sidecar, such as:

docs.odb/
  manifest.json
  index.tvrq
  ids.bin

The verifier should own path/size/hash/probe checks. The caller should own the semantic sidecar parser.

Evidence

  • VerifiedLoadPlan exposes the verified primary artifact path and auxiliary artifact plans: ordvec-manifest/src/lib.rs:2760, ordvec-manifest/src/lib.rs:2830, ordvec-manifest/src/lib.rs:2842.
  • AuxiliaryArtifact is part of the public manifest schema: ordvec-manifest/src/lib.rs:2405.
  • The verifier validates auxiliary artifact path, SHA-256, and byte size: ordvec-manifest/src/lib.rs:1845-1978.
  • OrdinalDB’s target bundle shape is exactly manifest.json + index.tvrq + ids.bin.

Acceptance Criteria

  • Add a README or docs example creating an index artifact plus a required sidecar.
  • Example writes index.tvrq through ordvec, declares a required auxiliary sidecar, writes manifest.json, and verifies it.
  • Example load path uses verify_for_load, checks the verified index metadata, loads the index from plan.artifact_path(), then locates the sidecar via the verified auxiliary plan.
  • Docs explicitly state that sidecar byte verification belongs to ordvec-manifest, while semantic parsing of the sidecar remains caller-owned.
  • Include a negative/tamper example or test showing sidecar hash/size mismatch fails before caller parsing.

Non-goals

  • No OrdinalDB-specific .odb API in ordvec.
  • No sidecar schema owned by ordvec.
  • No application ID map semantics in the verifier.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions