@flowscripter/runtime 1.1.2 → 1.2.0

package/README.md

@@ -19,9 +19,17 @@ Add the module:
 Use the module:
 
 ```typescript
-import { world } from "@flowscripter/runtime";
+import { createRuntime } from "@flowscripter/runtime";
 
-world();
+const runtime = createRuntime({
+  config: { logLevel: "info", components: { myComponent: { retries: 3 } } },
+  logger, // optional: a plugin-api Logger
+  output, // optional: a plugin-api Output
+  onProgress: (event) => {},
+  onMetric: (event) => {},
+});
+
+runtime.updateConfig({ logLevel: "debug" });
 ```
 
 ## Development
@@ -54,12 +62,14 @@ Generate HTML API Documentation:
 
 ### Overview
 
-Sample mermaid diagram to test rendering in markdown:
+`createRuntime(options)` returns an independent runtime instance with no module-level state and no platform-specific imports, so it runs under Bun and in browsers. The host supplies an already parsed config object and the `Logger`, `Output`, progress and metric sinks defined in `@flowscripter/plugin-api`.
 
-```mermaid
-classDiagram
-    Foo <|-- Bar
-```
+- Log level comes from `config.logLevel` (`debug`, `info`, `warn`, `error`, `silent`; default `info`) and is applied by the runtime before the host logger is called.
+- `updateConfig` replaces the whole config. Listeners registered with `onConfigChange` receive the new and previous config, and only when something changed.
+- Component config is returned opaque by `getComponentConfig(handle)`; each component validates its own config.
+- Unknown top-level config keys are ignored with a single warning.
+- Failures in host supplied loggers, outputs, callbacks and listeners never propagate to the caller.
+- `runtime.context` is the `RuntimeContext` passed to components. It requires the `session`, `registry`, `datastoreManager` and `sessionManager` options.
 
 ### API
 

package/dist/index.d.ts

@@ -1,2 +1,4 @@
-export * from "./src/world.ts";
+export { createRuntime } from "./src/runtime.ts";
+export type { ConfigChangeListener, Runtime, RuntimeOptions } from "./src/runtime.ts";
+export type { RuntimeConfig } from "./src/config.ts";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,YAAY,EAAE,oBAAoB,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACtF,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -1 +1 @@
-export * from "./src/world.js";
+export { createRuntime } from "./src/runtime.js";

package/dist/src/config.d.ts

@@ -0,0 +1,18 @@
+import type { LogLevel } from "@flowscripter/plugin-api";
+export declare const LOG_LEVELS: ReadonlyArray<LogLevel>;
+export interface RuntimeConfig {
+    readonly logLevel?: LogLevel;
+    /** Opaque per-component config keyed by component handle; validated by each component. */
+    readonly components?: Readonly<Record<string, unknown>>;
+}
+export interface ResolvedConfig {
+    readonly config: Readonly<RuntimeConfig>;
+    readonly unknownKeys: ReadonlyArray<string>;
+}
+/**
+ * Validate and deep-copy a host supplied config into a deep-frozen snapshot.
+ * The input object is never retained or mutated.
+ */
+export declare function resolveConfig(input: unknown): ResolvedConfig;
+export declare function deepEqual(a: unknown, b: unknown): boolean;
+//# sourceMappingURL=config.d.ts.map

package/dist/src/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEzD,eAAO,MAAM,UAAU,EAAE,aAAa,CAAC,QAAQ,CAAgD,CAAC;AAIhG,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B,0FAA0F;IAC1F,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACzD;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,aAAa,CAAC,CAAC;IACzC,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAC7C;AAyCD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAyB5D;AAED,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAezD"}

package/dist/src/config.js

@@ -0,0 +1,82 @@
+export const LOG_LEVELS = ["debug", "info", "warn", "error", "silent"];
+const KNOWN_KEYS = ["logLevel", "components"];
+function isPlainObject(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+function copyAndFreeze(value, path, ancestors) {
+    if (value === null || typeof value === "string" || typeof value === "boolean") {
+        return value;
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new TypeError(`Config value at ${path} must be a finite number`);
+        }
+        return value;
+    }
+    if (Array.isArray(value) || isPlainObject(value)) {
+        if (ancestors.includes(value)) {
+            throw new TypeError(`Config value at ${path} is circular`);
+        }
+        ancestors.push(value);
+        let copy;
+        if (Array.isArray(value)) {
+            copy = value.map((item, i) => copyAndFreeze(item, `${path}[${i}]`, ancestors));
+        }
+        else {
+            const obj = {};
+            for (const key of Object.keys(value)) {
+                obj[key] = copyAndFreeze(value[key], `${path}.${key}`, ancestors);
+            }
+            copy = obj;
+        }
+        ancestors.pop();
+        return Object.freeze(copy);
+    }
+    throw new TypeError(`Config value at ${path} must be plain data (got ${typeof value})`);
+}
+/**
+ * Validate and deep-copy a host supplied config into a deep-frozen snapshot.
+ * The input object is never retained or mutated.
+ */
+export function resolveConfig(input) {
+    if (input === undefined) {
+        return { config: Object.freeze({}), unknownKeys: [] };
+    }
+    if (!isPlainObject(input)) {
+        throw new TypeError("Runtime config must be a plain object");
+    }
+    const { logLevel, components } = input;
+    if (logLevel !== undefined && !LOG_LEVELS.includes(logLevel)) {
+        throw new TypeError(`Invalid logLevel ${JSON.stringify(logLevel)}; allowed values: ${LOG_LEVELS.join(", ")}`);
+    }
+    if (components !== undefined && !isPlainObject(components)) {
+        throw new TypeError("Runtime config 'components' must be a plain object keyed by handle");
+    }
+    const config = {};
+    if (logLevel !== undefined) {
+        config.logLevel = logLevel;
+    }
+    if (components !== undefined) {
+        config.components = copyAndFreeze(components, "components", []);
+    }
+    const unknownKeys = Object.keys(input).filter((key) => !KNOWN_KEYS.includes(key));
+    return { config: Object.freeze(config), unknownKeys };
+}
+export function deepEqual(a, b) {
+    if (a === b) {
+        return true;
+    }
+    if (Array.isArray(a)) {
+        return Array.isArray(b) && a.length === b.length && a.every((item, i) => deepEqual(item, b[i]));
+    }
+    if (isPlainObject(a) && isPlainObject(b)) {
+        const keys = Object.keys(a);
+        return (keys.length === Object.keys(b).length &&
+            keys.every((key) => key in b && deepEqual(a[key], b[key])));
+    }
+    return false;
+}

package/dist/src/runtime.d.ts

@@ -0,0 +1,36 @@
+import type { DatastoreManager, Logger, MetricEvent, Output, ProgressEvent, Registry, RuntimeContext, Session, SessionManager } from "@flowscripter/plugin-api";
+import type { RuntimeConfig } from "./config.ts";
+export type ConfigChangeListener = (next: Readonly<RuntimeConfig>, prev: Readonly<RuntimeConfig>) => void;
+export interface RuntimeOptions {
+    /** Already parsed plain object; the runtime performs no I/O. */
+    config?: RuntimeConfig;
+    logger?: Logger;
+    output?: Output;
+    onProgress?: (event: ProgressEvent) => void;
+    onMetric?: (event: MetricEvent) => void;
+    session?: Session;
+    registry?: Registry;
+    datastoreManager?: DatastoreManager;
+    sessionManager?: SessionManager;
+}
+export interface Runtime {
+    /** Level-filtered wrapper around the injected logger. */
+    readonly logger: Logger;
+    readonly output: Output;
+    /**
+     * The context passed to components. Throws if `session`, `registry`, `datastoreManager` or
+     * `sessionManager` were not supplied in {@link RuntimeOptions}.
+     */
+    readonly context: RuntimeContext;
+    reportProgress(event: ProgressEvent): void;
+    reportMetric(event: MetricEvent): void;
+    getConfig(): Readonly<RuntimeConfig>;
+    getComponentConfig<T = unknown>(handle: string): T | undefined;
+    /** Full replacement. Throws `TypeError` on invalid config, keeping the previous config. */
+    updateConfig(next: RuntimeConfig): void;
+    /** Returns an unsubscribe function. */
+    onConfigChange(listener: ConfigChangeListener): () => void;
+    dispose(): void;
+}
+export declare function createRuntime(options?: RuntimeOptions): Runtime;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/src/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAEhB,MAAM,EAEN,WAAW,EACX,MAAM,EACN,aAAa,EACb,QAAQ,EACR,cAAc,EACd,OAAO,EACP,cAAc,EAEf,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,MAAM,oBAAoB,GAAG,CACjC,IAAI,EAAE,QAAQ,CAAC,aAAa,CAAC,EAC7B,IAAI,EAAE,QAAQ,CAAC,aAAa,CAAC,KAC1B,IAAI,CAAC;AAEV,MAAM,WAAW,cAAc;IAC7B,gEAAgE;IAChE,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IAC5C,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;IACxC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED,MAAM,WAAW,OAAO;IACtB,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IAC3C,YAAY,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IACvC,SAAS,IAAI,QAAQ,CAAC,aAAa,CAAC,CAAC;IACrC,kBAAkB,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;IAC/D,2FAA2F;IAC3F,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CAAC;IACxC,uCAAuC;IACvC,cAAc,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,IAAI,CAAC;IAC3D,OAAO,IAAI,IAAI,CAAC;CACjB;AAoBD,wBAAgB,aAAa,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAqJnE"}

package/dist/src/runtime.js

@@ -0,0 +1,165 @@
+import { deepEqual, resolveConfig } from "./config.js";
+const LEVEL_RANK = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+    silent: 4,
+};
+const DEFAULT_LOG_LEVEL = "info";
+function attempt(fn) {
+    try {
+        fn();
+    }
+    catch {
+        // failures in host supplied sinks must never break callers
+    }
+}
+export function createRuntime(options = {}) {
+    const hostLogger = options.logger;
+    const hostOutput = options.output;
+    let disposed = false;
+    let config = Object.freeze({});
+    const listeners = new Set();
+    const pending = [];
+    let notifying = false;
+    const enabled = (level) => !disposed &&
+        hostLogger !== undefined &&
+        LEVEL_RANK[level] >= LEVEL_RANK[config.logLevel ?? DEFAULT_LOG_LEVEL];
+    const logger = {
+        debug(message, fields) {
+            if (enabled("debug"))
+                attempt(() => hostLogger.debug(message, fields));
+        },
+        info(message, fields) {
+            if (enabled("info"))
+                attempt(() => hostLogger.info(message, fields));
+        },
+        warn(message, fields) {
+            if (enabled("warn"))
+                attempt(() => hostLogger.warn(message, fields));
+        },
+        error(message, fields, cause) {
+            if (enabled("error"))
+                attempt(() => hostLogger.error(message, fields, cause));
+        },
+    };
+    const output = {
+        write(value) {
+            if (!disposed && hostOutput)
+                attempt(() => hostOutput.write(value));
+        },
+    };
+    const forward = (name, callback, event) => {
+        if (disposed || !callback)
+            return;
+        try {
+            callback(event);
+        }
+        catch (cause) {
+            logger.error(`${name} callback threw`, { callback: name }, cause);
+        }
+    };
+    const warnUnknown = (unknownKeys) => {
+        if (unknownKeys.length > 0) {
+            logger.warn("Ignoring unknown runtime config keys", { keys: [...unknownKeys] });
+        }
+    };
+    const apply = (next) => {
+        const prev = config;
+        if (deepEqual(prev, next))
+            return;
+        config = next;
+        for (const listener of Array.from(listeners)) {
+            try {
+                listener(next, prev);
+            }
+            catch (cause) {
+                logger.error("Config change listener threw", { event: "configChange" }, cause);
+            }
+        }
+    };
+    const initial = resolveConfig(options.config);
+    config = initial.config;
+    warnUnknown(initial.unknownKeys);
+    let context;
+    const runtime = {
+        logger,
+        output,
+        get context() {
+            if (!context) {
+                const { session, registry, datastoreManager, sessionManager } = options;
+                const missing = [
+                    ["session", session],
+                    ["registry", registry],
+                    ["datastoreManager", datastoreManager],
+                    ["sessionManager", sessionManager],
+                ]
+                    .filter(([, value]) => value === undefined)
+                    .map(([name]) => name);
+                if (missing.length > 0) {
+                    throw new Error(`Runtime context unavailable; options not supplied: ${missing.join(", ")}`);
+                }
+                context = {
+                    logger,
+                    output,
+                    reportProgress: runtime.reportProgress,
+                    reportMetric: runtime.reportMetric,
+                    registry: registry,
+                    datastoreManager: datastoreManager,
+                    sessionManager: sessionManager,
+                    session: session,
+                };
+            }
+            return context;
+        },
+        reportProgress(event) {
+            forward("onProgress", options.onProgress, event);
+        },
+        reportMetric(event) {
+            forward("onMetric", options.onMetric, event);
+        },
+        getConfig: () => config,
+        getComponentConfig(handle) {
+            const components = config.components;
+            return components && Object.hasOwn(components, handle)
+                ? components[handle]
+                : undefined;
+        },
+        updateConfig(next) {
+            if (disposed)
+                throw new Error("Runtime is disposed");
+            const resolved = resolveConfig(next);
+            warnUnknown(resolved.unknownKeys);
+            if (notifying) {
+                pending.push(resolved.config);
+                return;
+            }
+            notifying = true;
+            try {
+                apply(resolved.config);
+                while (pending.length > 0 && !disposed) {
+                    apply(pending.shift());
+                }
+            }
+            finally {
+                pending.length = 0;
+                notifying = false;
+            }
+        },
+        onConfigChange(listener) {
+            if (disposed)
+                throw new Error("Runtime is disposed");
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        dispose() {
+            disposed = true;
+            listeners.clear();
+            pending.length = 0;
+        },
+    };
+    return runtime;
+}

package/index.ts

@@ -1 +1,3 @@
-export * from "./src/world.ts";
+export { createRuntime } from "./src/runtime.ts";
+export type { ConfigChangeListener, Runtime, RuntimeOptions } from "./src/runtime.ts";
+export type { RuntimeConfig } from "./src/config.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowscripter/runtime",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "Flowscripter runtime library",
   "keywords": [
     "bun",
@@ -38,11 +38,13 @@
     "build": "tsc -p tsconfig.build.json"
   },
   "devDependencies": {
+    "@flowscripter/plugin-api": "^2.0.0",
     "@types/bun": "^1.4.3",
-    "oxfmt": "0.73.0",
-    "oxlint": "1.88.0"
+    "oxfmt": "0.74.0",
+    "oxlint": "1.89.0"
   },
   "peerDependencies": {
+    "@flowscripter/plugin-api": "^2.0.0",
     "typescript": "^7.0.2"
   },
   "typedocOptions": {

package/src/config.ts

@@ -0,0 +1,103 @@
+import type { LogLevel } from "@flowscripter/plugin-api";
+
+export const LOG_LEVELS: ReadonlyArray<LogLevel> = ["debug", "info", "warn", "error", "silent"];
+
+const KNOWN_KEYS = ["logLevel", "components"];
+
+export interface RuntimeConfig {
+  readonly logLevel?: LogLevel;
+  /** Opaque per-component config keyed by component handle; validated by each component. */
+  readonly components?: Readonly<Record<string, unknown>>;
+}
+
+export interface ResolvedConfig {
+  readonly config: Readonly<RuntimeConfig>;
+  readonly unknownKeys: ReadonlyArray<string>;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+function copyAndFreeze(value: unknown, path: string, ancestors: unknown[]): unknown {
+  if (value === null || typeof value === "string" || typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new TypeError(`Config value at ${path} must be a finite number`);
+    }
+    return value;
+  }
+  if (Array.isArray(value) || isPlainObject(value)) {
+    if (ancestors.includes(value)) {
+      throw new TypeError(`Config value at ${path} is circular`);
+    }
+    ancestors.push(value);
+    let copy: unknown;
+    if (Array.isArray(value)) {
+      copy = value.map((item, i) => copyAndFreeze(item, `${path}[${i}]`, ancestors));
+    } else {
+      const obj: Record<string, unknown> = {};
+      for (const key of Object.keys(value)) {
+        obj[key] = copyAndFreeze(value[key], `${path}.${key}`, ancestors);
+      }
+      copy = obj;
+    }
+    ancestors.pop();
+    return Object.freeze(copy);
+  }
+  throw new TypeError(`Config value at ${path} must be plain data (got ${typeof value})`);
+}
+
+/**
+ * Validate and deep-copy a host supplied config into a deep-frozen snapshot.
+ * The input object is never retained or mutated.
+ */
+export function resolveConfig(input: unknown): ResolvedConfig {
+  if (input === undefined) {
+    return { config: Object.freeze({}), unknownKeys: [] };
+  }
+  if (!isPlainObject(input)) {
+    throw new TypeError("Runtime config must be a plain object");
+  }
+  const { logLevel, components } = input;
+  if (logLevel !== undefined && !LOG_LEVELS.includes(logLevel as LogLevel)) {
+    throw new TypeError(
+      `Invalid logLevel ${JSON.stringify(logLevel)}; allowed values: ${LOG_LEVELS.join(", ")}`,
+    );
+  }
+  if (components !== undefined && !isPlainObject(components)) {
+    throw new TypeError("Runtime config 'components' must be a plain object keyed by handle");
+  }
+  const config: { logLevel?: LogLevel; components?: Readonly<Record<string, unknown>> } = {};
+  if (logLevel !== undefined) {
+    config.logLevel = logLevel as LogLevel;
+  }
+  if (components !== undefined) {
+    config.components = copyAndFreeze(components, "components", []) as Record<string, unknown>;
+  }
+  const unknownKeys = Object.keys(input).filter((key) => !KNOWN_KEYS.includes(key));
+  return { config: Object.freeze(config), unknownKeys };
+}
+
+export function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) {
+    return true;
+  }
+  if (Array.isArray(a)) {
+    return Array.isArray(b) && a.length === b.length && a.every((item, i) => deepEqual(item, b[i]));
+  }
+  if (isPlainObject(a) && isPlainObject(b)) {
+    const keys = Object.keys(a);
+    return (
+      keys.length === Object.keys(b).length &&
+      keys.every((key) => key in b && deepEqual(a[key], b[key]))
+    );
+  }
+  return false;
+}

package/src/runtime.ts

@@ -0,0 +1,223 @@
+import type {
+  DatastoreManager,
+  LogFields,
+  Logger,
+  LogLevel,
+  MetricEvent,
+  Output,
+  ProgressEvent,
+  Registry,
+  RuntimeContext,
+  Session,
+  SessionManager,
+  StructuredValue,
+} from "@flowscripter/plugin-api";
+import { deepEqual, resolveConfig } from "./config.ts";
+import type { RuntimeConfig } from "./config.ts";
+
+export type ConfigChangeListener = (
+  next: Readonly<RuntimeConfig>,
+  prev: Readonly<RuntimeConfig>,
+) => void;
+
+export interface RuntimeOptions {
+  /** Already parsed plain object; the runtime performs no I/O. */
+  config?: RuntimeConfig;
+  logger?: Logger;
+  output?: Output;
+  onProgress?: (event: ProgressEvent) => void;
+  onMetric?: (event: MetricEvent) => void;
+  session?: Session;
+  registry?: Registry;
+  datastoreManager?: DatastoreManager;
+  sessionManager?: SessionManager;
+}
+
+export interface Runtime {
+  /** Level-filtered wrapper around the injected logger. */
+  readonly logger: Logger;
+  readonly output: Output;
+  /**
+   * The context passed to components. Throws if `session`, `registry`, `datastoreManager` or
+   * `sessionManager` were not supplied in {@link RuntimeOptions}.
+   */
+  readonly context: RuntimeContext;
+  reportProgress(event: ProgressEvent): void;
+  reportMetric(event: MetricEvent): void;
+  getConfig(): Readonly<RuntimeConfig>;
+  getComponentConfig<T = unknown>(handle: string): T | undefined;
+  /** Full replacement. Throws `TypeError` on invalid config, keeping the previous config. */
+  updateConfig(next: RuntimeConfig): void;
+  /** Returns an unsubscribe function. */
+  onConfigChange(listener: ConfigChangeListener): () => void;
+  dispose(): void;
+}
+
+const LEVEL_RANK: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+  silent: 4,
+};
+
+const DEFAULT_LOG_LEVEL: LogLevel = "info";
+
+function attempt(fn: () => void): void {
+  try {
+    fn();
+  } catch {
+    // failures in host supplied sinks must never break callers
+  }
+}
+
+export function createRuntime(options: RuntimeOptions = {}): Runtime {
+  const hostLogger = options.logger;
+  const hostOutput = options.output;
+  let disposed = false;
+  let config = Object.freeze({}) as Readonly<RuntimeConfig>;
+  const listeners = new Set<ConfigChangeListener>();
+  const pending: Readonly<RuntimeConfig>[] = [];
+  let notifying = false;
+
+  const enabled = (level: LogLevel): boolean =>
+    !disposed &&
+    hostLogger !== undefined &&
+    LEVEL_RANK[level] >= LEVEL_RANK[config.logLevel ?? DEFAULT_LOG_LEVEL];
+
+  const logger: Logger = {
+    debug(message: string | (() => string), fields?: LogFields) {
+      if (enabled("debug")) attempt(() => hostLogger!.debug(message, fields));
+    },
+    info(message: string, fields?: LogFields) {
+      if (enabled("info")) attempt(() => hostLogger!.info(message, fields));
+    },
+    warn(message: string, fields?: LogFields) {
+      if (enabled("warn")) attempt(() => hostLogger!.warn(message, fields));
+    },
+    error(message: string, fields?: LogFields, cause?: unknown) {
+      if (enabled("error")) attempt(() => hostLogger!.error(message, fields, cause));
+    },
+  };
+
+  const output: Output = {
+    write(value: string | StructuredValue) {
+      if (!disposed && hostOutput) attempt(() => hostOutput.write(value));
+    },
+  };
+
+  const forward = <E>(name: string, callback: ((event: E) => void) | undefined, event: E) => {
+    if (disposed || !callback) return;
+    try {
+      callback(event);
+    } catch (cause) {
+      logger.error(`${name} callback threw`, { callback: name }, cause);
+    }
+  };
+
+  const warnUnknown = (unknownKeys: ReadonlyArray<string>) => {
+    if (unknownKeys.length > 0) {
+      logger.warn("Ignoring unknown runtime config keys", { keys: [...unknownKeys] });
+    }
+  };
+
+  const apply = (next: Readonly<RuntimeConfig>) => {
+    const prev = config;
+    if (deepEqual(prev, next)) return;
+    config = next;
+    for (const listener of Array.from(listeners)) {
+      try {
+        listener(next, prev);
+      } catch (cause) {
+        logger.error("Config change listener threw", { event: "configChange" }, cause);
+      }
+    }
+  };
+
+  const initial = resolveConfig(options.config);
+  config = initial.config;
+  warnUnknown(initial.unknownKeys);
+
+  let context: RuntimeContext | undefined;
+
+  const runtime: Runtime = {
+    logger,
+    output,
+    get context() {
+      if (!context) {
+        const { session, registry, datastoreManager, sessionManager } = options;
+        const missing = (
+          [
+            ["session", session],
+            ["registry", registry],
+            ["datastoreManager", datastoreManager],
+            ["sessionManager", sessionManager],
+          ] as const
+        )
+          .filter(([, value]) => value === undefined)
+          .map(([name]) => name);
+        if (missing.length > 0) {
+          throw new Error(
+            `Runtime context unavailable; options not supplied: ${missing.join(", ")}`,
+          );
+        }
+        context = {
+          logger,
+          output,
+          reportProgress: runtime.reportProgress,
+          reportMetric: runtime.reportMetric,
+          registry: registry!,
+          datastoreManager: datastoreManager!,
+          sessionManager: sessionManager!,
+          session: session!,
+        };
+      }
+      return context;
+    },
+    reportProgress(event) {
+      forward("onProgress", options.onProgress, event);
+    },
+    reportMetric(event) {
+      forward("onMetric", options.onMetric, event);
+    },
+    getConfig: () => config,
+    getComponentConfig<T = unknown>(handle: string): T | undefined {
+      const components = config.components;
+      return components && Object.hasOwn(components, handle)
+        ? (components[handle] as T)
+        : undefined;
+    },
+    updateConfig(next) {
+      if (disposed) throw new Error("Runtime is disposed");
+      const resolved = resolveConfig(next);
+      warnUnknown(resolved.unknownKeys);
+      if (notifying) {
+        pending.push(resolved.config);
+        return;
+      }
+      notifying = true;
+      try {
+        apply(resolved.config);
+        while (pending.length > 0 && !disposed) {
+          apply(pending.shift()!);
+        }
+      } finally {
+        pending.length = 0;
+        notifying = false;
+      }
+    },
+    onConfigChange(listener) {
+      if (disposed) throw new Error("Runtime is disposed");
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    dispose() {
+      disposed = true;
+      listeners.clear();
+      pending.length = 0;
+    },
+  };
+  return runtime;
+}

package/dist/src/world.d.ts

@@ -1,5 +0,0 @@
-/**
- * Logs out `World`.
- */
-export declare function world(): void;
-//# sourceMappingURL=world.d.ts.map

package/dist/src/world.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"world.d.ts","sourceRoot":"","sources":["../../src/world.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,KAAK,IAAI,IAAI,CAE5B"}

package/dist/src/world.js

@@ -1,6 +0,0 @@
-/**
- * Logs out `World`.
- */
-export function world() {
-    console.info("World");
-}

package/src/world.ts

@@ -1,6 +0,0 @@
-/**
- * Logs out `World`.
- */
-export function world(): void {
-  console.info("World");
-}