browsermesh-kernel 0.1.0

package/src/index.mjs

@@ -0,0 +1,73 @@
+/**
+ * kernel — Capability-secure browser microkernel.
+ *
+ * Provides resource handles, ByteStreams, IPC, service mesh, structured
+ * tracing, chaos engineering, and tenant isolation — all with zero npm
+ * dependencies, pure ES modules.
+ *
+ * ## Quick start
+ *
+ * ```js
+ * import { Kernel, KERNEL_CAP } from 'browsermesh-kernel';
+ *
+ * const kernel = new Kernel();
+ *
+ * // Create a tenant with scoped capabilities
+ * const tenant = kernel.createTenant({
+ *   capabilities: [KERNEL_CAP.CLOCK, KERNEL_CAP.IPC, KERNEL_CAP.STDIO],
+ *   env: { MODE: 'sandbox' },
+ * });
+ *
+ * // Use kernel subsystems
+ * const handle = kernel.resources.allocate('stream', myStream, tenant.id);
+ * kernel.tracer.emit({ type: 'custom', tenant: tenant.id });
+ *
+ * // Clean up
+ * kernel.destroyTenant(tenant.id);
+ * kernel.close();
+ * ```
+ *
+ * @module kernel
+ */
+
+// Constants + errors
+export { KERNEL_DEFAULTS, KERNEL_CAP, KERNEL_ERROR } from './constants.mjs';
+export {
+  KernelError, HandleNotFoundError, HandleTypeMismatchError,
+  TableFullError, StreamClosedError, CapabilityDeniedError,
+  AlreadyRegisteredError, NotFoundError,
+} from './errors.mjs';
+
+// Resource management
+export { ResourceTable } from './resource-table.mjs';
+
+// ByteStream protocol
+export { BYTE_STREAM, isByteStream, asByteStream, createPipe, pipe, devNull, compose } from './byte-stream.mjs';
+
+// Clock + RNG
+export { Clock } from './clock.mjs';
+export { RNG } from './rng.mjs';
+
+// Capabilities
+export { buildCaps, requireCap, CapsBuilder } from './caps.mjs';
+
+// IPC
+export { KernelMessagePort, createChannel } from './message-port.mjs';
+export { ServiceRegistry } from './service-registry.mjs';
+
+// Observability
+export { Tracer } from './tracer.mjs';
+export { Logger, LOG_LEVEL } from './logger.mjs';
+
+// Chaos engineering
+export { ChaosEngine } from './chaos.mjs';
+
+// Environment
+export { Environment } from './env.mjs';
+
+// Signals + Stdio
+export { SIGNAL, SignalController } from './signal.mjs';
+export { Stdio } from './stdio.mjs';
+
+// Kernel facade
+export { Kernel } from './kernel.mjs';

package/src/kernel.mjs

@@ -0,0 +1,155 @@
+/**
+ * Kernel — top-level facade composing all kernel subsystems.
+ *
+ * Creates and wires ResourceTable, Clock, RNG, Tracer, Logger, ChaosEngine,
+ * ServiceRegistry, and SignalController. Provides tenant lifecycle management
+ * with capability-scoped access.
+ *
+ * @module kernel
+ */
+
+import { ResourceTable } from './resource-table.mjs';
+import { Clock } from './clock.mjs';
+import { RNG } from './rng.mjs';
+import { Tracer } from './tracer.mjs';
+import { Logger } from './logger.mjs';
+import { ChaosEngine } from './chaos.mjs';
+import { ServiceRegistry } from './service-registry.mjs';
+import { SignalController } from './signal.mjs';
+import { Environment } from './env.mjs';
+import { Stdio } from './stdio.mjs';
+import { buildCaps } from './caps.mjs';
+
+/**
+ * The Kernel facade. Creates and wires all subsystems.
+ */
+export class Kernel {
+  #resources;
+  #clock;
+  #rng;
+  #tracer;
+  #logger;
+  #chaos;
+  #services;
+  #signals;
+  #tenants = new Map();
+  #tenantCounter = 0;
+
+  /**
+   * @param {Object} [opts={}]
+   * @param {Object} [opts.clock] - Clock instance (defaults to real clock).
+   * @param {Object} [opts.rng] - RNG instance (defaults to crypto RNG).
+   * @param {Object} [opts.tracerOpts] - Options for Tracer constructor.
+   * @param {Object} [opts.loggerOpts] - Options for Logger constructor.
+   * @param {Object} [opts.resourceOpts] - Options for ResourceTable constructor.
+   */
+  constructor({ clock, rng, tracerOpts, loggerOpts, resourceOpts } = {}) {
+    this.#clock = clock || new Clock();
+    this.#rng = rng || new RNG();
+    this.#resources = new ResourceTable(resourceOpts);
+    this.#tracer = new Tracer({ clock: this.#clock, ...tracerOpts });
+    this.#logger = new Logger({ tracer: this.#tracer, ...loggerOpts });
+    this.#chaos = new ChaosEngine({ rng: this.#rng, clock: this.#clock });
+    this.#services = new ServiceRegistry();
+    this.#signals = new SignalController();
+  }
+
+  /** The kernel's resource table. */
+  get resources() { return this.#resources; }
+
+  /** The kernel clock. */
+  get clock() { return this.#clock; }
+
+  /** The kernel RNG. */
+  get rng() { return this.#rng; }
+
+  /** The kernel tracer. */
+  get tracer() { return this.#tracer; }
+
+  /** The kernel logger (shorthand). */
+  get log() { return this.#logger; }
+
+  /** The chaos engine. */
+  get chaos() { return this.#chaos; }
+
+  /** The service registry. */
+  get services() { return this.#services; }
+
+  /** The signal controller. */
+  get signals() { return this.#signals; }
+
+  /**
+   * Create a new tenant with scoped capabilities.
+   *
+   * @param {Object} [opts={}]
+   * @param {string[]} [opts.capabilities=[]] - KERNEL_CAP tags to grant.
+   * @param {Record<string,string>} [opts.env={}] - Tenant environment variables.
+   * @param {Object} [opts.stdio] - Tenant stdio streams ({stdin, stdout, stderr}).
+   * @returns {{ id: string, caps: Readonly<Object>, env: Environment, stdio: Stdio, signals: SignalController }}
+   */
+  createTenant({ capabilities = [], env = {}, stdio } = {}) {
+    const id = `tenant_${++this.#tenantCounter}`;
+    const caps = buildCaps(this, capabilities);
+    const tenantEnv = new Environment(env);
+    const tenantStdio = new Stdio(stdio || {});
+    const tenantSignals = new SignalController();
+
+    const tenant = { id, caps, env: tenantEnv, stdio: tenantStdio, signals: tenantSignals };
+    this.#tenants.set(id, tenant);
+
+    this.#logger.info('kernel', `Tenant created: ${id}`, { capabilities });
+
+    return tenant;
+  }
+
+  /**
+   * Destroy a tenant, dropping all owned resources.
+   *
+   * @param {string} tenantId - Tenant identifier.
+   */
+  destroyTenant(tenantId) {
+    const tenant = this.#tenants.get(tenantId);
+    if (!tenant) return;
+
+    // Drop all resources owned by this tenant
+    const handles = this.#resources.listByOwner(tenantId);
+    for (const h of handles) {
+      try { this.#resources.drop(h); } catch (_) {}
+    }
+
+    this.#tenants.delete(tenantId);
+    this.#logger.info('kernel', `Tenant destroyed: ${tenantId}`);
+  }
+
+  /**
+   * Get a tenant by ID.
+   *
+   * @param {string} tenantId - Tenant identifier.
+   * @returns {Object|undefined}
+   */
+  getTenant(tenantId) {
+    return this.#tenants.get(tenantId);
+  }
+
+  /**
+   * List all tenant IDs.
+   *
+   * @returns {string[]}
+   */
+  listTenants() {
+    return [...this.#tenants.keys()];
+  }
+
+  /**
+   * Close the kernel, destroying all tenants and clearing all subsystems.
+   */
+  close() {
+    for (const id of [...this.#tenants.keys()]) {
+      this.destroyTenant(id);
+    }
+    this.#resources.clear();
+    this.#services.clear();
+    this.#tracer.clear();
+    this.#logger.info('kernel', 'Kernel closed');
+  }
+}

package/src/logger.mjs

@@ -0,0 +1,182 @@
+/**
+ * Logger — structured per-module logging with optional Tracer integration.
+ *
+ * Provides leveled logging (DEBUG, INFO, WARN, ERROR) with module tagging.
+ * Optionally pipes entries to a Tracer for unified event streaming.
+ *
+ * @module logger
+ */
+
+import { KERNEL_DEFAULTS } from './constants.mjs';
+
+/**
+ * Log level constants.
+ */
+export const LOG_LEVEL = Object.freeze({
+  DEBUG: 0,
+  INFO: 1,
+  WARN: 2,
+  ERROR: 3,
+});
+
+/**
+ * Structured logger with per-module tagging and async iteration.
+ */
+export class Logger {
+  #entries = [];
+  #capacity;
+  #tracer;
+  #waiters = [];
+
+  /**
+   * @param {Object} [opts={}]
+   * @param {number} [opts.capacity=1024] - Maximum log entries in buffer.
+   * @param {Object} [opts.tracer] - Optional Tracer to pipe log entries to.
+   */
+  constructor({ capacity = KERNEL_DEFAULTS.DEFAULT_LOGGER_CAPACITY, tracer } = {}) {
+    this.#capacity = capacity;
+    this.#tracer = tracer || null;
+  }
+
+  /**
+   * Log a debug message.
+   * @param {string} module - Module name.
+   * @param {string} message - Log message.
+   * @param {Object} [data] - Additional data.
+   */
+  debug(module, message, data) {
+    this.#log(LOG_LEVEL.DEBUG, module, message, data);
+  }
+
+  /**
+   * Log an info message.
+   * @param {string} module - Module name.
+   * @param {string} message - Log message.
+   * @param {Object} [data] - Additional data.
+   */
+  info(module, message, data) {
+    this.#log(LOG_LEVEL.INFO, module, message, data);
+  }
+
+  /**
+   * Log a warning message.
+   * @param {string} module - Module name.
+   * @param {string} message - Log message.
+   * @param {Object} [data] - Additional data.
+   */
+  warn(module, message, data) {
+    this.#log(LOG_LEVEL.WARN, module, message, data);
+  }
+
+  /**
+   * Log an error message.
+   * @param {string} module - Module name.
+   * @param {string} message - Log message.
+   * @param {Object} [data] - Additional data.
+   */
+  error(module, message, data) {
+    this.#log(LOG_LEVEL.ERROR, module, message, data);
+  }
+
+  /**
+   * Create a scoped logger for a specific module.
+   *
+   * @param {string} name - Module name.
+   * @returns {{ debug, info, warn, error: function(string, Object=): void }}
+   */
+  forModule(name) {
+    return {
+      debug: (message, data) => this.debug(name, message, data),
+      info: (message, data) => this.info(name, message, data),
+      warn: (message, data) => this.warn(name, message, data),
+      error: (message, data) => this.error(name, message, data),
+    };
+  }
+
+  /**
+   * Get an AsyncIterable of log entries, optionally filtered.
+   *
+   * @param {Object} [opts={}]
+   * @param {string} [opts.module] - Filter by module name.
+   * @param {number} [opts.minLevel] - Minimum log level (LOG_LEVEL constant).
+   * @returns {AsyncIterable<Object>}
+   */
+  entries({ module, minLevel } = {}) {
+    const self = this;
+    let done = false;
+
+    return {
+      [Symbol.asyncIterator]() {
+        return {
+          next() {
+            if (done) return Promise.resolve({ value: undefined, done: true });
+            return new Promise(resolve => {
+              self.#waiters.push({
+                module,
+                minLevel,
+                resolve: (entry) => resolve({ value: entry, done: false }),
+              });
+            });
+          },
+          return() {
+            done = true;
+            return Promise.resolve({ value: undefined, done: true });
+          },
+        };
+      },
+    };
+  }
+
+  /**
+   * Get a snapshot of all currently buffered entries.
+   *
+   * @param {Object} [opts={}]
+   * @param {string} [opts.module] - Filter by module.
+   * @param {number} [opts.minLevel] - Minimum level.
+   * @returns {Object[]}
+   */
+  snapshot({ module, minLevel } = {}) {
+    return this.#entries.filter(e => {
+      if (module && e.module !== module) return false;
+      if (minLevel != null && e.level < minLevel) return false;
+      return true;
+    });
+  }
+
+  #log(level, module, message, data) {
+    const entry = {
+      level,
+      module,
+      message,
+      data: data || null,
+      timestamp: Date.now(),
+    };
+
+    this.#entries.push(entry);
+
+    // Evict-half strategy
+    if (this.#entries.length > this.#capacity) {
+      const half = Math.floor(this.#capacity / 2);
+      this.#entries = this.#entries.slice(-half);
+    }
+
+    // Pipe to tracer if available
+    if (this.#tracer) {
+      this.#tracer.emit({ type: 'log', ...entry });
+    }
+
+    // Notify filtered waiters
+    const matched = [];
+    const remaining = [];
+    for (const w of this.#waiters) {
+      if (w.module && w.module !== module) { remaining.push(w); continue; }
+      if (w.minLevel != null && level < w.minLevel) { remaining.push(w); continue; }
+      matched.push(w);
+    }
+    this.#waiters.length = 0;
+    this.#waiters.push(...remaining);
+    for (const w of matched) {
+      w.resolve(entry);
+    }
+  }
+}

package/src/message-port.mjs

@@ -0,0 +1,93 @@
+/**
+ * KernelMessagePort — structured IPC with FIFO ordering.
+ *
+ * Provides in-memory message passing between kernel components. Messages are
+ * dispatched asynchronously via queueMicrotask for same-realm FIFO delivery.
+ *
+ * @module message-port
+ */
+
+import { StreamClosedError } from './errors.mjs';
+
+/**
+ * A message endpoint. Part of a channel pair created by {@link createChannel}.
+ * Posting to one port delivers to the peer's listeners in FIFO order.
+ */
+export class KernelMessagePort {
+  #listeners = [];
+  #closed = false;
+  #peer = null;
+
+  /**
+   * @param {KernelMessagePort} [peer] - The peer port (set internally by createChannel).
+   * @private
+   */
+  _setPeer(peer) {
+    this.#peer = peer;
+  }
+
+  /**
+   * Post a structured message. Delivered to the **peer** port's listeners.
+   *
+   * @param {*} msg - The message payload.
+   * @param {Array} [transfers] - Optional transferable objects.
+   * @throws {StreamClosedError} If this port has been closed.
+   */
+  post(msg, transfers) {
+    if (this.#closed) throw new StreamClosedError();
+    if (!this.#peer || this.#peer.closed) return;
+    this.#peer._deliver(msg, transfers);
+  }
+
+  /**
+   * Deliver a message to this port's listeners (called by peer).
+   * @private
+   */
+  _deliver(msg, transfers) {
+    const snapshot = [...this.#listeners];
+    queueMicrotask(() => {
+      for (const cb of snapshot) {
+        try { cb(msg, transfers); } catch (_) {}
+      }
+    });
+  }
+
+  /**
+   * Register a callback to receive messages.
+   *
+   * @param {function(*, Array=): void} cb - Message handler.
+   * @returns {function(): void} Unsubscribe function.
+   */
+  onMessage(cb) {
+    this.#listeners.push(cb);
+    return () => {
+      const idx = this.#listeners.indexOf(cb);
+      if (idx >= 0) this.#listeners.splice(idx, 1);
+    };
+  }
+
+  /**
+   * Close the port. Subsequent `post` calls throw StreamClosedError.
+   */
+  close() {
+    this.#closed = true;
+    this.#listeners.length = 0;
+  }
+
+  /** Whether this port has been closed. */
+  get closed() { return this.#closed; }
+}
+
+/**
+ * Create a connected pair of KernelMessagePorts.
+ * Posting to portA delivers to portB's listeners, and vice versa.
+ *
+ * @returns {[KernelMessagePort, KernelMessagePort]}
+ */
+export function createChannel() {
+  const portA = new KernelMessagePort();
+  const portB = new KernelMessagePort();
+  portA._setPeer(portB);
+  portB._setPeer(portA);
+  return [portA, portB];
+}

package/src/resource-table.mjs

@@ -0,0 +1,164 @@
+/**
+ * ResourceTable — handle-based resource management.
+ *
+ * Provides a capability-secure resource table where every resource is accessed
+ * through an opaque string handle (`res_N`). Supports typed lookups, ownership
+ * transfer, and bounded capacity with TOCTOU-safe allocation.
+ *
+ * @module resource-table
+ */
+
+import { KERNEL_DEFAULTS } from './constants.mjs';
+import { HandleNotFoundError, HandleTypeMismatchError, TableFullError } from './errors.mjs';
+
+/**
+ * A bounded, handle-keyed resource table with ownership tracking.
+ */
+export class ResourceTable {
+  #entries = new Map();
+  #counter = 0;
+  #maxSize;
+
+  /**
+   * @param {Object} [opts={}]
+   * @param {number} [opts.maxSize=4096] - Maximum number of entries.
+   */
+  constructor({ maxSize = KERNEL_DEFAULTS.MAX_RESOURCE_TABLE_SIZE } = {}) {
+    this.#maxSize = maxSize;
+  }
+
+  /**
+   * Allocate a new handle for a resource.
+   *
+   * @param {string} type - Resource type tag (e.g. `'stream'`, `'port'`, `'socket'`).
+   * @param {*} value - The resource value.
+   * @param {string} owner - Owner identifier (e.g. tenant ID).
+   * @returns {string} The allocated handle (e.g. `'res_1'`).
+   * @throws {TableFullError} If the table is at maximum capacity.
+   */
+  allocate(type, value, owner) {
+    // TOCTOU-safe: check size immediately before insert
+    if (this.#entries.size >= this.#maxSize) {
+      throw new TableFullError(this.#maxSize);
+    }
+    const handle = `res_${++this.#counter}`;
+    this.#entries.set(handle, { type, value, owner });
+    return handle;
+  }
+
+  /**
+   * Get a resource entry by handle.
+   *
+   * @param {string} handle - The resource handle.
+   * @returns {{ type: string, value: *, owner: string }} The resource entry.
+   * @throws {HandleNotFoundError} If the handle does not exist.
+   */
+  get(handle) {
+    const entry = this.#entries.get(handle);
+    if (!entry) throw new HandleNotFoundError(handle);
+    return { type: entry.type, value: entry.value, owner: entry.owner };
+  }
+
+  /**
+   * Get a resource value by handle, verifying the expected type.
+   *
+   * @param {string} handle - The resource handle.
+   * @param {string} type - The expected resource type.
+   * @returns {*} The resource value.
+   * @throws {HandleNotFoundError} If the handle does not exist.
+   * @throws {HandleTypeMismatchError} If the resource type does not match.
+   */
+  getTyped(handle, type) {
+    const entry = this.get(handle);
+    if (entry.type !== type) {
+      throw new HandleTypeMismatchError(handle, type, entry.type);
+    }
+    return entry.value;
+  }
+
+  /**
+   * Transfer ownership of a resource to a new owner.
+   *
+   * @param {string} handle - The resource handle.
+   * @param {string} newOwner - The new owner identifier.
+   * @throws {HandleNotFoundError} If the handle does not exist.
+   */
+  transfer(handle, newOwner) {
+    const entry = this.#entries.get(handle);
+    if (!entry) throw new HandleNotFoundError(handle);
+    entry.owner = newOwner;
+  }
+
+  /**
+   * Drop (remove) a resource from the table.
+   *
+   * @param {string} handle - The resource handle to drop.
+   * @returns {*} The resource value that was removed.
+   * @throws {HandleNotFoundError} If the handle does not exist.
+   */
+  drop(handle) {
+    const entry = this.#entries.get(handle);
+    if (!entry) throw new HandleNotFoundError(handle);
+    this.#entries.delete(handle);
+    return entry.value;
+  }
+
+  /**
+   * Check whether a handle exists in the table.
+   *
+   * @param {string} handle - The resource handle.
+   * @returns {boolean}
+   */
+  has(handle) {
+    return this.#entries.has(handle);
+  }
+
+  /**
+   * List all handles owned by a given owner.
+   *
+   * @param {string} owner - The owner identifier.
+   * @returns {string[]} Array of handles owned by the owner.
+   */
+  listByOwner(owner) {
+    const result = [];
+    for (const [handle, entry] of this.#entries) {
+      if (entry.owner === owner) result.push(handle);
+    }
+    return result;
+  }
+
+  /**
+   * List all handles of a given type.
+   *
+   * @param {string} type - The resource type tag.
+   * @returns {string[]} Array of handles of the given type.
+   */
+  listByType(type) {
+    const result = [];
+    for (const [handle, entry] of this.#entries) {
+      if (entry.type === type) result.push(handle);
+    }
+    return result;
+  }
+
+  /**
+   * List all handles in the table.
+   *
+   * @returns {string[]} Array of all allocated handles.
+   */
+  listAll() {
+    return [...this.#entries.keys()];
+  }
+
+  /** Current number of entries. */
+  get size() {
+    return this.#entries.size;
+  }
+
+  /**
+   * Remove all entries from the table.
+   */
+  clear() {
+    this.#entries.clear();
+  }
+}