litekernel

litekernel

A minimal, environment-agnostic operating system kernel for JavaScript/TypeScript applications

Bringing Unix philosophy to modern applications

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:

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

Read more: PHILOSOPHY.md

License

MIT