@a0n/aeon 5.0.1

package/LICENSE

@@ -0,0 +1,15 @@
+Copyright (c) 2026 Taylor William Buley (https://buley.fyi)
+
+All rights reserved.
+
+This software is provided for personal, non-commercial, and academic use only.
+You may not use, modify, distribute, or sell this software, in whole or in part,
+for any commercial purpose without explicit written permission from the copyright holder.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,199 @@
+# Aeon
+
+A TypeScript toolkit for collaborative systems. At its center: **Aeon Flow**, a multiplexed frame protocol for moving many independent streams over one transport.
+
+The package covers ground teams usually assemble themselves: transport, sync, offline queues, compression, presence, versioning, persistence, crypto, and topology analysis.
+
+## Install
+
+```bash
+bun add @a0n/aeon
+```
+
+```bash
+npm install @a0n/aeon   # or yarn / pnpm
+```
+
+## Aeon Flow
+
+One connection. Many independent streams. Less waiting behind unrelated work.
+
+```text
+┌──────────────────────────────────────────────────────────┐
+│                   10-byte Flow Frame                     │
+├──────────┬──────────┬───────┬────────────────────────────┤
+│ stream_id│ sequence │ flags │ length    │    payload ...  │
+│  (u16)   │  (u32)   │ (u8)  │ (u24)    │                 │
+└──────────┴──────────┴───────┴────────────────────────────┘
+```
+
+- Streams progress independently -- no head-of-line blocking
+- Frames can arrive out of order and reassemble correctly
+- Protocol overhead stays small (10 bytes per frame)
+- Same framing works across UDP, WebSocket, WebTransport, IPC
+
+The UDP path includes MTU-aware fragmentation, ACK bitmaps, AIMD congestion control, and per-stream reassembly.
+
+### Quick Start: Flow Protocol
+
+```ts
+import { AeonFlowProtocol, UDPFlowTransport } from '@a0n/aeon';
+
+// Set up transport
+const transport = new UDPFlowTransport({
+  host: '0.0.0.0',
+  port: 4242,
+  remoteHost: 'target.example.com',
+  remotePort: 4242,
+  reliable: true,
+});
+await transport.bind();
+
+// Create protocol instance
+const flow = new AeonFlowProtocol(transport, {
+  role: 'client',
+  maxConcurrentStreams: 256,
+});
+
+// Open a parent stream and fork 3 children
+const parentId = flow.open();
+const childIds = flow.fork(parentId, 3);
+
+// Race: first child to complete wins, losers are vented
+const { winner, result } = await flow.race(childIds);
+
+// Or fold: wait for all, merge results
+const merged = await flow.fold(childIds, (results) => {
+  // results: Map<streamId, Uint8Array>
+  return concatBuffers([...results.values()]);
+});
+```
+
+### Quick Start: Sync Coordination
+
+```ts
+import { SyncCoordinator } from '@a0n/aeon';
+
+const coordinator = new SyncCoordinator();
+
+coordinator.registerNode({
+  id: 'node-1',
+  address: 'localhost',
+  port: 3000,
+  status: 'online',
+  lastHeartbeat: new Date().toISOString(),
+  version: '1.0.0',
+  capabilities: ['sync', 'replicate'],
+});
+
+const session = coordinator.createSyncSession('node-1', ['node-2', 'node-3']);
+```
+
+### Quick Start: Recovery Ledger
+
+```ts
+import { RecoveryLedger } from '@a0n/aeon';
+
+const ledger = new RecoveryLedger({
+  objectId: 'asset:app.bundle.js',
+  dataShardCount: 4,
+  parityShardCount: 2,
+});
+
+ledger.registerRequest('req-a');
+ledger.registerRequest('req-b');
+
+ledger.recordShardObservation({
+  shardRole: 'data',
+  shardIndex: 0,
+  digest: 'sha256:data-0',
+  observedBy: 'edge-a',
+});
+
+ledger.recordShardObservation({
+  shardRole: 'parity',
+  shardIndex: 0,
+  digest: 'sha256:parity-0',
+  observedBy: 'edge-b',
+});
+
+const status = ledger.getStatus();
+if (status.canReconstruct) {
+  // Fold the request family once the merged shard ledger crosses threshold.
+}
+```
+
+### Quick Start: Schema Migrations
+
+```ts
+import { MigrationEngine } from '@a0n/aeon';
+
+const engine = new MigrationEngine();
+
+engine.registerMigration({
+  id: 'add-status-field',
+  version: '2.0.0',
+  name: 'Add user status field',
+  up: (data) => ({ ...data, status: 'active' }),
+  down: (data) => {
+    const { status, ...rest } = data;
+    return rest;
+  },
+  timestamp: new Date().toISOString(),
+  description: 'Adds status field to all user records',
+});
+```
+
+## Modules
+
+Everything is available from the root import. Subpath imports are available for tree-shaking:
+
+| Import | What it does |
+|--------|-------------|
+| `@a0n/aeon` | Everything (barrel export) |
+| `@a0n/aeon/core` | Core types and interfaces |
+| `@a0n/aeon/distributed` | Sync coordination, replication, conflict resolution, and recovery ledgers |
+| `@a0n/aeon/versioning` | Schema versions, migrations, tracking |
+| `@a0n/aeon/offline` | Queued work for unreliable or offline periods |
+| `@a0n/aeon/compression` | Compression and delta-sync helpers |
+| `@a0n/aeon/persistence` | In-memory and storage adapter surfaces |
+| `@a0n/aeon/presence` | Real-time node and session state |
+| `@a0n/aeon/crypto` | Signing and UCAN-related primitives |
+
+The flow protocol, topology analysis, transport helpers, and federation modules are exported from the root barrel.
+
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [`@a0n/aeon-pipelines`](https://github.com/forkjoin-ai/aeon-pipelines) | Execution engine for fork/race/fold as computation primitives (race on speed, value, or any lambda) |
+| [`packages/shootoff`](./packages/shootoff/README.md) | Side-by-side protocol benchmarks against HTTP/1.1 and HTTP/2 |
+| [`packages/wall`](./packages/wall/README.md) | Command-line client and benchmark harness for Aeon Flow, including native raw-path Aeon blasts, preconnected launch-gate benchmarking, mixed UDP+TCP transport races, and direct bearer or `X-Aeon-*` auth injection |
+| `packages/nginx-flow-aeon` | nginx bridge for Aeon Flow behind HTTP infrastructure |
+| [`aeon-bazaar`](https://github.com/forkjoin-ai/aeon-bazaar) | Unbounded negotiation engine -- void walking, complement distributions |
+| [`aeon-neutral`](https://github.com/forkjoin-ai/aeon-neutral) | Bounded dispute resolution -- three-walker Skyrms mediation with convergence certificates |
+
+## Formal Surface
+
+TLA+ specifications for negotiation convergence (in `companion-tests/formal/`):
+
+| Spec | What it models |
+|------|---------------|
+| `NegotiationConvergence.tla` | Single-party fork/race/fold with BATNA threshold |
+| `MetacognitiveWalker.tla` | c0-c3 cognitive loop, kurtosis convergence |
+| `SkyrmsNadir.tla` | Two walkers converging via accumulated failure |
+| `SkyrmsThreeWalker.tla` | Mediator as third walker on the convergence site |
+
+## Documentation
+
+- [docs/README.md](./docs/README.md) -- repo docs index
+- [src/README.md](./src/README.md) -- source tree index
+- [Manuscript source](./docs/ebooks/145-log-rolling-pipelined-prefill/ch17-arxiv-manuscript.md) -- Chapter 17 formal manuscript
+- [Companion tests](./docs/ebooks/145-log-rolling-pipelined-prefill/companion-tests/README.md) -- reproducibility suite
+- [ROADMAP.md](./ROADMAP.md) -- near-term direction
+
+## License
+
+Copyright Taylor William Buley. All rights reserved.
+
+MIT

package/dist/CryptoProvider-SLWjqByk.d.cts

@@ -0,0 +1,407 @@
+/**
+ * Aeon Crypto Types
+ *
+ * Type definitions for cryptographic operations in Aeon.
+ * These are compatible with @affectively/auth and @affectively/auth.
+ */
+/**
+ * Decentralized Identifier (DID)
+ * Format: did:method:identifier
+ */
+type DID = `did:${string}:${string}`;
+/**
+ * Supported signing algorithms
+ */
+type SigningAlgorithm = 'ES256' | 'Ed25519' | 'ES384' | 'ES512';
+/**
+ * Key pair for signing and verification
+ */
+interface KeyPair {
+    algorithm: SigningAlgorithm;
+    publicKey: JsonWebKey;
+    privateKey?: JsonWebKey;
+    fingerprint: string;
+}
+/**
+ * Identity representing a user or node
+ */
+interface Identity {
+    did: DID;
+    signingKey: KeyPair;
+    encryptionKey?: KeyPair;
+    createdAt: number;
+    displayName?: string;
+}
+/**
+ * UCAN Capability structure
+ */
+interface Capability {
+    can: string;
+    with: string;
+    constraints?: Record<string, unknown>;
+}
+/**
+ * UCAN Token payload
+ */
+interface UCANPayload {
+    iss: DID;
+    aud: DID;
+    exp: number;
+    nbf?: number;
+    iat?: number;
+    nonce?: string;
+    jti?: string;
+    att: Capability[];
+    prf?: string[];
+    fct?: Record<string, unknown>;
+}
+/**
+ * Parsed UCAN Token
+ */
+interface UCANToken {
+    payload: UCANPayload;
+    raw: string;
+    signature: Uint8Array;
+    algorithm: string;
+}
+/**
+ * UCAN verification result
+ */
+interface VerificationResult {
+    valid: boolean;
+    payload?: UCANPayload;
+    error?: string;
+    expired?: boolean;
+    shouldRotate?: boolean;
+    expiresIn?: number;
+}
+/**
+ * Encryption algorithms supported
+ */
+type EncryptionAlgorithm = 'ECIES-P256' | 'AES-256-GCM';
+/**
+ * HKDF domain separator categories
+ */
+type DomainCategory = 'default' | 'sync' | 'message' | 'api-key' | 'personal-data' | string;
+/**
+ * EC Key pair for ECDH operations
+ */
+interface ECKeyPair {
+    publicKey: JsonWebKey;
+    privateKey: JsonWebKey;
+    keyId: string;
+    createdAt: string;
+}
+/**
+ * Encrypted data envelope
+ */
+interface EncryptedPayload {
+    alg: EncryptionAlgorithm;
+    ct: string;
+    iv: string;
+    tag: string;
+    epk?: JsonWebKey;
+    category?: DomainCategory;
+    nonce?: string;
+    encryptedAt: number;
+}
+/**
+ * Decryption result
+ */
+interface DecryptionResult {
+    plaintext: Uint8Array;
+    category?: DomainCategory;
+    encryptedAt: number;
+}
+/**
+ * Aeon encryption mode
+ */
+type AeonEncryptionMode = 'none' | 'transport' | 'at-rest' | 'end-to-end';
+/**
+ * Aeon sync capability namespace
+ */
+declare const AEON_CAPABILITIES: {
+    readonly SYNC_READ: "aeon:sync:read";
+    readonly SYNC_WRITE: "aeon:sync:write";
+    readonly SYNC_ADMIN: "aeon:sync:admin";
+    readonly NODE_REGISTER: "aeon:node:register";
+    readonly NODE_HEARTBEAT: "aeon:node:heartbeat";
+    readonly REPLICATE_READ: "aeon:replicate:read";
+    readonly REPLICATE_WRITE: "aeon:replicate:write";
+    readonly STATE_READ: "aeon:state:read";
+    readonly STATE_WRITE: "aeon:state:write";
+    readonly STATE_RECONCILE: "aeon:state:reconcile";
+};
+type AeonCapability = (typeof AEON_CAPABILITIES)[keyof typeof AEON_CAPABILITIES];
+/**
+ * Crypto configuration for Aeon
+ */
+interface AeonCryptoConfig {
+    /** Default encryption mode for sync messages */
+    defaultEncryptionMode: AeonEncryptionMode;
+    /** Require all messages to be signed */
+    requireSignatures: boolean;
+    /** Require UCAN capability verification */
+    requireCapabilities: boolean;
+    /** Allowed signature algorithms */
+    allowedSignatureAlgorithms: string[];
+    /** Allowed encryption algorithms */
+    allowedEncryptionAlgorithms: string[];
+    /** UCAN audience DID for verification */
+    ucanAudience?: string;
+    /** Session key expiration (ms) */
+    sessionKeyExpiration?: number;
+}
+/**
+ * Default crypto configuration
+ */
+declare const DEFAULT_CRYPTO_CONFIG: AeonCryptoConfig;
+/**
+ * Authenticated sync message fields
+ */
+interface AuthenticatedMessageFields {
+    /** Sender DID */
+    senderDID?: string;
+    /** Receiver DID */
+    receiverDID?: string;
+    /** UCAN token for capability verification */
+    ucan?: string;
+    /** Message signature (base64url) */
+    signature?: string;
+    /** Whether payload is encrypted */
+    encrypted?: boolean;
+}
+/**
+ * Secure sync session
+ */
+interface SecureSyncSession {
+    id: string;
+    initiator: string;
+    participants: string[];
+    sessionKey?: Uint8Array;
+    encryptionMode: AeonEncryptionMode;
+    requiredCapabilities: string[];
+    status: 'pending' | 'active' | 'completed' | 'failed';
+    startTime: string;
+    endTime?: string;
+}
+/**
+ * Node with identity information
+ */
+interface SecureNodeInfo {
+    id: string;
+    did?: string;
+    publicSigningKey?: JsonWebKey;
+    publicEncryptionKey?: JsonWebKey;
+    capabilities?: string[];
+    lastSeen?: number;
+}
+/**
+ * Capability verification result
+ */
+interface AeonCapabilityResult {
+    authorized: boolean;
+    error?: string;
+    issuer?: string;
+    grantedCapabilities?: Array<{
+        can: string;
+        with: string;
+    }>;
+}
+/**
+ * Signed data envelope for sync operations
+ */
+interface SignedSyncData<T = unknown> {
+    payload: T;
+    signature: string;
+    signer: string;
+    algorithm: string;
+    signedAt: number;
+}
+
+/**
+ * Aeon Crypto Provider Interface
+ *
+ * Abstract interface for cryptographic operations.
+ * Aeon core remains zero-dependency - crypto is injected through this interface.
+ */
+
+/**
+ * Abstract crypto provider interface
+ *
+ * Implementations use @affectively/auth and @affectively/auth
+ * or other compatible libraries.
+ */
+interface ICryptoProvider {
+    /**
+     * Generate a new identity with DID and key pairs
+     */
+    generateIdentity(displayName?: string): Promise<{
+        did: string;
+        publicSigningKey: JsonWebKey;
+        publicEncryptionKey?: JsonWebKey;
+    }>;
+    /**
+     * Get the local identity's DID
+     */
+    getLocalDID(): string | null;
+    /**
+     * Export local identity's public info for sharing
+     */
+    exportPublicIdentity(): Promise<SecureNodeInfo | null>;
+    /**
+     * Register a known remote node's public keys
+     */
+    registerRemoteNode(node: SecureNodeInfo): Promise<void>;
+    /**
+     * Get a remote node's public key
+     */
+    getRemotePublicKey(did: string): Promise<JsonWebKey | null>;
+    /**
+     * Sign data with local identity's private key
+     */
+    sign(data: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Sign structured data and wrap in SignedSyncData envelope
+     */
+    signData<T>(data: T): Promise<SignedSyncData<T>>;
+    /**
+     * Verify a signature from a remote node
+     */
+    verify(did: string, signature: Uint8Array, data: Uint8Array): Promise<boolean>;
+    /**
+     * Verify a SignedSyncData envelope
+     */
+    verifySignedData<T>(signedData: SignedSyncData<T>): Promise<boolean>;
+    /**
+     * Encrypt data for a recipient
+     */
+    encrypt(plaintext: Uint8Array, recipientDID: string): Promise<{
+        alg: string;
+        ct: string;
+        iv: string;
+        tag: string;
+        epk?: JsonWebKey;
+        encryptedAt: number;
+    }>;
+    /**
+     * Decrypt data
+     */
+    decrypt(encrypted: {
+        alg: string;
+        ct: string;
+        iv: string;
+        tag: string;
+        epk?: JsonWebKey;
+    }, senderDID?: string): Promise<Uint8Array>;
+    /**
+     * Derive or get a session key for communication with a peer
+     */
+    getSessionKey(peerDID: string): Promise<Uint8Array>;
+    /**
+     * Encrypt with a session key
+     */
+    encryptWithSessionKey(plaintext: Uint8Array, sessionKey: Uint8Array): Promise<{
+        alg: string;
+        ct: string;
+        iv: string;
+        tag: string;
+        encryptedAt: number;
+    }>;
+    /**
+     * Decrypt with a session key
+     */
+    decryptWithSessionKey(encrypted: {
+        ct: string;
+        iv: string;
+        tag: string;
+    }, sessionKey: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Create a UCAN token
+     */
+    createUCAN(audience: string, capabilities: Array<{
+        can: string;
+        with: string;
+    }>, options?: {
+        expirationSeconds?: number;
+        proofs?: string[];
+    }): Promise<string>;
+    /**
+     * Verify a UCAN token
+     */
+    verifyUCAN(token: string, options?: {
+        expectedAudience?: string;
+        requiredCapabilities?: Array<{
+            can: string;
+            with: string;
+        }>;
+    }): Promise<AeonCapabilityResult>;
+    /**
+     * Delegate capabilities
+     */
+    delegateCapabilities(parentToken: string, audience: string, capabilities: Array<{
+        can: string;
+        with: string;
+    }>, options?: {
+        expirationSeconds?: number;
+    }): Promise<string>;
+    /**
+     * Compute hash of data
+     */
+    hash(data: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Generate random bytes
+     */
+    randomBytes(length: number): Uint8Array;
+    /**
+     * Check if crypto is properly initialized
+     */
+    isInitialized(): boolean;
+}
+/**
+ * Null crypto provider for when crypto is disabled
+ *
+ * All operations either throw or return permissive defaults.
+ */
+declare class NullCryptoProvider implements ICryptoProvider {
+    private notConfiguredError;
+    generateIdentity(): Promise<{
+        did: string;
+        publicSigningKey: JsonWebKey;
+        publicEncryptionKey?: JsonWebKey;
+    }>;
+    getLocalDID(): string | null;
+    exportPublicIdentity(): Promise<SecureNodeInfo | null>;
+    registerRemoteNode(): Promise<void>;
+    getRemotePublicKey(): Promise<JsonWebKey | null>;
+    sign(): Promise<Uint8Array>;
+    signData<T>(_data: T): Promise<SignedSyncData<T>>;
+    verify(): Promise<boolean>;
+    verifySignedData(): Promise<boolean>;
+    encrypt(): Promise<{
+        alg: string;
+        ct: string;
+        iv: string;
+        tag: string;
+        epk?: JsonWebKey;
+        encryptedAt: number;
+    }>;
+    decrypt(): Promise<Uint8Array>;
+    getSessionKey(): Promise<Uint8Array>;
+    encryptWithSessionKey(): Promise<{
+        alg: string;
+        ct: string;
+        iv: string;
+        tag: string;
+        encryptedAt: number;
+    }>;
+    decryptWithSessionKey(): Promise<Uint8Array>;
+    createUCAN(): Promise<string>;
+    verifyUCAN(): Promise<AeonCapabilityResult>;
+    delegateCapabilities(): Promise<string>;
+    hash(): Promise<Uint8Array>;
+    randomBytes(length: number): Uint8Array;
+    isInitialized(): boolean;
+}
+
+export { AEON_CAPABILITIES as A, type Capability as C, DEFAULT_CRYPTO_CONFIG as D, type ECKeyPair as E, type ICryptoProvider as I, type KeyPair as K, NullCryptoProvider as N, type SecureNodeInfo as S, type UCANPayload as U, type VerificationResult as V, type AeonCapability as a, type AeonCapabilityResult as b, type AeonCryptoConfig as c, type AeonEncryptionMode as d, type AuthenticatedMessageFields as e, type DID as f, type DecryptionResult as g, type DomainCategory as h, type EncryptedPayload as i, type EncryptionAlgorithm as j, type Identity as k, type SecureSyncSession as l, type SignedSyncData as m, type SigningAlgorithm as n, type UCANToken as o };