requisite 0.1.0

Data-handling requirements encoded in Rust types.
Documentation
# requisite

`requisite` makes data-handling requirements part of Rust function signatures.
Values carry the state required by the next operation, and APIs state that
requirement in their parameter types.

```rust
use requisite::prelude::*;

fn db_lookup(id: Tainted<u64, Trusted>) -> String { /* ... */ }

let body = Tainted::<_, Untrusted>::from_input(request_body);
let customer_id = sanitize(body, clean_customer_id);
db_lookup(customer_id);
```

The receiving function states its requirement in its parameter type. The
compiler then verifies that callers perform the required transition.

| module | role |
|---|---|
| [`trust`]#trust | routes external input through a named sanitizer before trusted use |
| [`confidence`]#confidence | converts a probability into an action tier and issues proof for the highest tier |
| [`fresh`]#freshness | checks TTLs at read time and binds scoped values to their use site |

## Installation

```sh
cargo add requisite
```

`requisite` supports Rust 1.70 and later.

## Guides

| guide | use it to |
|---|---|
| [Getting started]docs/getting-started.md | add `requisite` and build an end-to-end flow |
| [Trust transitions]docs/trust.md | route external input through infallible or fallible policies |
| [Confidence gates]docs/confidence.md | validate probabilities and authorize high-confidence actions |
| [Freshness]docs/freshness.md | enforce TTLs, recover stale values, and scope live data |
| [Integration patterns]docs/integration.md | place wrappers at application boundaries and design typed APIs |

## Trust

```rust
use requisite::prelude::*;

fn db_lookup(id: Tainted<u64, Trusted>) -> String { /* ... */ }

let raw = Tainted::<_, Untrusted>::from_input("42; DROP TABLE customers".into());

println!("{:?}", raw.as_ref());

let clean = try_sanitize(raw, |s| {
    s.chars()
        .filter(char::is_ascii_digit)
        .collect::<String>()
        .parse::<u64>()
})?;
db_lookup(clean);
```

`Tainted<T, Untrusted>` marks data at an input boundary. `sanitize` handles
infallible transformations, while `try_sanitize` returns validation errors to
the caller. Successful transitions produce `Tainted<U, Trusted>`, which trusted
sinks accept directly.

The sanitizer closure defines what “trusted” means for a specific sink. Keep
the destination's cleaning policy in that closure. `widen()` supports APIs that
accept a lower trust requirement.

See [Trust transitions](docs/trust.md) for validation, type-changing policies,
and sink design.

## Confidence

`Confident<T>` carries a value and a validated probability. `gate()` applies the
default thresholds, and `gate_with()` accepts application-defined thresholds.

```rust
let aurora = Confident::new(forecast(kp_index), 0.97)?;

let plan = match aurora.gate() {
    Gate::HighConfidence(proof, _) => {
        wake_slepp(proof);
        "woke him up"
    }
    Gate::Likely(_) => {
        buzz_phone();
        "sent a buzz"
    }
    Gate::Unsure(_) => "logged it",
};
```

The highest tier includes a `Certain` token. Functions such as `wake_slepp` can
require that token, making a successful confidence check part of their call
contract. Lower tiers remain available for proportionate actions such as a
notification or log entry.

```rust
let forecast = Confident::new(predicted_event, 0.99)?;
let thresholds = Thresholds::new(0.70, 0.98)?;
match forecast.gate_with(thresholds) {
    Gate::HighConfidence(proof, value) => act(proof, value),
    Gate::Likely(value) => notify(value),
    Gate::Unsure(value) => record(value),
}
```

Custom thresholds may raise the `Certain` boundary above `0.95`. The lower
bound keeps every `Certain` token consistent for functions that require one.

See [Confidence gates](docs/confidence.md) for threshold configuration and
typed action authorization.

## Freshness

```rust
let quote = Fresh::fetch(price, Duration::from_secs(30));

match quote.get() {
    Ok(price) => charge(customer, *price),
    Err(stale) => println!("price is {} old, refetching", stale.age.as_secs()),
}
```

`Fresh::get` compares the value's age with its TTL and returns either the value
or a `Stale` error containing both durations. `into_inner` performs the same
check while consuming the wrapper, allowing ownership of a fresh non-`Clone`
value to move into the next operation. A stale result returns the value in
`StaleValue<T>`. `fetched_at` supports deterministic tests and rejects
timestamps ahead of the current monotonic clock.

`with_live` handles values whose validity is tied to one operation:

```rust
with_live(price, |live| {
    let total = live.get().cents + tax;
    total
});
```

The branded `Live` value stays within the closure while derived owned values can
be returned. The closure’s return type is independent of the private lifetime
brand, so retaining `Live` produces a lifetime error at the return site.

See [Freshness](docs/freshness.md) for cache access, stale-value recovery, and
deterministic tests.

## Enforcement model

| requirement | enforcement |
|---|---|
| trusted sink arguments | `Tainted<T, Trusted>` parameter types |
| confidence-based action tiers | `Confident::gate()`, `gate_with()`, and `Gate<T>` |
| high-confidence action authorization | private `Certain` construction |
| operation-scoped values | branded `Live<'id, T>` lifetimes |
| TTL validity | `Fresh::get()` or `into_inner()` at read time |
| sanitization policy | the closure passed to `sanitize` or `try_sanitize` |

Runtime checks produce types that carry their result into the next operation.
For example, `gate()` converts a probability into a `Gate<T>`, and the highest
tier carries the `Certain` token required by sensitive actions.

## Compile-time guarantees

`tests/ui/` contains compile-fail cases for each type-level contract. `trybuild`
compares the compiler output with checked-in snapshots, so CI detects changes
that weaken a contract.

| test | contract |
|---|---|
| `untrusted_to_sink.rs` | trusted sinks require sanitized input |
| `widen_upward.rs` | trust promotion goes through `sanitize` |
| `confidence_as_bool.rs` | confidence values go through `gate` |
| `forge_certain.rs` | `Certain` originates from the highest gate tier |
| `escape_live.rs` | scoped values remain inside their closure |

Regenerate snapshots after an intentional compiler diagnostic change:

```sh
TRYBUILD=overwrite cargo test --test compile_fail
```

Review the resulting diff to confirm that each failure still exercises its
documented contract.

## Try it

```sh
cargo run --example payment_flow
cargo test
```

## Layout

```
src/trust.rs             Tainted<T, Tr>, sanitize, widen
src/confidence.rs        Confident<T>, gate() -> Gate, Certain
src/fresh.rs             Fresh<T> with a TTL; scoped::with_live
examples/payment_flow.rs   payment and alerting example
tests/runtime.rs            behavior tests
tests/ui/*.rs + .stderr     compile-fail tests
docs/                       user guides
```

## License

Licensed under either of

- Apache License, Version 2.0 ([LICENSE-APACHE]LICENSE-APACHE)
- MIT license ([LICENSE-MIT]LICENSE-MIT)

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.