# SLM Format ## Purpose `.slm` is the local model file format for TinyRustLM. It is designed for simple browser loading and strict Rust-side validation. ## Constraints The format is little-endian, self-describing, versioned, non-JSON, and static. It has no dynamic schema language and no dependency on GGUF, ONNX, safetensors, or external tokenization formats. ## Data Structures The v1 header stores model dimensions, tokenizer offsets, tensor directory offsets, tensor count, tensor data offset, and checksum. The checksum is a simple custom u64 over the complete file with the checksum field itself treated as zero, so the packer can write it after all payload bytes are finalized. Tensor directory entries store name hash, dtype, rank, dimensions, data offset, byte length, quant scale offset, and block size. q8_0 uses one f32 scale per row. q4_0 uses f32 scales per row block. The tokenizer section is now validated as either `BTOK` byte-tokenizer metadata or `BPE1` custom BPE metadata. ## Binary Formats Header fields start with four bytes `SLM1`, followed by u32/u64/f32 fields in little-endian order. Tensor directory entries are 64 bytes. Tensor payloads and quantization scale payloads are aligned to 64-byte offsets. `BTOK` tokenizer sections contain magic, version, fixed vocab size, and special token ids. `BPE1` tokenizer sections contain magic, version, vocab size, special token ids, token count, merge count, variable token records, and merge records. BPE token records store `token_id`, byte length, and raw bytes. BPE merge records store `left`, `right`, `output`, and `rank`. ## Failure Cases Invalid magic, short files, unsupported versions, zero checksum, checksum mismatch, zero dimensions, attention shape mismatch, out-of-range offsets, malformed tokenizer sections, malformed tensor directory entries, unsupported dtype, missing scale payloads, invalid q4 block sizes, missing required tensors, and an omitted `output.weight` without the v1 tied-output flag are fatal loader errors. ## Validation Rules The parser validates the file has enough bytes before every read. Header length must be at least the v1 minimum. Tensor data offset must be 64-byte aligned. A v1 file must carry a nonzero checksum, and the parser recomputes the checksum with bytes 100..108 treated as zero before accepting the header. Each tensor payload range must fit inside the file. The model loader validates dtype-specific byte lengths and scale counts before decoding tensors. The v1 tied-output flag is `flags & 1 != 0`; when set, `output.weight` may be omitted and output projection uses `tok_embeddings.weight`. Without that flag, `output.weight` remains required. The native packer also exposes `tinyrustlm-slm-pack validate ` as an admission gate for generated or future converted models. That command verifies checksum, byte-tokenizer or BPE metadata, required tensor names and shapes, dtype-specific payload lengths, quantization scale ranges, finite f32 payload values, duplicate tensor hashes, and reports the accepted shape, tensor count, parameter count, quantization mode, and checksum. The packer also exposes a line-based provenance sidecar: `tinyrustlm-slm-pack manifest [source_kind]` and `tinyrustlm-slm-pack validate-manifest `. The sidecar is outside the v1 binary file so the runtime format stays stable. It binds model bytes, `.slm` checksum, shape, tensor count, parameter count, quantization mode, source kind, admission status, and quality boundary. Deterministic smoke models must not claim trained quality; converted trained models validate only as structure-accepted and quality-pending. The packer also exposes a line-based parent compatibility report: `tinyrustlm-slm-pack compatibility [output.compat]`. The command validates both `.slm` files first, then records `compatible_parent_set`, parent byte counts, `.slm` checksums, shape summaries, tensor counts, parameter counts, quantization labels, output-head contracts, format flags, tokenizer checksums, and tensor layout checksums. The report is outside the v1 binary file and is intended as a no-crate assembly gate for future offline model-breeding operators. The packer also exposes a line-based candidate lineage template: `tinyrustlm-slm-pack lineage-template [resource-budget]` and `tinyrustlm-slm-pack validate-lineage `. The template accepts only a passing compatibility report. It records the candidate id, planned status, operator id, resource budget, compatibility report checksum, parent checksums, parent shapes, parent quantization, parent output-head contracts, pending candidate artifact paths, and the next admission gate. The packer also exposes offline direct-parameter operators. `tinyrustlm-slm-pack blend-candidate [parent0-weight-ppm]` and `tinyrustlm-slm-pack validate-blend-candidate ` validate lineage, check supplied parent checksums against the compatibility report, dequantize compatible tensors as needed, blend f32 values by parts-per-million weights, write a normal `.slm`, and write an operator receipt that validation recomputes byte-for-byte. `tinyrustlm-slm-pack delta-candidate [delta-weight-ppm]` and `tinyrustlm-slm-pack validate-delta-candidate ` use the same gates, compute `base + weight * (target - base)` with signed parts-per-million weights, and bind a recomputable task-delta receipt to the output `.slm`. `tinyrustlm-slm-pack sparse-delta-candidate [delta-weight-ppm] [keep-ppm]` and `validate-sparse-delta-candidate` use the same base/target contract, select the largest absolute target-minus-base deltas by keep rate, leave unselected entries at the base value, and bind a recomputable sparse task-delta receipt with selection metric, parameter counts, density and nonzero-delta retention ppm, pruned/unchanged counts, and an implicit top-k mask checksum. The packer also exposes offline adapter artifact paths. `tinyrustlm-slm-pack adapter-delta ` validates lineage, checks compatibility-bound parent checksums, dequantizes compatible tensors as needed, and writes an `ADP1` binary package containing raw f32 `target - base` tensor deltas in parent tensor order. `tinyrustlm-slm-pack validate-adapter-delta ` recomputes the package and manifest byte-for-byte. `tinyrustlm-slm-pack sparse-adapter-delta [delta-weight-ppm] [keep-ppm]` writes an `ASP1` sparse f32 task-delta package with sorted `(u64 value_index, f32 delta)` pairs per tensor, using the largest absolute target-minus-base deltas by keep rate. `tinyrustlm-slm-pack low-rank-adapter-delta [rank-limit]` writes an `ALR1` low-rank f32 task-delta package with deterministic cross-residual `A` and `B` factors for matrix tensors. `validate-sparse-adapter-delta` and `validate-low-rank-adapter-delta` recompute their packages and manifests byte-for-byte. Raw adapter manifests record `adapter_artifact_kind=raw-f32-task-delta-v1`; sparse manifests record `adapter_artifact_kind=sparse-f32-task-delta-v1`, `adapter_sparse_pair_width_bytes=12`, density, nonzero-delta retention, selected/pruned/unchanged counts, and an implicit sparse mask checksum; low-rank manifests record `adapter_artifact_kind=low-rank-f32-task-delta-v1`, `adapter_low_rank_format=ALR1`, component limit/cap, matrix and active tensor counts, factor density ppm, and initial/residual L1 microunits. F32-base raw/sparse manifests record `adapter_apply_status=runtime-f32-compatible-or-fuse-to-slm`; q8_0 and q4_0 raw/sparse manifests record `adapter_apply_status=runtime-q8-q4-compatible-or-fuse-to-slm`; low-rank manifests record runtime-compatible low-rank apply statuses. `tinyrustlm-slm-pack fuse-adapter-delta ` validates a raw `ADP1` package and manifest, checks its header and tensor directory against the base parent, fuses base plus deltas into a normal `.slm` candidate using the base parent dtype/layout, and writes an adapter-fuse receipt. `validate-fuse-adapter-delta` recomputes the fused candidate and receipt byte-for-byte before candidate-manifest. The runtime can apply compatible `ADP1` raw, `ASP1` sparse, or `ALR1` low-rank packages to an already loaded f32, q8_0, or q4_0 model through the WASM ABI; it validates the same identity fields and payload checksums before mutating loaded tensors, re-quantizes compact q8_0 rows or q4_0 blocks when needed, then clears generation and KV state. The checked browser fixtures serve `models/tiny-test-model-self.adp1`, `models/tiny-test-model-q8-self.adp1`, and `models/tiny-test-model-q4-self.adp1` as local zero-delta sidecars for the current browser ADP1 route. The packer also exposes a line-based candidate artifact manifest: `tinyrustlm-slm-pack candidate-manifest ` and `tinyrustlm-slm-pack validate-candidate `. The command validates lineage first, validates the candidate `.slm`, requires the candidate to match the direct-parameter parent contract, then records lineage checksum, candidate checksum, shape, tokenizer checksum, tensor layout checksum, admission status, pending eval status, and the next promotion gate. The packer also exposes line-based promotion templates. `tinyrustlm-slm-pack promotion-template [promoter-id] [promotion-scope]` and `tinyrustlm-slm-pack validate-promotion ` validate the two-parent candidate artifact manifest first, record the candidate manifest checksum, keep runtime-smoke and eval statuses pending, and keep browser selector plus public-claim admission closed until later evidence sidecars exist. `tinyrustlm-slm-pack multi-parent-promotion-template --parents [...parent.slm] --admissions [...input.admission]` and `validate-multi-parent-promotion` validate the sign-merge candidate manifest first, then bind the candidate manifest checksum, operator receipt checksum, parent-pool recipe checksum, ledger/review/admission checksums, parent count, candidate `.slm` fields, and pending runtime-smoke/eval route for the multi-parent path. The packer also exposes line-based runtime-smoke, selector admission, promotion ledger, population review, parent-pool recipe, sign-merge candidate, multi-parent candidate manifest, multi-parent promotion, multi-parent selector admission, and selector registry records. `tinyrustlm-slm-pack runtime-smoke ` writes a sidecar bound to the provenance manifest checksum, `.slm` checksum, source kind, model shape, and passed runtime-smoke decision; `validate-runtime-smoke` proves it still matches. `tinyrustlm-slm-pack admission-record [selector-id]` accepts only a valid promotion, runtime-smoke sidecar, and passed converted-trained eval sidecar. The resulting admission record binds all evidence checksums, marks the browser selector as admitted, and keeps public claims bound to the declared eval scope. `tinyrustlm-slm-pack promotion-ledger [...input.admission]` writes a hash-chained promotion history from admitted records; `validate-promotion-ledger` rejects entry drift and duplicate candidate artifacts. `tinyrustlm-slm-pack population-review [...input.admission]` validates the ledger against the same admissions, ranks candidates by quality, artifact frugality, and quantization fit, records a weighted fitness-objective vector contract plus per-entry objective checksums, then records the frontier candidate and parent-pool route; `validate-population-review` recomputes the review from ledger plus admissions. `tinyrustlm-slm-pack parent-pool-recipe [...input.admission]` validates the review, requires the reviewed parents to share one direct-parameter contract, and writes ranked parent roles, fitness-normalized seed weights, relatedness metric/scope/pair count/status, a shared relatedness checksum, and per-parent relatedness group fields; `validate-parent-pool-recipe` recomputes the recipe from ledger, review, and admissions. `tinyrustlm-slm-pack sign-merge-candidate --parents [...parent.slm] --admissions [...input.admission]` validates the recipe and supplied parent artifacts, uses parent 0 as the frontier base, applies seed-weighted positive or negative delta consensus across the remaining parents, writes a normal `.slm`, and records recipe, relatedness, ledger, review, admission, parent, sign-count, and candidate checksum fields; `validate-sign-merge-candidate` recomputes the candidate and receipt byte-for-byte. `tinyrustlm-slm-pack multi-parent-candidate-manifest --parents [...parent.slm] --admissions [...input.admission]` validates that sign-merge receipt, then writes a manifest with receipt checksum, recipe checksum, relatedness summary, parent summaries, candidate `.slm` fields, pending eval status, and next promotion route; `validate-multi-parent-candidate` recomputes it. `tinyrustlm-slm-pack multi-parent-promotion-template --parents [...parent.slm] --admissions [...input.admission]` validates that manifest and writes a promotion template for runtime-smoke/eval handoff; `validate-multi-parent-promotion` recomputes it. `tinyrustlm-slm-pack multi-parent-admission-record --parents [...parent.slm] --admissions [...input.admission]` accepts only that validated multi-parent promotion template plus matching provenance, runtime-smoke, and passed eval sidecars. The resulting record binds the sign-merge receipt, parent-pool recipe, review, ledger, admission-set, candidate, provenance, runtime, and eval checksums; `validate-multi-parent-admission` recomputes it. `tinyrustlm-slm-pack selector-registry [...input.admission]` accepts selector admission records and multi-parent admission records whose candidate paths resolve under served `tinyrustlm/models/`, writes browser-safe `../models/*.slm` routes, and `validate-selector-registry` rejects entry drift. Generated bundle registries may also carry optional f32/q8_0/q4_0 adapter route fields for a selected entry. Single-route registries use `entry.N.adapter_path`, `entry.N.adapter_manifest_path`, `entry.N.adapter_label`, `entry.N.adapter_apply_status`, `entry.N.adapter_artifact_checksum`, and `entry.N.adapter_manifest_checksum`. Adapter-family registries keep those fields as the first-route mirror and add `entry.N.adapter_count` plus indexed `entry.N.adapter.K.path`, `manifest_path`, `label`, `apply_status`, `artifact_checksum`, and `manifest_checksum` fields. A generated bundle may also include `entry.N.adapter_family_receipt_path`, `adapter_family_receipt_checksum`, `adapter_family_label`, `adapter_family_status`, `adapter_family_strategy`, and `adapter_family_adapter_count`, pointing at a served `.adapter-family.receipt` file that is recomputed from the member manifests during bundle generation. Selector validation requires local `../models/*.adp1`, `../models/*.asp1`, or `../models/*.alr1` routing, sidecar manifest pairing, non-duplicate adapter paths per candidate, a f32/q8_0/q4_0 registry entry, route-format-specific apply status matching the entry quantization, a local receipt route when family receipt fields are present, a hex receipt checksum, and matching adapter-family count. The browser consumes generated adapter-family receipt fields as an assembly menu gate: after Rust accepts the `.slm` model and JavaScript loads its `.slm.manifest`, the browser fetches the served receipt and adapter manifests, recomputes the same text checksums, verifies the receipt kind/status/strategy/count, verifies each adapter manifest kind/status/dtype/apply status, and matches each member's route, manifest route, label, apply status, artifact checksum, manifest checksum, manifest byte count, and shared base-quantization identity fields before exposing the sidecar choices. When a sidecar is applied, JavaScript recomputes the selected ADP1, ASP1, or ALR1 artifact checksum before transferring bytes into WASM. Trained source conversion is intentionally outside the browser runtime. `tinyrustlm-slm-pack source-template [tiny-fixture|tiny-fixture-tied|tiny-fixture-bpe|tinylm16|tinylm16-tied]` writes a reviewable source-weight directory with `source.manifest` and raw little-endian f32 tensor files under `tensors/`. `validate-source ` checks the source before conversion. `convert-trained [f32|q8_0|q4_0]` reads validated f32 tensors, writes a checksum-bearing `.slm`, validates it, and writes a converted-trained provenance sidecar. The source manifest is line-based, not JSON. It declares `tinyrustlm_trained_source_version=1`, `layout=raw-f32-tensor-files-v1`, `tied_output=true|false`, shape fields, tokenizer, source dtype, source kind, source evidence fields, tensor count, and one record per required tensor. Existing manifests without `tied_output` are accepted as `false` for backward compatibility. BPE source manifests use `tokenizer=bpe-v1`, a BPE model shape such as `tiny-fixture-bpe` or future `tinylm16-bpe`, `bpe_token_count`, `bpe_merge_count`, `bpe.token.N.id`, `bpe.token.N.bytes_hex`, and ranked `bpe.merge.N.*` records; conversion serializes those records into the actual `BPE1` tokenizer section. Tied source manifests must use a tied shape name, must omit `output.weight`, and must produce a v1 `.slm` file with the tied-output flag set. Each tensor record must name the expected tensor, rank, dimensions, safe relative file path, exact byte count, and source checksum. Source paths must stay under `tensors/`; absolute paths and parent traversal are rejected. Source-weight constraints are deliberately strict. The first conversion layout accepts raw f32 source tensors only, then performs q8_0 or q4_0 quantization itself when requested. Every source tensor must have the exact byte length implied by shape, finite f32 values, absolute values no larger than 64.0, a nonzero payload, and a matching source checksum. The validator also rejects `model_shape` and `tied_output` disagreement, BPE tokenizer labels without BPE source shapes, BPE source shapes without `tokenizer=bpe-v1`, duplicate BPE token ids, duplicate BPE merge ranks, merge outputs outside the declared vocabulary, and stray BPE records outside declared counts. These checks catch broken endian exports, missing files, path confusion, placeholder tensors, accidental prequantized input, tokenizer/source mismatch, and output-head layout drift before a converted model can receive a `.slm.manifest`. Quality admission is a separate gate. `tinyrustlm-slm-pack quality-gate runtime-smoke` permits deterministic smoke or converted-trained artifacts only for runtime-execution evidence. `tinyrustlm-slm-pack eval-template assistant-quality` writes a pending line-based evaluation sidecar bound to the exact model checksum, model shape, source kind, and manifest checksum. `cargo run -p tinyrustlm-runtime --bin tinyrustlm-eval -- ` executes exact local cases through the Rust runtime and writes a scoped eval sidecar; runtime integration coverage invokes that public binary against checked-in fixture evidence. Eval case files must declare at least one nonempty exact case and cannot carry stray case keys outside the declared count. `tinyrustlm-slm-pack quality-gate assistant-quality ` requires `source_kind=converted-trained`, matching checksums, `eval_status=pass`, `task_eval_status=pass`, `safety_review_status=pass`, `quality_decision=accepted-for-assistant-quality`, non-placeholder `quality_scope`, evaluator, dataset, summary, quality boundary, positive case count, all cases passed, zero failed cases, and exact per-case expected/actual matches. Pending templates, missing case evidence, mismatched case text, and deterministic smoke manifests fail the assistant-quality gate. Parent compatibility is exact for the first direct-parameter lane. Two parents pass only when `.slm` version, model shape, tokenizer checksum, output-head contract, quantization label, tensor count, parameter count, and tensor layout checksum match. q8_0 and q4_0 parents with the same architecture stay in separate direct-parameter lanes because their tensor layouts and quantization semantics differ. Heterogeneous parent sets can still become future candidates through source conversion, distillation, or retraining routes before normal `.slm` admission, provenance, runtime-smoke, and eval gates. Candidate lineage validation binds a planned candidate to the exact compatibility report checksum and copied parent fields before any operator writes a candidate artifact. Blend, task-delta, and sparse task-delta validation then recompute the produced `.slm` and operator receipt from the same parents, lineage, and operator weights; sparse receipts also bind keep rate, absolute-delta selection, deterministic tie break, and selected/pruned counts. Adapter-delta validation recomputes `ADP1` raw packages, `ASP1` sparse packages, or `ALR1` low-rank packages and manifests from the same compatibility-bound parents and lineage; adapter-family receipt validation then proves generated sidecars share the same adapter identity fields, including base quantization before selector routing; adapter-fuse validation recomputes the `.slm` candidate and receipt from a raw adapter package before candidate artifact validation binds the produced `.slm` back to the lineage checksum and parent contract. Promotion validation binds the candidate manifest checksum and preserves the pending runtime-smoke/eval gate before browser exposure. Admission validation binds promotion, runtime-smoke, and eval sidecar checksums before a candidate can enter a promotion ledger, population review, parent-pool recipe, sign-merge operator, or selector registry. Ledger validation chains admitted records and rejects duplicate candidate artifacts. Population review validation recomputes deterministic candidate rankings, objective-vector metadata, and per-entry objective checksums from the ledger plus admissions before parent selection or selector-registry routing. Parent-pool recipe validation recomputes the review first, checks that all selected parents share one direct-parameter contract, and binds seed weights normalized from population fitness plus a deterministic relatedness checksum over the selected parent family. Sign-merge validation recomputes recipe validation, parent artifact checks, seed-weighted sign consensus, candidate bytes, relatedness fields, and receipt text; multi-parent candidate manifest validation then binds that receipt checksum, recipe checksum, relatedness summary, parent summaries, and candidate `.slm` fields. Multi-parent promotion validation binds the candidate manifest checksum and keeps the same pending runtime-smoke/eval route before multi-parent admission. Multi-parent admission validation binds the promotion template to runtime-smoke, provenance, and eval sidecars. Registry validation then binds either admission record family to a browser-served model route before optional selector consumption, and generated registry adapter-family receipt fields bind compatible f32/q8_0/q4_0 sidecars to the same entry without moving adapter validation out of Rust. Generated registry adapter-family receipt fields are also verified in the browser before use. That check binds selector metadata to the served receipt and adapter manifest text, including the entry quantization matched to adapter apply status; the apply path then checks the selected ADP1 artifact checksum while keeping the payload opaque until Rust validates the selected package. ## Future Expansion Path The first format path supports f32, q8_0, and q4_0 tiny byte-tokenizer fixtures, a tiny f32 BPE fixture with a checked runtime merge proof, a tied-output tiny fixture that omits `output.weight`, and real-shaped TinyLM-16M f32, q8_0, and q4_0 models. The first trained-source conversion path is raw f32 by design so quantization stays local and reviewable, and it now supports BPE source manifests that serialize into `BPE1` sections plus tied raw source bundles that omit `output.weight` while setting the v1 tied-output flag during conversion. Current `BPE1` support gives trained models a custom tokenizer table and merge table without external formats. The parent compatibility report is the first model-breeding assembly bead, the candidate lineage template is the second, the blend, task-delta, or sparse task-delta operator receipt is the third `.slm` output bead, the raw `ADP1`, sparse `ASP1`, and low-rank `ALR1` adapter-delta packages are parallel adapter beads, adapter-fuse is the bridge from raw ADP1 back to a normal `.slm` candidate, runtime f32/q8_0/q4_0 adapter apply is the browser-local assembly bead for a compatible loaded base plus raw, sparse, or low-rank sidecar, adapter-family receipts are the browser assembly menu bead for generated compatible ADP1/ASP1/ALR1 sidecar sets, browser-side adapter artifact checksum verification is the pre-transfer bead for selected ADP1/ASP1/ALR1 bytes, the candidate artifact manifest is the fourth `.slm` bead, the promotion template is the fifth for the two-parent path, the runtime-smoke sidecar is the sixth, the selector admission record is the seventh, the promotion ledger is the eighth, the population review is the ninth and now carries weighted objective-vector metadata, the parent-pool recipe is the tenth and now carries shared-family relatedness metadata, the sign-merge receipt is the eleventh offline multi-parent bead and echoes that metadata, the multi-parent candidate manifest is the twelfth and carries the relatedness summary, the multi-parent promotion template is the thirteenth for that path, the multi-parent admission record is the fourteenth, the selector registry is the served-model route bead for both admission families, and registry-carried f32/q8_0/q4_0 adapter families are the browser assembly route bead for compatible generated entries: together they prove which admitted artifacts share a direct-parameter contract, which planned candidate may proceed to an offline operator, which operator wrote a recomputable `.slm` or adapter artifact, which adapter package produced a recomputable `.slm` or runtime f32/q8_0/q4_0 assembly input, which generated sidecar set has one identity-bound receipt, which produced `.slm` still fits that lineage or sign-merge recipe, which candidate is waiting for runtime/eval proof, which evaluated candidate can enter promotion history, which objective contract selected the current frontier, which reviewed parent set has one relatedness identity and can produce a sign-aware candidate, which multi-parent candidate has runtime/eval evidence, which served route the browser may load, and which compatible sidecars the browser may transfer to Rust. Later versions can add larger reviewed BPE vocabularies, richer trained conversion metadata, embedded provenance sections, trained LoRA-style low-rank modules, richer compact adapter metadata, compact retention metadata, and paging metadata without changing the v1 parser contract. In the current browser bead, registry-carried f32/q8_0/q4_0 adapter families are transfer-eligible only after the served receipt and adapter manifests pass checksum and member matching in JavaScript; ADP1, ASP1, and ALR1 package validation and mutation remain in Rust.