@superinstance/fleet-math

Core fleet math for multi-agent constraint systems.

Fleet as in fishery — you're running a fleet of autonomous agents.
Math as in rigor — topology, homology, and rigidity keep the fleet coherent.

Provides three constraint-theoretic primitives and one continuous field analyzer:

Module	Name	What it does
ZHC	Zero Holonomy Consensus	Check if pairwise agent constraints are globally consistent
H1	Homological emergence	Detect when the constraint graph has enough complexity for emergent behavior
Laman	Rigidity analysis	Laman's theorem — is the fleet rigid, flexible, or minimally braced?
Field	Continuous constraint field	Embed discrete constraints into a 2D field and scan for coverage gaps

Install

npm install @superinstance/fleet-math

Quick Start

ZHC — Constraint consistency

import { ConstraintGraph } from '@superinstance/fleet-math';

const g = new ConstraintGraph();
g.addEdge('agent-a', 'agent-b', 1.0);
g.addEdge('agent-b', 'agent-c', 1.0);
g.addEdge('agent-a', 'agent-c', 1.0);

const { consensus, violations } = g.checkConsensus();
console.log('Consensus:', consensus); // true (consistent triangle)

H1 — Emergence detection

import { ConstraintGraph, betti1, detectEmergence } from '@superinstance/fleet-math';

const g = new ConstraintGraph();
g.addEdge('a', 'b');
g.addEdge('b', 'c');
g.addEdge('a', 'c');

console.log('β₁:', betti1(g));          // 1
console.log('Emergence?', detectEmergence(g, 0.2)); // true

Laman — Rigidity

import { ConstraintGraph, isRigid, isMinimallyRigid, rigidMargin } from '@superinstance/fleet-math';

const g = new ConstraintGraph();
g.addEdge('a', 'b');
g.addEdge('b', 'c');
g.addEdge('a', 'c');

console.log('Rigid:', isRigid(g));               // true
console.log('Minimally rigid:', isMinimallyRigid(g));  // true
console.log('Margin:', rigidMargin(g));           // 0

Field — Constraint coverage scanning

import { Field } from '@superinstance/fleet-math';

const f = new Field();
f.embed('agent-a', 2, 5, 1.2);
f.embed('agent-b', 8, 3, 0.8);

const gaps = f.gaps(20); // 20x20 grid scan
console.log('Biggest gap at:', gaps[0].x, gaps[0].y);

ASCII — Laman's Theorem

Laman's theorem for 2D rigidity:

              |E| = 2|V| - 3
                   |
                   ▼
            ┌───────────────┐
            │  MINIMALLY    │
            │   RIGID       │
            │  (braced)     │
            └───────┬───────┘
                    │
        ┌───────────┴───────────┐
        │                       │
        ▼                       ▼
   |E| < 2|V|-3           |E| > 2|V|-3
        │                       │
        ▼                       ▼
    FLEXIBLE             OVER-BRACED
   (collapses)          (redundant)

Example frameworks

TRIANGLE (minimally rigid)        SQUARE (flexible)
      a                               a ── b
     / \                              │    │
    /   \                             │    │
   b ─── c                            d ── c

SQUARE + DIAGONAL (over-braced)     K5 (over-braced)
      a ── b                          ◈ complete graph
     / \\ │                           |V| = 5, |E| = 10
    /   \\│                           margin = 10 - 7 = 3
   d ─── c

Full Monograph

For the complete theory, proofs, and worked examples, see:

Constraint Theory for Fleet Operations / FLUX ISA

The monograph covers:

• Holonomy in multi-agent constraint graphs
• Homological emergence bounds
• Laman rigidity for agent fleet topology
• Constraint field theory and gap analysis

License

MIT — Cocapn