mod census

module census

Append-only descriptor-basin census with exact visit accounting.

Variables

const PRODUCTION_MAX_UNSEEN_MASS: f64

Production Good–Turing unseen-mass ceiling α = 1/5.

const PRODUCTION_MINIMUM_VISITS: u64

Production Good–Turing visit floor: gt_min_visits(1, 5, 3) = 20.

const PRODUCTION_SINGLETON_BUDGET: u64

Largest leftover-singleton count that must stay hatch-stable at the visit floor. n_min(α, k) = \lfloor (k+1)/α \rfloor.

const PRODUCTION_UNSEEN_MASS_DEN: u64

Denominator of the coverage policy. With the numerator this is (alpha = 1/5).

const PRODUCTION_UNSEEN_MASS_NUM: u64

Coverage policy: leftover and packing Good–Turing refuse to call the census complete while unseen mass is at least num/den.

Functions

const fn gt_min_visits(ceiling_num: u64, ceiling_den: u64, singleton_budget: u64) -> u64

Smallest n such that singleton_budget leftover singletons stay hatch-stable at ceiling ceiling_num/ceiling_den.

(k+1)/(n+1) < p/q` iff n ≥ \lfloor (k+1) q / p \rfloor` when ``p divides (k+1)q. For α = 1/5 and k = 3 this is 20.

Enums

enum CensusError

Configuration or observation error that leaves the census unchanged.

ZeroDescriptorDimension

Descriptor dimension must be positive.

InvalidRadius

Census radius must be finite and nonnegative.

DescriptorDimension

Observation length differs from the census schema.

expected: usize

Dimension fixed by the census.

actual: usize

Dimension carried by the observation.

NonFiniteDescriptor

An observation contains NaN or infinity.

index: usize

Index of the first invalid value.

UnknownBasin

An exact-identity assignment names no census entry.

basin: u64

Canonical integer identifier supplied by the caller.

CounterOverflow

A visit or identifier counter cannot be represented by u64.

Structs and Unions

struct BasinCensus

Exact, uncapped census of fixed-radius descriptor basins.

Implementations

impl BasinCensus

Functions

fn basin_for(&self, descriptor: &[f64]) -> Result<Option<BasinId>, CensusError>

Classify a descriptor without changing visit counts.

fn doubleton_count(&self) -> u64

Number of basins observed exactly twice.

fn entries(&self) -> &[CensusEntry]

All entries in stable identifier order.

fn entry(&self, id: BasinId) -> Option<&CensusEntry>

Look up one entry by stable identifier.

fn is_empty(&self) -> bool

Whether the census contains no basins.

fn is_saturated(&self) -> bool

Whether the production visit floor and unseen-mass threshold are met.

fn len(&self) -> usize

Number of immutable census basins.

fn new(descriptor_dim: usize, radius: f64) -> Result<Self, CensusError>

Create an empty census with a fixed descriptor schema and radius.

fn observe(&mut self, descriptor: &[f64]) -> Result<CensusObservation, CensusError>

Assign one descriptor to its nearest existing medoid within the radius.

fn observe_assigned(&mut self, descriptor: &[f64], basin: Option<BasinId>) -> Result<CensusObservation, CensusError>

Record an observation under an identity assignment made by an exact witness.

Some increments that immutable basin irrespective of descriptor distance. None opens a new basin. The descriptor remains the geometry used for retrieval and coverage, while the caller owns structural identity.

fn saturated_at(&self, minimum_visits: u64, maximum_unseen_mass: f64) -> bool

Evaluate a declared visit floor and strict unseen-mass threshold.

fn singleton_count(&self) -> u64

Number of basins observed exactly once.

fn total_visits(&self) -> u64

Exact number of successful observations.

fn unseen_mass(&self) -> Option<f64>

Good–Turing unseen-mass estimate N1 / n, if any visit exists.

fn validate_descriptor(&self, descriptor: &[f64]) -> Result<(), CensusError>

Validate descriptor shape and finiteness without assigning a basin.

struct BasinId(u64)

Stable identifier for one immutable census medoid.

Implementations

impl BasinId

Functions

const fn as_raw(self) -> u64

Return the canonical integer representation.

const fn from_raw(value: u64) -> Self

Construct an identifier from its canonical integer representation.

struct CensusEntry

One immutable medoid and its exact visit count.

Implementations

impl CensusEntry

Functions

fn id(&self) -> BasinId

Stable basin identifier.

fn medoid(&self) -> &[f64]

Descriptor that opened the basin.

fn visits(&self) -> u64

Exact number of observations assigned to this basin.

struct CensusObservation

Result of assigning one validated descriptor observation.

basin_id: BasinId

Assigned basin identifier.

created: bool

Whether this observation opened a new basin.

basin_visits: u64

Exact basin count after this observation.

total_visits: u64

Exact global count after this observation.