| name | substrate-lib |
| description | Use this skill when an agent is deciding whether to depend on SubstrateLib or one of its three sub-packages, or is working with the substrate's write path — the nine verbs, the row-state automaton, or the AuditGate write gate. SubstrateLib is the retained orchestration layer of the four-package substrate split; depend on it only if you drive the verbs / row-state machine (today only LocusKit does). For value types, kernels, or ML primitives, depend on SubstrateTypes / SubstrateKernel / SubstrateML directly. Trigger this when adding a SubstrateLib import, writing through AuditGate, or reasoning about verb/row-state mechanics. |
substrate-lib — the substrate orchestration layer
When this skill applies
An agent is about to:
- Add a
SubstrateLib dependency (Swift Package.swift or Rust Cargo.toml)
- Write a mutation through the substrate (every write goes through
AuditGate)
- Work with the nine verbs or the
RowStateAutomaton state machine
- Decide whether SubstrateLib or a sub-package is the right dependency
The one rule
SubstrateLib is retained as the orchestration layer (four-package
split, 2026-05-29 addendum) — it is NOT deprecated. But depend on it
only if you drive the verbs / row-state machine / write gate. If you
only need a value type, a kernel, or an ML primitive, depend on the
precise sub-package instead.
What lives in SubstrateLib (and only here)
| Symbol | Use |
|---|
Verbs | The nine substrate verbs and their mechanics |
RowStateAutomaton | RowStateAutomaton.validate(from:on:targetingFields:) — legal-transition + I-22 check |
AuditGate | try AuditGate.admit(verb:prior:writes:actor:hlc:) — the only legitimate path to a mutation |
AuditGate lives here (not in SubstrateKernel) because it calls
RowStateAutomaton; it consumes SubstrateKernel's BitField + SHA256.
Where everything else lives (depend on these directly)
| If you wanted… | Depend on |
|---|
Fingerprint256, HLC + HLCGenerator, AuditEvent, LatticeAnchor, Row, NounType, layout constants, SimHash, Hamming, ORReduce, MatrixF/C/O/T, GSetAuditLog, RecallTypes | SubstrateTypes |
PortableKernel/SimdKernel, HammingNN, BitField, SHA256 | SubstrateKernel |
MatrixDecay, BradleyTerry, FFT, NMF, AuditLogFold, PartialStateRecall, PairingHandshake, TierContribution*, DPORReduction, … | SubstrateML |
How to depend on it (verb-drivers)
.package(path: "../../libs/SubstrateLib"),
import SubstrateLib
substrate-lib = { path = "../../libs/SubstrateLib/rust" }
Anti-patterns
- Depending on SubstrateLib for a value type / kernel / ML primitive.
Those moved to the sub-packages; SubstrateLib no longer re-exports them.
Depend on
SubstrateTypes / SubstrateKernel / SubstrateML directly.
- Writing to the audit log without
AuditGate.admit. Bypasses I-22
enforcement, the seal, and the per-mode sealed bit. The gate is the
only authoring point.
What to read
packages/libs/SubstrateLib/AGENTS.md for the AuditGate write-path
reference. The three sub-packages each have their own AGENTS.md/SKILL.md.
