Provenance

Provenance in Sounio is not just a logging concern; it is part of how the language wants knowledge-bearing values to remain auditable. The current artifact does not expose the full research model everywhere, but it already enforces an important discipline around intentional boundary crossing.

Current contract

• The clearest provenance boundary in the public surface is still explicit unwrap with a reason.
• Public docs should describe provenance as part of a value’s meaning, not as an after-the-fact annotation.
• When uncertainty and confidence matter, provenance is part of whether a program should be trusted at all.

Where this lives in the repo

• docs/reference/KNOWLEDGE_REFERENCE.md explains the larger epistemic data model.
• docs/research/vancomycin-uncertainty.md shows how provenance and confidence affect a real clinical decision path.
• self-hosted/check/epistemic.sio is the implementation-facing place to inspect current checker logic.

Boundary discipline

let measured = Knowledge { value: 14.2 }
let plain: f64 = measured.unwrap("final report boundary")

Documentation guidance

• When you document a plain numeric result derived from a Knowledge value, explain where and why the unwrap happened.
• If a workflow needs stronger provenance guarantees than the checked artifact currently exposes, say so directly.
• Do not collapse provenance, uncertainty, and confidence into one generic “metadata” bucket in user-facing docs.