Module policy 

Semantic policy contract for cass hybrid search.

This module is the single source of truth for all semantic search policy decisions. Downstream beads (asset manifests, backfill scheduler, model acquisition, configuration surfaces, capability reporting) implement against the types and constants defined here rather than guessing or hardcoding their own values.

Product contract

Ordinary search always works lexically. Semantic quality improves opportunistically: when model files are present, vectors are built in the background and hybrid results are blended in. A missing or broken semantic tier never blocks or degrades lexical search.

Precedence (lowest to highest)

1. Compiled defaults — SemanticPolicy::compiled_defaults
2. Persisted config — ~/.config/cass/semantic.toml (planned)
3. Environment variables — CASS_SEMANTIC_*
4. CLI flags — --semantic-mode, --semantic-budget-mb, etc.

Higher layers override lower layers field-by-field; unset fields inherit.

Behaviour modes

Mode	Lexical	Fast-tier semantic	Quality-tier semantic
HybridPreferred (default)	always	if available	if model present
LexicalOnly	always	never	never
StrictSemantic	always (floor)	required	required

StrictSemantic is for callers that want hard guarantees about semantic quality (e.g., bake-off). It is never the default.

Storage budget

Semantic artifacts are derivative — they can always be rebuilt from the canonical SQLite database. They must never crowd out the DB or the required lexical index.

Eviction order (first to go → last to go):

1. HNSW accelerator indices (.chsw)
2. Quality-tier vector index (.fsvi)
3. Fast-tier vector index
4. Downloaded model files

The lexical index and SQLite DB are never evicted.

Structs

CliSemanticOverrides

CLI-level overrides — None means “inherit from lower layer”.

EffectiveSetting

A single setting with its resolved value and provenance.

EffectiveSettings

Complete effective-settings report for cass status --json.

SemanticAssetManifest

Metadata stored alongside semantic assets to detect invalidation.

SemanticCapabilityReport

JSON-serializable capability snapshot for cass status --json.

SemanticPolicy

Resolved semantic policy after layering defaults → config → env → CLI.

Enums

BudgetDecision

Result of a disk-budget check.

InvalidationAction

What happened and what to do about existing semantic assets.

ModelDownloadPolicy

Whether model downloads are automatic, opt-in, or budget-gated.

SemanticArtifactKind

Categories of semantic artifacts for eviction / budget accounting.

SemanticCapability

What semantic quality level is achievable on this machine right now.

SemanticMode

How aggressively cass pursues semantic search.

SettingSource

Where a configuration value came from.

Constants

CHUNKING_STRATEGY_VERSION

Changing the chunking strategy (e.g., max tokens per chunk, overlap) invalidates all existing vectors even if the model is unchanged.

DEFAULT_CHUNK_TIMEOUT_SECONDS

Maximum wall-clock seconds for a single background work chunk. The scheduler yields after this to re-check budgets and user activity.

DEFAULT_FAST_DIMENSION

Fast-tier embedding dimension (hash embedder).

DEFAULT_FAST_TIER_EMBEDDER

Default fast-tier embedder name (always available, no model files).

DEFAULT_IDLE_DELAY_SECONDS

How long (seconds) the scheduler waits after last user activity before starting background work. This prevents contention during interactive search or indexing.

DEFAULT_MAX_BACKFILL_RSS_MB

Maximum RSS the backfill worker should target (MB). This is advisory — the embedder ONNX runtime is the main consumer.

DEFAULT_MAX_BACKFILL_THREADS

Maximum CPU cores the background backfill worker may saturate. On a typical 4-core dev laptop this is ~25 %.

DEFAULT_MAX_REFINEMENT_DOCS

Maximum documents to refine via quality tier per query.

DEFAULT_QUALITY_DIMENSION

Quality-tier embedding dimension (MiniLM).

DEFAULT_QUALITY_TIER_EMBEDDER

Default quality-tier embedder name (requires ML model files).

DEFAULT_QUALITY_WEIGHT

Quality-tier score weight when blending (0.0-1.0).

DEFAULT_RERANKER

Default reranker name (requires cross-encoder model files).

DEFAULT_SEMANTIC_BUDGET_MB

Default total semantic disk budget in megabytes.

EVICTION_ORDER

Ordered list of semantic artifact categories, first-to-evict first.

MAX_MODEL_SIZE_MB

Model files are the biggest single cost. Cap per-model.

MIN_FREE_DISK_MB

Minimum free disk space (MB) that must remain after semantic writes.

SEMANTIC_SCHEMA_VERSION

Semantic schema version. Bump when the vector document ID encoding, quantization format, or normalization changes. A version mismatch forces a full vector rebuild.