Skip to content

manifest: support create-time auxiliary artifacts #194

@Fieldnote-Echo

Description

@Fieldnote-Echo

Context

OrdinalDB’s .odb bundle should be a directory with an ordvec index artifact plus required sidecars such as ids.bin. ordvec-manifest already verifies auxiliary artifacts by path/size/hash, so OrdinalDB should not duplicate path policy or hashing. The remaining gap is ergonomic: create_manifest_for_index_with_options always emits auxiliary_artifacts: Vec::new(), so callers must manually hash sidecars and mutate the manifest before writing.

A create-time auxiliary-artifact API would keep sidecar hashing, path normalization, resource limits, and schema generation inside ordvec-manifest.

Related: #148 covers unified reporting for auxiliary artifacts after verification. This issue is specifically about manifest creation.

Evidence

  • Manifest schema has auxiliary_artifacts: ordvec-manifest/src/lib.rs:3421-3427.
  • CreateManifestOptions currently only carries path policy and limits: ordvec-manifest/src/lib.rs:3317-3322.
  • create_manifest_for_index_with_options probes and hashes the primary index but always leaves auxiliary_artifacts empty: ordvec-manifest/src/lib.rs:3339-3450.
  • The verifier already has path policy and limits for auxiliary artifacts: ordvec-manifest/src/lib.rs:2218-2238.

Proposed Shape

Sketch:

pub struct CreateAuxiliaryArtifact {
    pub name: String,
    pub path: PathBuf,
    pub required: bool,
    pub media_type: Option<String>,
    pub description: Option<String>,
}

pub struct CreateManifestOptions {
    pub auxiliary_artifacts: Vec<CreateAuxiliaryArtifact>,
    // existing fields...
}

Equivalent builder-style API is fine.

Acceptance Criteria

  • Library callers can request one or more auxiliary artifacts at manifest creation time.
  • Sidecar paths use the same path policy as the primary artifact creation path.
  • Sidecar SHA-256 and byte size are computed by shared sha256_file logic.
  • Required vs optional sidecars are represented in the manifest.
  • Duplicate auxiliary names are rejected at create time.
  • Resource limits apply consistently.
  • Tests cover a successful required sidecar, optional sidecar, missing sidecar, duplicate names, absolute path policy, and path-escape policy.
  • Docs include a minimal bundle example: index.tvrq + ids.bin + manifest.json.

Non-goals

  • No semantic parsing of application sidecars. OrdinalDB still validates the ids.bin binary format, duplicate IDs, and ID count.
  • No OrdinalDB-specific schema inside ordvec-manifest.

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