Skip to main content

hyprstream_decision_stub/
lib.rs

1//! # hyprstream-decision-stub — System One P0.7 stub decision service + wire smoke test
2//!
3//! A deterministic mock decision service returning **jev-1-shaped, schema-valid answers**
4//! behind the two contracts the real serving paths will implement:
5//!
6//! 1. **The jev-1 JSON/HTTPS facade** ([`facade`]): `POST /v1/systemone` and
7//!    `GET /v1/models` with the envelope, answer derivations, and error shapes of the
8//!    jev-1 compatibility profile pinned by `hyprstream-decision` (P0.1a). This is the
9//!    portability-prove surface: the stock TypeSafe SDKs (`typesafe-sdk-python`,
10//!    `@typesafe-ai/sdk`, both MIT) run against it unmodified via `TYPESAFE_BASE_URL`
11//!    (S6a §4 — the adapter never speaks the `/v1/systemone` wire, so stock-SDK
12//!    repointing is the proof).
13//! 2. **The P3.5 Flight SQL/ADBC `decide` contract** ([`flight`]): a prepared statement
14//!    pins a question set plus the (schema, model, calib) version triple; bound parameter
15//!    batches carry one `state` per row; the result stream is a
16//!    `hyprstream-decision` [`arrow`](https://docs.rs) `DecisionSchema` batch. Handles
17//!    are content-derived and unknown handles fail loudly (`not_found`) — the drift
18//!    semantics P3.5 requires of prepared statements.
19//!
20//! The mock ([`mock`]) is **deterministic**: distributions are a hash of
21//! (model id, canonical question serialization, state, row index), so every byte on the
22//! wire is reproducible and the wire-overhead floor (`tests/wire_floor.rs`) can pin exact
23//! sizes. It is not a model — it exists so contract conformance and overhead are
24//! measurable before P1.x lands.
25//!
26//! ## Facade decision — bare bool/number entries (deferred from P0.1a, owned by P0.7)
27//!
28//! The upstream jev-1 `EntryType` is `string | object | array | null`; bare booleans and
29//! numbers in entry positions are outside it. `hyprstream-decision`'s IR admits
30//! [`Entry::Bool`](hyprstream_decision::entry::Entry) / `Entry::Number` as a documented
31//! superset-permissive extension (structured criteria routinely carry numeric
32//! thresholds). **Decision: the facade ACCEPTS bare booleans and finite numbers in every
33//! entry position** (`state`, `instructions`, criteria values) and treats them as the
34//! IR's native scalars — canonical serialization renders them as their JSON literals
35//! (`true`, `42.5`). It does **not** stringify them (that would change rubric text the
36//! encoder trains on) and does **not** reject them (the IR, the Arrow contract, and the
37//! scorer all handle them). Consequence, documented for P3.6 migration recipes: a
38//! request using bare scalars is valid against this superset profile but is **not
39//! portable to the upstream service**, whose schema admits only string/object/array/null.
40//!
41//! ## What the stub deliberately does not do
42//!
43//! No auth (any Bearer token is accepted; a missing one is a 401), no rate limiting, no
44//! persistence, no calibration. `usage.input_tokens` is a documented stub approximation
45//! (`ceil(serialized_bytes / 4)` over the canonical serialization — S6a A11 leaves the
46//! tokenizer unspecified; consumers must not compare counts cross-service), and
47//! `output_tokens` is the sum of answered cardinalities.
48
49pub mod facade;
50pub mod flight;
51pub mod mock;
52pub mod render;
53pub mod wire;