<!-- Sema documentation — std.adaptive_dynamics
     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.adaptive_dynamics

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

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

# `adaptive_dynamics`

std.adaptive_dynamics - bounded adaptive-model lifecycle primitives.

The module separates state updates, parameter refits, structural switching, and
safe unknown outcomes. Proposed models cannot become active without held-out
validation, invariant evidence, dwell time, hysteresis, and an audit record.
Numerical fitting and domain equations remain application responsibilities.

# `enum ModelLifecycle`

**Variants**

- `proposed`
- `validated`
- `active`
- `retired`
- `rejected`

# `enum AdaptationMode`

**Variants**

- `retain`
- `state_update`
- `parameter_refit`
- `structural_switch`
- `ensemble`
- `safe_unknown`

# `enum RegimeStatus`

**Variants**

- `stable`
- `suspected`
- `shifted`
- `unknown`

# `enum ValidationStatus`

**Variants**

- `passed`
- `failed`
- `inconclusive`

# `enum TransitionKind`

**Variants**

- `observation`
- `regime_suspected`
- `regime_shifted`
- `parameter_refit`
- `candidate_proposed`
- `candidate_validated`
- `candidate_rejected`
- `model_activated`
- `horizon_contracted`
- `horizon_restored`
- `action_abstained`
- `action_executed`

# `struct ModelDescriptor`

**Fields**

| field | type | descriptor |
|---|---|---|
| `id` | `str` |  |
| `family` | `str` |  |
| `version` | `int` |  |
| `lifecycle` | `ModelLifecycle` |  |
| `parameter_names` | `list[str]` |  |
| `parameters` | `list[f64]` |  |
| `structure_signature` | `str` |  |
| `assumptions` | `list[Assumption]` |  |
| `validity` | `ValidityRegion` |  |
| `fit_error` | `f64` |  |
| `validation_error` | `f64` |  |
| `created_at` | `f64` |  |
| `activated_step` | `int` |  |

# `struct SelectionPolicy`

**Fields**

| field | type | descriptor |
|---|---|---|
| `min_validation_improvement` | `f64` |  |
| `max_validation_error` | `f64` |  |
| `max_invariant_violations` | `int` |  |
| `min_dwell_steps` | `int` |  |
| `hysteresis_margin` | `f64` |  |
| `required_horizon_steps` | `int` |  |

# `struct CandidateValidation`

**Fields**

| field | type | descriptor |
|---|---|---|
| `model` | `ModelDescriptor` |  |
| `status` | `ValidationStatus` |  |
| `training_error` | `f64` |  |
| `validation_error` | `f64` |  |
| `relative_improvement` | `f64` |  |
| `invariant_violations` | `int` |  |
| `evidence` | `list[Evidence]` |  |
| `evaluated_at` | `f64` |  |

# `struct ResidualDetector`

**Fields**

| field | type | descriptor |
|---|---|---|
| `window_size` | `int` |  |
| `min_samples` | `int` |  |
| `score_threshold` | `f64` |  |
| `required_consecutive` | `int` |  |
| `baseline_mean` | `f64` |  |
| `baseline_scale` | `f64` |  |
| `history` | `list[f64]` |  |
| `consecutive_high` | `int` |  |
| `score` | `f64` |  |
| `status` | `RegimeStatus` |  |
| `updated_at` | `f64` |  |

# `struct ModelTransition`

**Fields**

| field | type | descriptor |
|---|---|---|
| `sequence` | `int` |  |
| `kind` | `TransitionKind` |  |
| `from_model_id` | `str` |  |
| `to_model_id` | `str` |  |
| `regime` | `RegimeStatus` |  |
| `adaptation` | `AdaptationMode` |  |
| `reason` | `str` |  |
| `evidence` | `list[Evidence]` |  |
| `occurred_at` | `f64` |  |

# `enum AdaptationDecision`

**Variants**

- `selected(AdaptationMode, ModelDescriptor, str)`
- `abstained(AdaptationMode, str)`

# `enum ActivationDecision`

**Variants**

- `activated(ModelDescriptor, ModelDescriptor, ModelTransition)`
- `blocked(str, ModelTransition)`

# `def model_with_lifecycle`

```sema
def model_with_lifecycle(model: ModelDescriptor, lifecycle: ModelLifecycle, fit_error: f64, validation_error: f64, activated_step: int)
```

**Parameters**

| name | type |
|---|---|
| `model` | `ModelDescriptor` |
| `lifecycle` | `ModelLifecycle` |
| `fit_error` | `f64` |
| `validation_error` | `f64` |
| `activated_step` | `int` |

# `def make_detector`

```sema
def make_detector(window_size: int, min_samples: int, score_threshold: f64, required_consecutive: int, baseline_mean: f64, baseline_scale: f64) -> ResidualDetector !{}
```

**Parameters**

| name | type |
|---|---|
| `window_size` | `int` |
| `min_samples` | `int` |
| `score_threshold` | `f64` |
| `required_consecutive` | `int` |
| `baseline_mean` | `f64` |
| `baseline_scale` | `f64` |

**Returns** `ResidualDetector`

**Effects** `!{}`

# `def append_bounded`

```sema
def append_bounded(values: list[f64], value: f64, limit: int) -> list[f64] !{}
```

**Parameters**

| name | type |
|---|---|
| `values` | `list[f64]` |
| `value` | `f64` |
| `limit` | `int` |

**Returns** `list[f64]`

**Effects** `!{}`

# `def update_detector`

```sema
def update_detector(detector: ResidualDetector, residual: f64, observed_at: f64) -> ResidualDetector !{}
```

**Parameters**

| name | type |
|---|---|
| `detector` | `ResidualDetector` |
| `residual` | `f64` |
| `observed_at` | `f64` |

**Returns** `ResidualDetector`

**Effects** `!{}`

# `def relative_improvement`

```sema
def relative_improvement(reference_error: f64, candidate_error: f64)
```

**Parameters**

| name | type |
|---|---|
| `reference_error` | `f64` |
| `candidate_error` | `f64` |

# `def validate_candidate`

```sema
def validate_candidate(active: ModelDescriptor, candidate: ModelDescriptor, training_error: f64, validation_error: f64, invariant_violations: int, evidence: list[Evidence], evaluated_at: f64, policy: SelectionPolicy) -> CandidateValidation !{}
```

**Parameters**

| name | type |
|---|---|
| `active` | `ModelDescriptor` |
| `candidate` | `ModelDescriptor` |
| `training_error` | `f64` |
| `validation_error` | `f64` |
| `invariant_violations` | `int` |
| `evidence` | `list[Evidence]` |
| `evaluated_at` | `f64` |
| `policy` | `SelectionPolicy` |

**Returns** `CandidateValidation`

**Effects** `!{}`

# `def choose_adaptation`

```sema
def choose_adaptation(regime: RegimeStatus, parameter_fit: CandidateValidation, structural_fit: CandidateValidation)
```

**Parameters**

| name | type |
|---|---|
| `regime` | `RegimeStatus` |
| `parameter_fit` | `CandidateValidation` |
| `structural_fit` | `CandidateValidation` |

# `def transition`

```sema
def transition(sequence: int, kind: TransitionKind, from_model_id: str, to_model_id: str, regime: RegimeStatus, adaptation: AdaptationMode, reason: str, evidence: list[Evidence], occurred_at: f64)
```

**Parameters**

| name | type |
|---|---|
| `sequence` | `int` |
| `kind` | `TransitionKind` |
| `from_model_id` | `str` |
| `to_model_id` | `str` |
| `regime` | `RegimeStatus` |
| `adaptation` | `AdaptationMode` |
| `reason` | `str` |
| `evidence` | `list[Evidence]` |
| `occurred_at` | `f64` |

# `def blocked_activation`

```sema
def blocked_activation(active: ModelDescriptor, candidate: ModelDescriptor, step: int, sequence: int, reason: str, evidence: list[Evidence])
```

**Parameters**

| name | type |
|---|---|
| `active` | `ModelDescriptor` |
| `candidate` | `ModelDescriptor` |
| `step` | `int` |
| `sequence` | `int` |
| `reason` | `str` |
| `evidence` | `list[Evidence]` |

# `def activate_validated`

```sema
def activate_validated(active: ModelDescriptor, candidate: ModelDescriptor, step: int, sequence: int, evidence: list[Evidence], policy: SelectionPolicy) -> ActivationDecision !{}
```

**Parameters**

| name | type |
|---|---|
| `active` | `ModelDescriptor` |
| `candidate` | `ModelDescriptor` |
| `step` | `int` |
| `sequence` | `int` |
| `evidence` | `list[Evidence]` |
| `policy` | `SelectionPolicy` |

**Returns** `ActivationDecision`

**Effects** `!{}`