Crate rustev_contract

Expand description

Rustev’s versioned wire contract (spec 002).

Every document Rustev reads or writes is defined here, with its schema string, its parse limits, its canonical form and, where it is identified, its identity. An outside project reads Rustev’s records and reports by depending on this crate alone (spec 001, 3.4.5).

Parsing supplied bytes is two-staged (bounded): a scan checks every resource bound before typed deserialization builds anything. Reading the bytes from a transport, and bounding that buffer, is the caller’s job.

Re-exports§

pub use decimal::Decimal;
pub use document::Document;
pub use document::DocumentError;
pub use document::Identified;
pub use time::DurationMs;
pub use time::Timestamp;

Modules§

acquisition: Acquisition wire documents and pure page validation (spec 036, 3.2 and 3.3).
acquisition_record: Acquisition plan bindings and observations (spec 036, 3.10 and 3.14). These records contain digests and metadata, never page contents.
acquisition_step: Definition 2 acquisition vocabulary (spec 036, 3.4 to 3.8).
actionability: Provenance-conditional checks and actionable outcomes (spec 033): the definition 2 actionability member and the wire types of judgment 2’s actions, causes, remediations and questions.
bounded: Bounded JSON: resource limits checked on raw bytes before typed parsing.
cache_entry: rustev.cache-entry/1: one entry of the persistent tier (spec 044, 3.4.3).
calibration: Calibration artifacts, rustev.calibration/1 (spec 002, 3.6).
canonical: Canonical bytes and digests (spec 002, 3.3).
decimal: Fixed-point decimal with nine fractional digits.
definition: Decision definitions, rustev.definition/1 (spec 002, 3.7 to 3.11) and rustev.definition/2 (spec 032, 3.1.1).
descriptor: Backend capability descriptors, rustev.backend/1 (spec 002, 3.9.3). A backend states what it returns; the compiler never assumes more.
document: The document protocol: schema check, bounded parse, canonical bytes and identity (spec 002, 3.2 and 3.3).
dynamic: Dynamic questions (spec 019): a separate, explicitly invoked class for one bounded proposition, classify or rubric question over caller-selected structured context.
eval_report: The versioned evaluation report envelope, rustev.eval-report/1 (R-06).
evidence: Evidence records, rustev.evidence/1, and rustev.evidence/2 for plan 3 (spec 032, 3.10): what one decision used and computed. Emitting and storing them is the runtime’s job (spec 003); the pure core builds the record.
execution: Execution policies, rustev.execution/1 (spec 003, 3.2.2): how the runtime may retry, time out and fall back per semantic step, and the cost budget one decision may draw on. A policy is declared, validated by the compiler and embedded in the plan, so it is part of the PlanId; it is never inferred from whichever backends are installed (R-10).
explanation: Decision explanation wire vocabulary and structural checks (spec 040, section 3). This module describes evidence; it computes no explanation or authorization.
extraction: Structured extraction declarations (spec 038). Compilation remains closed.
extraction_documents: Extraction wire documents (spec 038, 3.3.5 and 3.7).
extraction_results: Plan and result wire members for structured extraction (spec 038).
generation: Bounded generation declarations and plan bindings (spec 037). Template source is retained verbatim. Core owns template compilation.
generation_result: Text results and digest-only evidence (spec 037, 3.10 and 3.15).
grade: Evidence grades, value metadata and presence (spec 032, 3.2 to 3.4).
ids: Identities (spec 002, 3.3.2 and 3.3.3): sha256: and 64 lowercase hex digits. Computed identities come from crate::Identified::id (and content digests from crate::Document::record_digest); supplied ones (ArtifactId, DatasetId, EvaluatorConfigId) are validated only.
judgment: Judgments, rustev.judgment/1, and rustev.judgment/2 for plans with actionability (spec 033, 3.1.3): the typed result of a plan. A judgment is a proposal, an escalation, an unresolved outcome, or (version 2) a refusal or a request for input; it is never a grant and never an effect (spec 001, 3.2). Version 2 carries an action on every unresolved outcome, refusal, request for input and notice (spec 033, 3.5).
limits: The named parse limit sets of spec 002, 3.2.5. Each document type uses exactly one of them through crate::Document::LIMITS.
live: Live re-execution evidence, rustev.live-reexecution/1 (spec 026).
optimization: Neutral runtime optimization policy and evidence vocabulary (spec 017).
output: Supplied semantic backend outputs, rustev.backend-output/1. Validated against the plan before any policy reads them (spec 002, 3.10.2).
parameter: Template-only shapes (spec 034, 3.1 to 3.4). Core checks declaration bounds, locks and site compatibility before substituting JSON values.
plan: Compiled plans, rustev.plan/2 (spec 002, 3.3.4, amended by spec 003, 3.2.1) and rustev.plan/3 (spec 032, 3.1.1). A plan embeds its canonical definition, every binding that affects behavior and its execution policy, so its identity changes whenever behavior can.
plan_bundle: Plan bundle integrity documents (spec 042, 3.3). Signatures and registrations describe integrity, never execution authority.
plan_diff: Plan comparison wire document (spec 034, 3.12). Computing the diff is core’s job; this module defines only its bounded, canonical shape.
profile: Profile documents and definition-independent validation (spec 034, 3.5).
ranking: Ranking and selection declarations (spec 039). Compilation remains closed.
ranking_result: Wire-only ranking results (spec 039). No evaluation or kind conversions.
reason: Retained runtime reasons, rustev.runtime-reason/1 (spec 004, 3.2): a historical runtime observation supplied to the core in place of an output. Only the four runtime reasons are accepted; a reason is never a backend output and never predicts a candidate’s failure.
redaction: The redaction policy, rustev.redaction/1, its evaluation and the keyed digest (spec 028, 3.3 and 3.4).
remote: The rustev.remote/1 protocol documents (spec 009, 3.10) and the vendor-neutral exchange record rustev.remote-exchange/1 (3.9.1).
remote_context: Transport-neutral context callback documents (spec 042, 3.10). Protocol names identify a family; request and response documents carry schemas.
remote_sink: Transport-neutral evidence delivery documents (spec 042, 3.11). A receipt is a delivery observation, never authorization.
replay: Replay bundles, rustev.replay/1 (spec 004, 3.2), and the in-memory capture a runtime hands back (spec 004, 5.3).
request: Request identity documents, rustev.request/1 (spec 004, 3.4.1).
retention: Retention items and availability (spec 004, 3.1.2, 3.1.6 and 3.1.7).
run: Run records, rustev.run/1 (spec 003, 3.9): what the runtime delivers for one admitted decision. The core’s evidence record is carried unchanged in its own member; everything else is a runtime observation, recorded and never promised to repeat (principle XIII).
schema: Schema strings of every document (spec 002, 3.2.1, as amended by spec 003, 3.2: plans are at version 2; execution policies and run records are new; by spec 004, 5.1: replay, request and runtime-reason documents; and by spec 009, 3.10: the remote protocol documents; by spec 032, 3.1.1: the #76 track versions and source descriptors; and by spec 019: the dynamic question documents).
schema_emit: JSON Schema (draft 2020-12) for every public document type and version (spec 027, 3.2.2), derived from the same type definitions the bounded parser enforces. Emission is pure and deterministic: canonical JSON with sorted keys, byte-identical across runs and targets. The schemas are descriptive; the bounded parser stays the only authority on validity.
scope: Replay isolation scopes (spec 004, 3.1.3 to 3.1.5).
screening: Authored screening and its plan bindings (spec 035, 3.4 and 3.5.8). Only document-local shape is checked here; compilation owns semantic checks.
serve: Pure service documents and operation metadata (spec 042).
snapshot: Context snapshots, rustev.snapshot/1 (spec 002, 3.7.3) and rustev.snapshot/2 (spec 032, 3.1.1), whose entries may claim a grade.
source: Context source descriptors, rustev.source/1 (spec 032, 3.3.1): what the host says a source can attest, per definition input and path. Bound at compile time like a backend descriptor; Rustev stores nothing and verifies no source.
time: Time as a value (spec 002, 3.4.4). Nothing in Rustev’s contract or core reads a clock; the evaluation time is supplied.
trace: The span line document, rustev.trace/1 (spec 028, 3.10.1): one compact JSON object per span per line, keys sorted, at most 64 KiB per line.
trace_fields: The field catalogue of span schema rustev.otel/1 (spec 028, 3.5 and 3.6): the closed table of exportable field names and each one’s class rule. A name outside it is never exported, and a reader withholds it.
version: Numeric versions and comparator sets (spec 034, 3.6.1 and 3.6.2).