@enfyra/kernel

Enfyra kernel runtime package.

Dynamic context

The isolated executor snapshots cloneable $ctx keys into the sandbox automatically. Runtime platforms can expose new data fields from their own context factory without changing the kernel, while protected runtime capabilities such as $helpers, $cache, $repos, $socket, $throw, $trigger, $logs, $req, and $res stay kernel-managed. $env is readable inside the sandbox when provided by the host application, but sandbox mutations to $env are not merged back to the host context.

Use

import { createEnfyraKernel } from '@enfyra/kernel';

const kernel = createEnfyraKernel({
  knexService,
  mongoService,
  databaseConfigService,
  runtimeMetricsCollectorService,
  lazyRef,
  getPackageCacheService: () => packageCacheService,
  getPackageCdnLoaderService: () => packageCdnLoaderService,
});

container.register({
  queryBuilderService: asValue(kernel.queryBuilderService),
  isolatedExecutorService: asValue(kernel.isolatedExecutorService),
  executorEngineService: asValue(kernel.executorEngineService),
});

Executor capacity

Each runner process executes multiple independent task-owned ivm.Isolate instances, up to isolatesPerWorker. Each execution creates its own isolate and context directly on dispatch, without an idle isolate reserve pool. Completion or cancellation disposes only that task's isolate; other tasks in the worker keep running. A batch's hooks and handler share that batch's isolate. There is no shared lane or multi-task heap.

Tuning selects up to two runner processes using effective CPU and container memory. Admission capacity and isolate heap limits are independent policies. Admission uses a 25% memory planning budget, a 40–128 MiB planning unit, CPU baseline/flexible unit counts, and six independent execution slots per unit. This is capacity arithmetic, not a shared isolate or lane: each admitted task still owns its isolate. Below 2 GiB, admission uses one unit per runner; larger profiles are bounded at 128 units per runner. A 14 CPU / 36 GiB profile admits 216 task isolates per worker, or 432 total.

Each isolate's native heap limit is effective memory divided by 32, with a 40 MiB minimum and no fixed MB ceiling. Limits are not preallocated RAM, and their sum may exceed physical memory. The parent applies RSS backpressure; runner, package-child, IPC and host memory remain outside isolate heap limits. Large simultaneous tasks can still exhaust real memory, so benchmark the expected payload and concurrency on the target hardware.

computeEngineTuning({ logicalCpuCount, totalMemoryBytes, maxIsolatesPerWorker }) can lower the per-worker capacity for a host-owned profile. A custom executor tuning contains maxConcurrentWorkers, isolatesPerWorker, and isolateMemoryLimitMb. Queued tasks start only after prior tasks release their isolate capacity. $body and the exact $req.rawBody remain available.

Run yarn test:executor-isolates for capacity and failure containment. Never automatically replay a task after ambiguous isolate or runner loss.