cortexkit_usage_steps/
lib.rs

1//! Wire contract of the live usage step feed, contract version 1.
2//!
3//! The usage feed provider serves two operations. `usage.steps.subscribe`
4//! sends a [`Notice`] whenever new steps may exist, and `usage.steps.read`
5//! returns them as [`StepRow`]s in a [`ReadReply`]. Apps on every platform
6//! decode these shapes; `CONTRACT.md` in this crate is the normative text and
7//! `test-vectors/usage-steps-v1/` holds the pinned bytes.
8//!
9//! Readers are lenient toward a newer provider: an unknown member on a reply,
10//! notice or row is ignored, and an unknown [`Verdict`], [`StepSource`] or
11//! [`RequestSize`] value decodes as `Other`. Requests are strict: the
12//! provider refuses an unknown request member `malformed`, so the request
13//! types refuse one too.
14//!
15//! [`LatestRows`] applies rows in the order reads return them and keeps the
16//! last row per identity (`harness` plus `step_ref`).
17
18mod cursor;
19mod latest;
20mod open_set;
21mod ops;
22mod row;
23
24pub use cursor::Cursor;
25pub use latest::{Applied, LatestRows};
26pub use open_set::{RequestSize, StepSource, Verdict};
27pub use ops::{Notice, ReadReply, ReadRequest, Refusal, SubscribeRequest};
28pub use row::{live_row_identity, BadCounts, NotClosed, StepRow};
29
30/// The version of this contract. Changing a member's meaning or type, removing
31/// a member, or changing any threshold below makes a new version.
32pub const CONTRACT_VERSION: u32 = 1;
33
34/// Operation that opens the notice stream.
35pub const OP_SUBSCRIBE: &str = "usage.steps.subscribe";
36/// Operation that returns a page of rows.
37pub const OP_READ: &str = "usage.steps.read";
38
39/// `limit` used when a read names none.
40pub const DEFAULT_READ_LIMIT: u32 = 200;
41/// Largest `limit` a read may name; above it the read is refused
42/// `range_too_large`.
43pub const MAX_READ_LIMIT: u32 = 1_000;
44
45/// A retention of at least this is `stable`. Part of the contract version.
46pub const STABLE_RETENTION_AT_LEAST: f64 = 0.95;
47/// A retention of at least this (and below the stable threshold) is
48/// `warning`; anything lower is `bust`. Part of the contract version.
49pub const WARNING_RETENTION_AT_LEAST: f64 = 0.80;
50/// `prompt_dropped` is true when a step's `prompt` is at least this many
51/// tokens smaller than the earlier step it is compared with. Part of the
52/// contract version.
53pub const PROMPT_DROP_TOKENS: u64 = 15_000;
54
55/// Refusal and ending codes. The provider sends them as the `code` of an
56/// error body; see [`Refusal`].
57pub mod codes {
58    /// The caller is not an admitted reader (a local same-user app, or the
59    /// operator's phone relayed by the federation module).
60    pub const NOT_PERMITTED: &str = "not_permitted";
61    /// The request did not decode, or it carries an unknown member.
62    pub const MALFORMED: &str = "malformed";
63    /// Subscribe: more than 16 subscriptions would be open.
64    pub const SUBSCRIPTION_CAPACITY: &str = "subscription_capacity";
65    /// Subscribe: the provider is stopping.
66    pub const DRAINING: &str = "draining";
67    /// Read: `limit` is 0, or `after` is not a cursor the provider issued.
68    /// Read and subscribe: the request names `harness` without `session`, or
69    /// `session` without `harness`.
70    pub const INVALID_REQUEST: &str = "invalid_request";
71    /// Read: `limit` is above [`crate::MAX_READ_LIMIT`].
72    pub const RANGE_TOO_LARGE: &str = "range_too_large";
73    /// Read: `after` is older than the feed holds. The detail carries
74    /// `through`, the newest cursor.
75    pub const CURSOR_EXPIRED: &str = "cursor_expired";
76    /// Subscription ending: the subscriber fell behind its queue bound. The
77    /// detail carries `through`, the last notified cursor.
78    pub const LAGGED: &str = "lagged";
79    /// Subscription ending after the caller's own Cancel. The provider may
80    /// send it as the last frame, and the daemon may drop it because the
81    /// caller asked to stop. A reader treats it, after its own Cancel, as the
82    /// normal end.
83    pub const CANCELLED: &str = "cancelled";
84
85    /// Every code that refuses opening a subscription.
86    pub const SUBSCRIBE_REFUSALS: &[&str] = &[
87        NOT_PERMITTED,
88        SUBSCRIPTION_CAPACITY,
89        DRAINING,
90        MALFORMED,
91        INVALID_REQUEST,
92    ];
93    /// Every code that ends an open subscription with an error.
94    pub const SUBSCRIBE_ENDINGS: &[&str] = &[LAGGED, CANCELLED];
95    /// Every code that refuses a read.
96    pub const READ_REFUSALS: &[&str] = &[
97        MALFORMED,
98        INVALID_REQUEST,
99        RANGE_TOO_LARGE,
100        CURSOR_EXPIRED,
101        NOT_PERMITTED,
102    ];
103}
cortexkit_usage_steps/lib.rs

cortexkit_usage_steps/
lib.rs
