# recourse
`recourse` is the framework-neutral core for versioned failure contracts in
Rust services.
```toml
[dependencies]
recourse = "=0.0.1-rc.3"
```
It provides:
- permanent catalog codes and type URIs;
- typed, schema-governed public evidence;
- strict RFC 9457 Problem construction and HTTP policy headers;
- structurally separate public Problems and private reports;
- durable operation diagnostics and health findings;
- bounded tolerant client decoding;
- append-only catalog locks and conservative compatibility classification.
Applications register declarations explicitly with `Catalog::builder()`. The
core crate has no async runtime or application-framework dependency. Framework
adapters consume its concrete response parts at the edge.
This minimal program declares one permanent diagnostic and encodes its
canonical HTTP Problem without a server framework:
```rust
use recourse::{
catalog::{Catalog, CatalogSpec, CodeNumber},
diagnostic::{DiagnosticType, NoEvidence},
http::{CorrelationId, Fixed, HttpProblemType, ProblemOccurrence},
};
enum ServiceCatalog {}
impl CatalogSpec for ServiceCatalog {
const NAME: &'static str = "example-service";
const PREFIX: &'static str = "EXM";
const TYPE_BASE: &'static str = "https://example.invalid/problems/";
}
enum ResourceMissing {}
impl DiagnosticType for ResourceMissing {
type Catalog = ServiceCatalog;
type Evidence = NoEvidence;
const NUMBER: CodeNumber = CodeNumber::new(1001);
const TITLE: &'static str = "Resource missing";
const DETAIL: &'static str = "The requested resource does not exist.";
const SUGGESTIONS: &'static [&'static str] = &["Check the resource identifier."];
const DOCS: &'static str = "Verify the identifier before retrying.";
}
impl HttpProblemType for ResourceMissing {
type Policy = Fixed<404>;
}
fn main() -> Result<(), Box<dyn std::error::Error>> {
let catalog = Catalog::<ServiceCatalog>::builder()
.problem::<ResourceMissing>()
.build()?;
let occurrence = ProblemOccurrence::new(
CorrelationId::new("request-01")?,
"/problem-occurrences/request-01",
)?;
let encoded = catalog
.try_problem::<ResourceMissing>(occurrence, NoEvidence)?
.try_encode()?;
assert_eq!(encoded.status().as_u16(), 404);
assert_eq!(encoded.headers()["content-type"], "application/problem+json");
Ok(())
}
```
The catalog owns the status, headers, JSON shape, code, and type URI. Public
evidence must explicitly implement `PublicEvidence`; private source errors use
the structurally separate `PrivateReport` type.
The evidence-schema profile treats retained string `format` keywords as runtime
assertions and rejects unknown formats during catalog construction. Fixed-width
numeric formats require their exact JSON type and receive complete
representation bounds. Platform-sized and 128-bit integer formats are rejected
because the protocol's intermediate JSON representation cannot guarantee their
portable, lossless encoding. Runtime numeric evidence must use Rust primitive
integers or finite floats. `serde_json::Number` and numeric `serde_json::Value`
variants are intentionally unsupported because their serializer-private raw
tokens bypass that governed emitter domain. The exact vocabularies are exposed
as `catalog::SUPPORTED_SCHEMA_FORMATS` and
`catalog::SUPPORTED_SCHEMA_NUMERIC_FORMATS`. Catalog construction also rejects
declared minimum sizes, required members, fixed values, and provably mandatory
nesting that cannot fit the default diagnostic wire profile.
See the [repository](https://github.com/zsumz/recourse) for the Dispatch
reference implementation, executable conformance fixtures, and the canonical
verification gate for the workspace and publishable package artifacts.