litekernel

Overview

litekernel é o core do StateDelta - um sistema operacional determinístico orientado a patches via ticks. Como um kernel Unix gerencia processos e recursos, o StateDeltaKernel gerencia providers e processos em qualquer ambiente JavaScript.

O kernel é agnóstico - recebe tudo já resolvido da camada de persistência e foca apenas em execução.

┌─────────────────────────────────────────────────────────────────┐
│              PERSISTENCE LAYER (externa)                         │
│         Chain / Gateway / Assembler                              │
│         Resolve deltas, reconstrói estado                        │
└─────────────────────────┬───────────────────────────────────────┘
                          │ entrega manifest resolvido
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│                     litekernel                           │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │              Root Providers (IRootContext)              │   │
│  │   ErrorProvider │ TickProvider │ SystemProvider         │   │
│  └────────────────────────┬────────────────────────────────┘   │
│                           │                                     │
│  ┌────────────────────────▼────────────────────────────────┐   │
│  │          High-Level Providers (IProviderContext)        │   │
│  │     RouterProvider │ StateProvider │ APIProvider        │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

Features

| Feature | Description | | ------------------------- | ------------------------------------------------------ | | Minimal Core | Minimal dependencies (@statedelta/event-emitter) | | Two-Tier Architecture | Root providers (full access) vs High-level (sandboxed) | | Atomic Tick System | Deterministic execution via TickProvider | | Provider Bindings | Direct high-performance access between providers | | Lazy Install | Install providers on-demand via registry | | Hot-Swappable | Install/remove/reload providers at runtime | | IPC System | Request/response, fire-and-forget, broadcast | | Process Management | Spawn, suspend, resume, kill processes | | Event System | O(1) dispatch with Map-based handlers | | Manifest-Driven | Configure entire apps with JSON | | TypeScript First | Full type safety and IntelliSense |

Installation

pnpm add litekernel
# or
npm install litekernel

Quick Start

Minimal Example

import { StateDeltaKernel } from "litekernel";

// Manifest já resolvido pela camada de persistência
const manifest = {
  kernel: {
    bootOrder: ["system"],
    providers: {
      system: { version: "1.0.0" },
    },
  },
  providers: {
    router: { version: "1.0.0" },
  },
};

// Classes dos providers
const providers = {
  system: SystemProvider,
  router: RouterProvider,
};

const kernel = new StateDeltaKernel(manifest, { providers });
await kernel.boot();

With KernelInitializer

import { KernelInitializer, StateDeltaKernel } from "litekernel";

// Manifest já resolvido pela camada de persistência (Chain/Gateway/Assembler)
const resolvedManifest = await persistence.resolve("./app.delta.json");

// Inicializa (valida, congela, extrai providers)
const initializer = new KernelInitializer(resolvedManifest, {
  dependencyResolver: {
    resolve: async () => ({
      system: SystemProvider,
      error: ErrorProvider,
      router: RouterProvider,
    }),
  },
});

const { manifest, providers, dependencies } = await initializer.initialize();

// Cria e boota kernel
const kernel = new StateDeltaKernel(manifest, { providers, dependencies });
await kernel.boot();

Architecture

Separation of Concerns

Persistence Layer (external)     │  Kernel (this package)
─────────────────────────────────│─────────────────────────────
Chain: resolve extends           │  Receive ready manifest
Gateway: I/O abstraction         │  Boot providers
Assembler: replay deltas         │  Manage processes
                                 │  Route IPC/events
                                 │
NÃO sabe: boot, IPC, providers   │  NÃO sabe: extends, chain, deltas

Two-Tier Provider System

O kernel implementa dois níveis de providers seguindo o princípio de separação de privilégios:

| | Root Providers | High-Level Providers | |---|---|---| | Manifest | kernel.providers | providers | | Interface | IKernelProvider | IProvider | | Contexto | IRootContext (acesso total) | IProviderContext (sandboxed) | | Lifecycle | constructor → boot() | register → activate ↔ deactivate → shutdown | | Acesso ao kernel | ✅ Direto | ❌ Não | | Acesso ao manifest | ✅ Completo | 📋 Seções permitidas | | Comunicação | kernel.getProvider() | IPC ou Bindings | | Gerenciado por | Kernel | SystemProvider | | Exemplos | TickProvider, SystemProvider | RouterProvider, StateProvider |

Root Providers (manifest.kernel.providers)

Infraestrutura crítica com acesso total ao kernel:

import { IKernelProvider, IRootContext } from "litekernel";

class ErrorProvider implements IKernelProvider {
  constructor(config: any, context: IRootContext) {
    this.kernel = context.kernel;     // ✅ Acesso direto ao kernel
    this.manifest = context.manifest; // ✅ Manifest completo
  }

  async boot() {
    // Setup error handling
  }
}

High-Level Providers (manifest.providers)

Lógica de aplicação com acesso controlado via IProviderContext:

import { IProvider, IProviderContext } from "litekernel";

class RouterProvider implements IProvider {
  constructor(config: any, context: IProviderContext) {
    this.context = context;
    // ❌ Sem acesso ao kernel
    // 📋 Apenas seções permitidas do manifest
    this.routes = context.getManifestSection("routes");
  }

  register() {
    this.context.on("navigate", this.handleNavigate);
    this.context.handleRequest("getCurrentRoute", () => this.current);
  }

  activate() {
    this.navigateToInitial();
    this.context.emit("router:ready");
  }

  deactivate() {}
  shutdown() {}
}

Provider Lifecycle

ROOT PROVIDERS:     constructor → boot()

HIGH-LEVEL:         PENDING → REGISTERED → ACTIVE ↔ INACTIVE → SHUTDOWN
                              register()   activate() deactivate() shutdown()

IProviderContext API

interface IProviderContext {
  readonly providerId: string;

  // Manifest (controlled access)
  getManifestSection<T>(path: string): T | undefined;
  canRead(path: string): boolean;

  // Events
  on<T>(event: string, handler: (data: T) => void): () => void;
  emit(event: string, data?: any): void;
  waitFor<T>(event: string, timeout?: number): Promise<T>;

  // IPC
  sendMessage(target: string, type: string, payload?: any): void;
  sendRequest<T>(target: string, type: string, payload?: any): Promise<T>;
  broadcast(type: string, payload?: any): void;
  handleRequest<T, R>(type: string, handler: (payload: T) => R): () => void;

  // Process Management (own processes only)
  spawnProcess(config: ProcessConfig): Promise<IProcessInstance>;
  listProcesses(): IProcessInstance[];
  killProcess(id: string): Promise<void>;

  // Provider Bindings (high-performance direct access)
  getBinding<T>(id: string): T | null;
  requireBinding<T>(id: string): T;
  hasBinding(id: string): boolean;

  // Logging
  debug(message: string, data?: any): void;
  info(message: string, data?: any): void;
  warn(message: string, data?: any): void;
  error(message: string, data?: any): void;
}

Provider Bindings

Bindings permitem que providers acessem outros providers diretamente, sem overhead de IPC:

IPC (serialização)        Binding (direto)
─────────────────         ────────────────
~0.1-1ms                  ~0.001ms (100x faster)

Declaração no Manifest

{
  "providers": {
    "rules": {
      "dependencies": ["handler"],
      "bindings": ["tick", "handler"]
    }
  }
}

Uso no Provider

class RulesProvider implements IProvider {
  private tick: TickProvider;
  private handler: HandlerProvider;

  activate() {
    // Binding obrigatório - throw se não declarado
    this.tick = this.context.requireBinding<TickProvider>("tick");

    // Binding opcional - retorna null se não existir
    this.handler = this.context.getBinding<HandlerProvider>("handler");

    // Chamada direta, sem IPC!
    this.tick.register((t, ctx) => {
      const patches = this.executeRules(ctx);
      this.handler?.handlePatches(t, patches);
    });
  }
}

Provider Registry & Lazy Install

O kernel suporta instalação de providers sob demanda através de um registry:

import {
  StateDeltaKernel,
  InMemoryProviderRegistry
} from "litekernel";

// Registry controla quais providers estão disponíveis
const registry = new InMemoryProviderRegistry();

// Registra provider como disponível (mas não instalado)
registry.registerAvailable({ id: "cache", version: "1.0.0" });

// Define como instalar providers
registry.setInstaller(async (id) => {
  const module = await import(`@myapp/providers/${id}`);
  return module.default;
});

// Kernel com lazy install habilitado
const kernel = new StateDeltaKernel(manifest, resources, {
  registry,
  lazyInstall: true,      // Instalar automaticamente se necessário
  installTimeout: 30000,  // Timeout de instalação
});

await kernel.boot();
// Providers serão instalados automaticamente quando necessários

Fluxo de Resolução

Provider no manifest?
├─ Em dependencies? → Usa diretamente ✓
├─ Em registry como INSTALLED? → Usa diretamente ✓
├─ Em registry como AVAILABLE?
│   ├─ lazyInstall: true → Instala automaticamente ✓
│   └─ lazyInstall: false → ProviderNotInstalledError ✗
└─ Não encontrado → ProviderNotFoundError ✗

Per-Provider Override

{
  "providers": {
    "heavy-provider": {
      "lazyInstall": true
    }
  }
}

Manifest Structure

{
  "kernel": {
    "bootOrder": ["error", "tick", "system"],
    "providers": {
      "error": { "version": "1.0.0" },
      "tick": {
        "version": "1.0.0",
        "config": { "timing": true }
      },
      "system": { "version": "1.0.0" }
    }
  },
  "providers": {
    "router": {
      "version": "1.0.0",
      "dependencies": ["state"],
      "reads": ["routes"]
    },
    "state": {
      "version": "1.0.0",
      "config": { "persist": true }
    }
  },
  "routes": {
    "/": { "page": "home" },
    "/users/:id": { "page": "user-detail" }
  }
}

Events

import { KernelEvent, SystemEvent, TickEvent } from "litekernel";

// Kernel events
kernel.subscribe(KernelEvent.BOOT_START, () => {});
kernel.subscribe(KernelEvent.BOOT_COMPLETE, () => {});
kernel.subscribe(KernelEvent.ERROR, (e) => {});

// System events (via SystemProvider)
kernel.subscribe(SystemEvent.PROVIDERS_READY, (data) => {});
kernel.subscribe(SystemEvent.PROVIDER_ERROR, ({ providerId, error }) => {});

// Tick events (via TickProvider)
kernel.subscribe(TickEvent.TICK_AFTER, ({ tick, duration }) => {});
kernel.subscribe(TickEvent.STATE_LOCKED, ({ tick, reason }) => {});

Performance

O kernel foi otimizado com estruturas de dados de alto desempenho:

Complexidade de Operações

| Operation | Complexity | Notes | | --------------------- | ---------- | ------------------------ | | Event dispatch | O(1) | Map-based handlers | | Provider lookup | O(1) | Map storage | | Process access | O(1) | Map + secondary index | | Process by provider | O(k) | k = processes do provider| | Boot order resolution | O(V+E) | Topological sort | | Log push | O(1) | CircularBuffer | | IPC queue | O(1) | Deque (double-ended) | | Path lookup | O(1) | LRU Cache |

Estruturas de Dados Otimizadas

| Estrutura | Uso | Benefício vs Array/Object | | --------------- | ---------------------------- | -------------------------- | | CircularBuffer| Event log, boot logs | O(1) push vs O(n) shift | | Deque | IPC message queue | O(1) em ambas pontas | | LRUCache | Path segments, manifest | Evita recomputação | | Map | Providers, handlers, events | 27-53x faster que Object | | Set | Cleanup functions, listeners | O(1) add/delete |

Benchmarks

pnpm bench        # Run benchmarks (watch mode)
pnpm bench:run    # Run benchmarks (single run)

Resultados típicos:

• Boot 200 providers: ~25x mais lento que 1 provider (escala linear)
• Map lookup: 27-53x mais rápido que Object
• CircularBuffer: elimina O(n) shift overhead

Testing

pnpm test              # Run all tests
pnpm test:watch        # Run in watch mode
pnpm test:coverage     # Run with coverage (95%+)
pnpm bench             # Run benchmarks (watch)
pnpm bench:run         # Run benchmarks (single)

Documentation

| Document | Description | | -------------------------------------------------------------- | --------------------------- | | PHILOSOPHY.md | Design principles | | docs/ARCHITECTURE.md | System architecture | | docs/PROVIDER-BINDING.md | Provider bindings & DI | | docs/TICK-PROVIDER.md | TickProvider guide | | docs/API.md | Complete API reference | | docs/INITIALIZATION.md | Initialization flow | | docs/SYSTEM-PROVIDER.md | SystemProvider guide | | docs/FUTURE-OPTIMIZATIONS.md | Performance roadmap |

Philosophy

StateDeltaKernel follows Unix principles:

1. Do One Thing Well - Kernel only manages providers and IPC
2. Everything is a Provider - All functionality lives in providers
3. Composition Over Inheritance - Build systems from simple parts
4. Agnostic Core - Kernel doesn't know about persistence/deltas

Read more: PHILOSOPHY.md

License

MIT