@nomix-ai/nomix-harness 0.2.4 → 0.2.6

package/dist/kernel/cordis/lib/types/registry.js

@@ -0,0 +1,218 @@
+import { defineProperty } from '../../../cosmokit/lib/index.js';
+import { Fiber } from "./fiber.js";
+import { buildOuterStack, DisposableList, symbols, withProps } from "./utils.js";
+function isApplicable(object) {
+    return object && typeof object === 'object' && typeof object.apply === 'function';
+}
+/**
+ * Decorator for declaring service dependencies on classes or class methods.
+ *
+ * On classes it contributes to the plugin's static `inject` map. On methods it
+ * delays the method call until the declared services are available.
+ */
+/**
+ * @param name — the required service name.
+ * @param config — optional intercept config applied for that service.
+ * @returns the class or method decorator.
+ */
+export function Inject(name, config) {
+    return function (value, decorator) {
+        if (decorator.kind === 'class') {
+            if (!Object.hasOwn(value, 'inject')) {
+                defineProperty(value, 'inject', Object.create(Object.getPrototypeOf(value).inject ?? null));
+                defineProperty(value.inject, symbols.checkProto, true);
+            }
+            value.inject[name] = config;
+        }
+        else if (decorator.kind === 'method') {
+            const inject = (value[symbols.metadata] ??= {}).inject ??= Object.create(null);
+            inject[name] = config;
+            decorator.addInitializer(function () {
+                const property = this[symbols.tracker]?.property;
+                (this[symbols.initHooks] ??= []).push(() => {
+                    this.ctx.inject(inject, (ctx) => {
+                        return value.call(property ? withProps(this, { [property]: ctx }) : this);
+                    });
+                });
+            });
+        }
+        else {
+            throw new Error('@Inject() can only be used on class or class methods');
+        }
+    };
+}
+/** Utilities for normalizing plugin dependency declarations. */
+(function (Inject) {
+    /**
+     * Convert array/object/class-inherited inject metadata into a plain map.
+     *
+     * @param inject — the declaration to normalize; `null`/`undefined` add nothing.
+     * @param result — the map to fill (service name → intercept config or `null`).
+     * @returns `result`.
+     */
+    function resolve(inject, result = Object.create(null)) {
+        if (!inject)
+            return result;
+        if (Array.isArray(inject)) {
+            for (const name of inject) {
+                result[name] = null;
+            }
+        }
+        else if (Reflect.has(inject, symbols.checkProto)) {
+            Object.assign(result, resolve(Object.getPrototypeOf(inject)));
+            for (const name of Object.keys(inject)) {
+                result[name] = inject[name] ?? null;
+            }
+        }
+        else {
+            for (const name of Object.keys(inject)) {
+                result[name] = inject[name] ?? null;
+            }
+        }
+        return result;
+    }
+    Inject.resolve = resolve;
+})(Inject || (Inject = {}));
+/**
+ * Plugin registry installed as `ctx.registry` and mixed into every context.
+ *
+ * It normalizes plugin shapes, tracks plugin runtimes, starts fibers, and
+ * exposes map-like inspection over active plugin callbacks.
+ */
+export class RegistryService {
+    ctx;
+    _counter = 0;
+    _internal = new Map();
+    constructor(ctx) {
+        this.ctx = ctx;
+        defineProperty(this, symbols.tracker, {
+            property: 'ctx',
+            noShadow: true,
+        });
+    }
+    /** Allocate the next fiber uid (increments on every read). */
+    get counter() {
+        return ++this._counter;
+    }
+    /** Number of registered plugin runtimes. */
+    get size() {
+        return this._internal.size;
+    }
+    /**
+     * Resolve a supported plugin shape to its executable callback.
+     *
+     * @param plugin — a function, class, or `{ apply }` object plugin.
+     * @returns the callback identifying the plugin, or `undefined` if invalid.
+     */
+    resolve(plugin) {
+        // plugin.apply may throw
+        try {
+            if (typeof plugin === 'function')
+                return plugin;
+            if (isApplicable(plugin))
+                return plugin.apply;
+        }
+        catch { }
+    }
+    /**
+     * Look up the runtime record for a plugin.
+     *
+     * @param plugin — any supported plugin shape.
+     * @returns the runtime, or `undefined` when the plugin is not registered.
+     */
+    get(plugin) {
+        const key = this.resolve(plugin);
+        return key && this._internal.get(key);
+    }
+    /**
+     * Check whether a plugin has a registered runtime.
+     *
+     * @param plugin — any supported plugin shape.
+     * @returns `true` when at least one fiber of the plugin exists.
+     */
+    has(plugin) {
+        const key = this.resolve(plugin);
+        return !!key && this._internal.has(key);
+    }
+    /**
+     * Dispose every running fiber for a plugin and remove its runtime record.
+     *
+     * @param plugin — any supported plugin shape.
+     * @returns the removed runtime, or `undefined` when none was registered.
+     */
+    delete(plugin) {
+        const key = this.resolve(plugin);
+        const runtime = key && this._internal.get(key);
+        if (!runtime)
+            return;
+        this._internal.delete(key);
+        for (const fiber of runtime.fibers) {
+            fiber.dispose();
+        }
+        return runtime;
+    }
+    /** Iterate the registered plugin callbacks. */
+    keys() {
+        return this._internal.keys();
+    }
+    /** Iterate the registered plugin runtimes. */
+    values() {
+        return this._internal.values();
+    }
+    /** Iterate `[callback, runtime]` pairs. */
+    entries() {
+        return this._internal.entries();
+    }
+    /**
+     * Visit every registered runtime.
+     *
+     * @param callback — receives each runtime and its identifying callback.
+     */
+    forEach(callback) {
+        return this._internal.forEach(callback);
+    }
+    /**
+     * Start a callback once the requested dependencies are available.
+     *
+     * @param inject — required services, as an array or a name → config map.
+     * @param callback — plugin body called with `(ctx, config)`.
+     * @returns the fiber; awaiting it settles once loading finished.
+     */
+    inject(inject, callback) {
+        return this.plugin({ inject, apply: callback, name: callback.name });
+    }
+    /**
+     * Start a plugin in the current context and return its fiber.
+     *
+     * Creates (or reuses) the plugin's runtime record, then starts a new fiber
+     * under the current context. Throws if `plugin` is not a supported shape or
+     * if the current fiber is already disposed.
+     *
+     * @param plugin — a function, class, or `{ apply }` object plugin.
+     * @param config — the plugin config, validated against its `Config` schema.
+     * @param getOuterStack — captures the caller stack for effect diagnostics.
+     * @returns the fiber; awaiting it settles once loading finished.
+     */
+    plugin(plugin, config, getOuterStack = buildOuterStack()) {
+        // check if it's a valid plugin
+        const callback = this.resolve(plugin);
+        if (!callback)
+            throw new Error('invalid plugin, expect function or object with an "apply" method, received ' + typeof plugin);
+        this.ctx.fiber.assertActive();
+        let runtime = this._internal.get(callback);
+        if (!runtime) {
+            let name = plugin.name;
+            if (name === 'apply')
+                name = undefined;
+            runtime = { name, callback, fibers: new DisposableList(), Config: plugin.Config };
+            this._internal.set(callback, runtime);
+        }
+        const fiber = new Fiber(this.ctx, config, Inject.resolve(plugin.inject), runtime, getOuterStack);
+        const wrapped = Object.create(fiber);
+        wrapped.then = (onFulfilled, onRejected) => {
+            return fiber.await().then(onFulfilled, onRejected);
+        };
+        return wrapped;
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/kernel/cordis/lib/types/service.d.ts

@@ -0,0 +1,55 @@
+import { Context } from './context.ts';
+import { symbols } from './utils.ts';
+/**
+ * Base class for services that expose a named API on `ctx`.
+ *
+ * Subclasses call `super(ctx, name)` from their constructor. The service is
+ * registered immediately and is automatically removed with the owning fiber.
+ */
+export declare abstract class Service<out T = never> {
+    protected ctx: Context;
+    /** Symbol key of an instance method run after construction (class plugins). */
+    static readonly init: unique symbol;
+    /** Symbol key of the availability predicate passed to `ctx.provide()`. */
+    static readonly check: unique symbol;
+    /** Symbol key of the phantom intercept-config type parameter. */
+    static readonly config: unique symbol;
+    /** Symbol key of the call body making a service callable (e.g. `ctx.logger()`). */
+    static readonly invoke: unique symbol;
+    /** Symbol key of the helper deriving an extended service instance. */
+    static readonly extend: unique symbol;
+    /** Symbol key of the tracker metadata used for context tracing. */
+    static readonly tracker: unique symbol;
+    /** Symbol key of the intercept-config resolution helper below. */
+    static readonly resolveConfig: unique symbol;
+    [symbols.config]: T;
+    /** The service name this instance is registered under. */
+    name: string;
+    /**
+     * Register this instance as `name` in the current context.
+     *
+     * Calls `ctx.reflect.provide(name, this, this[Service.check])`, so the
+     * service is unregistered automatically when the owning fiber unloads.
+     * Services with a `[Service.invoke]` body return a callable instance.
+     *
+     * @param ctx — the context to register in (stored as `this.ctx`).
+     * @param name — the service name; defaults to the static `provide` field.
+     */
+    constructor(ctx: Context, name: string);
+    protected [symbols.filter](ctx: Context): boolean;
+    protected [symbols.extend](props?: any): any;
+    /**
+     * Merge intercept config from ancestors with optional base and head values.
+     *
+     * Entries added closer to the root apply first; `base` is prepended and
+     * `head` appended. Uses `Config.merge` when the service declares one,
+     * otherwise a shallow `Object.assign`.
+     *
+     * @param base — lowest-precedence config merged before all intercepts.
+     * @param head — highest-precedence config merged after all intercepts.
+     * @returns the merged config.
+     */
+    [symbols.resolveConfig](base?: T, head?: T): T;
+    static [Symbol.hasInstance](instance: any): boolean;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/kernel/cordis/lib/types/service.js

@@ -0,0 +1,113 @@
+import { defineProperty } from '../../../cosmokit/lib/index.js';
+import { Context } from "./context.js";
+import { createCallable, joinPrototype, symbols } from "./utils.js";
+/**
+ * Base class for services that expose a named API on `ctx`.
+ *
+ * Subclasses call `super(ctx, name)` from their constructor. The service is
+ * registered immediately and is automatically removed with the owning fiber.
+ */
+export class Service {
+    ctx;
+    /** Symbol key of an instance method run after construction (class plugins). */
+    static init = symbols.init;
+    /** Symbol key of the availability predicate passed to `ctx.provide()`. */
+    static check = symbols.check;
+    /** Symbol key of the phantom intercept-config type parameter. */
+    static config = symbols.config;
+    /** Symbol key of the call body making a service callable (e.g. `ctx.logger()`). */
+    static invoke = symbols.invoke;
+    /** Symbol key of the helper deriving an extended service instance. */
+    static extend = symbols.extend;
+    /** Symbol key of the tracker metadata used for context tracing. */
+    static tracker = symbols.tracker;
+    /** Symbol key of the intercept-config resolution helper below. */
+    static resolveConfig = symbols.resolveConfig;
+    /** The service name this instance is registered under. */
+    name;
+    /**
+     * Register this instance as `name` in the current context.
+     *
+     * Calls `ctx.reflect.provide(name, this, this[Service.check])`, so the
+     * service is unregistered automatically when the owning fiber unloads.
+     * Services with a `[Service.invoke]` body return a callable instance.
+     *
+     * @param ctx — the context to register in (stored as `this.ctx`).
+     * @param name — the service name; defaults to the static `provide` field.
+     */
+    constructor(ctx, name) {
+        this.ctx = ctx;
+        name ??= this.constructor['provide'];
+        let self = this;
+        const tracker = {
+            associate: name,
+            property: 'ctx',
+        };
+        if (self[symbols.invoke]) {
+            self = createCallable(name, joinPrototype(Object.getPrototypeOf(this), Function.prototype), tracker);
+        }
+        self.ctx = ctx;
+        self.name = name;
+        defineProperty(self, symbols.tracker, tracker);
+        self.ctx.reflect.provide(name, self, this[symbols.check]);
+        return self;
+    }
+    [symbols.filter](ctx) {
+        return ctx[symbols.isolate][this.name] === this.ctx[symbols.isolate][this.name];
+    }
+    [symbols.extend](props) {
+        let self;
+        if (this[Service.invoke]) {
+            self = createCallable(this.name, this, this[symbols.tracker]);
+        }
+        else {
+            self = Object.create(this);
+        }
+        return Object.assign(self, props);
+    }
+    /**
+     * Merge intercept config from ancestors with optional base and head values.
+     *
+     * Entries added closer to the root apply first; `base` is prepended and
+     * `head` appended. Uses `Config.merge` when the service declares one,
+     * otherwise a shallow `Object.assign`.
+     *
+     * @param base — lowest-precedence config merged before all intercepts.
+     * @param head — highest-precedence config merged after all intercepts.
+     * @returns the merged config.
+     */
+    [symbols.resolveConfig](base, head) {
+        let intercept = this.ctx[Context.intercept];
+        const configs = [];
+        while (this.name in intercept) {
+            if (Object.hasOwn(intercept, this.name)) {
+                configs.unshift(intercept[this.name]);
+            }
+            intercept = Object.getPrototypeOf(intercept);
+        }
+        if (base)
+            configs.unshift(base);
+        if (head)
+            configs.push(head);
+        if (this['Config']?.merge) {
+            return this['Config'].merge(...configs);
+        }
+        else {
+            return Object.assign({}, ...configs);
+        }
+    }
+    static [Symbol.hasInstance](instance) {
+        if (!instance)
+            return false;
+        let constructor = instance.constructor;
+        while (constructor) {
+            // constructor may be a proxy
+            constructor = constructor.prototype?.constructor;
+            if (constructor === this)
+                return true;
+            constructor &&= Object.getPrototypeOf(constructor);
+        }
+        return false;
+    }
+}
+//# sourceMappingURL=service.js.map

package/dist/kernel/cordis/lib/types/utils.d.ts

@@ -0,0 +1,62 @@
+import type { Context, Service } from './index.ts';
+/** Ordered collection of disposable values with O(1) deletion by value. */
+export declare class DisposableList<T extends WeakKey> {
+    private sn;
+    private map;
+    private weak;
+    get length(): number;
+    push(value: T): () => boolean;
+    delete(value: T): boolean;
+    clear(): T[];
+    [Symbol.iterator](): MapIterator<T>;
+}
+/** Metadata used by traceable proxies to rebind `ctx` and associated services. */
+export interface Tracker {
+    associate?: string;
+    property?: string;
+    noShadow?: boolean;
+}
+/** Shared symbols used to avoid public property-name collisions. */
+export declare const symbols: {
+    shadow: symbol;
+    receiver: symbol;
+    original: symbol;
+    metadata: symbol;
+    initHooks: symbol;
+    checkProto: symbol;
+    effect: typeof Context.effect;
+    filter: typeof Context.filter;
+    isolate: typeof Context.isolate;
+    intercept: typeof Context.intercept;
+    init: typeof Service.init;
+    check: typeof Service.check;
+    config: typeof Service.config;
+    invoke: typeof Service.invoke;
+    extend: typeof Service.extend;
+    tracker: typeof Service.tracker;
+    resolveConfig: typeof Service.resolveConfig;
+};
+/** Return true when a plugin callback should be constructed with `new`. */
+export declare function isConstructor(func: any): func is new (...args: any) => any;
+/** Merge two prototype chains while preserving descriptors from `proto1`. */
+export declare function joinPrototype(proto1: {}, proto2: {}): any;
+/** Return true for non-null objects and functions. */
+export declare function isObject(value: any): value is {};
+/** Find a property descriptor by walking an object's prototype chain. */
+export declare function getPropertyDescriptor(target: any, prop: string | symbol): TypedPropertyDescriptor<any> | undefined;
+/** Wrap services/functions so method calls see the caller's active context. */
+export declare function getTraceable<T>(ctx: Context, value: T): T;
+/** Return a proxy that overlays readonly or writable properties onto a target. */
+export declare function withProps(target: any, props?: {}): any;
+/** Create a callable service object that dispatches through `symbols.invoke`. */
+export declare function createCallable(name: string, proto: {}, tracker: Tracker): any;
+interface StackInfo {
+    offset: number;
+    error: Error;
+}
+/** Run a callback and splice outer call-site frames into thrown async errors. */
+export declare function composeError<T>(callback: (info: StackInfo) => T, getOuterStack?: () => string[]): T;
+/** Capture a lazy stack-frame supplier for later error composition. */
+export declare function buildOuterStack(offset?: number): () => string[];
+export {};
+//# sourceMappingURL=utils.d.ts.map