Kernel Orchestrator lifecycle

Browser-only MUST • SharedWorker-kernel • 3 kern-workers (VFS/Wallet/Chain) • health-monitor + stop-sequence • status: ontwerp, bron: orchestrator/*.ts

Besluit in 1 zin: De KernelOrchestrator is een singleton-class in de SharedWorker die bij boot wordt opgebouwd via geordende init-stappen, periodiek health-checks uitvoert, en bij stop/shutdown een 12-staps guarded stop-sequentie doorloopt waarbij elke stap best-effort is (een fout breekt de rest niet).

1. Architectuur-overzicht

Shell (main-thread)
  └── boot-orchestrator.ts  ──postMessage──▶ SharedWorker
                                               │
                              ┌─────────────────┼─────────────────┐
                              │            KernelOrchestrator      │
                              │  ┌──────────┬──────────┬────────┐ │
                              │  │VFSWorker │WalletWkr │ChainWkr│ │
                              │  └──────────┴──────────┴────────┘ │
                              │  VAPIServer (method dispatch)      │
                              │  MultiTierRateLimiter              │
                              │  LockGate (singleton)              │
                              │  SessionKeyManager                 │
                              │  ResourceOrchestrator              │
                              │  KernelHealthMonitor               │
                              │  PluginManager                     │
                              │  [Q17] kernel.preload() cache      │
                              └─────────────────────────────────────┘

2. Init-stappen (volgorde is cruciaal)

StapFunctieBronResultaat
1initKernelWorkerskernel-init.ts:43VFSWorker + WalletWorker + ChainWorker (kernel-level perms)
2initVFSAndEncryptionkernel-init.ts:89NovaVFS store, PBKDF2-sleutel, MAOSVFS, VersionManager
3createDAppManagerkernel-init.ts:256Sync DAppManager (over NovaVFS)
4initAddonWorkerManagerkernel-init.ts:257Async (fire-and-forget) addon worker
5initResourceMonitoringkernel-init.ts:262ResourceOrchestrator + MemoryMonitor
6initMemoryCompactLifecyclekernel-init.ts:267SettingsService + MemoryGuard + SuspendScheduler + ProcessAutoRestart
7initPluginManagerkernel-init.ts:278PluginManager + IPFS + Metrics plugins
8registerVAPIHandlerskernel-init.ts:281Alle VAPI-methoden geregistreerd (60+ handlers)
9initAddonVFSPersistencekernel-init.ts:284Addons overleven page-refresh
10initQRLoginServerkernel-init.ts:287QR-login server (alleen Node.js/server)
11LockGate clear + armGracekernel-orchestrator.ts:307-311Stale lock opruimen, 60s grace-window
REGEL: Elke stap is idempotent: dubbel aanroepen geeft hetzelfde resultaat. De volgorde is niet flexibel — stap 8 (VAPI-handlers) vereist stap 1-7.
Q17 — kernel.preload bij boot (preload-0.6 flow): De orchestrator ondersteunt een kernel.preload()-call na stap 11. Deze vult de init-cache (PermissionRegistry, Storage scope resolver, DApp manifest cache) zodat de eerste DApp-call niet 10s lazy-init wacht. Preload is optioneel: als overgeslagen, gedraagt de kernel zich exact als voorheen (lazy init bij eerste VAPI-call). Trigger: KernelConfig.preload.enabled (default: false, consumer zet aan na wallet-connect). Bron: kernel-orchestrator.ts, client-kernel-worker.ts:49.

3. Kernel workers (VFS/Wallet/Chain)

Elke worker krijgt kernel-level permissions bij aanmaak — ze hebben meer rechten dan DApp-workers.

WorkerPermissionsDefault ChainBron
VFSWorkerstorage:read, storage:write, storage:deleten.v.t.kernel-init.ts:49-58
WalletWorkerwallet:read, wallet:sign, wallet:signTypedDatan.v.t.kernel-init.ts:61-69
ChainWorkerchain:call, chain:send324 (zkSync Era)kernel-init.ts:72-80

3.1 Worker health monitoring

De KernelHealthMonitor voert periodiek een health-check uit (interval: HEALTH_CHECK_INTERVAL_MS). De check-callback komt van de orchestrator en heeft toegang tot workers, sessions en events.

4. Rate-limiting (multi-tier)

De MultiTierRateLimiter beheert drie tiers met eigen limits:

TierIdentificatieDefault limitWanneer
internalx-client-id: maos-core500 req/minDesktop UI (eigen kernel)
verifiedx-dapp-id aanwezig100 req/minGeverifieerde DApp
untrustedAlles anders100 req/minExterne / onbekende clients

Wallet-specifieke rate-limiting via optionele WalletRateLimiter (van BootOrchestrator). Bridge: kernel-orchestrator.ts:221-228.

5. Session key management

De SessionKeyManager beheert de levenscyclus van sessiesleutels voor geregistreerde DApps.

createSessionKey(dapp, dappId, config)
  → genereert willekeurige key
  → slaat op in dapp.sessionKeys + activeSessions Map
  → key verloopt na config.durationHours

validateSessionKey(dapp, key)
  → returning key of null (verlopen = verwijderd uit beide Maps)

revokeSessionKey(dapp, key)
  → verwijdert uit dapp.sessionKeys + activeSessions

Bron: kernel-sessions.ts:25-78.

6. Permission enforcement

De kernel-permissions.ts module beheert drie lagen:

  1. Manifest validatie — verplichte velden: id, name, version, entry + geldig security.tier (untrusted/verified/internal)
  2. Permission extractie — ondersteunt twee formats: string-array (["STORAGE"]) en object-array ([{type:"STORAGE"}]). Mapping via VAPI_EQUIVALENTS naar granulaire permissies
  3. Permission check — per VAPI-call: checkPermission() + permissionCovers() voor equivalente permissies

Bron: kernel-permissions.ts:25-80.

7. Stop-sequentie (12 stappen)

Bij shutdown doorloopt de orchestrator een 12-staps guarded stop-sequentie. Elke stap is best-effort: een fout in stap N breekt de rest niet.

#ReleaseBronOpgave
1releaseQRLoginServerkernel-stop-sequence.ts:29QR-login server destroy
2releaseEncryptionWorker:44Encryption worker terminate
3releaseVAPIWSServer:55VAPI WebSocket stop (poort 3008)
4releaseVFSBackends:67Elke geregistreerde VFS-backend close()
5releaseNovaVFS:84Flush pending debounced writes + stop cross-tab sync
6flushObservabilityLogs:97systemLog + securityAudit + logAggregator flush
7releasePlugins:119Plugin unregister (onKernelStop hooks)
8releaseExtensionBridge:134Extension bridge disconnect
9releaseExtensionEventBus:145Extension event listeners verwijderen
10stopVAPIHandlersregister-handlers.tsL3 ticker, netting engine, backup scheduler
11stopHeartbeatWatchdogkernel-orchestrator.tsHeartbeat watchdog stoppen
12flushDesktopStateSafekernel-stop-sequence.ts:156Desktop state flush (debounced save)
REGEL: Stop-sequentie is niet omkeerbaar. Na stop() is de orchestrator in running = false-toestand. Herinitialisatie vereist een nieuw KernelOrchestrator-instance.

8. Resource orchestrator + enforcement

De ResourceOrchestrator beheert OS-level monitoring (CPU, geheugen, process stats) met dynamische budgetten:

Bron: resource-orchestrator.ts:32-100, enforcement.ts:26-80.

9. Risico's en aanbevelingen

RisicoImpactAanbeveling
Init-stap-fout blokkeert hele kernelhoogElke stap moet fallback bieden (bv. default config bij ontbrekende service)
Stop-sequentie mist resource (dubbele call)middelIdempotente helpers (zoals nu) + guard-checks op null. Q19: Lineair houden, tree als future-note bij >20 stappen.
LockGate singleton door meerdere moduleshoogBlijf getLockGate() gebruiken, nooit eigen instantie
Memory pressure zonder emergency cleanuphoogSuspendScheduler + MemoryGuard + ProcessAutoRestart als triple safety-net
Health-check interval te langmiddelConfigurable via KernelConfig.healthCheck.intervalMs
Aanbeveling: De orchestrator-architectuur is goed gesplitst (slimme orchestrator, domme helpers). De stop-sequentie is het zwakste punt. Q19: De lineaire stop-sequentie wordt aangehouden — een dependency-tree is onnodige complexiteit voor Fase 1A. Tree/dependency-graph wordt genoteerd als future-optie bij uitbreiding van de stop-sequentie naar 20+ stappen.