fold

@intuitionlabs/fold

Matryoshka fold/unfold with fidelity receipts. Shrink a vector or a list to a lower rung, keep the parts that must survive, and read how much you kept.

Part of the Intuition Labs foundry — github.com/Intuition-Labs-LLC/jspace.

Install

npm i @intuitionlabs/fold

Until the first npm publish, install from the GitHub Release tarball.

Quickstart

import { foldVec, unfoldVec, tower, foldSeq, foldToRung } from '@intuitionlabs/fold';

// fold a vector to its first 2 components
const f = foldVec([3, 4, 0, 0], 2);
console.log(f.v, f.fidelity);           // [3, 4] 1  (the tail was all zeros)
console.log(f.receipt.scalar);          // 'glueR'

// the matryoshka tower: fidelity at each descending rung
console.log(tower([3, 4, 5, 6], [4, 2, 1]).map((r) => r.fidelity));

// fold a chat history, protecting the system turns
const turns = [{ kind: 'system' }, { kind: 'user' }, { kind: 'user' }, { kind: 'user' }];
const kept = foldSeq(turns, { rung: 1 });          // keep system + every 2nd user turn
console.log(kept.kept.length, kept.fidelity);

// or let a regime pick the rung
console.log(foldToRung(turns, 'continuous').kept.length);

The mechanism

Folding a vector keeps its first dim components and drops the rest. The fidelity is the fraction of the vector's length (its L2 norm) that the prefix keeps. A full-length fold has fidelity 1; a zero vector folds at fidelity 1 by convention. Unfolding zero-pads a vector back to a target length. This gives a clean identity: the cosine between a vector and its folded-then-unfolded self equals the fold fidelity exactly, because the zero padding contributes nothing to the dot product or the norm.

Folding a sequence keeps fewer items at a lower rung. Rung 0 keeps everything. Rung 1 keeps every 2nd unprotected item (positions 0, 2, 4, … of the unprotected subsequence). Rung 2 keeps every 3rd (0, 3, 6, …). Protected kinds — system by default — are always kept, at every rung, so the load-bearing turns never fall out. The fidelity is the fraction of items kept, and it only ever goes down as the rung goes up. A regime picks a rung through REGIME_RUNG: current → 0, refined/coupled → 1, continuous → 2. Every fidelity is a glueR scalar. glueR measures fold fidelity and nothing else; it is never routed into a coherence gate (law L1).

Laws

• L1 — R-one-source & never-alias. Every fold receipt sets scalar: 'glueR' and carries the note "never a coherence gate input (L1)". Pins: test/vec.test.ts › foldVec receipt carries scalar glueR… and test/seq.test.ts › foldSeq receipt carries scalar glueR….
• L3-adjacent — rung 0 is a byte-identical passthrough. Folding to the top rung returns the same items, in the same order, by reference. Pin: test/seq.test.ts › rung 0 is a byte-identical passthrough.
• L7 — degrade closed. foldToRung on an unknown regime keeps everything (rung 0) and notes it, rather than throwing. Pin: test/seq.test.ts › foldToRung degrades closed on an unknown regime.
• Protection invariant. Protected kinds are never dropped, verified against 200 seeded random sequences. Pin: test/seq.test.ts › protected kinds are never dropped at any rung.
• Monotonicity. Fold fidelity is non-increasing in rung, and the tower's dims descend. Pins: test/seq.test.ts › fold fidelity is monotone non-increasing in rung, test/vec.test.ts › tower dims descend….

Provenance

This externalizes foldToRung / glueRegions from the maxwell kernel's context partitioner (research_worker/src/kernel/context/partition.ts), where glueR is the fold fidelity and is deliberately kept out of coherence gates.

• Matryoshka Representation Learning — Kusupati et al., arXiv:2205.13147: a single vector whose prefixes are each a usable lower-dimensional embedding.
• The Matryoshka Sheaf — Tej Desai, Intuition Labs, huggingface.co/datasets/intuitionlabs/matryoshka-sheaf (CC-BY-4.0): fold/unfold graded by a freeze threshold τ, with R = exp(−d_tail/scale) as the degree-0 existence-of-a-global-section obstruction (an honest relabel, not an H¹ statement).