Free Association Protocol - Pure allocation algorithm and recognition system
npm install @playnet/free-associationA pure, framework-agnostic protocol for decentralized resource allocation and mutual recognition.
@playnet/free-associationVersion: 1.0.8
License: AGPL-3.0-or-later
The Free Association Protocol implements priority aligned capacity distribution, enabling decentralized communities to coordinate resource allocation without central authority, bureaucratic overhead, or market exclusion.
- Priority Aligned Capacity Distribution - Resources flow based on priority alignment and declared needs
- Distributed IPF Allocation - Iterative Proportional Fitting for decentralized coordination
- Recognition Trees - Hierarchical contribution attribution and priority derivation
- Interval Tree Clocks (ITC) - Causality tracking for distributed systems
- Compliance Filters - JSON Logic-based slot compatibility rules
- Zod Schemas - Runtime validation for all data structures
``bash`
npm install @playnet/free-association
`typescript`
import {
calculateSlotBasedPriorityAllocation,
calculateCollectiveRecognitionDistribution,
mutualFulfillment
} from '@playnet/free-association';
`typescript
// Schemas and types
import { type Commitment, type NeedSlot, type AvailabilitySlot } from '@playnet/free-association/schemas';
// Allocation algorithm
import { calculateSlotBasedPriorityAllocation } from '@playnet/free-association/allocation';
// Recognition distribution
import { calculateCollectiveRecognitionDistribution } from '@playnet/free-association/distribution';
// Recognition trees
import { mutualFulfillment } from '@playnet/free-association/tree';
// Interval Tree Clocks
import { itcSeed, itcEvent, itcFork, itcJoin } from '@playnet/free-association/itc';
// Utilities
import { slotsCompatible, passesSlotFilters } from '@playnet/free-association/utils/match';
// Filters
import { evaluateComplianceFilter } from '@playnet/free-association/filters/compliance';
// Configuration
import { DEFAULT_CONFIG } from '@playnet/free-association/config';
`
Distributed IPF Allocation Protocol - Implements the "Distributed Recipient Broadcast" protocol where agents coordinate asynchronously by exchanging scaling factors.
Key Functions:
`typescript
function updateProviderState(
capacitySlots: AvailabilitySlot[],
knownNeeds: NeedSlot[],
allCommitments: Record
state: DistributedIPFState,
epsilon?: number,
gamma?: number
): DistributedIPFState
function generateFlowProposals(
capacitySlots: AvailabilitySlot[],
knownNeeds: NeedSlot[],
allCommitments: Record
state: DistributedIPFState,
epsilon?: number,
gamma?: number
): FlowProposal[]
function updateRecipientState(
needSlots: NeedSlot[],
incomingProposals: FlowProposal[],
state: DistributedIPFState,
epsilon?: number
): DistributedIPFState
`
Features:
- Asynchronous coordination via scaling factor exchange
- Provider row scaling (x_p) to satisfy capacity constraints
- Recipient column scaling (y_r) to satisfy need constraints
- Mathematical basis: A_pr = K_pr x_p y_r (Iterative Proportional Fitting)
- Converges to optimal allocation through distributed computation
Collective recognition distribution using Shapley values.
Key Function:
`typescript`
function calculateCollectiveRecognitionDistribution(
nodes: Node[],
options?: DistributionOptions
): RecognitionDistribution
Hierarchical contribution tracking and mutual fulfillment.
Key Function:
`typescript`
function mutualFulfillment(
tree: Node,
recognitionWeights: Record
): MutualFulfillmentResult
Comprehensive Zod schemas for runtime validation:
- CommitmentSchema - User commitments with slots and recognitionNeedSlotSchema
- - Resource needs with prioritiesAvailabilitySlotSchema
- - Resource capacity with prioritiesSlotAllocationRecordSchema
- - Allocation results
- And many more...
Interval Tree Clocks for distributed causality tracking.
`typescript
import { itcSeed, itcEvent, itcFork, itcJoin, itcLeq } from '@playnet/free-association/itc';
const stamp1 = itcSeed();
const stamp2 = itcEvent(stamp1);
const isOrdered = itcLeq(stamp1, stamp2); // true
`
90 tests passing across all modules:
`bash`
npm test
Test Coverage:
- Allocation: 6 tests
- Divisibility: 18 tests
- Matching: 39 tests
- Distribution: 17 tests
- ADMM Optimization: 2 tests
- And more...
Detailed documentation available in /docs:
- Algorithm specifications
- Schema definitions
- Integration guides
- Performance benchmarks
1. Pure Functions - No side effects, fully testable
2. Framework Agnostic - Works with any JS/TS framework
3. Runtime Validation - Zod schemas at all boundaries
4. Type Safety - Full TypeScript with strict mode
5. Standards Compliance - JSON Logic, Zod, modern ES modules
``
src/
โโโ allocation.ts # Slot-based priority allocation
โโโ distribution.ts # Recognition distribution (Shapley)
โโโ tree.ts # Recognition trees & mutual fulfillment
โโโ itc.ts # Interval Tree Clocks
โโโ schemas.ts # Zod schemas & types
โโโ config.ts # Default configuration
โโโ utils/ # Utility functions
โ โโโ match.ts # Slot compatibility matching
โ โโโ memoize.ts # Memoization helpers
โ โโโ ...
โโโ filters/ # Compliance filters
โ โโโ compliance.ts # JSON Logic evaluation
โ โโโ ...
โโโ attributes/ # Attribute definitions
โโโ collective/ # Collective coordination
Resources flow based on priority alignment and declared needs:
- Capacity Slots - What you can provide (time, money, skills)
- Need Slots - What you need
- Priority Weights - How you prioritize capacity distribution to different recipients
- Priority Alignment - Resources flow to entities contributing to your priorities
Decentralized allocation through Iterative Proportional Fitting (IPF):
- Provider Scaling (x_p) - Providers adjust their offers to stay within capacity
- Recipient Scaling (y_r) - Recipients signal saturation to prevent overflow
- Seed Values (K_pr) - Base compatibility between capacity and need slots
- Flow Proposals - Asynchronous exchange of allocation proposals: A_pr = K_pr x_p y_r
- Convergence - System converges to optimal allocation through iterative updates
Hierarchical contribution tracking:
- Recognition Weights - How much you value others' contributions to your priorities
- Priority Derivation - Priorities often derived from recognition of contribution
- Recognition Trees - Hierarchical attribution of collective value
JSON Logic rules for slot compatibility:
`typescript``
{
"filter_rule": {
"and": [
{ ">=": [{ "var": "quantity" }, 10] },
{ "in": [{ "var": "location" }, ["NYC", "SF"]] }
]
}
}
- Free Association App - SvelteKit application using this protocol
- Playnet - Broader ecosystem of decentralized coordination tools
AGPL-3.0-or-later
This is an active research and development project. Contributions welcome!
Repository: https://github.com/playnet/free-association
Built with:
- Zod - Schema validation
- json-logic-js - Filter evaluation
- Vitest - Testing framework
---
Status: Production-ready v1.0.8 with 90 tests passing โ