npm package: @hwy-fm/kernel
Description: Kernel is not a framework. It is the thing you use to build one.
Author: hwyn
Latest version: 0.1.3

# @hwy-fm/kernel

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-Strict-blue.svg)](https://www.typescriptlang.org/)

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`](https://www.npmjs.com/package/@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:

```typescript
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:

```typescript
// 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:

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

## Install

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

For a ready-to-use architecture built on Kernel, see [`@hwy-fm/std`](https://www.npmjs.com/package/@hwy-fm/std).

## API Reference

### KernelModel

```typescript
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`](./KERNEL_CORE_PRINCIPLES.md).

## Related Packages

| Package | Description |
|---------|-------------|
| [`@hwy-fm/di`](https://www.npmjs.com/package/@hwy-fm/di) | The DI container powering Kernel — Scoping, Hooks, Async Governance |
| [`@hwy-fm/std`](https://www.npmjs.com/package/@hwy-fm/std) | An architecture built on Kernel — 8 pre-configured Slots, Gateway, one-liner decorators |
| [`@hwy-fm/cli`](https://www.npmjs.com/package/@hwy-fm/cli) | Build tools + CLI scaffolding |

## Documentation

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

## License

MIT © [hwyn](https://github.com/hwyn)