Developer Documentation Report: The .slm Artifact Format and TinyRustLM Runtime Integration

Full report

On this page

Overview of the System Architecture and Artifact Domain

The .slm (Small Language Model) file format stands as the foundational execution artifact within the TinyRustLM ecosystem and the broader MiniModel decentralization network. As a highly specialized, locally executed model container, the .slm format is strictly engineered for ingestion by TinyRustLM’s browser-local Rust and WebAssembly (WASM) runtime environment1. This documentation provides a comprehensive architectural and implementational breakdown of the .slm format, often denoted internally and within the magic byte header as the SLM1 binary format1. The analysis delineates its structural paradigms, memory layout, typestate validation state machines, integration with MiniModel metadata, and deployment limitations. The central architectural constraint governing the .slm format within the MiniModel and MiRust architecture is the strict principle of non-hosting. Project servers, including MiRust.com and MiniModel.org, operate as research guides, documentation hubs, and metadata registries; they absolutely do not host the executable model weights, nor do they execute WebAssembly inference or WebGPU computation on the server side1. Executable authority, model artifacts, and measured compatibility remain independently governed1. Consequently, users must explicitly select and pass verified .slm files through a browser file picker to instantiate the local runtime1. This design guarantees user autonomy, preserves copyright boundaries, and enforces localized execution.

The Teleodynamic Rationale for a Custom Binary Format

To understand the necessity of the .slm format, one must analyze the limitations of existing ecosystems and the underlying project philosophy. The TinyRustLM environment is built upon the five commitments of Teleodynamic Learning4. These commitments—specifically defined as two adaptive timescales, an endogenous resource, a local action objective, emergent structural halt, and a diagnosable phase structure—dictate a need for absolute, deterministic control over the runtime memory envelope and the exact execution state4. While GGUF serves as an established, generalized external format with extensive tensor naming conventions and broad quantization families, it is fundamentally misaligned with the strict limitations of a purely browser-local engine5. Generic formats require complex, dynamic parsing and extensive memory allocations during loader initialization. In a browser-local Rust/WASM environment, relying on dynamic memory allocation for a complex artifact loader introduces unpredictable garbage collection pauses within the browser host and potential out-of-memory (OOM) fatal errors in the bounded WASM linear memory space. The SLM1 format mitigates this by being designed around specific Rust-oriented architecture traits, including focused adapters, enums for closed domains, typestates, newtypes, explicit errors, and strictly bounded use of dynamic dispatch1. By flattening the model into an SLM1 binary layout, TinyRustLM completely bypasses dynamic memory planning at runtime. It allows the browser host to transfer the ArrayBuffer directly into the WASM instance, relying on pre-calculated offset directories and deterministic tensor metadata1.

Binary Format Specification: The SLM1 Layout

The .slm format is constructed as a contiguous binary blob intended to be memory-mapped directly into the linear memory space of a WebAssembly module. The structural layout ensures that a parser can iterate through the header, configuration, tokenizer dictionary, and tensor directory in continuous operational time without reading the heavy tensor payloads into higher-level, dynamically allocated data structures.

Fixed-Size Header Structure

The header is fixed-size and acts as the initial typestate boundary during the loader validation sequence. It occupies a predefined contiguous byte region at the start of the file and enforces container checksum and integrity limits3. The fields are strictly little-endian to match the standard byte order of WebAssembly.

Tokenizer and Configuration Serialization

Immediately following the header, the .slm format embeds the tokenizer dictionary and hyperparameter configuration. Because the TinyRustLM ecosystem utilizes a synchronous scalar Rust/WASM path2, the tokenizer boundaries must be strictly defined within the binary itself, avoiding external dependency resolution. The format heavily features the BTOK / BPE1 tokenizer format2. The BTOK segment is structured to allow the Rust loader to instantiate the vocabulary mapping directly from the binary buffer using zero-copy slice references (&\[u8\]). It includes an explicit vocabulary size integer, a continuous sequence of length-prefixed byte strings representing the tokens, and a secondary array for merging priority scores inherent to Byte-Pair Encoding3. Explicit no-op behavior and diagnosable phase structures are embedded here to ensure the tokenizer gracefully fails if a locally input character maps outside the defined closed domain, preventing unbounded loops1. The configuration segment follows the tokenizer. It utilizes a flattened schema check containing the exact hyperparameters required for memory planning and tensor metadata generation1. These parameters typically include the hidden dimension size, intermediate dimension size, number of attention heads, number of key-value heads, the total number of transformer blocks, and the context length (which dictates the static allocation of the Key-Value caches upon initialization)1.

Tensor Directory

The Tensor Directory is located at the absolute position indicated by the DIR\_OFFSET in the header. It serves as the master index for all trainable parameters and buffers contained within the model. To support rapid Rust typestate transitions and memory-safe schema checks, the directory is formalized as an array of fixed-size C-style structs1.

Tensor Payloads and Execution Alignment

Tensor payloads begin at the position denoted by DATA\_OFFSET. The foremost requirement of the SLM1 format is absolute zero-copy compliance. When a user selects a file via the browser file picker, the browser parses the file object into a JavaScript ArrayBuffer. This raw buffer is handed directly to the WebAssembly memory space. To prevent costly and memory-exhaustive copying within the WASM sandbox, the tensor payloads must adhere to strict alignment constraints6. All tensor payloads within the .slm file are padded during the conversion process to ensure they begin on a 64-byte or 128-byte aligned memory boundary. This alignment is not merely a recommendation; it is a critical requirement because the TinyRustLM CPU execution paths and experimental WebGPU dispatch routines demand aligned vectors for SIMD (Single Instruction, Multiple Data) processing and scalar transformer operations1. If a tensor payload begins at an unaligned byte boundary, the model metadata and validation sequence will deterministically reject the artifact to prevent WASM panic conditions2.

Bounded Quantization Modes

The SLM1 binary format explicitly limits the permitted quantization structures to dramatically simplify the WebAssembly Application Binary Interface (ABI) and the Rust execution paths. Unlike overarching server-side frameworks that support dozens of experimental and legacy quantization schemes, TinyRustLM dictates bounded use to maintain the integrity of its synchronous scalar paths1. The baseline format supported is standard F32 (32-bit Float) unquantized scalars1. This is utilized primarily for TinyLM-16M reference workloads where the overall parameter count is small enough that the F32 representation does not violate the maximum memory limits of the browser environment1. The lack of decompression overhead allows the F32 path to achieve maximum throughput in memory-abundant client scenarios. For larger models operating within the restrictive WASM environment, Q8\_0 (8-bit Quantization) serves as the primary compression standard1. This is a block-based quantization format where the tensor is divided into linear blocks (typically of size 32 elements). Each block contains a 32-bit float scaling factor followed by 32 8-bit integers (i8). The Q8\_0 path minimizes memory bandwidth while ensuring the synchronous scalar Rust/WASM path maintains high throughput, as unpacking 8-bit integers into floating-point math is highly optimized across client architectures2. While Q4 (4-bit Quantization) modes are considered experimental and heavily dependent on the specific architecture's memory planning capabilities, they require a similar block architecture but pack two 4-bit values into a single byte1. The loader design must explicitly feature fallback behavior if the local hardware does not support efficient unpacking of the heavily compressed Q4 schema1.

Browser Runtime Loading Mechanics and Memory Planning

The integration between the browser's JavaScript environment and the Rust/WASM runtime relies on highly scrutinized state transitions and strict memory management1. The WebAssembly sandbox isolates execution, meaning data must traverse an interface boundary seamlessly. The browser runtime loading sequence begins with explicit user interaction. The user engages with an \<input type="file"\> HTML DOM element, selecting the local .slm artifact from their local file system. The browser host streams this file into a JavaScript ArrayBuffer. Following this, the implementation encounters the memory handoff gap2. The JavaScript environment must allocate space within the WASM linear memory and copy the ArrayBuffer data into it, traversing the WebAssembly ABI boundary1. This one-time transfer is the only memory copy permitted in the lifecycle of the model. Once the buffer is handed to the Rust environment, the runtime asserts ownership and a global lock is applied2. The Rust runtime assumes exclusive, immutable ownership of this memory region. If multi-threading web workers are active for parallelized execution, the global lock ensures that the underlying tensor data is treated strictly as read-only memory across all threads, preventing race conditions and ensuring deterministic inference2.

Local Import Validation State Machine

Once the memory buffer is handed to Rust, the execution engine relies on typestate validation to enforce strict operational transitions. In Rust, a typestate pattern ensures that the compiler prevents invalid operations by encoding the state of the loader into the type system itself. A failure in any state immediately drops the memory reference, safely executing Resource Acquisition Is Initialization (RAII) cleanup, and returns an explicit error to the JavaScript host1. The validation sequence operates as a linear state machine: First, the loader parses the 64-byte header. It asserts that the magic bytes strictly read SLM11 and that the version is compatible with the compiled runtime. If this fails, the buffer is dropped as an unrecognized format. Second, the system performs cryptographic verification3. The loader computes the checksum of the artifact and asserts it identically matches the CHECKSUM\_ROOT provided in the header. Third, the loader transitions to schema and configuration validation1. It deserializes the flat hyperparameters and validates that they fall within the predefined compatibility limits of the specific compiled WASM engine. This prevents scenarios where a massive configuration (e.g., a model requiring 8GB of KV cache) attempts to initialize inside a WASM environment capped at 4GB. Fourth, directory traversal guarantees memory bounds. The loader iterates through the Tensor Directory, computing the absolute bounds of every tensor (using DATA\_OFFSET \+ offset \+ size\_bytes). It strictly verifies that no computed boundary points outside the allocated WASM memory buffer, categorically preventing buffer over-read vulnerabilities3. Finally, sampler validation and deterministic PRNG (Pseudo-Random Number Generator) limits are instantiated, and the sampler validates fixed candidate storage for the tokenizer to ensure the generation loop cannot allocate unbounded memory during inference3.

Failure Modes and Deterministic Rejection

The loader design incorporates the deterministic rejection of ambiguous artifacts3. Under the Teleodynamic framework, an explicit failure is vastly preferred over an ambiguous, potentially destructive state transition4. Common failure modes natively handled by the ABI include alignment faults. If offset values in the directory are not multiples of the required SIMD alignment boundaries, the execution aborts to prevent a WASM trap during matrix multiplication6. Typestate mismatches represent another failure domain; if the runtime operator expects an F32 tensor for a specific layer but encounters a Q8\_0 quantization flag in the directory, the explicit error framework halts the execution rather than attempting an unsafe memory cast. Furthermore, out-of-memory (OOM) handoff failures occur if the initial file size physically exceeds the contiguous linear memory available to the WebAssembly engine, causing the browser to fail the promise before the Rust loader state machine even begins.

Ecosystem Decentralization: Manifests and Receipts

Because MiRust.com and the associated MiniModel projects maintain strict source-of-truth boundaries and refuse to host executable model weights or artifacts directly, a decentralized routing and metadata architecture is deployed1. The project serves as an evidence model and research index, while the actual artifacts are distributed independently1.

The MiniModel Manifest Relationship

The MiniModel framework orchestrates execution using configuration manifests. A manifest is a lightweight JSON file hosted by MiniModel metadata servers or distributed via peer-to-peer (P2P) nodes. It describes the AI agent's required skills, its modular composition, and the specific .slm dependencies necessary to execute a local action objective4. Crucially, the manifest never contains the model bytes. Instead, it contains cryptographic identities (such as the CHECKSUM\_ROOT), model architecture parameters, license records, and source revisions3. When a client application reads a manifest, it parses these requirements and either initiates a P2P search across a localized swarm or prompts the user via the browser file picker to manually supply an .slm file matching the exact checksum specified in the manifest3. This strictly decouples the enterprise governance of the execution engine from the distribution of copyrighted model artifacts1.

The Conversion Receipt Relationship

To trace provenance from upstream sources—such as Hugging Face safetensors models—to the localized SLM1 format, offline conversion tools generate a "Conversion Receipt." This is an accompanying cryptographic document proving that the Hugging Face source model was deterministically converted into an .slm artifact without malicious tampering. The receipt contains the original source model's SHA-256 hash, the quantization hyper-parameters applied during conversion, and the resulting .slm container checksum. The runtime validation sequence can optionally consume this receipt to verify supply chain observability and ensure compliance with the user's model license policy1.

Upstream Workflows: From Hugging Face to .slm

Because .slm is a custom format explicitly designed for the TinyRustLM execution boundary, upstream models hosted on platforms like Hugging Face (typically distributed in .bin or .safetensors formats) must be converted. This conversion pipeline operates entirely offline on the developer's local machine, reinforcing the evidence model and source-of-truth boundaries by ensuring neither the source nor the destination file touches the MiRust infrastructure1. The offline pipeline begins with intake and parsing, where a specialized Python-based conversion utility loads the .safetensors file and the tokenizer.json configuration. Following ingestion, metadata translation occurs; the utility maps the complex PyTorch or Hugging Face layer nomenclature to the simplified, flat layer names expected by the TinyRustLM scalar transformer path1. Next, quantization routing processes the heavy F32 weights into Q8\_0 or experimental Q4 block structures, significantly reducing the memory footprint1. The utility then performs serialization, writing the BTOK/BPE1 dictionary2, hyperparameter struct, directory index, and the strictly aligned payload buffers into a single, contiguous binary file. Finally, the tool hashes the finalized output and produces the JSON Conversion Receipt to guarantee the provenance of the transformation.

Deliverables and Implementational References

1. Developer Documentation Outline for MiniModel.MiRust.com

This outline represents the proposed structure for integrating .slm format documentation into the official MiniModel site.

• 1\. Introduction to TinyRustLM and MiniModel Architecture
• System Boundaries and the Non-Hosting Principle1.
• Modular AI and the Teleodynamic AI Research Hub1.
• 2\. The .slm Artifact Specification
• SLM1 Binary Format Definition and Magic Bytes1.
• Header Serialization, Endianness, and Byte Alignment6.
• The BTOK / BPE1 Tokenizer Specification2.
• 3\. Memory, Bounds, and Runtime Architecture
• WebAssembly ABI and Contiguous Memory Planning1.
• Navigating the Implementation Memory Handoff Gap2.
• CPU and WebGPU Dispatch Fallback Behavior1.
• 4\. Security, Validation, and Governance
• Cryptographic Container Checksums and Integrity Limits3.
• Typestates and the Rejection of Ambiguous Artifacts3.
• Enterprise Governance, Receipts, and Supply Chain1.
• 5\. Developer Tooling and Workflows
• Hugging Face Source Models to SLM1 Conversion Pipeline.
• Authoring Manifests and Generating Provenance Receipts.
• Phase Diagnostics and the Teleodynamic Phase Structure4.

2. Implementation Glossary

The following terms define the strict operational boundaries of the .slm architecture.

3. Example MiniModel Decentralized Manifest

The following JSON manifest represents how a MiniModel application requests an .slm dependency to fulfill a local action objective without centrally hosting the artifact.

JSON { "manifest\_version": "1.1.0", "model\_identity": { "name": "TinyLM-16M-Instruct", "architecture": "scalar\_transformer", "required\_format": "SLM1" }, "runtime\_constraints": { "quantization\_profile": "Q8\_0", "context\_window\_max": 2048, "max\_memory\_allocation\_mb": 128 }, "cryptographic\_verification": { "checksum\_root": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2", "license\_policy\_compliance": "MIT", "conversion\_receipt\_cid": "ipfs://QmXyZ..." }, "p2p\_resolution\_strategy": { "primary\_uri": "magnet:?xt=urn:btih:...", "fallback\_to\_local\_picker": true } }

4. Example Conversion Receipt

The conversion receipt mathematically tracks the supply chain from an external repository format to the highly constrained local SLM1 file.

JSON { "receipt\_version": "1.0", "timestamp": "2026-07-02T14:57:10Z", "source\_provenance": { "hf\_repository": "TinyRustLM/TinyLM-16M-Base", "hf\_revision": "main", "safetensors\_sha256": "b2c3d4e5f6g7h8i9j0..." }, "conversion\_parameters": { "quantization\_target": "Q8\_0", "tokenizer\_serialization": "BPE1", "alignment\_padding\_bytes": 64 }, "output\_artifact\_integrity": { "file\_name": "tinylm-16m-q8\_0.slm", "magic\_bytes\_written": "SLM1", "final\_checksum\_root": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2" } }

5. Example Validation Sequence (Typestate Transitions)

The table below describes the mandatory, synchronous typestate transitions executed by the Rust runtime when parsing an .slm file. Failure at any node prevents progression.

6. Validation Scenarios: Valid vs. Invalid Artifact Examples

To thoroughly comprehend the strictness of the loader design1, one must analyze specific physical layout scenarios.

7. Security and Observability Checklist for Developers

When implementing loaders, converting datasets, or compiling dependent applications for the .slm format, developers must adhere to the project's enterprise governance, testing, and observability guidelines4.

• \[ \] Strict ABI Buffering Enforcement: Ensure the JavaScript host explicitly drops all external references to the ArrayBuffer immediately after the memory handoff gap is traversed. This guarantees the Rust global lock prevents concurrent, unsafe mutation of the linear memory2.
• \[ \] Bounds-Checked Traversal Iteration: Always utilize memory-safe Rust iterators when traversing the Tensor Directory array. Never cast raw directory pointers blindly into C-structs without strictly validating the n\_dims integer bounds and maximum name\_len limits to prevent buffer exploitation3.
• \[ \] Deterministic PRNG Constraint: Guarantee that the runtime sampler logic accurately enforces deterministic PRNG implementations and replay limits as fundamentally required by the schema check and the Teleodynamic bounds3.
• \[ \] Zero-Copy Memory Pinning: Assert that all active tensor memory wrappers (&\[u8\]) strictly reflect and are statically bound to the exact lifetime of the underlying WebAssembly allocation.
• \[ \] Deny External Dependencies: The .slm parser must remain architecturally self-contained. It must solely utilize core Rust serialization methodologies (such as bytemuck) without dynamically calling out to external C libraries. This aggressively protects the WebAssembly sandbox from foreign memory corruption vulnerabilities inherent to legacy parsers.

8. Developer Onboarding and Integration Guide

For engineers, systems integrators, and AI agents interfacing with the TinyRustLM ecosystem, strict adherence to the project philosophy is required. Phase 1: Understand the Governance Boundary. MiRust.com and MiniModel.org will never serve executable model weights directly1. Do not write application logic attempting to statically fetch() an .slm file from an official repository API. Your front-end application must gracefully orchestrate the prompt to the end-user to supply the file locally, or it must rely on a P2P node protocol indicated in the MiniModel decentralized manifest. Phase 2: Study the Rust Typestates. Extensively review the codebase's rigorous use of Rust typestates and enums1. You cannot instantiate a TransformerLayer struct directly from raw byte pointers. You must programmatically construct a ValidatedModel by passing the raw byte slice through the sequential, strict state transitions defined in the loader design1. Avoid utilizing unsafe blocks to bypass this. Phase 3: Execute the Conversion Utility. When porting new research models from external ecosystems into the architecture, utilize the TinyLM-16M reference workload as a foundational baseline1. Ensure your local Python environment exports the tensors using only the supported Q8\_0 or F32 quantization flags1. Critically, execute the offline testing suite to verify that the generated BTOK tokenizer byte-array perfectly aligns with the model's expected vocabulary matrix indices before generating the final JSON conversion receipt. Phase 4: Implement Runtime Diagnostics. Implement extensive observability hooks by studying the teleodynamic diagnosable phase structure4. Ensure that your web frontend gracefully handles the explicit, enumerated errors emitted by the WASM execution paths. For instance, catching an Error::UnsupportedArch at the WASM boundary and displaying a helpful GUI guide to the user is significantly preferred over allowing a generic, opaque WebAssembly trap to crash the browser tab.

Works cited

1. Research \- MiRust, https://mirust.com/research/
2. Current implementation limitations – MiRust, https://mirust.com/docs/gguf-implementation/current-implementation-limitations/
3. Model metadata and validation – MiRust, https://mirust.com/docs/runtime-architecture/model-metadata-and-validation/
4. The five commitments of Teleodynamic Learning \- MiRust, https://mirust.com/five-commitments-of-teleodynamic-learning/
5. Model format versus project name – MiRust, https://mirust.com/docs/gguf-implementation/model-format-versus-project-name/
6. MiRust site layout hotfix 1.1.1 \- MiRust, https://mirust.com/mirust-site-layout-hotfix-1-1-1/