@hwy-fm/kernel

Kernel is not a framework. It is the thing you use to build one.

Kernel is a statically compiled computation kernel. It defines five primitives — Seed, Instruction, Slot, Composer, Context — that let you assemble any architecture: how many pipeline stages, what protocols, what execution topology. Those are your decisions, not Kernel's.

@hwy-fm/std is proof: its entire framework — 8 Slots, a default protocol, one-liner decorators — is built from these five primitives plus one registerModelHook() call. std is not special. It is one possible architecture. You can build a completely different one.

Five Primitives

| Primitive | Role | |-----------|------| | Seed | Addressable computation. Match pattern (URL, command, event, any identifier) + execute(). | | Instruction | Processing step that runs around Seeds. Can be atomic — or an entire sub-Kernel. | | Slot | Named pipeline position. Stage (INGRESS / PROCESS / EGRESS) + topology anchors for ordering. | | Composer | Execution physics within a Slot — onion, linear, or custom. | | Context | The state that flows through the pipeline from start to finish. |

INGRESS    [ Slots you define: parse, authenticate, validate, ... ]
    ↓
PROCESS    [ Seed.execute() — your computation ]
    ↓
EGRESS     [ Slots you define: format, log, trace, ... ]
             always executes (finally semantics)

Architecture as Code

Your architecture is not a comment. Not a diagram. It is compilable structure:

const System   = KernelModel();
const Auth     = KernelModel();
const Business = KernelModel();
const View     = KernelModel();

// Each Kernel defines its own pipeline shape
@Auth.slot({ name: 'identify', stage: 'INGRESS' })
@Auth.slot({ name: 'verify',   stage: 'PROCESS' })
@Auth.slot({ name: 'session',  stage: 'EGRESS' })

@Business.slot({ name: 'validate', stage: 'INGRESS' })
@Business.slot({ name: 'execute',  stage: 'PROCESS' })
@Business.slot({ name: 'event',    stage: 'EGRESS' })

@View.slot({ name: 'resolve', stage: 'INGRESS' })
@View.slot({ name: 'render',  stage: 'PROCESS' })
@View.slot({ name: 'cache',   stage: 'EGRESS' })

// Connect them — each bridge is an Instruction
@System.instruction({ protocol: SYS, slotName: 'auth', match: '**' })
class AuthBridge { /* → dispatch into Auth Kernel */ }

@System.instruction({ protocol: SYS, slotName: 'process', match: '**' })
class BusinessBridge { /* → dispatch into Business Kernel */ }

@System.instruction({ protocol: SYS, slotName: 'deliver', match: '**' })
class ViewBridge { /* → dispatch into View Kernel */ }

                        System
                ┌─────────┼─────────┐
                │         │         │
              Auth     Business    View
             ┌──┼──┐   ┌──┼──┐   ┌──┼──┐
             I  P  E   I  P  E   I  P  E

I = INGRESS    P = PROCESS    E = EGRESS
Each box is a complete Kernel — own Slots, own compilation, own DI tree.

Four isolated systems — each with its own Slots, Seeds, compilation, and DI tree — composed through Kernel's own primitives. Every KernelModel() is a physically independent Kernel: own registry, own routing, own compilation. Yet every Kernel exposes the same createContext() / forward() interface. Teams own separate Kernels. The pattern is the same at every scale.

Static Compilation

Kernel is statically compiled. The entire pipeline structure — Slot topology, Instruction matching, route resolution — compiles once at mount(). At runtime, nothing is interpreted.

mount() — once at startup:
  Slots      → topologically sorted by anchors (DAG)
  Routes     → compiled into a Radix Tree
  Pipeline   → immutable, cached execution plan

dispatch() — every request:
  match address → O(k), k = path segments
  execute plan  → pre-compiled, zero reflection

Building on Kernel

registerModelHook() is how frameworks are born. Every hook is applied once per KernelModel() call — injecting Slots, providers, and custom API onto the model without touching Kernel source code:

// How @hwy-fm/std builds its entire framework — a single Model Hook
registerModelHook({
  bootstrapProviders: () => [
    { provide: STD_PROTOCOL, useValue: STD_PROTOCOL },
  ],
  setup(model) {
    setupSlotDrive(model);   // declareSlot / ingress / process / egress
    setupStdSlots(model);    // 8 pre-configured Slots
    setupAdmissionOfficers(model);
  },
});

Admission Officers let you filter or transform Instructions at compile time:

@model.admission()
class SecurityAdmission {
  admitInstruction(instruction) {
    if (!instruction.protocol) return null;  // veto
    return instruction;                       // pass through
  }
}

Install

npm install @hwy-fm/kernel @hwy-fm/di

For a ready-to-use architecture built on Kernel, see @hwy-fm/std.

API Reference

KernelModel

const model = KernelModel();

| Method | Description | |--------|-------------| | model.seed(def) | Register a Seed (class or method decorator) | | model.instruction(def) | Register an Instruction (class or method decorator) | | model.slot(def) | Register a Slot (class decorator) | | model.exclude(def) | Exclude a specific Instruction from a Seed's pipeline | | model.reset(def) | Reset all Instructions in a Slot for a Seed | | model.admission() | Register an Admission Officer (compile-time filter) | | model.configure(options) | Set timeout, debug mode, concurrency, logger | | model.security(config) | Set security limits | | model.bootstrap | Bootstrap decorator | | model.kernel | Access the bootstrapped Kernel instance | | model.destroy() | Destroy all Kernel instances |

Kernel Instance

| Method | Description | |--------|-------------| | kernel.createContext(options) | Create a Context | | kernel.dispatch(ctx) | Full dispatch — telemetry, timeout, debug tracing | | kernel.forward(ctx) | Lightweight dispatch — no telemetry overhead | | kernel.mount() | Compile pending Seeds into Pipelines | | kernel.remount() | Recompile all Pipelines | | kernel.shutdown(timeout?) | Graceful shutdown — drain in-flight, then abort | | kernel.inject(token) | Resolve a dependency from the Kernel injector | | kernel.events | Subscribe to lifecycle events |

Full API inventory — Context fields, Configuration, EGRESS semantics, Events, Exceptions, Inspector, extension points — is in KERNEL_CORE_PRINCIPLES.md.

Related Packages

| Package | Description | |---------|-------------| | @hwy-fm/di | The DI container powering Kernel — Scoping, Hooks, Async Governance | | @hwy-fm/std | An architecture built on Kernel — 8 pre-configured Slots, Gateway, one-liner decorators | | @hwy-fm/cli | Build tools + CLI scaffolding |

Documentation

| Document | Description | |----------|-------------| | KERNEL_CORE_PRINCIPLES.md | Full API reference, internal design, extensibility interfaces |

License

MIT © hwyn