Source: https://guthlabs.ai/docs/instruments/database-index-selectivity-cardinality-estimator/

instrument / verified-clean

# Database Index Selectivity / Cardinality Estimator

The current ledger marks this instrument verified clean within the source-bound verification corpus.

Status: **VERIFIED_CLEAN**Lifecycle: **verified-clean**

## Inspectable records

[01**Overview**Purpose and lifecycle](<https://guthlabs.ai/docs/instruments/database-index-selectivity-cardinality-estimator/>)[02**Mechanism**Method and assumptions](<https://guthlabs.ai/docs/instruments/database-index-selectivity-cardinality-estimator/mechanism/>)[03**Implementation**Binding and validation](<https://guthlabs.ai/docs/instruments/database-index-selectivity-cardinality-estimator/implementation/>)[04**Qualification**Evidence and errata](<https://guthlabs.ai/docs/instruments/database-index-selectivity-cardinality-estimator/qualification/>)

## Ledger state

The current ledger marks this instrument verified clean within the source-bound verification corpus.

**Area**: Computing & Information

**Tranche**: tranche-5

**Evidence ID**: t5-079

**Ledger rows**: 1

No ledger note is attached.

## Review findings

The exact ambiguity requiring review is whether selectivity means the catalog's uniqueness ratio (distinct_values/total_rows) or standard equality-predicate selectivity (approximately 1/distinct_values under uniform distribution). Rename the current output to uniqueness_ratio or redefine selectivity. Specify the index-usefulness rule, input validation, NULL counting, and zero-input behavior before release.

### Formula and scope findings

- The formula selectivity=distinct_values/total_rows is a uniqueness ratio, not the standard equality-predicate selectivity in most database terminology. Under a uniform-distribution assumption, equality selectivity is 1/distinct_values, while estimated rows per equality lookup is total_rows/distinct_values.

- The specification does not define the rule for the required index-usefulness verdict, so that output cannot be computed from the supplied formulas.

- The uniform-distribution assumption is required for estimated rows per value to be meaningful and should be stated as a constraint, including how NULLs and nonuniform values are handled.

### Unit assumptions

- total_rows and distinct_values are nonnegative integer counts with the same scope and population.

- For valid nonempty data, total_rows must be greater than 0 and distinct_values must be greater than 0.

- For a conventional column, distinct_values must not exceed total_rows; NULL handling must be specified because counting NULL as a distinct value affects both results.

- selectivity as currently named is dimensionless; estimated rows per lookup has units of rows per distinct value.

- The estimated-rows formula assumes uniformly distributed values and an equality lookup.

## Boundary hardening

**BREAK_CLAIMED** · SELF_FLAGGED

The formulas have undefined results when total_rows or distinct_values is zero, and the specification does not state input validation for zero or for distinct_values greater than total_rows. The specification also does not define a threshold or rule for the requested index-usefulness verdict, so that output cannot be reliably produced.

## Errata and corrections

No applied erratum is attached to this unique-name record.

## Inspectable example

4 review vectors are recorded. One source-bound sample is shown below.

````
{
  "inputs": {
    "total_rows": 1000000,
    "distinct_values": 1000000
  },
  "expected_outputs": {
    "selectivity_ratio": 1,
    "estimated_rows_per_lookup": 1,
    "index_usefulness_verdict": "UNDEFINED_BY_SPEC"
  },
  "working": "selectivity_ratio = distinct_values / total_rows = 1000000 / 1000000 = 1. estimated_rows_per_lookup = total_rows / distinct_values = 1000000 / 1000000 = 1 row per lookup. The index-usefulness verdict has no specified formula or threshold."
}
````

## Related workflows

No source-defined multi-instrument workflow membership is recorded.

## Sources and evidence

These pointers bind the page to evidence. They do not grant authority or collapse verification into deployment.

- `VERIFIED_LEDGER.json · VERIFIED_CLEAN`

- `evidence-tranche5/tranche5-results.json`

- `BOUNDARY_HAZARD_CATALOG.json`