Knowledge Types

The Knowledge<T> type is Sounio’s core epistemic primitive, representing values with associated uncertainty, provenance, and confidence.

What is Knowledge?

In traditional programming, a temperature reading might be stored as:

let temp: f64 = 23.5  // Just a number

But this loses crucial information:

How accurate is this measurement?
Where did it come from?
How confident are we in this value?

Sounio’s Knowledge<T> captures all of this:

let temp: Knowledge<celsius> = measure(
    value: 23.5,
    uncertainty: 0.2,
    source: "sensor_A"
)
// temp.value = 23.5
// temp.uncertainty = 0.2
// temp.confidence = 0.95
// temp.provenance = ["sensor_A"]

Creating Knowledge Values

From Measurements

let mass: Knowledge<kg> = measure(
    value: 75.3,
    uncertainty: 0.5,
    source: "scale_001"
)

From Observations

let count: Knowledge<i32> = observe(
    value: 42,
    confidence: 0.99,
    source: "manual_count"
)

From Computation

When you compute with Knowledge values, uncertainty propagates:

let a: Knowledge<f64> = measure(value: 10.0, uncertainty: 0.1, source: "A")
let b: Knowledge<f64> = measure(value: 5.0, uncertainty: 0.05, source: "B")

let sum = a + b
// sum.value = 15.0
// sum.uncertainty ≈ 0.112 (propagated via GUM rules)
// sum.provenance = ["A", "B"]

Knowledge Properties

Property	Type	Description
`.value`	`T`	The underlying value
`.uncertainty`	`f64`	Standard uncertainty (σ)
`.confidence`	`f64`	Confidence level (0.0-1.0)
`.provenance`	`Vec<String>`	Data sources

Uncertainty Propagation

Sounio automatically propagates uncertainty following GUM (Guide to the Expression of Uncertainty in Measurement) rules:

Addition/Subtraction

let c = a + b
// c.uncertainty = sqrt(a.uncertainty² + b.uncertainty²)

Multiplication/Division

let c = a * b
// Relative uncertainties combine

Functions

let y = sin(x)
// Uncertainty propagates through derivatives

Confidence Gates

Use confidence to guard decisions:

fn make_decision(data: Knowledge<f64>) with IO {
    if data.confidence > 0.95 {
        // High confidence - act on the data
        execute_action(data.value)
    } else if data.confidence > 0.70 {
        // Medium confidence - proceed with caution
        perform IO::warn("Acting on uncertain data")
        execute_action(data.value)
    } else {
        // Low confidence - don't act
        perform IO::error("Insufficient confidence to proceed")
    }
}

Pattern Matching

match measurement {
    m if m.confidence > 0.99 => "Highly reliable",
    m if m.uncertainty < 0.01 => "Very precise",
    m if m.provenance.contains("calibrated") => "Calibrated source",
    _ => "Standard measurement",
}

Type Conversions

Extracting Raw Values

let raw: f64 = measurement.value  // Loses epistemic info

Promoting to Knowledge

let known: Knowledge<f64> = Knowledge::certain(42.0)
// Creates Knowledge with zero uncertainty

Best Practices

Preserve uncertainty: Don’t extract .value unless necessary
Check confidence: Always gate critical decisions on confidence
Track provenance: Use meaningful source identifiers
Propagate properly: Let Sounio handle uncertainty math