<!-- Sema documentation — std.epistemic
     Sema is a new AI-native, neurosymbolic programming language most models
     have not been trained on. Full corpus: https://sema.cortex.a2olabs.com/llms-full.txt
     Install language support: https://sema.cortex.a2olabs.com/install-skill/ -->

# std.epistemic

> Reflected API reference for the Sema standard-library module std.epistemic.

> Generated by `sema doc` from `crates/sema-runtime/assets/stdlib/sema/epistemic.sema`. Import with `from std.epistemic import …`. For a narrative introduction see [std.epistemic](/stdlib/epistemic/).

# `epistemic`

std.epistemic - explicit uncertainty, evidence, horizons, and decisions.

Epistemic estimates never coerce to their payload. Callers must match an
EpistemicDecision and keep the estimate plus its conditional guarantee attached.
Composition uses an explicit conservative or independent rule and preserves
all evidence, assumptions, validity, and provenance.

# `enum EpistemicStatus`

**Variants**

- `known`
- `degraded`
- `unknown`

# `enum GuaranteeStatus`

**Variants**

- `supported`
- `violated`
- `unknown`

# `enum DecisionReason`

**Variants**

- `accepted`
- `unknown_value`
- `outside_validity`
- `excessive_uncertainty`
- `insufficient_horizon`
- `insufficient_coverage`
- `unsupported_guarantee`

# `enum CompositionRule`

**Variants**

- `conservative`
- `independent`

# `struct Evidence`

**Fields**

| field | type | descriptor |
|---|---|---|
| `id` | `str` |  |
| `source` | `str` |  |
| `observed_at` | `f64` |  |
| `reliability` | `f64` |  |
| `summary` | `str` |  |
| `provenance` | `list[str]` |  |

# `struct Assumption`

**Fields**

| field | type | descriptor |
|---|---|---|
| `id` | `str` |  |
| `statement` | `str` |  |
| `active` | `bool` |  |
| `checked_at` | `f64` |  |
| `evidence_ids` | `list[str]` |  |

# `struct ValidityRegion`

**Fields**

| field | type | descriptor |
|---|---|---|
| `label` | `str` |  |
| `in_scope` | `bool` |  |
| `distance_to_boundary` | `f64` |  |
| `checked_at` | `f64` |  |

# `struct Uncertainty`

**Fields**

| field | type | descriptor |
|---|---|---|
| `aleatoric` | `f64` |  |
| `epistemic` | `f64` |  |
| `parameter` | `f64` |  |
| `structural` | `f64` |  |
| `distributional` | `f64` |  |
| `numerical` | `f64` |  |
| `evidence` | `f64` |  |
| `agent` | `f64` |  |
| `rule` | `CompositionRule` |  |

# `struct Horizon`

**Fields**

| field | type | descriptor |
|---|---|---|
| `steps` | `int` |  |
| `duration` | `f64` |  |
| `error_threshold` | `f64` |  |
| `coverage` | `f64` |  |
| `method` | `str` |  |
| `uncertainty` | `Uncertainty` |  |
| `assumptions` | `list[Assumption]` |  |
| `valid` | `bool` |  |

# `struct ConditionalGuarantee`

**Fields**

| field | type | descriptor |
|---|---|---|
| `property` | `str` |  |
| `limit` | `f64` |  |
| `observed_bound` | `f64` |  |
| `coverage` | `f64` |  |
| `horizon` | `Horizon` |  |
| `assumptions` | `list[Assumption]` |  |
| `evidence` | `list[Evidence]` |  |
| `status` | `GuaranteeStatus` |  |

# `struct Estimate`

**Fields**

| field | type | descriptor |
|---|---|---|
| `value` | `T` |  |
| `status` | `EpistemicStatus` |  |
| `uncertainty` | `Uncertainty` |  |
| `evidence` | `list[Evidence]` |  |
| `assumptions` | `list[Assumption]` |  |
| `validity` | `ValidityRegion` |  |
| `provenance` | `list[str]` |  |
| `measured_at` | `f64` |  |

# `enum EpistemicValue`

**Variants**

- `known(Estimate[T])`
- `unknown(str, Uncertainty, list[Evidence], list[Assumption], list[str])`

# `enum EpistemicDecision`

**Variants**

- `accepted(Estimate[T], ConditionalGuarantee)`
- `abstained(DecisionReason, str, list[Evidence])`

# `def zero_uncertainty`

```sema
def zero_uncertainty()
```

# `def component`

```sema
def component(left: f64, right: f64, rule: CompositionRule)
```

**Parameters**

| name | type |
|---|---|
| `left` | `f64` |
| `right` | `f64` |
| `rule` | `CompositionRule` |

# `def compose_uncertainty`

```sema
def compose_uncertainty(left: Uncertainty, right: Uncertainty, rule: CompositionRule)
```

**Parameters**

| name | type |
|---|---|
| `left` | `Uncertainty` |
| `right` | `Uncertainty` |
| `rule` | `CompositionRule` |

# `def has_evidence`

```sema
def has_evidence(values: list[Evidence], id: str)
```

**Parameters**

| name | type |
|---|---|
| `values` | `list[Evidence]` |
| `id` | `str` |

# `def merge_evidence`

```sema
def merge_evidence(left: list[Evidence], right: list[Evidence])
```

**Parameters**

| name | type |
|---|---|
| `left` | `list[Evidence]` |
| `right` | `list[Evidence]` |

# `def has_assumption`

```sema
def has_assumption(values: list[Assumption], id: str)
```

**Parameters**

| name | type |
|---|---|
| `values` | `list[Assumption]` |
| `id` | `str` |

# `def merge_assumptions`

```sema
def merge_assumptions(left: list[Assumption], right: list[Assumption])
```

**Parameters**

| name | type |
|---|---|
| `left` | `list[Assumption]` |
| `right` | `list[Assumption]` |

# `def has_text`

```sema
def has_text(values: list[str], value: str)
```

**Parameters**

| name | type |
|---|---|
| `values` | `list[str]` |
| `value` | `str` |

# `def merge_provenance`

```sema
def merge_provenance(left: list[str], right: list[str], operation: str)
```

**Parameters**

| name | type |
|---|---|
| `left` | `list[str]` |
| `right` | `list[str]` |
| `operation` | `str` |

# `def all_assumptions_active`

```sema
def all_assumptions_active(values: list[Assumption])
```

**Parameters**

| name | type |
|---|---|
| `values` | `list[Assumption]` |

# `def estimate`

```sema
def estimate[T](value: T, status: EpistemicStatus, uncertainty: Uncertainty, evidence: list[Evidence], assumptions: list[Assumption], validity: ValidityRegion, provenance: list[str], measured_at: f64)
```

**Parameters**

| name | type |
|---|---|
| `value` | `T` |
| `status` | `EpistemicStatus` |
| `uncertainty` | `Uncertainty` |
| `evidence` | `list[Evidence]` |
| `assumptions` | `list[Assumption]` |
| `validity` | `ValidityRegion` |
| `provenance` | `list[str]` |
| `measured_at` | `f64` |

# `def known_value`

```sema
def known_value[T](value: T, status: EpistemicStatus, uncertainty: Uncertainty, evidence: list[Evidence], assumptions: list[Assumption], validity: ValidityRegion, provenance: list[str], measured_at: f64)
```

**Parameters**

| name | type |
|---|---|
| `value` | `T` |
| `status` | `EpistemicStatus` |
| `uncertainty` | `Uncertainty` |
| `evidence` | `list[Evidence]` |
| `assumptions` | `list[Assumption]` |
| `validity` | `ValidityRegion` |
| `provenance` | `list[str]` |
| `measured_at` | `f64` |

# `def unknown_value`

```sema
def unknown_value[T](reason: str, uncertainty: Uncertainty, evidence: list[Evidence], assumptions: list[Assumption], provenance: list[str])
```

**Parameters**

| name | type |
|---|---|
| `reason` | `str` |
| `uncertainty` | `Uncertainty` |
| `evidence` | `list[Evidence]` |
| `assumptions` | `list[Assumption]` |
| `provenance` | `list[str]` |

# `def derive`

```sema
def derive[T, U](parent: Estimate[T], value: U, status: EpistemicStatus, local_uncertainty: Uncertainty, local_evidence: list[Evidence], local_assumptions: list[Assumption], operation: str, measured_at: f64)
```

**Parameters**

| name | type |
|---|---|
| `parent` | `Estimate[T]` |
| `value` | `U` |
| `status` | `EpistemicStatus` |
| `local_uncertainty` | `Uncertainty` |
| `local_evidence` | `list[Evidence]` |
| `local_assumptions` | `list[Assumption]` |
| `operation` | `str` |
| `measured_at` | `f64` |

# `def compose`

```sema
def compose[T, U, V](left: Estimate[T], right: Estimate[U], value: V, status: EpistemicStatus, local_uncertainty: Uncertainty, local_evidence: list[Evidence], local_assumptions: list[Assumption], operation: str, measured_at: f64)
```

**Parameters**

| name | type |
|---|---|
| `left` | `Estimate[T]` |
| `right` | `Estimate[U]` |
| `value` | `V` |
| `status` | `EpistemicStatus` |
| `local_uncertainty` | `Uncertainty` |
| `local_evidence` | `list[Evidence]` |
| `local_assumptions` | `list[Assumption]` |
| `operation` | `str` |
| `measured_at` | `f64` |

# `def evaluate_guarantee`

```sema
def evaluate_guarantee(property: str, limit: f64, observed_bound: f64, coverage: f64, horizon: Horizon, assumptions: list[Assumption], evidence: list[Evidence])
```

**Parameters**

| name | type |
|---|---|
| `property` | `str` |
| `limit` | `f64` |
| `observed_bound` | `f64` |
| `coverage` | `f64` |
| `horizon` | `Horizon` |
| `assumptions` | `list[Assumption]` |
| `evidence` | `list[Evidence]` |

# `def decide`

```sema
def decide[T](value: EpistemicValue[T], guarantee: ConditionalGuarantee, min_horizon_steps: int, max_uncertainty: f64, min_coverage: f64) -> EpistemicDecision[T]
```

**Parameters**

| name | type |
|---|---|
| `value` | `EpistemicValue[T]` |
| `guarantee` | `ConditionalGuarantee` |
| `min_horizon_steps` | `int` |
| `max_uncertainty` | `f64` |
| `min_coverage` | `f64` |

**Returns** `EpistemicDecision[T]`