Skip to main content

Crate logit_loom_core

Crate logit_loom_core 

Source
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.
  • AudioPrefillPlanV1 binds 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.
  • TextMechanicsPlanV2 composes those mechanics, while TextMechanicsCheckpointReceiptV2 binds 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.
  • StructuredProjectionPlanV1 binds 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§

ActivationCapturePlanV1
Bounded activation-capture request.
ActivationCaptureReceiptV1
Aggregate evidence for one completed activation capture.
ActivationCaptureRecordV1
One topology-bound captured tensor row.
ActivationInvocationReceiptV1
Evidence for one successful native tensor write-back.
ActivationInvocationRowV1
Evidence for one successful copy-transform-write transaction.
ActivationOperationV1
One ordered, position-scoped activation operation.
ActivationProgramReceiptV1
Aggregate successful accounting for one activation program runtime.
ActivationProgramV1
Ordered activation operations and observation requests.
ActivationStatisticsV1
Deterministic scalar statistics represented by exact f32 bits.
ActivationVectorAccumulatorV1
Deterministic accumulator for sparse activation samples.
ActivationVectorBankV1
Topology-bound sparse activation vectors.
ActivationVectorProvenanceV1
Mechanical provenance for vector construction.
ActivationVectorRowV1
One canonical sparse vector row.
ActivationVectorSampleV1
One caller-ordered, content-bound sparse activation sample.
AudioPrefillPlanV1
Exact, model-free contract for one audio projector prefill.
AudioPrefillReceiptV1
Content-free terminal accounting for one projected audio prefill.
ByteFeedbackReceiptV1
Complete exact-byte feedback execution for one projection attempt.
ByteFeedbackSpecV1
Exact byte-feedback implementation and resource bounds.
ByteFeedbackStepReceiptV1
Exact symbolic decision before one native sampling operation.
CallbackFailure
Complete error or panic isolated at a callback boundary.
CausalPositionRangeV1
Inclusive causal-position interval.
CheckpointReceipt
Serializable compatibility metadata for one backend-owned causal checkpoint.
ControlVectorSpec
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.
GenerationPlan
Complete bounded generation mechanics independent of prompt semantics.
GenerationPlanV2
Version-two generation mechanics with explicit eager or lazy grammar.
GenerationReceipt
Mechanical receipt for one bounded generation call.
Grammar
An eager llama.cpp GBNF grammar.
GrammarPlanV2
Version-two eager or lazy llama.cpp GBNF grammar.
LogitBias
One additive token-logit bias.
LoraSpec
One model-compatible LoRA adapter application.
MirostatSampler
Stateful Mirostat terminal sampler configuration.
ObserverReceipt
Mechanical accounting for one generated-token observer.
PipelineReceipt
Aggregate accounting for an ordered transform pipeline.
PipelineSpec
Ordered transform contracts sharing one candidate exposure.
PrefillProgress
Progress at one complete text-prefill boundary.
PrefillReceipt
Mechanical accounting for controlled prefill.
RepetitionSampler
Stateful repetition, frequency, and presence penalties.
SamplingPlan
Native sampler configuration.
SpeculationBoundaryReceiptV1
Target-authoritative accounting for one completed proposal boundary.
SpeculationPlanV1
Complete backend-neutral configuration for one speculative text operation.
SpeculationReceiptV1
Aggregate proposal and target-acceptance accounting.
SpeculationTelemetryResolutionV1
Final disposition of one provisional activation telemetry record.
SpeculativeCheckpointReceiptV1
Serializable evidence for one quiescent speculative checkpoint envelope.
StageReceipt
Mechanical accounting for one transform stage.
SteeringReceipt
Mechanical receipt for one steering lifecycle transition.
StructuredAttemptReceiptV1
One generated, incrementally constrained, and validated projection attempt.
StructuredCompilationReceiptV1
Evidence that an identified compiler produced one complete projection plan.
StructuredMechanicIdentityV1
Content identities for one installed compiler, validator, or feedback implementation and its exact configuration.
StructuredProjectionPlanV1
Complete compiled mechanics for one structured projection controller.
StructuredProjectionReceiptV1
Terminal evidence for a projection selected after zero or more explicit cancelled/rejected attempts.
StructuredValidationReceiptV1
Content-free evidence from one installed authoritative validator.
TextMechanicsCheckpointReceiptV2
Exact ordinary-context state captured at an aggregate operation boundary.
TextMechanicsCleanupReceiptV2
Resource-release and quiescence evidence at aggregate operation completion.
TextMechanicsPlanV1
Complete backend-neutral mechanics for one bounded text operation.
TextMechanicsPlanV2
Aggregate text mechanics with topology-bound activation and speculation.
TextMechanicsReceiptV1
Content-free terminal evidence for TextMechanicsPlanV1.
TextMechanicsReceiptV2
Content-free terminal evidence for TextMechanicsPlanV2.
TextModelTopologyV1
Backend-neutral, content-bound model topology.
TokenId
A non-negative model-tokenizer identifier.
TransformSpec
One content-identified transform contract.

Enums§

ActivationCapturePositionsV1
Causal positions retained by one activation capture.
ActivationCaptureRetentionV1
Data retained for each selected tensor row.
ActivationCapturedDataV1
Retained data for one captured tensor row.
ActivationOperatorV1
Built-in transactional tensor operator.
ActivationPhaseV1
Decode phase at which one activation operation executes.
ActivationPositionScopeV1
Causal positions selected by one activation operation.
ActivationTelemetryDispositionV1
Causal status of telemetry created during target or draft evaluation.
ActivationVectorNormalizationV1
Per-row vector normalization contract.
ActivationVectorOperationV1
Content-free vector construction performed by an accumulator.
CallbackPhase
Callback phase that produced a contained failure.
CandidateMode
Candidate-logit exposure presented to every stage in a pipeline.
ControlFlow
Cooperative action returned at a documented safe execution boundary.
CoreError
Failures raised while constructing or validating public contracts.
GenerationFinish
Why one bounded generation call stopped.
GrammarActivationV2
Activation policy for a version-two native grammar.
MirostatVersion
Native Mirostat algorithm version.
PrefillFinish
Current or terminal disposition of one controlled prefill operation.
SpeculationActivationPolicyV1
Explicit target and draft activation-program selection.
SteeringAction
Lifecycle action recorded at the Rust/native boundary.
SteeringKind
Session steering resource kind.
StructuredAttemptDispositionV1
Effect of one caller-explicit projection attempt.
StructuredValidationStatusV1
Authoritative post-generation validation result.
TextSpeculativeMechanismV1
Speculative mechanisms a loaded text topology can report.
TextTensorElementTypeV1
Tensor element representation expected at a selected graph site.
TextTensorSiteFamilyV1
Stable family shared by compatible activation vector rows and tensor sites.
TextTensorSiteV1
Exact graph tensor selected for capture or mutation.

Constants§

MAX_ACTIVATION_CAPTURE_POSITIONS
Maximum causal positions selected by one capture.
MAX_ACTIVATION_ELEMENTS
Maximum f32 elements 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 LoRA applications 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 f32 row.
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.