API: Kernel-accessor + context middleware
Ticket 1D-01 • Bron: src/routes/kernel.ts (gepland) • Status: ontwerp • Risico: hoog (kernel-afhankelijkheid)
Kerndefinitie: Kernel-accessor biedt Hono-routes toegang tot de kernel-context via middleware, niet via zustand-stores. De kernel-context wordt per-request doorgegeven via c.get("kernel"). resolve() werkt zonder zustand-hooks. Stores zijn consumers van kernel-events, niet bronnen van waarheid.
1. Architectuur
Hono Request Pipeline
│
├── 1. Kernel middleware (per request)
│ ├── Maak kernel-context aan
│ ├── Voeg toe aan Hono context: c.set("kernel", ctx)
│ └── Kernel context bevat:
│ ├── wallet: WalletService
│ ├── storage: StorageService
│ ├── chain: ChainService
│ ├── session: SessionService
│ └── events: EventBus
│
├── 2. Route handler
│ └── const kernel = c.get("kernel")
│ ├── kernel.wallet.connect()
│ ├── kernel.storage.read(path)
│ └── kernel.chain.send(tx)
│
└── 3. Stores als consumers
├── Store subscribes op kernel-events
├── Store Update UI op basis van events
└── Store NIET als bron van waarheid
Versus zustand (oud):
OUD: const store = useStore() → zustand hook
NIEUW: const kernel = c.get("kernel") → Hono context
Reden: zustand is client-side, kernel-context is server-side.
Geen mix van paradigma's.
2. Endpoints
| Endpoint | Methode | Beschrijving | Auth |
/kernel/status | GET | Kernel-status en versie | Session cookie |
/kernel/context | GET | Kernel-context metadata (geen secrets) | Session cookie |
/kernel/resolve | POST | Resolve kernel-service op naam | Session + capability |
/kernel/events | GET | SSE stream van kernel-events | Session cookie |
3. Kernel-context als middleware
// kernel-middleware.ts
export const kernelMiddleware: MiddlewareHandler = async (c, next) => {
const kernel: KernelContext = {
wallet: createWalletService(c),
storage: createStorageService(c),
chain: createChainService(c),
session: getSessionFromCookie(c),
events: globalEventBus,
};
c.set("kernel", kernel);
await next();
};
// In route handler:
app.get("/kernel/status", kernelMiddleware, (c) => {
const kernel = c.get("kernel");
return c.json({
status: "ok",
walletConnected: kernel.wallet.isConnected(),
chainId: kernel.chain.getChainId(),
sessionId: kernel.session?.id,
});
});
Geen zustand. Geen React hooks. Puur Hono context.
3.1 KernelContext interface
interface KernelContext {
wallet: {
connect(): Promise<WalletInfo>;
disconnect(): void;
getAddress(): string | null;
isConnected(): boolean;
sign(message: string): Promise<string>;
};
storage: {
read(path: string): Promise<Uint8Array>;
write(path: string, data: Uint8Array): Promise<void>;
list(dir: string): Promise<FileEntry[]>;
delete(path: string): Promise<void>;
};
chain: {
getChainId(): number;
sendTx(tx: Transaction): Promise<TxReceipt>;
estimateGas(tx: Transaction): Promise<bigint>;
getBalance(addr: string): Promise<bigint>;
};
session: Session | null;
events: EventBus;
}
4. resolve() zonder zustand-hooks
Oude benadering (zustand):
// Client-side React component
const wallet = useStore(state => state.wallet);
wallet.connect();
Nieuwe benadering (resolve):
// Server-side Hono route
const kernel = c.get("kernel");
const wallet = kernel.wallet;
await wallet.connect();
Waarom geen zustand?
1. Zustand is client-side state management (React)
2. Hono routes zijn server-side (Node.js)
3. Kernel-context is request-scoped (per request een nieuwe instance)
4. Geen gedeelde mutable state (veiliger, testbaarder)
5. Geen React-afhankelijkheid in de API-laag
5. Stores als consumers van kernel-events
Kernel Event Bus:
├── event: "wallet:connected"
│ └── payload: { address, chainId }
│
├── event: "wallet:disconnected"
│ └── payload: {}
│
├── event: "storage:changed"
│ └── payload: { path, action: "create|update|delete" }
│
├── event: "chain:tx:sent"
│ └── payload: { txHash, from, to, value }
│
└── event: "session:expired"
└── payload: { sessionId }
Store (client-side React):
useEffect(() => {
kernel.events.on("wallet:connected", (data) => {
setWalletAddress(data.address);
});
return () => kernel.events.off("wallet:connected");
}, []);
Store is consumer, niet bron. Kernel-events drijven de UI aan.
6. Request / Response voorbeelden
6.1 GET /kernel/status
GET /kernel/status HTTP/1.1
Cookie: maos-session=...
Response:
{
"status": "ok",
"version": "1.0.0",
"walletConnected": true,
"walletAddress": "0x742d35Cc...",
"chainId": 270,
"storageAvailable": true,
"sessionId": "sess_abc123",
"uptime": 3600
}
6.2 POST /kernel/resolve
POST /kernel/resolve HTTP/1.1
Cookie: maos-session=...
Content-Type: application/json
{ "service": "wallet" }
Response:
{
"service": "wallet",
"available": true,
"methods": ["connect", "disconnect", "sign", "send"],
"connected": true,
"address": "0x742d35Cc..."
}
6.3 Foutafhandeling
// Onbekende service
POST /kernel/resolve { "service": "unknown" }
→ 400 { "error": "Unknown service", "available": ["wallet", "storage", "chain"] }
// Geen sessie
GET /kernel/status (geen cookie)
→ 401 { "error": "Session required" }
// Kernel niet geinitialiseerd
GET /kernel/status (tijdens boot)
→ 503 { "error": "Kernel not ready", "state": "booting" }
7. Acceptatiecriteria
- Kernel-context middleware: c.get("kernel") werkt in alle routes
- resolve() zonder zustand: puur Hono context, geen React hooks
- Stores als consumers: kernel-events sturen UI aan
- Request-scoped: elke request krijgt verse kernel-context
- Geen mutable gedeelde state: veiliger, testbaarder
- Status endpoint: toont kernel-status + services
- SSE events: kernel-events streamen naar clients
8. Risico's en aanbevelingen
| Risico | Impact | Mitigatie |
| Kernel-afhankelijkheid blokkeert andere routes | High | Kernel middleware is optioneel. Routes zonder kernel werken nog (zoals Fase 1A). |
| Request-scoped context = meer allocaties | Medium | Lazy initialisatie: services pas aanmaken bij eerste gebruik. |
| Event bus kan geheugenlekken veroorzaken | Medium | Automatische cleanup bij request-einde. Max listeners per event. |
| Stores missen kernel-events bij disconnect | Low | Reconnect + replay van gemiste events (event replay buffer). |
9. Verwijzingen
Fase 1D Nog niet geimplementeerd. Vereist: kernel service initialisatie, Hono middleware, event bus. Laatste fase: kernel is de kern van het systeem.