memwarden 0.0.1

package/dist/kernel/http.js

@@ -0,0 +1,261 @@
+//
+// The kernel's HTTP front door. A node:http server that matches
+// registered `type:"http"` routes by method + path, parses the JSON
+// body into `req.body`, runs the middleware chain, invokes the bound
+// function, and serializes its `{status_code, headers?, body}` return.
+// Answers CORS preflight per the configured origins.
+import { createServer } from "node:http";
+import { URL } from "node:url";
+const DEFAULT_ORIGINS = [
+    "http://localhost:3111",
+    "http://localhost:3113",
+    "http://127.0.0.1:3111",
+    "http://127.0.0.1:3113",
+];
+const ALLOWED_METHODS = "GET,POST,PUT,DELETE,OPTIONS";
+const ALLOWED_HEADERS = "Content-Type,Authorization";
+const DEFAULT_MAX_BODY = 16 * 1024 * 1024;
+export function startHttpServer(kernel, opts) {
+    const host = opts.host ?? "127.0.0.1";
+    const allowedOrigins = opts.allowedOrigins ?? DEFAULT_ORIGINS;
+    const maxBodyBytes = opts.maxBodyBytes ?? DEFAULT_MAX_BODY;
+    // Index routes by `METHOD path` for O(1) exact-match lookup.
+    const routeIndex = new Map();
+    for (const route of kernel.getHttpRoutes()) {
+        routeIndex.set(routeKey(route.method, route.path), route);
+    }
+    const server = createServer((req, res) => {
+        handleRequest(req, res, kernel, routeIndex, {
+            allowedOrigins,
+            maxBodyBytes,
+        }).catch((err) => {
+            // Last-resort guard: never let a handler throw take down the
+            // connection without a response.
+            if (!res.headersSent) {
+                sendJson(res, 500, undefined, {
+                    error: "internal",
+                    message: err instanceof Error ? err.message : String(err),
+                });
+            }
+        });
+    });
+    server.listen(opts.port, host);
+    return {
+        server,
+        port: opts.port,
+        close: () => new Promise((resolve) => {
+            server.close(() => resolve());
+        }),
+    };
+}
+async function handleRequest(req, res, kernel, routeIndex, cfg) {
+    const origin = req.headers.origin;
+    applyCors(res, origin, cfg.allowedOrigins);
+    const method = (req.method ?? "GET").toUpperCase();
+    // DNS-rebinding firewall: only serve requests whose Host header is a
+    // loopback host bound to our actual listening port. A malicious webpage can
+    // rebind its hostname's DNS to 127.0.0.1, but the browser still sends the
+    // page's own hostname in Host — so a non-loopback Host means the request did
+    // not originate from a local client. We compare the Host port against the
+    // socket's local port (handles ephemeral `port: 0` correctly). This runs
+    // BEFORE CORS-exempt routes and before any body is read, so it also blocks
+    // whole-brain exfil via GET /memwarden/export. Applies to every method incl.
+    // OPTIONS.
+    const localPort = req.socket.localPort;
+    if (!isLoopbackHost(req.headers.host, localPort)) {
+        sendJson(res, 403, undefined, { error: "forbidden_host" });
+        return;
+    }
+    // CORS preflight.
+    if (method === "OPTIONS") {
+        res.statusCode = 204;
+        res.end();
+        return;
+    }
+    const url = new URL(req.url ?? "/", "http://localhost");
+    const pathname = url.pathname;
+    const route = routeIndex.get(routeKey(method, pathname));
+    if (!route) {
+        sendJson(res, 404, undefined, { error: "not_found", path: pathname });
+        return;
+    }
+    // Require JSON for body-bearing methods BEFORE parsing. A cross-origin
+    // text/plain POST is a "simple request" that skips the CORS preflight, so
+    // without this a webpage could POST to /observe or /import (memory
+    // poisoning). Demanding application/json forces a preflight the browser
+    // will block. Bodyless POST/PUT (e.g. action triggers) still pass.
+    if (method === "POST" || method === "PUT") {
+        if (hasRequestBody(req) && !isJsonContentType(req.headers["content-type"])) {
+            sendJson(res, 415, undefined, {
+                error: "unsupported_media_type",
+                message: "Content-Type must be application/json",
+            });
+            return;
+        }
+    }
+    const headers = normalizeHeaders(req.headers);
+    const queryParams = queryToRecord(url);
+    // Middleware chain (auth). Short-circuits on `respond`.
+    const short = await kernel.runMiddleware(route.middlewareFunctionIds, headers);
+    if (short) {
+        sendJson(res, short.status_code, undefined, short.body);
+        return;
+    }
+    // Parse the JSON body for methods that carry one.
+    let body;
+    if (method === "POST" || method === "PUT" || method === "DELETE") {
+        const parsed = await readJsonBody(req, cfg.maxBodyBytes);
+        if (parsed.error) {
+            sendJson(res, parsed.status, undefined, { error: parsed.error });
+            return;
+        }
+        body = parsed.value;
+    }
+    const apiRequest = { headers, query_params: queryParams };
+    if (body !== undefined)
+        apiRequest.body = body;
+    const response = await kernel.invokeHttp(route.functionId, apiRequest);
+    sendJson(res, response.status_code, response.headers, response.body);
+}
+// --- helpers --------------------------------------------------------
+function routeKey(method, path) {
+    return `${method} ${path}`;
+}
+/**
+ * Accept only a loopback Host header bound to our port (or with no port). The
+ * Host header is case-insensitive and may carry `:port` or be a bracketed IPv6
+ * literal; we split host/port robustly and reject anything non-loopback. This
+ * is the DNS-rebinding guard: the value reflects the hostname the client
+ * actually targeted, which a rebinding attacker cannot forge to "localhost".
+ */
+export function isLoopbackHost(hostHeader, port) {
+    if (typeof hostHeader !== "string" || hostHeader.trim() === "")
+        return false;
+    const raw = hostHeader.trim();
+    let hostname;
+    let portPart;
+    if (raw.startsWith("[")) {
+        // Bracketed IPv6: [::1] or [::1]:3111
+        const close = raw.indexOf("]");
+        if (close === -1)
+            return false;
+        hostname = raw.slice(1, close);
+        const after = raw.slice(close + 1);
+        portPart = after.startsWith(":") ? after.slice(1) : after || undefined;
+    }
+    else {
+        const idx = raw.lastIndexOf(":");
+        if (idx === -1) {
+            hostname = raw;
+        }
+        else {
+            hostname = raw.slice(0, idx);
+            portPart = raw.slice(idx + 1);
+        }
+    }
+    const h = hostname.toLowerCase();
+    const loopback = h === "localhost" || h === "::1" || h === "127.0.0.1" || /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(h);
+    if (!loopback)
+        return false;
+    // A present port must match ours; absent port is allowed. If we can't
+    // determine our own port (port undefined), accept any numeric port on a
+    // loopback hostname — the hostname check already carries the guarantee.
+    if (portPart !== undefined && portPart !== "") {
+        if (!/^\d+$/.test(portPart))
+            return false;
+        if (port !== undefined && Number(portPart) !== port)
+            return false;
+    }
+    return true;
+}
+function isJsonContentType(contentType) {
+    if (typeof contentType !== "string")
+        return false;
+    // Strip any parameters (charset, boundary) and lowercase the media type.
+    const media = contentType.split(";")[0]?.trim().toLowerCase() ?? "";
+    return media === "application/json";
+}
+// A request carries a body if it advertises one. Bodyless POST/PUT (no
+// content-length, no chunked transfer-encoding) are exempt from the
+// content-type requirement.
+function hasRequestBody(req) {
+    const len = req.headers["content-length"];
+    if (typeof len === "string" && /^\d+$/.test(len) && Number(len) > 0)
+        return true;
+    const te = req.headers["transfer-encoding"];
+    if (typeof te === "string" && te.toLowerCase().includes("chunked"))
+        return true;
+    return false;
+}
+function applyCors(res, origin, allowedOrigins) {
+    if (origin && allowedOrigins.includes(origin)) {
+        res.setHeader("Access-Control-Allow-Origin", origin);
+    }
+    res.setHeader("Access-Control-Allow-Methods", ALLOWED_METHODS);
+    res.setHeader("Access-Control-Allow-Headers", ALLOWED_HEADERS);
+    res.setHeader("Vary", "Origin");
+}
+function normalizeHeaders(raw) {
+    const out = {};
+    for (const [k, v] of Object.entries(raw)) {
+        out[k] = Array.isArray(v) ? v.join(", ") : v;
+    }
+    return out;
+}
+function queryToRecord(url) {
+    const out = {};
+    for (const [k, v] of url.searchParams)
+        out[k] = v;
+    return out;
+}
+function readJsonBody(req, maxBytes) {
+    return new Promise((resolve) => {
+        const chunks = [];
+        let total = 0;
+        let aborted = false;
+        req.on("data", (chunk) => {
+            if (aborted)
+                return;
+            total += chunk.length;
+            if (total > maxBytes) {
+                aborted = true;
+                resolve({ error: "payload_too_large", status: 413 });
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => {
+            if (aborted)
+                return;
+            if (chunks.length === 0) {
+                resolve({ value: {}, status: 200 });
+                return;
+            }
+            const text = Buffer.concat(chunks).toString("utf-8").trim();
+            if (!text) {
+                resolve({ value: {}, status: 200 });
+                return;
+            }
+            try {
+                resolve({ value: JSON.parse(text), status: 200 });
+            }
+            catch {
+                resolve({ error: "invalid_json", status: 400 });
+            }
+        });
+        req.on("error", () => {
+            if (!aborted)
+                resolve({ error: "request_error", status: 400 });
+        });
+    });
+}
+function sendJson(res, status, headers, body) {
+    if (headers) {
+        for (const [k, v] of Object.entries(headers))
+            res.setHeader(k, v);
+    }
+    res.setHeader("Content-Type", "application/json");
+    res.statusCode = status;
+    res.end(JSON.stringify(body ?? null));
+}

package/dist/kernel/index.d.ts

@@ -0,0 +1,19 @@
+import type { VoidAction } from "./types.js";
+export { registerWorker, Kernel, __resetKernelSingleton } from "./kernel.js";
+export type { HttpRoute, KernelOptions } from "./kernel.js";
+export { startHttpServer } from "./http.js";
+export type { HttpServerOptions, RunningHttpServer } from "./http.js";
+export { PubSub } from "./pubsub.js";
+export type { StreamItem } from "./pubsub.js";
+export { TriggerError } from "./types.js";
+export type { ApiRequest, ApiResponse, ConnectionStateListener, Counter, FunctionHandler, Histogram, HttpMethod, ISdk, Meter, MiddlewareResult, RegisterWorkerOptions, StateChangeEvent, TriggerConfig, TriggerOptions, VoidAction, } from "./types.js";
+/**
+ * Fire-and-forget trigger sentinel. App code does
+ * `import { TriggerAction } from "<kernel>"` and calls
+ * `TriggerAction.Void()` to mark a trigger whose result is not awaited.
+ * `trigger` recognizes the `{ __void: true }` sentinel and swallows any
+ * rejection so a fire-and-forget failure never crashes the process.
+ */
+export declare const TriggerAction: {
+    readonly Void: () => VoidAction;
+};

package/dist/kernel/index.js

@@ -0,0 +1,21 @@
+//
+// Public barrel for the memwarden kernel. This is the module that
+// is the in-process runtime app code builds against: it exports the
+// `registerWorker` factory, the `TriggerAction` value, and the
+// `ISdk` / `ApiRequest` types the call sites import.
+export { registerWorker, Kernel, __resetKernelSingleton } from "./kernel.js";
+export { startHttpServer } from "./http.js";
+export { PubSub } from "./pubsub.js";
+export { TriggerError } from "./types.js";
+/**
+ * Fire-and-forget trigger sentinel. App code does
+ * `import { TriggerAction } from "<kernel>"` and calls
+ * `TriggerAction.Void()` to mark a trigger whose result is not awaited.
+ * `trigger` recognizes the `{ __void: true }` sentinel and swallows any
+ * rejection so a fire-and-forget failure never crashes the process.
+ */
+export const TriggerAction = {
+    Void() {
+        return { __void: true };
+    },
+};

package/dist/kernel/kernel.d.ts

@@ -0,0 +1,80 @@
+import { type ApiResponse, type ConnectionStateListener, type FunctionHandler, type HttpMethod, type ISdk, type Meter, type RegisterWorkerOptions, type TriggerConfig, type TriggerOptions } from "./types.js";
+import { PubSub } from "./pubsub.js";
+import type { StateStore } from "../state/store.js";
+/** A resolved HTTP route the server can dispatch against. */
+export interface HttpRoute {
+    method: HttpMethod;
+    path: string;
+    functionId: string;
+    middlewareFunctionIds: string[];
+}
+export interface KernelOptions {
+    /**
+     * The persistence store the five `state::*` ids route to. Defaults to
+     * an in-memory StoreMemory; the boot path injects a durable
+     * StoreLibsql.
+     */
+    store?: StateStore;
+}
+export declare class Kernel implements ISdk {
+    readonly workerName: string;
+    private readonly functions;
+    private readonly httpRoutes;
+    private readonly stateTriggers;
+    private readonly connectionStateListeners;
+    private readonly store;
+    private readonly unsubscribeMutations;
+    private readonly pubsub;
+    private shuttingDown;
+    private lastSwallowedLogAt;
+    constructor(opts: RegisterWorkerOptions, kernelOpts?: KernelOptions);
+    registerFunction(id: string, handler: FunctionHandler): void;
+    registerTrigger(cfg: TriggerConfig): void;
+    on(event: "connection_state", cb: ConnectionStateListener): void;
+    getMeter(_name: string): Meter;
+    trigger<P = any, R = any>(opts: TriggerOptions<P>): Promise<R>;
+    /**
+     * Resolve a function_id to a result. Built-in ids are routed here
+     * before consulting the app registry. Unregistered ids reject with a
+     * TriggerError carrying { code, function_id, message }.
+     */
+    private invoke;
+    /**
+     * Route engine-provided built-ins: the five `state::*` ops, the
+     * `stream::*` surface, and `engine::workers::list`. Returns the
+     * sentinel NOT_BUILTIN for everything else. State-change events are
+     * emitted by the store (via onMutation), not here, so set/update/delete
+     * stay a single store call.
+     */
+    private routeBuiltin;
+    /**
+     * Fan a store mutation event out to any `type:"state"` trigger bound
+     * to that scope. The original only ever subscribed `KV.sessions`, but
+     * this generically dispatches for any subscribed scope.
+     */
+    private dispatchStateChange;
+    /** Snapshot of registered HTTP routes. */
+    getHttpRoutes(): readonly HttpRoute[];
+    /**
+     * Run an ordered middleware chain. Returns the short-circuit response
+     * if any middleware responds, else null to proceed.
+     */
+    runMiddleware(middlewareFunctionIds: string[], headers: Record<string, string | undefined>): Promise<{
+        status_code: number;
+        body: unknown;
+    } | null>;
+    /** Invoke an HTTP-bound function and return its ApiResponse. */
+    invokeHttp(functionId: string, request: {
+        body?: unknown;
+        headers?: Record<string, string | undefined>;
+        query_params?: Record<string, string>;
+    }): Promise<ApiResponse>;
+    get streams(): PubSub;
+    /** The underlying state store (exposed for StateKV construction etc.). */
+    get stateStore(): StateStore;
+    shutdown(): Promise<void>;
+    private logSwallowed;
+}
+export declare function registerWorker(_engineUrl: string, opts: RegisterWorkerOptions, kernelOpts?: KernelOptions): Kernel;
+/** Test helper: drop the singleton so a fresh kernel can be built. */
+export declare function __resetKernelSingleton(): void;

package/dist/kernel/kernel.js

@@ -0,0 +1,297 @@
+//
+// The memwarden kernel: an in-process worker runtime
+// worker runtime. It owns
+// - the function registry (Map<id, handler>),
+// - the single `trigger` dispatch chokepoint (including the built-in
+// `state::*`, `stream::*`, and `engine::workers::list` ids that the
+// engine, not app code, used to provide),
+// - `registerTrigger` wiring to HTTP / durable-subscriber / state
+// surfaces,
+// - the optional `on("connection_state")` and `getMeter` shims,
+// - the `shutdown` lifecycle.
+//
+// Persistence lives behind the STATE layer's `StateStore` abstraction
+// (../state/store.ts). The kernel routes the five `state::*`
+// function_ids to that store and drives any registered `type:"state"`
+// trigger from the store's mutation events. The kernel does NOT carry
+// its own KV implementation.
+//
+// HTTP serving is delegated to the router in ./http.ts; the kernel just
+// collects route registrations and exposes them.
+import { TriggerError, } from "./types.js";
+import { PubSub } from "./pubsub.js";
+import { StoreMemory } from "../state/store-memory.js";
+const NOOP_METER = {
+    createCounter: () => ({ add: () => { } }),
+    createHistogram: () => ({ record: () => { } }),
+};
+export class Kernel {
+    workerName;
+    functions = new Map();
+    httpRoutes = [];
+    stateTriggers = new Map(); // scope -> functionIds
+    connectionStateListeners = [];
+    store;
+    unsubscribeMutations;
+    pubsub = new PubSub();
+    shuttingDown = false;
+    lastSwallowedLogAt = 0;
+    constructor(opts, kernelOpts = {}) {
+        this.workerName = opts.workerName;
+        this.store = kernelOpts.store ?? new StoreMemory();
+        // Drive registered type:"state" triggers from the store's mutation
+        // events. The store emits {scope, key, event_type, old/new_value};
+        // we fan it out to any function bound to that scope.
+        this.unsubscribeMutations = this.store.onMutation((event) => this.dispatchStateChange(event));
+    }
+    // --- registration -------------------------------------------------
+    registerFunction(id, handler) {
+        // Last-write-wins; ids are unique in practice.
+        this.functions.set(id, handler);
+    }
+    registerTrigger(cfg) {
+        switch (cfg.type) {
+            case "http": {
+                this.httpRoutes.push({
+                    method: cfg.config.http_method,
+                    path: cfg.config.api_path,
+                    functionId: cfg.function_id,
+                    middlewareFunctionIds: cfg.config.middleware_function_ids ?? [],
+                });
+                break;
+            }
+            case "durable:subscriber": {
+                const fnId = cfg.function_id;
+                this.pubsub.subscribe(cfg.config.topic, (payload) => {
+                    // Subscriber invocation is fire-and-forget; never crash.
+                    void this.invoke(fnId, payload).catch((err) => this.logSwallowed("durable:subscriber", fnId, err));
+                });
+                break;
+            }
+            case "state": {
+                const list = this.stateTriggers.get(cfg.config.scope) ?? [];
+                list.push(cfg.function_id);
+                this.stateTriggers.set(cfg.config.scope, list);
+                break;
+            }
+        }
+    }
+    on(event, cb) {
+        if (event === "connection_state") {
+            this.connectionStateListeners.push(cb);
+            // In-process kernel is "connected" the moment it exists. Fire on
+            // the next tick so listeners registered synchronously after
+            // construction still observe it.
+            queueMicrotask(() => cb("connected"));
+        }
+    }
+    getMeter(_name) {
+        // No real OTel transport in-process; hand back no-op instruments.
+        // The boot path feature-detects this and falls back to NOOP anyway,
+        // but providing it keeps the call site identical.
+        return NOOP_METER;
+    }
+    // --- dispatch -----------------------------------------------------
+    async trigger(opts) {
+        const isVoid = !!opts.action?.__void;
+        if (isVoid) {
+            // Fire-and-forget: never reject toward the caller (many call
+            // sites invoke without await, as a bare statement). Run the
+            // handler and swallow/log any rejection.
+            void this.invoke(opts.function_id, opts.payload).catch((err) => this.logSwallowed("trigger:void", opts.function_id, err));
+            return undefined;
+        }
+        return this.invoke(opts.function_id, opts.payload);
+    }
+    /**
+     * Resolve a function_id to a result. Built-in ids are routed here
+     * before consulting the app registry. Unregistered ids reject with a
+     * TriggerError carrying { code, function_id, message }.
+     */
+    async invoke(functionId, payload) {
+        const builtin = await this.routeBuiltin(functionId, payload);
+        if (builtin !== NOT_BUILTIN)
+            return builtin;
+        const handler = this.functions.get(functionId);
+        if (!handler) {
+            throw new TriggerError(`No function registered for "${functionId}"`, "FUNCTION_NOT_FOUND", functionId);
+        }
+        return (await handler(payload));
+    }
+    /**
+     * Route engine-provided built-ins: the five `state::*` ops, the
+     * `stream::*` surface, and `engine::workers::list`. Returns the
+     * sentinel NOT_BUILTIN for everything else. State-change events are
+     * emitted by the store (via onMutation), not here, so set/update/delete
+     * stay a single store call.
+     */
+    async routeBuiltin(functionId, payload) {
+        switch (functionId) {
+            case "state::get": {
+                const p = payload;
+                return (await this.store.get(p.scope, p.key));
+            }
+            case "state::set": {
+                const p = payload;
+                return (await this.store.set(p.scope, p.key, p.value));
+            }
+            case "state::update": {
+                const p = payload;
+                return (await this.store.update(p.scope, p.key, p.ops));
+            }
+            case "state::delete": {
+                const p = payload;
+                await this.store.delete(p.scope, p.key);
+                return undefined;
+            }
+            case "state::list": {
+                const p = payload;
+                return (await this.store.list(p.scope));
+            }
+            case "state::verify": {
+                // Tamper-evidence: verify the whole oplog hash chain. Read-only.
+                return (await this.store.verifyOplog());
+            }
+            case "state::oplog-count": {
+                const entries = await this.store.readOplog();
+                return { count: entries.length };
+            }
+            case "state::oplog-find": {
+                // Chain evidence for one key (delete receipts). Payloads are
+                // STRIPPED — a receipt proves an entry existed in the chain without
+                // re-disclosing the content that was just deleted.
+                const p = payload;
+                const entries = await this.store.readOplog();
+                const matches = entries
+                    .filter((e) => e.key === p.key)
+                    .map((e) => ({
+                    id: e.id,
+                    ts: e.ts,
+                    op: e.op,
+                    scope: e.scope,
+                    key: e.key,
+                    hash: e.hash,
+                    prev_hash: e.prev_hash,
+                }));
+                return { entries: matches };
+            }
+            case "stream::set":
+            case "stream::send": {
+                // Live-viewer surface. Best-effort fan-out to in-process
+                // listeners; no durable backing.
+                this.pubsub.emitStream(payload ?? {});
+                return undefined;
+            }
+            case "engine::workers::list": {
+                // Engine-internal in the original; the kernel is the only
+                // worker. Health monitor reads `.workers`.
+                return { workers: [] };
+            }
+            default:
+                return NOT_BUILTIN;
+        }
+    }
+    /**
+     * Fan a store mutation event out to any `type:"state"` trigger bound
+     * to that scope. The original only ever subscribed `KV.sessions`, but
+     * this generically dispatches for any subscribed scope.
+     */
+    dispatchStateChange(event) {
+        const fnIds = this.stateTriggers.get(event.scope);
+        if (!fnIds || fnIds.length === 0)
+            return;
+        const payload = {
+            key: event.key,
+            event_type: event.event_type,
+            ...(event.old_value !== undefined ? { old_value: event.old_value } : {}),
+            ...(event.new_value !== undefined ? { new_value: event.new_value } : {}),
+        };
+        for (const fnId of fnIds) {
+            // State-change handlers are fire-and-forget side effects.
+            void this.invoke(fnId, payload).catch((err) => this.logSwallowed("state-change", fnId, err));
+        }
+    }
+    // --- HTTP surface (consumed by ./http.ts) -------------------------
+    /** Snapshot of registered HTTP routes. */
+    getHttpRoutes() {
+        return this.httpRoutes;
+    }
+    /**
+     * Run an ordered middleware chain. Returns the short-circuit response
+     * if any middleware responds, else null to proceed.
+     */
+    async runMiddleware(middlewareFunctionIds, headers) {
+        for (const id of middlewareFunctionIds) {
+            const handler = this.functions.get(id);
+            if (!handler)
+                continue; // Missing middleware = open (no-op).
+            const result = (await handler({ request: { headers } }));
+            if (result && result.action === "respond") {
+                return result.response;
+            }
+        }
+        return null;
+    }
+    /** Invoke an HTTP-bound function and return its ApiResponse. */
+    async invokeHttp(functionId, request) {
+        const handler = this.functions.get(functionId);
+        if (!handler) {
+            return {
+                status_code: 500,
+                body: { error: `No handler for ${functionId}` },
+            };
+        }
+        return (await handler(request));
+    }
+    // --- pub/sub passthrough (for the viewer / external wiring) -------
+    get streams() {
+        return this.pubsub;
+    }
+    /** The underlying state store (exposed for StateKV construction etc.). */
+    get stateStore() {
+        return this.store;
+    }
+    // --- lifecycle ----------------------------------------------------
+    async shutdown() {
+        if (this.shuttingDown)
+            return;
+        this.shuttingDown = true;
+        this.unsubscribeMutations();
+        for (const cb of this.connectionStateListeners) {
+            try {
+                cb("disconnected");
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        await this.store.close().catch(() => undefined);
+    }
+    // --- internals ----------------------------------------------------
+    logSwallowed(context, functionId, err) {
+        const now = Date.now();
+        // Throttle to avoid spamming on bursts of fire-and-forget failures.
+        if (now - this.lastSwallowedLogAt < 60_000)
+            return;
+        this.lastSwallowedLogAt = now;
+        const message = err instanceof Error ? err.message : String(err);
+        console.warn(`[memwarden] swallowed ${context} rejection (${functionId}): ${message}`);
+    }
+}
+const NOT_BUILTIN = Symbol("not-builtin");
+/**
+ * Factory matching the daemon factory entrypoint. The kernel is a
+ * process singleton: repeated calls return the same instance so every
+ * module that imports `registerWorker` shares one registry + store.
+ */
+let singleton = null;
+export function registerWorker(_engineUrl, opts, kernelOpts) {
+    if (!singleton) {
+        singleton = new Kernel(opts, kernelOpts ?? {});
+    }
+    return singleton;
+}
+/** Test helper: drop the singleton so a fresh kernel can be built. */
+export function __resetKernelSingleton() {
+    singleton = null;
+}