@intuitionlabs/sheaf — local readings, agreement on overlaps, one global answer or a named obstruction.

You have many partial views of the same thing. Each view (a chart) reports local readings at named points. Where two views overlap, you check that they agree. If they all agree, you get one whole answer — a single global section. If they don't, you get the name of the disagreement — which chart said what, at which point — instead of a silent average.

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

Open in StackBlitz — runs npm run demo in-browser via WebContainers, no local install.

Install

npm i @intuitionlabs/sheaf

Until the first npm publish, install from the GitHub Release tarball. Zero runtime dependencies. The built package targets Node ≥20; running the .ts demos and tests directly needs Node ≥23.6 (native type stripping) or a prior npm run build.

Quickstart

import { glue } from '@intuitionlabs/sheaf';

// Two charts, one shared point 'pop'. They agree there.
const g = glue([
  { chart: 'census', values: { pop: '8.4M', area: 'large' } },
  { chart: 'survey', values: { pop: '8.4M' } },
]);
console.log(g.verdict);            // 'commit'
console.log(g.value?.global.pop);  // '8.4M'  (the union of every reading)

// Now they disagree. The obstruction is NAMED, never averaged.
const bad = glue([
  { chart: 'census', values: { pop: '8.4M' } },
  { chart: 'survey', values: { pop: '3.9M' } },
]);
console.log(bad.verdict);          // 'escalate'
console.log(bad.receipt.note);     // obstruction at pop: census=8.4M vs survey=3.9M (r=0.5134)

Run the full story with npm run demo (deterministic, zero deps) or the same tower in SQL with npm run demo:pglite.

The mechanism

One overlap. At a point shared by several charts, gather the readings. agreementR = exp(−d_tail / scale), where d_tail is how many readings fall outside the largest agreeing group. All agree → d_tail = 0 → r = 1. One dissenter drops r. The gate τ = exp(−0.5 / 1.5) ≈ 0.7165 decides: r ≥ τ commits, below escalates.

R = exp(−d_tail/scale) is the degree-0 existence-of-a-global-section obstruction — all overlaps agree — not an H¹ statement.

Gluing. glue checks every overlap point. Zero obstructions → it commits to one global section (the union of all readings; at an overlap it takes the modal reading). Any obstruction → it escalates and the receipt spells out each disagreement by chart, point, and reading. It never averages a disagreement away.

The tower. Readings can be vectors (embeddings). A Matryoshka vector nests a coarse view inside a fine one: a prefix is a usable low-dimensional reading. So glueLadder folds every section to the coarsest dimension first and glues there (cheap), then descends to the next finer dimension only while the coarse view still agrees. It freezes at the first resolution where agreement breaks — the freeze threshold — and names the chart that broke it. Coherent all the way down → commit.

Because d_tail is an integer count, r is quantized: at the default scale a rung is either unanimous (r = 1, commit) or has at least one dissenter (r ≤ 0.5134, escalate). The freeze is the first rung with a dissenter.

Laws

This package embodies three of the foundry laws, each pinned by a falsifier test in test/laws.test.ts:

• L4 — frozen seams. A section is exactly {chart, values}. An unknown key is drift, not metadata: validateSection throws unknown key: <k> (drift, not metadata). Falsifier: L4 falsifier: an unknown key in a section is drift, and it throws.
• L7 — degrade closed. Empty input never crashes — glue([]) and glueLadder([]) return a skip verdict. The optional PGlite demo prints a plain message when the dependency is absent. Falsifiers: L7: empty sections degrade closed to skip and L7: the pglite demo degrades closed when the optional dep is missing.
• L1 — one R, never aliased. Every R here is agreementR (verdict agreement). It is never routed into glueR (fold fidelity) or any other gate, even though the package glues. Falsifier: L1 never-alias: every R this package computes is agreementR (never glueR).

Plus the honesty relabel above: the R is a degree-0 obstruction (does a global section exist), not an H¹ cohomology statement.

Provenance

This starter operationalizes existing lab and literature sources — it copies no code from any of them:

• The Matryoshka Sheaf — Tej Desai, Intuition Labs. The paper this starter operationalizes, and the source of the honest degree-0 relabel. huggingface.co/datasets/intuitionlabs/matryoshka-sheaf (CC-BY-4.0).
• ix-search — github.com/Intuition-Labs-LLC/ix-search: the search-space instance of the same mechanism — structure ⊗ text ⊗ meaning glued at the same file:line by a coherence-R.
• Matryoshka Representation Learning — Kusupati et al., arXiv:2205.13147: why a prefix of an embedding is itself a usable, coarser embedding.
• The jspace foundry — github.com/Intuition-Labs-LLC/jspace: the canonical home of the vendored math (agreementR, gateDecision, cosine), currently inlined in src/vendor.ts pending the first npm publish.

License

AGPL-3.0-or-later. See LICENSE and NOTICE.md.