@nomix-ai/nomix-harness 0.2.5 → 0.2.6

package/dist/kernel/client-ui-settings/lib/types/client/index.d.ts

@@ -1,23 +1,31 @@
 /**
  * Settings domain base plugin, browser half. Provides `ctx.settingsScope`, the
- * settings-namespace Host transport every preference row binds its durable
- * section through, and owns the canonical slot-type contract for the settings
- * surface. It depends on no `ui-*` presentation package, so any feature that
- * owns a preference can reach it: the settings SHELL — the `sidebar.settings`
- * occupant, its navigation, and the chrome — lives in ui-settings-general,
- * because a shell dependency on ui-sidebar would close a reference cycle
- * through ui-layout and ui-theme. Export discipline: packages/client/AGENTS.md.
+ * settings-namespace scope service every preference row binds its durable
+ * section through, and owns the one `settings.describe` reader in the browser:
+ * the describe mirror, whose invalidation subscriptions
+ * (`settings/document-updated`, `connection/reset`) live here so every derived
+ * surface refreshes from a single wire read. It depends on no `ui-*`
+ * presentation package, so any feature that owns a preference can reach it:
+ * the settings SHELL — the `sidebar.settings` occupant, its navigation, and
+ * the chrome — lives in ui-settings-general, because a shell dependency on
+ * ui-sidebar would close a reference cycle through ui-layout and ui-theme.
+ * Export discipline: packages/client/AGENTS.md.
  */
 import type { ClientContext } from '../../../../client-runtime/lib/client.js';
 export type { SettingsGeneralItemOwnerProps, SettingsHeaderOwnerProps, SettingsOnboardingOwnerProps, SettingsPluginsTabOwnerProps, SettingsSectionOwnerProps, SettingsTriggerOwnerProps, } from './contract/slots.ts';
-export { SettingsScopeController, SettingsScopeBinder } from './settings-scope.ts';
+export type { SettingsScopeController, SettingsScopeBinder } from './settings-scope.ts';
+export type { SettingsSchemaService } from './schema.ts';
+export type { SchemaNode } from './schema.ts';
+export type { SettingsDescribeFace, SettingsDescribeView, SettingsMirrorSnapshot } from './settings-mirror.ts';
 /**
- * Required services: none. The transport is resolved per caller through
- * `this.ctx` at `bind` time, so this plugin waits for nothing.
+ * Required services: the wire handle for the mirror's reads and the forwarded
+ * settings invalidation the mirror refreshes on.
  */
-export declare const inject: never[];
+export declare const inject: string[];
 /**
- * Provide the settings-namespace scope service.
+ * Provide the settings-namespace scope service over one shared describe
+ * mirror, and keep that mirror fresh on the two signals that can move the
+ * settings document: a document commit and a (re)connect.
  *
  * Constructing the service in this plugin's fiber keeps its traced methods
  * bound to each consuming plugin's context.

package/dist/kernel/client-ui-settings/lib/types/client/index.js

@@ -1,18 +1,37 @@
+import { SettingsSchemaService } from "./schema.js";
 import { SettingsScopeBinder } from "./settings-scope.js";
-export { SettingsScopeController, SettingsScopeBinder } from "./settings-scope.js";
+import { SettingsDescribeMirror } from "./settings-mirror.js";
 /**
- * Required services: none. The transport is resolved per caller through
- * `this.ctx` at `bind` time, so this plugin waits for nothing.
+ * Required services: the wire handle for the mirror's reads and the forwarded
+ * settings invalidation the mirror refreshes on.
  */
-export const inject = [];
+export const inject = ['connection', 'remote'];
 /**
- * Provide the settings-namespace scope service.
+ * Provide the settings-namespace scope service over one shared describe
+ * mirror, and keep that mirror fresh on the two signals that can move the
+ * settings document: a document commit and a (re)connect.
  *
  * Constructing the service in this plugin's fiber keeps its traced methods
  * bound to each consuming plugin's context.
  * @param ctx - client root context.
  */
 export function apply(ctx) {
-    new SettingsScopeBinder(ctx);
+    const schema = new SettingsSchemaService(ctx);
+    const connection = ctx.get('connection');
+    const mirror = new SettingsDescribeMirror(connection.api, connection.isLoopback ? 'host' : 'memory');
+    ctx.effect(() => {
+        const disposers = [
+            ctx.get('remote').$on('settings/document-updated', () => { void mirror.load(); }),
+            ctx.on('connection/reset', () => { void mirror.load(); }),
+        ];
+        // The first connection also emits connection/reset, so startup normally
+        // costs two reads (budgeted in startup-rpc-budget.e2e.ts). The in-flight
+        // fold does not merge them into one; it guarantees at most one pending
+        // read at a time and that no invalidation arriving mid-read is lost.
+        void mirror.ensure();
+        return () => { for (const dispose of disposers)
+            dispose(); };
+    }, 'ui-settings: describe mirror invalidations');
+    new SettingsScopeBinder(ctx, { mirror, schema });
 }
 //# sourceMappingURL=index.js.map

package/dist/kernel/client-ui-settings/lib/types/client/schema.d.ts

@@ -0,0 +1,72 @@
+/** Synchronous schema introspection and immutable settings-draft edits. */
+import { Service } from '../../../../cordis/lib/index.js';
+import type { Context } from '../../../../cordis/lib/index.js';
+import Schema from '../../../../schemastery/lib/index.mjs';
+/** Live schemastery node used for settings introspection and validation. */
+export type SchemaNode = Schema;
+/**
+ * Settings-owned synchronous schema service. Dynamic client plugins receive
+ * this Cordis entity instead of importing executable helpers from one another.
+ */
+export declare class SettingsSchemaService extends Service {
+    /** @param ctx - providing ui-settings context. */
+    constructor(ctx: Context);
+    /**
+     * Rehydrate one serialized `schema.toJSON()` envelope.
+     * @param serialized - serialized Schemastery node.
+     * @returns live schema node.
+     */
+    rehydrate(serialized: unknown): SchemaNode;
+    /**
+     * Validate a settings draft.
+     * @param schema - live schema node.
+     * @param draft - candidate settings value.
+     * @returns validation failure text, or `undefined` when valid.
+     */
+    validate(schema: SchemaNode, draft: unknown): string | undefined;
+    /**
+     * Resolve an object, dict, or array schema node at a settings path.
+     * @param root - schema node to traverse.
+     * @param path - object keys or array indexes.
+     * @returns the resolved node, or `undefined` when the path is absent.
+     */
+    nodeAtPath(root: SchemaNode, path: readonly string[]): SchemaNode | undefined;
+    /**
+     * Read a nested value by a string-key or array-index path.
+     * @param value - value to traverse.
+     * @param path - object keys or array indexes.
+     * @returns the resolved value, or `undefined` when the path is absent.
+     */
+    getPath(value: unknown, path: readonly string[]): unknown;
+    /**
+     * Report whether the final path key exists independently of its value.
+     * @param value - value to traverse.
+     * @param path - object keys or array indexes.
+     * @returns whether the path exists.
+     */
+    hasPath(value: unknown, path: readonly string[]): boolean;
+    /**
+     * Immutably set a nested value, materializing missing containers.
+     * @param root - settings object to copy.
+     * @param path - non-empty object-key or array-index path.
+     * @param value - replacement value.
+     * @returns copied root containing the replacement.
+     * @throws when `path` is empty.
+     */
+    setPath(root: Record<string, unknown>, path: readonly string[], value: unknown): Record<string, unknown>;
+    /**
+     * Immutably remove a nested key, preserving an unchanged missing root.
+     * @param root - settings object to copy.
+     * @param path - non-empty object-key or array-index path.
+     * @returns copied root without the key, or `root` when the path is absent.
+     * @throws when `path` is empty.
+     */
+    deletePath(root: Record<string, unknown>, path: readonly string[]): Record<string, unknown>;
+}
+declare module '@nomix-ai/cordis' {
+    interface Context {
+        /** Settings-owned synchronous schema and immutable path operations. */
+        settingsSchema: SettingsSchemaService;
+    }
+}
+//# sourceMappingURL=schema.d.ts.map

package/dist/kernel/client-ui-settings/lib/types/client/schema.js

@@ -0,0 +1,152 @@
+/** Synchronous schema introspection and immutable settings-draft edits. */
+import { Service } from '../../../../cordis/lib/index.js';
+import Schema from '../../../../schemastery/lib/index.mjs';
+function cloneContainer(container, key) {
+    if (Array.isArray(container))
+        return [...container];
+    if (typeof container === 'object' && container !== null)
+        return { ...container };
+    return /^\d+$/.test(key) ? [] : {};
+}
+function cloneSpine(root, path) {
+    const result = { ...root };
+    let target = result;
+    for (let index = 0; index < path.length - 1; index++) {
+        const key = path[index];
+        const child = cloneContainer(Array.isArray(target) ? target[Number(key)] : target[key], path[index + 1]);
+        if (Array.isArray(target))
+            target[Number(key)] = child;
+        else
+            target[key] = child;
+        target = child;
+    }
+    return { result, parent: target, leaf: path[path.length - 1] };
+}
+/**
+ * Settings-owned synchronous schema service. Dynamic client plugins receive
+ * this Cordis entity instead of importing executable helpers from one another.
+ */
+export class SettingsSchemaService extends Service {
+    /** @param ctx - providing ui-settings context. */
+    constructor(ctx) {
+        super(ctx, 'settingsSchema');
+    }
+    /**
+     * Rehydrate one serialized `schema.toJSON()` envelope.
+     * @param serialized - serialized Schemastery node.
+     * @returns live schema node.
+     */
+    rehydrate(serialized) {
+        return new Schema(serialized);
+    }
+    /**
+     * Validate a settings draft.
+     * @param schema - live schema node.
+     * @param draft - candidate settings value.
+     * @returns validation failure text, or `undefined` when valid.
+     */
+    validate(schema, draft) {
+        try {
+            ;
+            schema(draft);
+            return undefined;
+        }
+        catch (error) {
+            return error instanceof Error ? error.message : String(error);
+        }
+    }
+    /**
+     * Resolve an object, dict, or array schema node at a settings path.
+     * @param root - schema node to traverse.
+     * @param path - object keys or array indexes.
+     * @returns the resolved node, or `undefined` when the path is absent.
+     */
+    nodeAtPath(root, path) {
+        let node = root;
+        for (const key of path) {
+            if (node === undefined)
+                return undefined;
+            if (node.type === 'object')
+                node = node.dict?.[key];
+            else if (node.type === 'dict' || node.type === 'array')
+                node = node.inner;
+            else
+                return undefined;
+        }
+        return node;
+    }
+    /**
+     * Read a nested value by a string-key or array-index path.
+     * @param value - value to traverse.
+     * @param path - object keys or array indexes.
+     * @returns the resolved value, or `undefined` when the path is absent.
+     */
+    getPath(value, path) {
+        let current = value;
+        for (const key of path) {
+            if (Array.isArray(current)) {
+                current = current[Number(key)];
+                continue;
+            }
+            if (typeof current !== 'object' || current === null)
+                return undefined;
+            current = current[key];
+        }
+        return current;
+    }
+    /**
+     * Report whether the final path key exists independently of its value.
+     * @param value - value to traverse.
+     * @param path - object keys or array indexes.
+     * @returns whether the path exists.
+     */
+    hasPath(value, path) {
+        if (path.length === 0)
+            return value !== undefined;
+        const parent = this.getPath(value, path.slice(0, -1));
+        const key = path[path.length - 1];
+        if (Array.isArray(parent))
+            return Number(key) < parent.length;
+        if (typeof parent !== 'object' || parent === null)
+            return false;
+        return key in parent;
+    }
+    /**
+     * Immutably set a nested value, materializing missing containers.
+     * @param root - settings object to copy.
+     * @param path - non-empty object-key or array-index path.
+     * @param value - replacement value.
+     * @returns copied root containing the replacement.
+     * @throws when `path` is empty.
+     */
+    setPath(root, path, value) {
+        if (path.length === 0)
+            throw new Error('ui-settings: setPath needs a non-empty path');
+        const { result, parent, leaf } = cloneSpine(root, path);
+        if (Array.isArray(parent))
+            parent[Number(leaf)] = value;
+        else
+            parent[leaf] = value;
+        return result;
+    }
+    /**
+     * Immutably remove a nested key, preserving an unchanged missing root.
+     * @param root - settings object to copy.
+     * @param path - non-empty object-key or array-index path.
+     * @returns copied root without the key, or `root` when the path is absent.
+     * @throws when `path` is empty.
+     */
+    deletePath(root, path) {
+        if (path.length === 0)
+            throw new Error('ui-settings: deletePath needs a non-empty path');
+        if (!this.hasPath(root, path))
+            return root;
+        const { result, parent, leaf } = cloneSpine(root, path);
+        if (Array.isArray(parent))
+            parent.splice(Number(leaf), 1);
+        else
+            Reflect.deleteProperty(parent, leaf);
+        return result;
+    }
+}
+//# sourceMappingURL=schema.js.map

package/dist/kernel/client-ui-settings/lib/types/client/settings-mirror.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Client mirror of the Host settings document: the one `settings.describe`
+ * reader in the browser. Every settings consumer derives from this store —
+ * per-namespace scopes through `SettingsScopeBinder.bind`, cross-namespace
+ * surfaces through the binder's shared describe face — so startup cost and
+ * freshness are properties of this class, not of how many features own a
+ * preference. The Host stays the fact source: the mirror re-reads on the
+ * invalidations its owning plugin subscribes to and folds write answers in
+ * through {@link SettingsDescribeMirror.acceptView}.
+ */
+import type { IApiClient, SettingsNamespaceView } from '../../../../api-remotes/lib/client.js';
+type SettingsFace = Pick<IApiClient, 'settings'>;
+/** The full `settings.describe` answer the mirror serves. */
+export interface SettingsDescribeView {
+    /** Every namespace a live Host plugin registered, as the Host reported it. */
+    namespaces: readonly SettingsNamespaceView[];
+    /** Whether the settings provider accepts writes. */
+    writable: boolean;
+    /** Whether a native settings document exists for the Host to open. */
+    hasDocument: boolean;
+}
+/** Mirror state every derived settings surface renders from. */
+export interface SettingsMirrorSnapshot {
+    /**
+     * `unavailable` is the terminal non-loopback state; `ready` persists across
+     * later failed refreshes (the held view keeps serving); `idle` means no
+     * answer is held and no read is running, so `ensure` will start one.
+     */
+    status: 'idle' | 'loading' | 'ready' | 'unavailable';
+    /** The last good answer; undefined until the first success. */
+    view: SettingsDescribeView | undefined;
+    /** The latest refresh failure message, cleared by the next success. */
+    error: string | null;
+}
+/**
+ * The mirror as cross-namespace surfaces consume it: current answer,
+ * subscription, first-use read, and the write-answer fold. `load` stays off
+ * this face — invalidation refreshes belong to the mirror's owning plugin.
+ */
+export interface SettingsDescribeFace {
+    /** @returns the current sync snapshot (stable reference until the next change). */
+    getSnapshot(): SettingsMirrorSnapshot;
+    /**
+     * Observe snapshot replacements.
+     * @param listener - invoked after each snapshot change.
+     * @returns the disposer removing this listener.
+     */
+    subscribe(listener: () => void): () => void;
+    /**
+     * Resolve once an answer is held (or the mirror is terminally unavailable),
+     * reading only from `idle`.
+     * @returns settlement of the current or newly started read, if any.
+     */
+    ensure(): Promise<void>;
+    /**
+     * Fold one write answer's namespace view into the held view without a wire
+     * read, invalidating any older read still in flight.
+     * @param view - the namespace view a settings write answered with.
+     */
+    acceptView(view: SettingsNamespaceView): void;
+}
+/**
+ * Serializes every Host `settings.describe` read behind one snapshot store.
+ * Concurrent {@link load} calls fold into the in-flight read plus one rerun,
+ * so an invalidation arriving mid-read is never lost and never duplicated.
+ */
+export declare class SettingsDescribeMirror implements SettingsDescribeFace {
+    private readonly api;
+    private readonly persistence;
+    private readonly store;
+    private inFlight;
+    private rerun;
+    private generation;
+    /**
+     * @param api - settings wire face.
+     * @param persistence - remote browsers stay process-local because settings RPCs are loopback-only.
+     */
+    constructor(api: SettingsFace, persistence?: 'host' | 'memory');
+    /** @returns the current sync snapshot (stable reference until the next change). */
+    getSnapshot(): SettingsMirrorSnapshot;
+    /**
+     * Observe snapshot replacements.
+     * @param listener - invoked after each snapshot change.
+     * @returns the disposer removing this listener.
+     */
+    subscribe(listener: () => void): () => void;
+    /**
+     * Refresh from the Host. A call during an in-flight read marks one rerun
+     * after it settles instead of racing a second wire read.
+     * @returns settlement after this call's freshness is reflected.
+     */
+    load(): Promise<void>;
+    /**
+     * Resolve once an answer is held (or the mirror is terminally unavailable),
+     * reading only from `idle`. The cheap idempotent entry for surfaces that
+     * render on first use.
+     * @returns settlement of the current or newly started read, if any.
+     */
+    ensure(): Promise<void>;
+    /**
+     * Fold one write answer's namespace view into the held view without a wire
+     * read, and invalidate any read still in flight. With no held document, the
+     * answer is not published as a partial document; an in-flight read reruns so
+     * it cannot publish a document fetched before the write committed.
+     * @param view - the namespace view a settings write answered with.
+     */
+    acceptView(view: SettingsNamespaceView): void;
+    /**
+     * Convenience row lookup on the held view.
+     * @param ns - namespace identity.
+     * @returns the namespace view, or undefined while unanswered or unregistered.
+     */
+    namespace(ns: string): SettingsNamespaceView | undefined;
+    private run;
+    private shouldRerun;
+}
+export {};
+//# sourceMappingURL=settings-mirror.d.ts.map

package/dist/kernel/client-ui-settings/lib/types/client/settings-mirror.js

@@ -0,0 +1,160 @@
+/**
+ * Client mirror of the Host settings document: the one `settings.describe`
+ * reader in the browser. Every settings consumer derives from this store —
+ * per-namespace scopes through `SettingsScopeBinder.bind`, cross-namespace
+ * surfaces through the binder's shared describe face — so startup cost and
+ * freshness are properties of this class, not of how many features own a
+ * preference. The Host stays the fact source: the mirror re-reads on the
+ * invalidations its owning plugin subscribes to and folds write answers in
+ * through {@link SettingsDescribeMirror.acceptView}.
+ */
+import { createSnapshotStore } from '../../../../client-runtime/lib/client.js';
+/**
+ * Serializes every Host `settings.describe` read behind one snapshot store.
+ * Concurrent {@link load} calls fold into the in-flight read plus one rerun,
+ * so an invalidation arriving mid-read is never lost and never duplicated.
+ */
+export class SettingsDescribeMirror {
+    api;
+    persistence;
+    store;
+    inFlight;
+    rerun = false;
+    generation = 0;
+    /**
+     * @param api - settings wire face.
+     * @param persistence - remote browsers stay process-local because settings RPCs are loopback-only.
+     */
+    constructor(api, persistence = 'host') {
+        this.api = api;
+        this.persistence = persistence;
+        this.store = createSnapshotStore({
+            status: persistence === 'host' ? 'idle' : 'unavailable',
+            view: undefined,
+            error: null,
+        });
+    }
+    /** @returns the current sync snapshot (stable reference until the next change). */
+    getSnapshot() {
+        return this.store.getSnapshot();
+    }
+    /**
+     * Observe snapshot replacements.
+     * @param listener - invoked after each snapshot change.
+     * @returns the disposer removing this listener.
+     */
+    subscribe(listener) {
+        return this.store.subscribe(listener);
+    }
+    /**
+     * Refresh from the Host. A call during an in-flight read marks one rerun
+     * after it settles instead of racing a second wire read.
+     * @returns settlement after this call's freshness is reflected.
+     */
+    load() {
+        if (this.persistence === 'memory')
+            return Promise.resolve();
+        if (this.inFlight !== undefined) {
+            this.rerun = true;
+            return this.inFlight;
+        }
+        // Own the slot before the loading publication can synchronously reenter load().
+        const run = Promise.resolve().then(() => this.run());
+        this.inFlight = run;
+        return run;
+    }
+    /**
+     * Resolve once an answer is held (or the mirror is terminally unavailable),
+     * reading only from `idle`. The cheap idempotent entry for surfaces that
+     * render on first use.
+     * @returns settlement of the current or newly started read, if any.
+     */
+    ensure() {
+        if (this.persistence === 'memory')
+            return Promise.resolve();
+        if (this.inFlight !== undefined)
+            return this.inFlight;
+        if (this.getSnapshot().status === 'idle')
+            return this.load();
+        return Promise.resolve();
+    }
+    /**
+     * Fold one write answer's namespace view into the held view without a wire
+     * read, and invalidate any read still in flight. With no held document, the
+     * answer is not published as a partial document; an in-flight read reruns so
+     * it cannot publish a document fetched before the write committed.
+     * @param view - the namespace view a settings write answered with.
+     */
+    acceptView(view) {
+        const before = this.store.getSnapshot();
+        this.generation += 1;
+        if (this.inFlight !== undefined)
+            this.rerun = true;
+        if (before.view === undefined)
+            return;
+        const namespaces = before.view.namespaces.some(row => row.ns === view.ns)
+            ? before.view.namespaces.map(row => row.ns === view.ns ? view : row)
+            : [...before.view.namespaces, view];
+        this.store.set({ ...before, view: { ...before.view, namespaces } });
+    }
+    /**
+     * Convenience row lookup on the held view.
+     * @param ns - namespace identity.
+     * @returns the namespace view, or undefined while unanswered or unregistered.
+     */
+    namespace(ns) {
+        return this.store.getSnapshot().view?.namespaces.find(row => row.ns === ns);
+    }
+    async run() {
+        // The in-flight slot must clear in the same synchronous segment that
+        // observes `rerun` false (and on abrupt exit): a `.finally()` on the
+        // returned promise runs one microtask later, and a `load()` landing in
+        // that gap would mark a rerun nobody reads, losing the read.
+        try {
+            do {
+                const before = this.store.getSnapshot();
+                if (before.status === 'idle')
+                    this.store.set({ ...before, status: 'loading' });
+                // Cleared immediately before the wire read goes out: a load() marked
+                // earlier (including one reentering from the loading publish above)
+                // is covered by this very read, while one landing after needs the
+                // rerun.
+                this.rerun = false;
+                const generation = ++this.generation;
+                let outcome;
+                try {
+                    const response = await this.api.settings.describe({});
+                    outcome = response.result.ok
+                        ? { view: response.result.value }
+                        : { failure: response.result.error.message };
+                }
+                catch (error) {
+                    outcome = { failure: error instanceof Error ? error.message : String(error) };
+                }
+                // A write answer invalidates a document read before that write committed.
+                if (generation !== this.generation)
+                    continue;
+                if ('view' in outcome) {
+                    this.store.set({ status: 'ready', view: outcome.view, error: null });
+                }
+                else {
+                    const held = this.store.getSnapshot();
+                    // No answer yet: fall back to idle so `ensure` retries; with one, the
+                    // held view keeps serving and only the error field reports the miss.
+                    this.store.set({
+                        status: held.view === undefined ? 'idle' : 'ready',
+                        view: held.view,
+                        error: outcome.failure,
+                    });
+                }
+            } while (this.shouldRerun());
+        }
+        finally {
+            this.inFlight = undefined;
+        }
+    }
+    shouldRerun() {
+        return this.rerun;
+    }
+}
+//# sourceMappingURL=settings-mirror.js.map