@nomix-ai/nomix-harness 0.2.3 → 0.2.5

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

@@ -0,0 +1,310 @@
+import { defineProperty, isNullable } from '../../../cosmokit/lib/index.js';
+import { getTraceable, symbols, withProps } from "./utils.js";
+function enhanceError(error) {
+    const lines = error.stack.split('\n');
+    lines.splice(0, 2, `Error: ${error.message}`);
+    error.stack = lines.join('\n');
+    return error;
+}
+const RESERVED_WORDS = ['prototype', 'then'];
+// - is a symbol
+// - is a reserved word (prototype, then)
+// - is a number string (0, 1, 2, ...)
+// - starts with `_`
+function isSpecialProperty(prop) {
+    return typeof prop === 'symbol'
+        || RESERVED_WORDS.includes(prop)
+        || parseInt(prop).toString() === prop
+        || prop.startsWith('_');
+}
+/**
+ * Reflection and service-resolution layer installed as `ctx.reflect`.
+ *
+ * This service powers the context proxy, service registration, accessors, and
+ * the mixins that expose core service methods directly on `ctx`.
+ */
+export class ReflectService {
+    ctx;
+    /** Proxy traps implementing service resolution for every context object. */
+    static handler = {
+        get: (target, prop, ctx) => {
+            if (isSpecialProperty(prop)) {
+                return Reflect.get(target, prop, ctx);
+            }
+            if (Reflect.has(target, prop)) {
+                return getTraceable(ctx, Reflect.get(target, prop, ctx));
+            }
+            const error = new Error(`cannot get property "${prop}" without inject`);
+            try {
+                const def = target.reflect.props[prop];
+                if (def?.type === 'accessor') {
+                    return def.get.call(ctx, ctx[symbols.receiver], error);
+                }
+                if (!ctx.fiber.runtime)
+                    return ctx.reflect.get(prop, false);
+                return ctx.events.waterfall('internal/get', ctx, prop, error, () => {
+                    const key = target[symbols.isolate][prop];
+                    let fiber = (ctx[symbols.shadow] ?? ctx).fiber;
+                    while (true) {
+                        const impl = fiber.store?.[prop];
+                        if (impl)
+                            return getTraceable(ctx, impl.value);
+                        if (prop in fiber.inject) {
+                            error.message = `cannot get required service "${prop}" in inactive context`;
+                            throw error;
+                        }
+                        if (!fiber.runtime)
+                            throw error;
+                        if (fiber.parent[symbols.isolate][prop] !== key)
+                            throw error;
+                        fiber = fiber.parent.fiber;
+                    }
+                });
+            }
+            catch (e) {
+                throw e === error ? enhanceError(e) : e;
+            }
+        },
+        set: (target, prop, value, ctx) => {
+            if (isSpecialProperty(prop)) {
+                return Reflect.set(target, prop, value, ctx);
+            }
+            const error = new Error(`cannot set property "${prop}" without provide`);
+            const def = target.reflect.props[prop];
+            if (!def) {
+                if (!ctx.fiber.runtime)
+                    return Reflect.set(target, prop, value, ctx);
+                throw enhanceError(error);
+            }
+            try {
+                if (def.type === 'accessor') {
+                    if (!def.set)
+                        return false;
+                    return def.set.call(ctx, value, ctx[symbols.receiver], error);
+                }
+                return ctx.events.waterfall('internal/set', ctx, prop, value, error, () => {
+                    return ctx.reflect.set(prop, value, error);
+                });
+            }
+            catch (e) {
+                throw e === error ? enhanceError(e) : e;
+            }
+        },
+        has: (target, prop) => {
+            if (isSpecialProperty(prop)) {
+                return Reflect.has(target, prop);
+            }
+            if (Reflect.has(target, prop))
+                return true;
+            return !!target.reflect.props[prop];
+        },
+    };
+    /** Service implementations, keyed by isolation label. */
+    store = Object.create(null);
+    /** Declared context properties (services and accessors), by name. */
+    props = Object.create(null);
+    constructor(ctx) {
+        this.ctx = ctx;
+        defineProperty(this, symbols.tracker, {
+            property: 'ctx',
+            noShadow: true,
+        });
+        this.mixin('reflect', ['get', 'set', 'provide', 'accessor', 'mixin']);
+        this.mixin('fiber', ['runtime', 'effect']);
+        this.mixin('registry', ['inject', 'plugin']);
+        this.mixin('events', ['on', 'once', 'parallel', 'emit', 'serial', 'bail', 'waterfall']);
+    }
+    /**
+     * Read a service from the store without the inject requirement.
+     *
+     * @param name — the service name.
+     * @param strict — when `true`, only return implementations whose providing
+     * fiber is currently active.
+     * @returns the service value, or `undefined` when not (yet) provided.
+     */
+    get(name, strict = true) {
+        return getTraceable(this.ctx, this._getImpl(name, strict)?.value);
+    }
+    _getImpl(name, strict = true) {
+        const key = this.ctx[symbols.isolate][name];
+        const impl = key && this.store[key];
+        if (!impl)
+            return;
+        if (strict && impl.fiber.state !== 2 /* FiberState.ACTIVE */)
+            return;
+        return impl;
+    }
+    /**
+     * Overwrite a provided service's value.
+     *
+     * @param name — the service name.
+     * @param value — the new service value.
+     * @param error — carrier for the caller stack in diagnostics.
+     * @returns `true` on success.
+     * @throws when `name` was never provided, or was provided by another fiber.
+     */
+    set(name, value, error) {
+        const key = this.ctx[symbols.isolate][name];
+        const impl = this.store[key];
+        if (!impl) {
+            throw new Error(`cannot set property "${name}" without provide`);
+        }
+        if (impl.fiber !== this.ctx.fiber) {
+            throw new Error(`cannot set property "${name}" in multiple fibers`);
+        }
+        impl.value = value;
+        return true;
+    }
+    /**
+     * Register a service implementation owned by the current fiber.
+     *
+     * See the `ctx.provide()` overload above for the full contract.
+     *
+     * @param name — the service name.
+     * @param value — the service value.
+     * @param check — optional availability predicate for dependents.
+     * @returns a disposer that unregisters the service.
+     */
+    provide(name, value, check) {
+        return this.ctx.fiber.effect(() => {
+            if (!this.props[name]) {
+                this.props[name] ??= { type: 'service' };
+            }
+            else if (this.props[name].type !== 'service') {
+                throw new Error(`property "${name}" is already declared as ${this.props[name].type}`);
+            }
+            this.props[name] = { type: 'service' };
+            this.ctx.root[symbols.isolate][name] ??= Symbol(name);
+            const key = this.ctx[symbols.isolate][name];
+            const impl = { name, value, fiber: this.ctx.fiber, check };
+            if (this.store[key]) {
+                throw new Error(`service "${name}" has been registered at <${this.store[key].fiber.name}>`);
+            }
+            this.store[key] = impl;
+            this.ctx.fiber.store[name] = impl;
+            if (this.ctx.fiber.state === 2 /* FiberState.ACTIVE */) {
+                this.notify([name]);
+            }
+            return async () => {
+                delete this.store[key];
+                const fibers = this.notify([name]);
+                await Promise.allSettled(fibers.map(fiber => fiber.await()));
+                // ensure self access before dependencies cleanup
+                delete this.ctx.fiber.store[name];
+            };
+        }, `ctx.provide(${JSON.stringify(name)})`);
+    }
+    /**
+     * Re-evaluate every fiber that requires one of the given services.
+     *
+     * @param names — the service names that changed.
+     * @param filter — restricts notification to matching isolation scopes.
+     * @returns the fibers whose dependency state was refreshed.
+     */
+    notify(names, filter = (ctx, name) => ctx[symbols.isolate][name] === this.ctx[symbols.isolate][name]) {
+        const fibers = [];
+        for (const runtime of this.ctx.registry.values()) {
+            for (const fiber of runtime.fibers) {
+                let hasUpdate = false;
+                for (const name of names) {
+                    if (!(name in fiber.inject))
+                        continue;
+                    if (!filter(fiber.ctx, name))
+                        continue;
+                    hasUpdate = true;
+                    fiber._checkImpl(name);
+                }
+                if (!hasUpdate)
+                    continue;
+                fiber._refresh();
+                fibers.push(fiber);
+            }
+        }
+        for (const name of names) {
+            const self = Object.create(this.ctx);
+            self[symbols.filter] = (target) => filter(target, name);
+            this.ctx.events.emit(self, 'internal/service', name, this._getImpl(name, false)?.value);
+        }
+        return fibers;
+    }
+    /**
+     * Define a computed context property backed by get/set hooks.
+     *
+     * @param name — the context property name.
+     * @param options — the `get` hook and optional `set` hook.
+     * @returns a disposer that removes the accessor.
+     */
+    accessor(name, options) {
+        return this.ctx.fiber.effect(() => {
+            if (name in this.props) {
+                throw new Error(`property "${name}" is already declared as ${this.props[name].type}`);
+            }
+            this.props[name] = { type: 'accessor', ...options };
+            return () => delete this.props[name];
+        }, `ctx.accessor(${JSON.stringify(name)})`);
+    }
+    /**
+     * Expose selected members of a service directly on `ctx`.
+     *
+     * See the `ctx.mixin()` overload above for the full contract.
+     *
+     * @param source — a context property name or a source object.
+     * @param mixins — keys to forward, or a source-key → ctx-key map.
+     * @returns a disposer that removes all created accessors.
+     */
+    mixin(source, mixins) {
+        const self = this;
+        return this.ctx.fiber.effect(function* () {
+            const entries = Array.isArray(mixins) ? mixins.map(key => [key, key]) : Object.entries(mixins);
+            const getTarget = (ctx, error) => {
+                // TODO enhance error message
+                return ctx[source];
+            };
+            for (const [key, value] of entries) {
+                yield self.accessor(value, {
+                    get(receiver, error) {
+                        const service = getTarget(this, error);
+                        if (isNullable(service))
+                            return service;
+                        const mixin = receiver ? withProps(receiver, service) : service;
+                        const value = Reflect.get(service, key, mixin);
+                        if (typeof value !== 'function')
+                            return value;
+                        return value.bind(mixin ?? service);
+                    },
+                    set(value, receiver, error) {
+                        const service = getTarget(this, error);
+                        const mixin = receiver ? withProps(receiver, service) : service;
+                        return Reflect.set(service, key, value, mixin);
+                    },
+                });
+            }
+        }, `ctx.mixin(${JSON.stringify(source)})`);
+    }
+    /**
+     * Attach this context's tracing wrapper to a value.
+     *
+     * @param value — the value to wrap.
+     * @returns the traceable wrapper (or the value itself when not applicable).
+     */
+    trace(value) {
+        return getTraceable(this.ctx, value);
+    }
+    /**
+     * Wrap a callback so calls trace `this` and arguments to this context.
+     *
+     * @param callback — the function to wrap.
+     * @returns a proxy delegating to `callback` with traced values.
+     */
+    bind(callback) {
+        return new Proxy(callback, {
+            apply: (target, thisArg, args) => {
+                return Reflect.apply(target, this.trace(thisArg), args.map(arg => this.trace(arg)));
+            },
+            construct: (target, args, newTarget) => {
+                return Reflect.construct(target, args.map(arg => this.trace(arg)), newTarget);
+            },
+        });
+    }
+}
+//# sourceMappingURL=reflect.js.map

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

@@ -0,0 +1,201 @@
+import type { Dict } from '../../../cosmokit/lib/index.js';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import { Context } from './context.ts';
+import { Fiber } from './fiber.ts';
+import { DisposableList, symbols } from './utils.ts';
+/**
+ * Service dependency declaration accepted by plugins and the `@Inject`
+ * decorator.
+ *
+ * Array form requests services without intercept config. Object form maps each
+ * service name to optional intercept config for the plugin context.
+ */
+export type Inject<M = Dict> = (keyof M)[] | {
+    [K in keyof M]?: M[K];
+};
+/** Context keys that correspond to services with typed intercept config. */
+export type InjectKey = keyof {
+    [K in keyof Context & string as Context[K] extends {
+        [symbols.config]: any;
+    } ? K : never]: any;
+};
+/**
+ * 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 declare function Inject<K extends InjectKey>(name: K, config?: Context[K] extends {
+    [symbols.config]: infer T;
+} ? T : never): (value: any, decorator: ClassDecoratorContext<any> | ClassMethodDecoratorContext<any>) => void;
+/** Utilities for normalizing plugin dependency declarations. */
+export declare namespace 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: Inject | null | undefined, result?: Dict): Dict;
+}
+/** Supported plugin entrypoint shapes. */
+export type Plugin<T = any> = Plugin.Function<T> | Plugin.Constructor<T> | Plugin.Object<T>;
+/** Types associated with plugin entrypoints and runtime records. */
+export declare namespace Plugin {
+    /** Shared metadata understood by the plugin registry and related tooling. */
+    interface Base<T = any> {
+        /** Display name used for fiber diagnostics and logger names. */
+        name?: string;
+        /** Standard-schema validator applied to config before the plugin starts. */
+        Config?: StandardSchemaV1<any, T>;
+        /** Services the plugin requires; it only loads while all are available. */
+        inject?: Inject;
+        /** Service name(s) the plugin provides (read by `Service` and by loaders). */
+        provide?: string | string[];
+        /** Service names whose intercept config the plugin declares it consumes. */
+        intercept?: Dict<boolean>;
+    }
+    interface Transform<S, T> {
+        /** Marks the transform object as a schema/config transform. */
+        schema?: true;
+        /** Convert user-facing config to runtime config. */
+        Config: (config: S) => T;
+    }
+    /** Function plugin called with `(ctx, config)`. */
+    interface Function<T = any> extends Base<T> {
+        (ctx: Context, config: T): any;
+    }
+    /** Class plugin constructed with `(ctx, config)`. */
+    interface Constructor<T = any> extends Base<T> {
+        new (ctx: Context, config: T): any;
+    }
+    /** Object plugin with an `apply(ctx, config)` method. */
+    interface Object<T = any> extends Base<T> {
+        apply(ctx: Context, config: T): any;
+    }
+    /** Mutable registry record shared by all fibers of one plugin callback. */
+    interface Runtime {
+        /** Display name copied from the first registered plugin shape. */
+        name?: string;
+        /** Every live fiber of this plugin (one per `ctx.plugin()` call). */
+        fibers: DisposableList<Fiber>;
+        /** The executable entrypoint all fibers share (registry identity key). */
+        callback: globalThis.Function;
+        /** Standard-schema validator applied to each fiber's config. */
+        Config?: StandardSchemaV1;
+    }
+}
+type Spread<T> = undefined extends T ? [config?: T] : [config: T];
+type GetPluginParameters<P> = P extends (ctx: Context, ...args: infer R) => any ? R : P extends new (ctx: Context, ...args: infer R) => any ? R : P extends {
+    apply(ctx: Context, ...args: infer R): any;
+} ? R : never;
+type GetPluginConfig<P> = P extends Plugin.Transform<infer S, any> ? S : GetPluginParameters<P>[0];
+declare module './context.ts' {
+    interface Context {
+        /**
+         * Run a callback once the requested services are available.
+         *
+         * Shorthand for `ctx.plugin({ inject, apply: callback })`: the callback
+         * is unloaded and re-run whenever a required service changes.
+         *
+         * @param deps — 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(deps: Inject, callback: Plugin.Function<void>): Fiber & PromiseLike<Fiber>;
+        /**
+         * Load a plugin in the current context.
+         *
+         * @param plugin — a function, class, or `{ apply }` object plugin.
+         * @param args — the plugin config, validated against its `Config` schema.
+         * @returns the fiber; awaiting it settles once loading finished
+         * (rejecting on config or startup errors).
+         */
+        plugin<P extends Plugin>(plugin: P, ...args: Spread<GetPluginConfig<P>>): Fiber & PromiseLike<Fiber>;
+    }
+}
+/**
+ * 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 declare class RegistryService {
+    ctx: Context;
+    private _counter;
+    private _internal;
+    constructor(ctx: Context);
+    /** Allocate the next fiber uid (increments on every read). */
+    get counter(): number;
+    /** Number of registered plugin runtimes. */
+    get size(): number;
+    /**
+     * 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): Function | undefined;
+    /**
+     * 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: Plugin): Plugin.Runtime | undefined;
+    /**
+     * 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: Plugin): boolean;
+    /**
+     * 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: Plugin): Plugin.Runtime | undefined;
+    /** Iterate the registered plugin callbacks. */
+    keys(): MapIterator<Function>;
+    /** Iterate the registered plugin runtimes. */
+    values(): MapIterator<Plugin.Runtime>;
+    /** Iterate `[callback, runtime]` pairs. */
+    entries(): MapIterator<[Function, Plugin.Runtime]>;
+    /**
+     * Visit every registered runtime.
+     *
+     * @param callback — receives each runtime and its identifying callback.
+     */
+    forEach(callback: (value: Plugin.Runtime, key: Function) => void): void;
+    /**
+     * 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: Inject, callback: Plugin.Function<void>): Fiber & PromiseLike<Fiber>;
+    /**
+     * 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: Plugin, config?: any, getOuterStack?: () => string[]): Fiber & PromiseLike<Fiber>;
+}
+export {};
+//# sourceMappingURL=registry.d.ts.map