| name | substrate-kernel |
| description | Use this skill when an agent needs to compute a substrate hot-path primitive — SimHash, Hamming distance, OR-reduce, bitwise combinators, Fingerprint256 construction, HammingNN top-K nearest neighbors, BitField bitmap extraction, or a SHA-256 hash. These are byte-identical Swift+Rust implementations behind a conformance-gated CRC. Trigger this skill whenever an agent is about to hand-write any of those operations, or use any bit operation on a Fingerprint256. (The AuditGate write gate lives in SubstrateLib and HLCGenerator in SubstrateTypes — see their skills.) The skill redirects to the existing implementation and prevents re-invention drift the conformance harness would catch in CI. |
substrate-kernel — hot-path bit ops, bitmap fields, hashing
When this skill applies
An agent is about to write code that does any of:
- Random-projection LSH (SimHash) over a bit vector
- Hamming distance between 256-bit fingerprints
- OR-reduce / AND / XOR / majority-prototype over a set of fingerprints
- Top-K nearest-neighbor search by Hamming distance
- Bitmap field extraction / masked-equals (
BitField)
- A SHA-256 hash (the primitive the AuditGate seal is built on)
(HLC comparison/tick and the audit-log write gate are NOT here — HLC
HLCGenerator live in SubstrateTypes, AuditGate in SubstrateLib.)
The one rule
These are conformance-gated with CRC-32 seals. Don't reinvent
any of them. Swift and Rust implementations must produce
byte-identical output on the canonical test vector; CI runs the
four-way check on every commit. A hand-rolled SimHash WILL drift
from the seal and turn CI red.
| Primitive | Use |
|---|
| SimHash | SimHash.computeBlock(_:family:) / simhash::compute_block |
| Hamming | fp.hammingDistance(other) / fp.hamming_distance(&other) |
| OR-reduce | Fingerprint256.orReduce([…]) / Fingerprint256::or_reduce(&[…]) |
| Bitwise | fp.intersect(other) / .difference(other) / Fingerprint256.prototype(of:) |
| Fingerprint construction | Fingerprint256.compute(row:manifest:) |
| HammingNN top-K | HammingNN.topK(anchor:candidates:K:) |
| BitField | BitField.extractField(_:shift:width:) / bit_field::extract_field |
| SHA-256 hash | SHA256.hash(_:) / sha256::hash(_:) |
Anti-patterns
- Hand-rolling a SimHash (one popcount-and-sign loop). It will
drift from the gated CRC
0x9af6b7e2.
- Using XOR + bit-loop for Hamming instead of
Fingerprint256.hammingDistance,
which is SIMD-vectorized.
- Open-coding bitmap field extraction instead of
BitField.
- Computing a custom hash for content addressing. The seal is
SHA-256 over a specific field order; deviation makes events
non-verifiable. (HLC stamping via
HLCGenerator and audit writes
via AuditGate are the same rule — but those symbols are in
SubstrateTypes / SubstrateLib; see their skills.)
How to use
import SubstrateKernel
let d = fpA.hammingDistance(fpB)
let fp = Fingerprint256.compute(row: row, manifest: manifest)
let top = HammingNN.topK(anchor: anchor, candidates: rows, K: 10)
let digest = SHA256.hash(bytes)
use substrate_kernel::{fingerprint::Fingerprint256, hamming_nn, sha256};
let d = fp_a.hamming_distance(&fp_b);
let fp = Fingerprint256::compute(&row, &manifest);
let top = hamming_nn::top_k(&anchor, &candidates, 10);
let digest = sha256::hash(&bytes);
Package wiring:
.package(path: "../SubstrateKernel"),
substrate-kernel = { path = "../../SubstrateKernel/rust" }
If you change a gated primitive
Run the four-way conformance check from the harness directory.
See docs/validation/substrate_math_performance/test-harness/SKILL.md
for the workflow. All four cells must PASS at the CRC listed in
this package's AGENTS.md table before you commit.
What to read
packages/libs/SubstrateKernel/AGENTS.md for the full API reference
with code examples per primitive. docs/engineering/HARNESS_REFERENCE.md
§2.1 for the canonical index with file paths and CRCs.
