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

EndpointMethodeBeschrijvingAuth
/kernel/statusGETKernel-status en versieSession cookie
/kernel/contextGETKernel-context metadata (geen secrets)Session cookie
/kernel/resolvePOSTResolve kernel-service op naamSession + capability
/kernel/eventsGETSSE stream van kernel-eventsSession 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

8. Risico's en aanbevelingen

RisicoImpactMitigatie
Kernel-afhankelijkheid blokkeert andere routesHighKernel middleware is optioneel. Routes zonder kernel werken nog (zoals Fase 1A).
Request-scoped context = meer allocatiesMediumLazy initialisatie: services pas aanmaken bij eerste gebruik.
Event bus kan geheugenlekken veroorzakenMediumAutomatische cleanup bij request-einde. Max listeners per event.
Stores missen kernel-events bij disconnectLowReconnect + 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.