feat: safe-by-default SignLoadPolicy for verified loads

benchmarks/arxiv-precomputed/src/main.rs

@@ -13,7 +13,7 @@
 
 use clap::Parser;
 use ordinaldb::manifest::{CreateManifestOptions, VerifyOptions};
-use ordinaldb::{DenseLoadOptions, DenseSearchOptions, OrdinalIndex};
+use ordinaldb::{DenseLoadOptions, DenseSearchOptions, OrdinalIndex, SignLoadPolicy};
 use std::fs::File;
 use std::io::{BufRead, BufReader, Read, Write};
 use std::path::{Path, PathBuf};
@@ -322,7 +322,7 @@ fn main() {
         &manifest_path,
         VerifyOptions::default(),
         DenseLoadOptions {
-            require_sign: true,
+            sign: SignLoadPolicy::Require,
             expected_dim: Some(dim),
             expected_bits: Some(BITS),
         },

cookbook/supportsearch/src/index.rs

@@ -8,7 +8,9 @@ use std::path::{Path, PathBuf};
 use ordinaldb::artifacts::{MANIFEST_FILE, SPARSE_BM25_AUX_NAME};
 use ordinaldb::hybrid::{Bm25MmapIndex, SparseIndexBuilder, TokenizerKind};
 use ordinaldb::manifest::{AuxiliaryArtifactDeclaration, CreateManifestOptions, VerifyOptions};
-use ordinaldb::{BuildOptions, DenseLoadOptions, IdMapIndex, OrdinalIndexBuilder, SignPolicy};
+use ordinaldb::{
+    BuildOptions, DenseLoadOptions, IdMapIndex, OrdinalIndexBuilder, SignLoadPolicy, SignPolicy,
+};
 
 use crate::corpus::{corpus, Doc};
 use crate::embedder::{Embedder, DIM};
@@ -87,7 +89,7 @@ pub fn build_and_persist(
 
     // Dense (OrdVec) side.
     // DIM=384 is sign-capable; Required fails fast instead of silently
-    // writing a bundle the require_sign load below would reject.
+    // writing a bundle the Require-policy load below would reject.
     let mut dense_builder = OrdinalIndexBuilder::new(
         DIM,
         BITS,
@@ -121,7 +123,7 @@ pub fn build_and_persist(
         &manifest_path,
         VerifyOptions::default(),
         DenseLoadOptions {
-            require_sign: true,
+            sign: SignLoadPolicy::Require,
             expected_dim: Some(DIM),
             expected_bits: Some(BITS),
         },

examples/downstream-smoke/src/main.rs

@@ -3,7 +3,9 @@ use ordinaldb::hybrid::{
     rrf_fuse_batch, Bm25MmapIndex, RrfConfig, SparseIndexBuilder, TokenizerKind,
 };
 use ordinaldb::manifest::{AuxiliaryArtifactDeclaration, CreateManifestOptions, VerifyOptions};
-use ordinaldb::{BuildOptions, DenseLoadOptions, IdMapIndex, OrdinalIndexBuilder, SignPolicy};
+use ordinaldb::{
+    BuildOptions, DenseLoadOptions, IdMapIndex, OrdinalIndexBuilder, SignLoadPolicy, SignPolicy,
+};
 use std::fs;
 use std::path::{Path, PathBuf};
 
@@ -37,7 +39,7 @@ fn main() {
         .expect("write sparse mmap");
 
     // dim=64 is sign-capable; Required fails fast instead of silently
-    // writing a bundle the require_sign load below would reject.
+    // writing a bundle the Require-policy load below would reject.
     let mut dense_builder = OrdinalIndexBuilder::new(
         dim,
         2,
@@ -70,7 +72,7 @@ fn main() {
         &manifest_path,
         VerifyOptions::default(),
         DenseLoadOptions {
-            require_sign: true,
+            sign: SignLoadPolicy::Require,
             expected_dim: Some(dim),
             expected_bits: Some(2),
         },

ordinaldb/src/error.rs

@@ -251,10 +251,9 @@ pub enum DenseError {
     /// constructed; a lower-level error than
     /// [`Self::ManifestVerification`].
     Manifest(ordvec_manifest::ManifestError),
-    /// A required auxiliary artifact declared on the manifest (for example
-    /// a sign sidecar requested via
-    /// [`crate::ordinal::DenseLoadOptions::require_sign`]) was missing or
-    /// invalid.
+    /// An auxiliary artifact declared on the manifest and required by the
+    /// load (for example a sign sidecar the [`crate::SignLoadPolicy`]
+    /// load policy requires) was declared but not loadable.
     Auxiliary(ordvec_manifest::RequireAuxiliaryError),
     /// The flat `queries` buffer length is not a multiple of `dim` (or
     /// `dim` is `0`, which only occurs when searching a lazily-constructed,
@@ -283,7 +282,13 @@ pub enum DenseError {
     /// [`crate::SignPolicy`] build policy allows one).
     /// `DenseSearchMode::Auto` never produces this error — it silently
     /// falls back to an exact scan instead.
+    ///
+    /// Also returned by a verified load whose [`crate::SignLoadPolicy`]
+    /// requires a sign sidecar the bundle does not declare.
     MissingSignSidecar,
+    /// The load policy is [`crate::SignLoadPolicy::Forbid`] but the
+    /// verified bundle declares a sign sidecar.
+    SignSidecarForbidden,
     /// An internal consistency check failed with a human-readable
     /// `message` — for example, a verified bundle's manifest metadata
     /// (dim/bits/row count) disagreeing with the artifact actually loaded
@@ -348,6 +353,9 @@ impl fmt::Display for DenseError {
                 "invalid query value at query {query_index}, coord {coord_index}: {value}"
             ),
             Self::MissingSignSidecar => f.write_str("verified dense load requires a sign sidecar"),
+            Self::SignSidecarForbidden => f.write_str(
+                "verified dense load forbids a sign sidecar, but the bundle declares one",
+            ),
             Self::MetadataMismatch(message) => f.write_str(message),
             Self::RowIdentity(message) => f.write_str(message),
             Self::AllowlistRowIdMissing(id) => {
@@ -374,6 +382,7 @@ impl Error for DenseError {
             Self::InvalidQueryDim { .. }
             | Self::InvalidQueryValue { .. }
             | Self::MissingSignSidecar
+            | Self::SignSidecarForbidden
             | Self::MetadataMismatch(_)
             | Self::RowIdentity(_)
             | Self::AllowlistRowIdMissing(_)

ordinaldb/src/id_map.rs

@@ -700,13 +700,16 @@ impl IdMapIndex {
 
     /// Load a bundle directory previously written by [`Self::write`] or
     /// [`Self::write_verified_bundle`], with default manifest
-    /// verification.
+    /// verification and the default sign-sidecar load policy
+    /// ([`crate::SignLoadPolicy::RequireIfSupported`]).
     ///
     /// # Errors
     /// Returns an `InvalidData` [`std::io::Error`] if the bundle is
     /// missing its ID sidecar (it was written by a bare [`OrdinalIndex`] —
     /// load it with [`OrdinalIndex::load`] instead), fails manifest
-    /// verification, or is otherwise malformed.
+    /// verification, is a sign-capable bundle missing its sign sidecar
+    /// (use [`Self::open_verified`] with [`crate::SignLoadPolicy::Any`] to
+    /// load it without one), or is otherwise malformed.
     pub fn load(path: impl AsRef<std::path::Path>) -> std::io::Result<Self> {
         let artifacts = crate::io::load_id_map_bundle(path)?;
         let inner = OrdinalIndex::from_loaded_parts(artifacts.rankquant, artifacts.sign)?;

ordinaldb/src/io.rs

@@ -611,8 +611,19 @@ fn load_bundle(path: &Path) -> io::Result<LoadedBundle> {
         ));
     }
 
+    // This backs the convenience `load()` entry points, which take no
+    // `DenseLoadOptions`; they inherit the same default sign policy as
+    // `open_verified` (`SignLoadPolicy::RequireIfSupported`).
+    // TODO(PR2): type this error surface as `DenseError` instead of an
+    // `InvalidData` `io::Error`.
     let sign = match auxiliary_path(&plan, SIGN_AUX_NAME)? {
         Some(path) => Some(SignBitmap::load(path)?),
+        None if crate::ordinal::sign_compatible(metadata.dim, metadata_bits) => {
+            return Err(invalid_data(
+                "sign-capable bundle (bits=2, dim divisible by 64) has no sign sidecar; \
+                 open it with open_verified and SignLoadPolicy::Any to load without one",
+            ));
+        }
         None => None,
     };
     let ids_path = auxiliary_path(&plan, IDS_AUX_NAME)?;

ordinaldb/src/lib.rs

@@ -53,14 +53,19 @@
 //! a bundle back:
 //!
 //! - `OrdinalIndex::load` / `IdMapIndex::load` open a bundle *directory*
-//!   with default verification.
+//!   with default verification and default load options.
 //! - `OrdinalIndex::open_verified` / `IdMapIndex::open_verified` open a
 //!   bundle from an explicit `manifest.json` path with caller-controlled
 //!   [`manifest::VerifyOptions`] (size limits, path-escape policy) and
-//!   [`ordinal::DenseLoadOptions`] (require a sign sidecar, assert an
+//!   [`ordinal::DenseLoadOptions`] (sign-sidecar load policy, assert an
 //!   expected `dim`/`bits`), reporting mismatches as a [`DenseError`]
 //!   instead of a generic I/O error.
 //!
+//! Both paths default to [`SignLoadPolicy::RequireIfSupported`]: a bundle
+//! whose `(dim, bits)` can carry a sign sidecar must have one to load.
+//! Pass [`SignLoadPolicy::Any`] to `open_verified` to load such a bundle
+//! without its sidecar.
+//!
 //! Loading an `OrdinalIndex` bundle that actually carries an ID sidecar
 //! (or vice versa) is a load-time error that names the correct type to use.
 //!
@@ -135,6 +140,6 @@ pub use ordinal::{
     rankquant_compatible, rankquant_required_multiple, sign_compatible, sign_required_multiple,
     BuildOptions, DenseBundleInspectReport, DenseLoadOptions, DenseSearchExecution,
     DenseSearchMode, DenseSearchOptions, DenseSearchPlan, DenseSearchReport, DenseSearchTimings,
-    OrdinalIndex, OrdinalIndexBuilder, SearchResults, SignPolicy, TwoStageOptions,
+    OrdinalIndex, OrdinalIndexBuilder, SearchResults, SignLoadPolicy, SignPolicy, TwoStageOptions,
     VerifiedBundleReport,
 };

ordinaldb/src/ordinal.rs

@@ -82,13 +82,36 @@ impl Default for BuildOptions {
     }
 }
 
+/// Policy controlling whether a verified load requires, tolerates, or
+/// rejects a sign sidecar on the bundle (see [`DenseLoadOptions::sign`]).
+/// This is the load-side counterpart of the build-side [`SignPolicy`]: it
+/// never changes what was written, only whether the load accepts it.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum SignLoadPolicy {
+    /// Require the sidecar whenever the bundle's `(dim, bits)` can carry
+    /// one (see [`sign_compatible`]), failing with
+    /// [`DenseError::MissingSignSidecar`] when it is absent; bundles that
+    /// cannot carry a sidecar load without one. This is the default.
+    RequireIfSupported,
+    /// Fail the load with [`DenseError::MissingSignSidecar`] unless the
+    /// bundle declares a sign sidecar.
+    Require,
+    /// Load the sidecar when the bundle declares one and proceed without
+    /// it otherwise; never fail over sidecar presence.
+    Any,
+    /// Fail the load with [`DenseError::SignSidecarForbidden`] when the
+    /// bundle declares a sign sidecar.
+    Forbid,
+}
+
 /// Options controlling how a verified bundle is loaded (see
 /// [`OrdinalIndex::open_verified`] / [`crate::IdMapIndex::open_verified`]).
-#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct DenseLoadOptions {
-    /// If `true`, fail the load with [`DenseError::MissingSignSidecar`]
-    /// when the bundle has no sign sidecar, instead of loading without one.
-    pub require_sign: bool,
+    /// Sign-sidecar load policy — see [`SignLoadPolicy`]. Defaults to
+    /// [`SignLoadPolicy::RequireIfSupported`]: a bundle whose `(dim, bits)`
+    /// can carry a sidecar must have one to load.
+    pub sign: SignLoadPolicy,
     /// If `Some`, fail the load with [`DenseError::MetadataMismatch`] when
     /// the bundle's manifest dim does not match.
     pub expected_dim: Option<usize>,
@@ -97,6 +120,16 @@ pub struct DenseLoadOptions {
     pub expected_bits: Option<u8>,
 }
 
+impl Default for DenseLoadOptions {
+    fn default() -> Self {
+        Self {
+            sign: SignLoadPolicy::RequireIfSupported,
+            expected_dim: None,
+            expected_bits: None,
+        }
+    }
+}
+
 /// Which search strategy to use.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub enum DenseSearchMode {
@@ -1152,13 +1185,16 @@ impl OrdinalIndex {
 
     /// Load a bundle directory previously written by [`Self::write`] or
     /// [`Self::write_verified_bundle`], with default manifest
-    /// verification.
+    /// verification and the default sign-sidecar load policy
+    /// ([`SignLoadPolicy::RequireIfSupported`]).
     ///
     /// # Errors
     /// Returns an `InvalidData` [`std::io::Error`] if the bundle carries an
     /// ID sidecar (it was written by [`crate::IdMapIndex`] — load it with
     /// [`crate::IdMapIndex::load`] instead), fails manifest verification,
-    /// or is otherwise malformed.
+    /// is a sign-capable bundle missing its sign sidecar (use
+    /// [`Self::open_verified`] with [`SignLoadPolicy::Any`] to load it
+    /// without one), or is otherwise malformed.
     pub fn load(path: impl AsRef<std::path::Path>) -> std::io::Result<Self> {
         let artifacts = crate::io::load_ordinal_bundle(path)?;
         Self::from_loaded_parts(artifacts.rankquant, artifacts.sign)
@@ -1718,16 +1754,19 @@ fn load_verified_bundle(
         ));
     }
 
-    let sign_path = if load_options.require_sign {
-        match plan.require_auxiliary(crate::io::SIGN_AUX_NAME) {
-            Ok(path) => Some(path.to_path_buf()),
-            Err(crate::manifest::RequireAuxiliaryError::MissingDeclaration { .. }) => {
-                return Err(DenseError::MissingSignSidecar);
-            }
-            Err(error) => return Err(DenseError::Auxiliary(error)),
+    let sign_declared = plan.auxiliary_by_name(crate::io::SIGN_AUX_NAME).is_some();
+    let sign_path = match load_options.sign {
+        SignLoadPolicy::Forbid if sign_declared => {
+            return Err(DenseError::SignSidecarForbidden);
+        }
+        SignLoadPolicy::Forbid => None,
+        SignLoadPolicy::Require => required_sign_path(&plan)?,
+        SignLoadPolicy::RequireIfSupported if sign_compatible(metadata.dim, metadata_bits) => {
+            required_sign_path(&plan)?
+        }
+        SignLoadPolicy::RequireIfSupported | SignLoadPolicy::Any => {
+            crate::io::auxiliary_path(&plan, crate::io::SIGN_AUX_NAME)?
         }
-    } else {
-        crate::io::auxiliary_path(&plan, crate::io::SIGN_AUX_NAME)?
     };
     let sign = match sign_path {
         Some(path) => {
@@ -1753,6 +1792,21 @@ fn load_verified_bundle(
     })
 }
 
+/// The verified path of the bundle's sign sidecar, required: a missing
+/// declaration is [`DenseError::MissingSignSidecar`]; a declared but
+/// unloadable sidecar is [`DenseError::Auxiliary`].
+fn required_sign_path(
+    plan: &ordvec_manifest::VerifiedLoadPlan,
+) -> Result<Option<PathBuf>, DenseError> {
+    match plan.require_auxiliary(crate::io::SIGN_AUX_NAME) {
+        Ok(path) => Ok(Some(path.to_path_buf())),
+        Err(crate::manifest::RequireAuxiliaryError::MissingDeclaration { .. }) => {
+            Err(DenseError::MissingSignSidecar)
+        }
+        Err(error) => Err(DenseError::Auxiliary(error)),
+    }
+}
+
 impl OrdinalIndexBuilder {
     /// Construct a new builder for a `dim`/`bits`/`options`-configured
     /// index.

ordinaldb/tests/boundary_api.rs

@@ -8,7 +8,7 @@ use ordinaldb::hybrid::{
 use ordinaldb::manifest::{AuxiliaryArtifactDeclaration, CreateManifestOptions, VerifyOptions};
 use ordinaldb::{
     BuildOptions, DenseError, DenseLoadOptions, IdMapIndex, OrdinalIndex, OrdinalIndexBuilder,
-    SignPolicy,
+    SignLoadPolicy, SignPolicy,
 };
 use std::fs;
 use std::path::{Path, PathBuf};
@@ -24,7 +24,7 @@ fn verified_idmap_bundle_loads_dense_and_sparse_with_stable_row_ids() {
         &manifest_path,
         VerifyOptions::default(),
         DenseLoadOptions {
-            require_sign: true,
+            sign: SignLoadPolicy::Require,
             expected_dim: Some(64),
             expected_bits: Some(2),
         },
@@ -83,7 +83,7 @@ fn verified_dense_load_can_require_sign_sidecar() {
         &manifest_path,
         VerifyOptions::default(),
         DenseLoadOptions {
-            require_sign: true,
+            sign: SignLoadPolicy::Require,
             expected_dim: Some(64),
             expected_bits: Some(2),
         },
@@ -208,7 +208,7 @@ fn declared_but_unloadable_sign_sidecar_is_not_reported_missing() {
         bundle.join(MANIFEST_FILE),
         VerifyOptions::default(),
         DenseLoadOptions {
-            require_sign: true,
+            sign: SignLoadPolicy::Require,
             expected_dim: Some(64),
             expected_bits: Some(2),
         },
@@ -230,7 +230,7 @@ fn batch_dense_sparse_and_rrf_preserve_per_query_allowlists() {
         &manifest_path,
         VerifyOptions::default(),
         DenseLoadOptions {
-            require_sign: true,
+            sign: SignLoadPolicy::Require,
             expected_dim: Some(64),
             expected_bits: Some(2),
         },
@@ -319,7 +319,7 @@ fn hybrid_bundle_open_verified_returns_dense_and_sparse_from_one_manifest() {
         &manifest_path,
         VerifyOptions::default(),
         DenseLoadOptions {
-            require_sign: true,
+            sign: SignLoadPolicy::Require,
             expected_dim: Some(64),
             expected_bits: Some(2),
         },
@@ -362,7 +362,7 @@ fn hybrid_bundle_open_verified_reports_dense_and_sparse_failures_distinctly() {
         &manifest_path,
         VerifyOptions::default(),
         DenseLoadOptions {
-            require_sign: true,
+            sign: SignLoadPolicy::Require,
             expected_dim: Some(32),
             expected_bits: Some(2),
         },
@@ -380,7 +380,7 @@ fn hybrid_bundle_open_verified_reports_dense_and_sparse_failures_distinctly() {
         &manifest_path,
         VerifyOptions::default(),
         DenseLoadOptions {
-            require_sign: true,
+            sign: SignLoadPolicy::Require,
             expected_dim: Some(64),
             expected_bits: Some(2),
         },