Expand description
§logit-loom-core
Serializable, backend-neutral contracts for bounded token-stream mechanics.
This crate defines token identifiers, candidate exposure, sampling plans, steering descriptors, checkpoints, bounded audio-prefill contracts, topology-bound activation programs, target-authoritative speculation, and structured-projection compiler/validator/feedback lineage and mechanical receipts. It contains no model runtime or native code.
[dependencies]
logit-loom-core = "=0.2.0"§Example
Build and validate a complete generation contract before handing it to an adapter:
use logit_loom_core::{GenerationPlan, SamplingPlan};
fn main() -> Result<(), Box<dyn std::error::Error>> {
let plan = GenerationPlan {
sampling: SamplingPlan {
seed: 7,
temperature: 0.8,
..SamplingPlan::default()
},
max_tokens: 32,
biases: Vec::new(),
grammar: None,
stops: vec![b"\n\n".to_vec()],
};
plan.validate()?;
let identity = plan.digest()?;
assert_eq!(identity.as_str().len(), 64);
Ok(())
}Plans and receipts implement serde::Serialize and serde::Deserialize.
Digest domains are explicit and versioned; changing a serialized shape or its
interpretation is a compatibility change.
§Boundaries
- Token pieces are arbitrary bytes, not necessarily standalone UTF-8.
AudioPrefillPlanV1binds one projector identity, its declared sample rate, and a bounded caller-owned normalized mono PCM slice. Its receipt binds only a caller-provided audio identity and causal accounting; it never serializes PCM bytes.- Public collections and native strings have documented bounds.
TextModelTopologyV1, activation capture/vector/program contracts,SpeculationPlanV1, and their receipts describe exact mechanics and target/draft lineage without naming a native tensor pointer or model path.TextMechanicsPlanV2composes those mechanics, whileTextMechanicsCheckpointReceiptV2binds an ordinary opaque state receipt to the exact aggregate mechanics and parent lineage which produced it.- Provisional speculative telemetry resolves to admitted or rejected target positions before entering aggregate capture receipts.
StructuredProjectionPlanV1binds semantic component identities without implementing their policy. Attempt receipts distinguish cancellation, authoritative rejection, and selected causal state.- Receipts record mechanics and causal lineage, not model quality or semantic correctness.
- Checkpoint metadata binds an opaque backend state; it does not make that state portable across native builds.
See the workspace overview, architecture, and compatibility policy.
Structs§
- Activation
Capture Plan V1 - Bounded activation-capture request.
- Activation
Capture Receipt V1 - Aggregate evidence for one completed activation capture.
- Activation
Capture Record V1 - One topology-bound captured tensor row.
- Activation
Invocation Receipt V1 - Evidence for one successful native tensor write-back.
- Activation
Invocation RowV1 - Evidence for one successful copy-transform-write transaction.
- Activation
Operation V1 - One ordered, position-scoped activation operation.
- Activation
Program Receipt V1 - Aggregate successful accounting for one activation program runtime.
- Activation
Program V1 - Ordered activation operations and observation requests.
- Activation
Statistics V1 - Deterministic scalar statistics represented by exact
f32bits. - Activation
Vector Accumulator V1 - Deterministic accumulator for sparse activation samples.
- Activation
Vector Bank V1 - Topology-bound sparse activation vectors.
- Activation
Vector Provenance V1 - Mechanical provenance for vector construction.
- Activation
Vector RowV1 - One canonical sparse vector row.
- Activation
Vector Sample V1 - One caller-ordered, content-bound sparse activation sample.
- Audio
Prefill Plan V1 - Exact, model-free contract for one audio projector prefill.
- Audio
Prefill Receipt V1 - Content-free terminal accounting for one projected audio prefill.
- Byte
Feedback Receipt V1 - Complete exact-byte feedback execution for one projection attempt.
- Byte
Feedback Spec V1 - Exact byte-feedback implementation and resource bounds.
- Byte
Feedback Step Receipt V1 - Exact symbolic decision before one native sampling operation.
- Callback
Failure - Complete error or panic isolated at a callback boundary.
- Causal
Position Range V1 - Inclusive causal-position interval.
- Checkpoint
Receipt - Serializable compatibility metadata for one backend-owned causal checkpoint.
- Control
Vector Spec - One in-memory control-vector application.
- Digest
- A domain-separated BLAKE3 digest encoded as 64 lowercase hexadecimal bytes.
- DrySampler
- Don’t Repeat Yourself sampler configuration.
- Generation
Plan - Complete bounded generation mechanics independent of prompt semantics.
- Generation
Plan V2 - Version-two generation mechanics with explicit eager or lazy grammar.
- Generation
Receipt - Mechanical receipt for one bounded generation call.
- Grammar
- An eager llama.cpp GBNF grammar.
- Grammar
Plan V2 - Version-two eager or lazy llama.cpp GBNF grammar.
- Logit
Bias - One additive token-logit bias.
- Lora
Spec - One model-compatible
LoRAadapter application. - Mirostat
Sampler - Stateful Mirostat terminal sampler configuration.
- Observer
Receipt - Mechanical accounting for one generated-token observer.
- Pipeline
Receipt - Aggregate accounting for an ordered transform pipeline.
- Pipeline
Spec - Ordered transform contracts sharing one candidate exposure.
- Prefill
Progress - Progress at one complete text-prefill boundary.
- Prefill
Receipt - Mechanical accounting for controlled prefill.
- Repetition
Sampler - Stateful repetition, frequency, and presence penalties.
- Sampling
Plan - Native sampler configuration.
- Speculation
Boundary Receipt V1 - Target-authoritative accounting for one completed proposal boundary.
- Speculation
Plan V1 - Complete backend-neutral configuration for one speculative text operation.
- Speculation
Receipt V1 - Aggregate proposal and target-acceptance accounting.
- Speculation
Telemetry Resolution V1 - Final disposition of one provisional activation telemetry record.
- Speculative
Checkpoint Receipt V1 - Serializable evidence for one quiescent speculative checkpoint envelope.
- Stage
Receipt - Mechanical accounting for one transform stage.
- Steering
Receipt - Mechanical receipt for one steering lifecycle transition.
- Structured
Attempt Receipt V1 - One generated, incrementally constrained, and validated projection attempt.
- Structured
Compilation Receipt V1 - Evidence that an identified compiler produced one complete projection plan.
- Structured
Mechanic Identity V1 - Content identities for one installed compiler, validator, or feedback implementation and its exact configuration.
- Structured
Projection Plan V1 - Complete compiled mechanics for one structured projection controller.
- Structured
Projection Receipt V1 - Terminal evidence for a projection selected after zero or more explicit cancelled/rejected attempts.
- Structured
Validation Receipt V1 - Content-free evidence from one installed authoritative validator.
- Text
Mechanics Checkpoint Receipt V2 - Exact ordinary-context state captured at an aggregate operation boundary.
- Text
Mechanics Cleanup Receipt V2 - Resource-release and quiescence evidence at aggregate operation completion.
- Text
Mechanics Plan V1 - Complete backend-neutral mechanics for one bounded text operation.
- Text
Mechanics Plan V2 - Aggregate text mechanics with topology-bound activation and speculation.
- Text
Mechanics Receipt V1 - Content-free terminal evidence for
TextMechanicsPlanV1. - Text
Mechanics Receipt V2 - Content-free terminal evidence for
TextMechanicsPlanV2. - Text
Model Topology V1 - Backend-neutral, content-bound model topology.
- TokenId
- A non-negative model-tokenizer identifier.
- Transform
Spec - One content-identified transform contract.
Enums§
- Activation
Capture Positions V1 - Causal positions retained by one activation capture.
- Activation
Capture Retention V1 - Data retained for each selected tensor row.
- Activation
Captured Data V1 - Retained data for one captured tensor row.
- Activation
Operator V1 - Built-in transactional tensor operator.
- Activation
Phase V1 - Decode phase at which one activation operation executes.
- Activation
Position Scope V1 - Causal positions selected by one activation operation.
- Activation
Telemetry Disposition V1 - Causal status of telemetry created during target or draft evaluation.
- Activation
Vector Normalization V1 - Per-row vector normalization contract.
- Activation
Vector Operation V1 - Content-free vector construction performed by an accumulator.
- Callback
Phase - Callback phase that produced a contained failure.
- Candidate
Mode - Candidate-logit exposure presented to every stage in a pipeline.
- Control
Flow - Cooperative action returned at a documented safe execution boundary.
- Core
Error - Failures raised while constructing or validating public contracts.
- Generation
Finish - Why one bounded generation call stopped.
- Grammar
Activation V2 - Activation policy for a version-two native grammar.
- Mirostat
Version - Native Mirostat algorithm version.
- Prefill
Finish - Current or terminal disposition of one controlled prefill operation.
- Speculation
Activation Policy V1 - Explicit target and draft activation-program selection.
- Steering
Action - Lifecycle action recorded at the Rust/native boundary.
- Steering
Kind - Session steering resource kind.
- Structured
Attempt Disposition V1 - Effect of one caller-explicit projection attempt.
- Structured
Validation Status V1 - Authoritative post-generation validation result.
- Text
Speculative Mechanism V1 - Speculative mechanisms a loaded text topology can report.
- Text
Tensor Element Type V1 - Tensor element representation expected at a selected graph site.
- Text
Tensor Site Family V1 - Stable family shared by compatible activation vector rows and tensor sites.
- Text
Tensor Site V1 - Exact graph tensor selected for capture or mutation.
Constants§
- MAX_
ACTIVATION_ CAPTURE_ POSITIONS - Maximum causal positions selected by one capture.
- MAX_
ACTIVATION_ ELEMENTS - Maximum
f32elements copied or retained by one activation operation. - MAX_
ACTIVATION_ INVOCATION_ RECEIPTS - Maximum successful tensor transactions retained in one program receipt.
- MAX_
ACTIVATION_ OBSERVATIONS - Maximum capture-plan observations named by one program.
- MAX_
ACTIVATION_ OPERATIONS - Maximum ordered activation operations in one program.
- MAX_
ACTIVATION_ POSITION_ RANGES - Maximum inclusive causal ranges selected by one contract.
- MAX_
ACTIVATION_ RETAINED_ BYTES - Maximum retained activation bytes declared by one capture.
- MAX_
ACTIVATION_ ROW_ SEQUENCES - Maximum sequence identifiers attached to one logical tensor row.
- MAX_
ACTIVATION_ SITES - Maximum exact tensor sites selected by one capture or operation.
- MAX_
ACTIVATION_ TRANSACTION_ ROWS - Maximum logical rows represented by one tensor transaction.
- MAX_
ACTIVATION_ VECTOR_ INPUTS - Maximum input artifacts represented by vector provenance.
- MAX_
ACTIVATION_ VECTOR_ ROWS - Maximum sparse vector rows in one bank.
- MAX_
AUDIO_ FRAMES - Largest number of mono frames accepted by one audio-prefill plan.
- MAX_
AUDIO_ SAMPLE_ RATE_ HZ - Largest projector-declared sampling rate accepted by this contract.
- MAX_
DRY_ SEQUENCE_ BREAKERS - Maximum exact sequence breakers accepted by one DRY sampler.
- MAX_
DRY_ SEQUENCE_ BREAKER_ BYTES - Maximum UTF-8 bytes accepted in one DRY sequence breaker.
- MAX_
GRAMMAR_ ROOT_ BYTES - Maximum UTF-8 bytes accepted in an eager grammar root name.
- MAX_
GRAMMAR_ SOURCE_ BYTES - Maximum UTF-8 bytes accepted in an eager grammar source.
- MAX_
LAZY_ GRAMMAR_ TRIGGER_ BYTES - Maximum aggregate UTF-8 bytes accepted across lazy-grammar trigger patterns.
- MAX_
LAZY_ GRAMMAR_ TRIGGER_ PATTERNS - Maximum trigger patterns accepted by one lazy grammar.
- MAX_
LAZY_ GRAMMAR_ TRIGGER_ PATTERN_ BYTES - Maximum UTF-8 bytes accepted in one lazy-grammar trigger pattern.
- MAX_
LAZY_ GRAMMAR_ TRIGGER_ TOKENS - Maximum trigger tokens accepted by one lazy grammar.
- MAX_
LOGIT_ BIASES - Maximum additive token biases accepted by one generation plan.
- MAX_
PIPELINE_ STAGES - Maximum stages in one ordered transform pipeline.
- MAX_
SPARSE_ CANDIDATES - Maximum sparse candidates exposed to one transform call.
- MAX_
SPECULATION_ BOUNDARIES - Maximum completed proposal boundaries retained in one aggregate receipt.
- MAX_
SPECULATION_ SEQUENCES - Maximum sequence slots declared by one speculative plan.
- MAX_
SPECULATION_ STATE_ BYTES - Maximum opaque speculative implementation-state bytes.
- MAX_
SPECULATION_ TELEMETRY_ RESOLUTIONS - Maximum activation telemetry resolutions retained at one proposal boundary.
- MAX_
SPECULATIVE_ TOKENS - Maximum speculative tokens requested from one draft boundary.
- MAX_
STOP_ SEQUENCES - Maximum exact byte stop sequences accepted by one generation plan.
- MAX_
STOP_ SEQUENCE_ BYTES - Maximum bytes accepted in one exact stop sequence.
- MAX_
STRUCTURED_ ATTEMPTS - Maximum caller-explicit attempts retained by one projection controller.
- MAX_
STRUCTURED_ CANDIDATES - Maximum model vocabulary accepted by structured byte feedback.
- MAX_
STRUCTURED_ OUTPUT_ BYTES - Maximum generated bytes accepted by one feedback implementation.
- MAX_
STRUCTURED_ SCOPE_ BYTES - Maximum UTF-8 bytes in one caller-defined projection scope.
- MAX_
STRUCTURED_ STEPS - Maximum generated-token decisions accepted by one feedback implementation.
- MAX_
TEXT_ MECHANICS_ CAPTURES - Maximum activation-capture plans bound into one aggregate operation.
- MAX_
TEXT_ MECHANICS_ LORAS - Maximum
LoRAapplications bound into one text-mechanics plan. - MAX_
TEXT_ MODEL_ EXPERTS - Maximum experts represented by one topology contract.
- MAX_
TEXT_ MODEL_ LAYERS - Maximum transformer layers represented by one topology contract.
- MAX_
TEXT_ TENSOR_ NAME_ BYTES - Maximum UTF-8 bytes in a backend-profile tensor name.
- MAX_
TEXT_ TENSOR_ ROW_ ELEMENTS - Maximum elements in one reported model row.
Functions§
- activation_
f32_ row_ identity - Returns the canonical identity of one bounded finite activation
f32row. - structured_
output_ digest - Returns the stable identity used for exact generated projection bytes.
- structured_
tokens_ digest - Returns the stable identity used for a complete ordered token-ID sequence.