@nomix-ai/nomix-harness 0.2.4 → 0.2.6

package/dist/kernel/client-modules/lib/types/client/manifest.js

@@ -16,19 +16,47 @@
  * so load order needs no external sequencing.
  *
  * Resolution branch order (import): seed word → shell instance; memoized
- * record → exports; static registry (shell-own modules, e.g. app-shell) →
- * module; registered factory → materialize; graph row → load + materialize;
- * anything else → throw (loud — the runtime mirror of the
- * build-time bundle purity gate). The synchronous `require` handed to
- * factories walks the same order minus the load branch: loading is async,
- * so only already-registered bundles can be required — and cross-plugin value
- * imports are a build error anyway.
+ * record → exports; graph row → register its dependency factories and own
+ * factory; registered factory → materialize; anything else → throw (loud —
+ * the runtime mirror of the build-time bundle purity gate).
+ * The synchronous `require` handed to factories walks the same order minus
+ * the load branch. Loading is async, so a requested dynamic package must have
+ * registered its factory before a consumer materializes.
  *
  * This file is the browser-safe contract face (zero node imports): the
  * `__NOMIX_BOOT__` wire types, the boot-manifest parser, and the boundaries around
  * {@link ClientModuleSystem}. The package root is the host-side service that
  * composes the wire.
  */
+/**
+ * Validate an optional string-array field read from a `nomix.client` declaration
+ * or from the boot wire.
+ * @param subject - diagnostic prefix naming the package or the wire row.
+ * @param field - field name as it appears in the diagnostic.
+ * @param value - the raw field value.
+ * @returns the validated array, or undefined when the field is absent.
+ * @throws {Error} when the value is present but is not an array of strings.
+ */
+export function optionalStringArray(subject, field, value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) || value.some(item => typeof item !== 'string')) {
+        throw new Error(`client-modules: ${subject} ${field} must be a string array`);
+    }
+    return value;
+}
+/**
+ * Normalize a module specifier onto the graph row that owns it: a plugin bundle
+ * IS its package's client half, so `<id>/client` (the exports subpath external
+ * bundles emit) and the bare package name resolve to the same exports. Both the
+ * require path and graph composition normalize here, which is what lets each
+ * importing package request the subpath its own code imports.
+ * @param spec - module specifier as a bundle requires it or a declaration spells it.
+ * @returns the specifier with a trailing `/client` removed.
+ */
+export function stripClientSuffix(spec) {
+    return spec.endsWith('/client') ? spec.slice(0, -'/client'.length) : spec;
+}
 /**
  * Parse `window.__NOMIX_BOOT__` into the two consumer views. Wire boundary:
  * a missing or malformed graph throws (the shell shows the loud failure —
@@ -58,16 +86,21 @@ export function parseBootManifest(wire) {
         if (typeof row.id !== 'string' || typeof row.url !== 'string' || typeof row.rev !== 'string') {
             throw new Error(`client-modules: boot manifest entry ${where} must carry string id/url/rev`);
         }
-        if (row.inject !== undefined && (!Array.isArray(row.inject) || row.inject.some(i => typeof i !== 'string'))) {
-            throw new Error(`client-modules: boot manifest entry ${where} inject must be a string array`);
-        }
+        const subject = `boot manifest entry ${where}`;
+        const inject = optionalStringArray(subject, 'inject', row.inject);
+        const external = optionalStringArray(subject, 'external', row.external);
         if (row.immediately !== undefined && typeof row.immediately !== 'boolean') {
             throw new Error(`client-modules: boot manifest entry ${where} immediately must be a boolean`);
         }
-        modules.push({ id: row.id, url: row.url, rev: row.rev });
+        modules.push({
+            id: row.id,
+            url: row.url,
+            rev: row.rev,
+            external: external === undefined ? [] : [...external],
+        });
         plugins.push({
             id: row.id,
-            inject: row.inject === undefined ? [] : [...row.inject],
+            inject: inject === undefined ? [] : [...inject],
             immediately: row.immediately === true,
         });
     }

package/dist/kernel/client-modules/lib/types/client/system.d.ts

@@ -1,22 +1,18 @@
-/**
- * ClientModuleSystem — the implementation behind the {@link ClientModuleLoader}
- * contract. The conceptual contract (lazy CJS model, resolution branch order) is
- * documented on the public interfaces in `./manifest.ts`; this file owns the
- * state tables and the load/materialize machinery.
- */
-import type { ClientModuleLoader, ClientModuleRecord, ClientModuleSystemOptions } from './manifest.ts';
+import type { BootManifest, ClientModuleLoader, ClientModuleRecord, ClientModuleSystemOptions } from './manifest.ts';
 /**
  * The client module system: state tables plus the arrival/materialization
  * machinery implementing {@link ClientModuleLoader} (whose members carry the
- * contract documentation). Construction indexes the boot rows and installs the
- * `window.__ModuleLoader__` registration sink — once per page.
+ * contract documentation). Construction indexes the boot rows, retains the
+ * already-materialized bootstrap module, and switches the HTML-installed
+ * loader facade from its pending queue to live registration.
  */
 export declare class ClientModuleSystem implements ClientModuleLoader {
     readonly version = "client";
+    readonly manifest: BootManifest;
     readonly loadCache: Map<string, ClientModuleRecord>;
     private readonly seed;
-    private readonly statics;
     private readonly factories;
+    private readonly bootstrapIds;
     /** In-flight prefetch (script load) per id; concurrent callers share it. */
     private readonly pendingArrival;
     /** Materialization re-entrancy guard: factory-form CJS cannot deliver partial exports, so a cycle is fatal. */
@@ -25,23 +21,25 @@ export declare class ClientModuleSystem implements ClientModuleLoader {
     private readonly loadBundle;
     /**
      * Build the module system over the parsed boot rows.
-     * @param options - Module rows, module-table staticModules, and bundle-load hook.
+     * @param options - Parsed graph, platform seed, bootstrap module, registration facade, and transport.
      */
     constructor(options: ClientModuleSystemOptions);
+    /** Register one bundle factory, rejecting a script that executes twice without invalidation. */
+    private register;
     /** Load one graph row so its factory is registered (idempotent per in-flight arrival). */
     private arrive;
+    /** Register each unresolved dynamic request before registering its consumer. */
+    private arriveGraphRow;
     /** Materialize a registered factory (synchronous; memoized in loadCache). */
     private materialize;
     /**
-     * The synchronous require answered to factories: seed → static → memoized
-     * record → registered factory (recursive materialization — this is what
-     * makes load order self-resolving). Fetching is async and therefore
-     * unreachable from here; an unregistered plugin specifier is loud (and a
-     * cross-plugin value import is already a build error upstream).
+     * The synchronous require answered to factories: seed → memoized record →
+     * registered factory. Fetching is async and therefore unreachable
+     * from here; an external dynamic package must have arrived before its
+     * consumer materializes.
      */
     private makeRequire;
     import(specifier: string): Promise<unknown>;
-    registerStatic(id: string, module: unknown): void;
     prefetch(id: string): Promise<void>;
     invalidate(id: string): void;
 }

package/dist/kernel/client-modules/lib/types/client/system.js

@@ -1,3 +1,10 @@
+/**
+ * ClientModuleSystem — the implementation behind the {@link ClientModuleLoader}
+ * contract. The conceptual contract (lazy CJS model, resolution branch order) is
+ * documented on the public interfaces in `./manifest.ts`; this file owns the
+ * state tables and the load/materialize machinery.
+ */
+import { stripClientSuffix } from "./manifest.js";
 /** Default bundle-load hook: same-origin external classic script. */
 const defaultLoadBundle = (url) => new Promise((resolve, reject) => {
     const el = document.createElement('script');
@@ -13,12 +20,6 @@ const defaultLoadBundle = (url) => new Promise((resolve, reject) => {
     }, { once: true });
     document.head.append(el);
 });
-/**
- * A plugin bundle IS its package's client half: `<id>/client` (the exports
- * subpath external bundles emit) and the bare graph id name the same
- * exports, so table lookups normalize the suffix away.
- */
-const stripClientSuffix = (spec) => spec.endsWith('/client') ? spec.slice(0, -'/client'.length) : spec;
 /**
  * Claim and inventory the <style> tags a factory injected during
  * materialization: preset-emitted tags arrive pre-tagged with data-plugin;
@@ -39,15 +40,17 @@ const claimStyles = (id) => {
 /**
  * The client module system: state tables plus the arrival/materialization
  * machinery implementing {@link ClientModuleLoader} (whose members carry the
- * contract documentation). Construction indexes the boot rows and installs the
- * `window.__ModuleLoader__` registration sink — once per page.
+ * contract documentation). Construction indexes the boot rows, retains the
+ * already-materialized bootstrap module, and switches the HTML-installed
+ * loader facade from its pending queue to live registration.
  */
 export class ClientModuleSystem {
     version = 'client';
+    manifest;
     loadCache = new Map();
     seed;
-    statics = new Map();
     factories = new Map();
+    bootstrapIds = new Set();
     /** In-flight prefetch (script load) per id; concurrent callers share it. */
     pendingArrival = new Map();
     /** Materialization re-entrancy guard: factory-form CJS cannot deliver partial exports, so a cycle is fatal. */
@@ -56,28 +59,44 @@ export class ClientModuleSystem {
     loadBundle;
     /**
      * Build the module system over the parsed boot rows.
-     * @param options - Module rows, module-table staticModules, and bundle-load hook.
+     * @param options - Parsed graph, platform seed, bootstrap module, registration facade, and transport.
      */
     constructor(options) {
+        this.manifest = options.manifest;
         this.seed = new Map(Object.entries(options.staticModules));
         this.loadBundle = options.loadBundle ?? defaultLoadBundle;
-        for (const row of options.modules) {
+        for (const row of options.manifest.modules) {
             if (this.graphRows.has(row.id))
                 throw new Error(`client-modules: duplicate graph entry "${row.id}"`);
             this.graphRows.set(row.id, row);
         }
-        const win = globalThis;
-        if (win.__ModuleLoader__ !== undefined)
-            throw new Error('client-modules: window.__ModuleLoader__ already installed (double boot?)');
-        win.__ModuleLoader__ = {
-            load: (handoff) => {
-                // Registration is keyed by the handoff id; a duplicate means a bundle
-                // executed twice without an invalidate — always a bug, always loud.
-                if (this.factories.has(handoff.id))
-                    throw new Error(`client-modules: duplicate factory registration for "${handoff.id}" (bundle executed twice without invalidate?)`);
-                this.factories.set(handoff.id, handoff.factory);
-            },
-        };
+        const bootstrapId = stripClientSuffix(options.bootstrapModule.id);
+        this.bootstrapIds.add(bootstrapId);
+        this.loadCache.set(bootstrapId, {
+            id: bootstrapId,
+            exports: options.bootstrapModule.exports,
+            styles: [],
+            edges: new Set(),
+        });
+        const target = options.registrationTarget;
+        if (target.mode !== 'queue') {
+            throw new Error('client-modules: window.__ModuleLoader__.create called after module-system boot');
+        }
+        const pending = target.pendingQueue.splice(0);
+        // Switch first: a bundle that executes while pending registrations drain
+        // must register live rather than append behind the drain.
+        target.mode = 'live';
+        target.load = (registration) => { this.register(registration); };
+        for (const registration of pending)
+            target.load(registration);
+    }
+    /** Register one bundle factory, rejecting a script that executes twice without invalidation. */
+    register(registration) {
+        const id = stripClientSuffix(registration.id);
+        if (this.bootstrapIds.has(id) || this.factories.has(id)) {
+            throw new Error(`client-modules: duplicate factory registration for "${registration.id}" (bundle executed twice without invalidate?)`);
+        }
+        this.factories.set(id, registration.factory);
     }
     /** Load one graph row so its factory is registered (idempotent per in-flight arrival). */
     arrive(row) {
@@ -85,7 +104,7 @@ export class ClientModuleSystem {
         const pending = this.pendingArrival.get(id);
         if (pending !== undefined)
             return pending;
-        if (this.factories.has(id))
+        if (this.loadCache.has(id) || this.factories.has(id))
             return Promise.resolve();
         const task = this.loadBundle(url).then(() => {
             if (!this.factories.has(id)) {
@@ -95,6 +114,24 @@ export class ClientModuleSystem {
         this.pendingArrival.set(id, task);
         return task;
     }
+    /** Register each unresolved dynamic request before registering its consumer. */
+    async arriveGraphRow(row, open = []) {
+        const cycleStart = open.indexOf(row.id);
+        if (cycleStart !== -1) {
+            throw new Error(`client-modules: module arrival cycle ${[...open.slice(cycleStart), row.id].join(' -> ')} `
+                + '(the host must reject this graph before serving it)');
+        }
+        const next = [...open, row.id];
+        for (const request of row.external) {
+            const id = stripClientSuffix(request);
+            if (this.seed.has(request) || this.loadCache.has(id))
+                continue;
+            const dependency = this.graphRows.get(id);
+            if (dependency !== undefined)
+                await this.arriveGraphRow(dependency, next);
+        }
+        await this.arrive(row);
+    }
     /** Materialize a registered factory (synchronous; memoized in loadCache). */
     materialize(id) {
         const existing = this.loadCache.get(id);
@@ -120,66 +157,58 @@ export class ClientModuleSystem {
         }
     }
     /**
-     * The synchronous require answered to factories: seed → static → memoized
-     * record → registered factory (recursive materialization — this is what
-     * makes load order self-resolving). Fetching is async and therefore
-     * unreachable from here; an unregistered plugin specifier is loud (and a
-     * cross-plugin value import is already a build error upstream).
+     * The synchronous require answered to factories: seed → memoized record →
+     * registered factory. Fetching is async and therefore unreachable
+     * from here; an external dynamic package must have arrived before its
+     * consumer materializes.
      */
     makeRequire(edges) {
         return (spec) => {
             edges.add(spec);
             if (this.seed.has(spec))
                 return this.seed.get(spec);
-            if (this.statics.has(spec))
-                return this.statics.get(spec);
             const id = stripClientSuffix(spec);
             const record = this.loadCache.get(id);
             if (record !== undefined)
                 return record.exports;
             if (this.factories.has(id))
                 return this.materialize(id).exports;
-            throw new Error(`client-modules: require("${spec}") missed the module table — not a platform seed word, not a shell-own module, `
-                + 'and no registered factory (a build-time externals drift, or a forbidden cross-plugin value import)');
+            throw new Error(`client-modules: require("${spec}") missed the module table — not a platform seed word, not a materialized module, `
+                + 'and no registered package factory (a build-time externals drift, or a dynamic dependency that did not arrive)');
         };
     }
     async import(specifier) {
         if (this.seed.has(specifier))
             return this.seed.get(specifier);
-        const existing = this.loadCache.get(specifier);
+        const id = stripClientSuffix(specifier);
+        const existing = this.loadCache.get(id);
         if (existing !== undefined)
             return existing.exports;
-        if (this.statics.has(specifier)) {
-            const exports = this.statics.get(specifier);
-            this.loadCache.set(specifier, { id: specifier, exports, styles: [], edges: new Set() });
-            return exports;
+        const row = this.graphRows.get(id);
+        if (row !== undefined) {
+            await this.arriveGraphRow(row);
         }
-        if (!this.factories.has(specifier)) {
-            const row = this.graphRows.get(specifier);
-            if (row === undefined) {
-                throw new Error(`client-modules: cannot resolve "${specifier}" — not a seed word, not a shell-own module, `
-                    + 'and not a row in the boot graph (the runtime mirror of the bundle purity gate)');
-            }
-            await this.arrive(row);
+        else if (!this.factories.has(id)) {
+            throw new Error(`client-modules: cannot resolve "${specifier}" — not a seed word, not a materialized module, `
+                + 'and not a row in the boot graph (the runtime mirror of the bundle purity gate)');
         }
-        return this.materialize(specifier).exports;
-    }
-    registerStatic(id, module) {
-        if (this.statics.has(id))
-            throw new Error(`client-modules: shell-own module "${id}" registered twice`);
-        this.statics.set(id, module);
+        return this.materialize(id).exports;
     }
     async prefetch(id) {
-        if (this.statics.has(id))
+        const normalized = stripClientSuffix(id);
+        if (this.loadCache.has(normalized))
             return;
-        const row = this.graphRows.get(id);
+        const row = this.graphRows.get(normalized);
         if (row === undefined)
             throw new Error(`client-modules: prefetch("${id}") — not a graph entry`);
-        await this.arrive(row);
+        await this.arriveGraphRow(row);
     }
     invalidate(id) {
-        this.factories.delete(id);
-        this.loadCache.delete(id);
+        const normalized = stripClientSuffix(id);
+        if (this.bootstrapIds.has(normalized))
+            return;
+        this.factories.delete(normalized);
+        this.loadCache.delete(normalized);
     }
 }
 //# sourceMappingURL=system.js.map

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

@@ -2,10 +2,11 @@
  * Node half of the client module system (`nomix.client` dual-face package): scans
  * the host Loader's entries for packages declaring `nomix.client`, composes the
  * `window.__NOMIX_BOOT__` entry graph (wire single source: {@link WebBootEntry}
- * in `./client/manifest.ts`), serves `/plugins/<id>/client.js` and its source
- * map, taps the index render to inject the boot manifest, and provides the
- * `clientModuleHost` service (the HMR node half's registration/notification
- * face).
+ * in `./client/manifest.ts`) in module-graph order, serves
+ * `/plugins/<id>/client.js` and its source map, contributes the boot manifest
+ * plus the parser-blocking bootstrap preloads to the webserver's index
+ * injection table, and provides the `clientModuleHost` service (the HMR node
+ * half's registration/notification face).
  *
  * Scanning is incremental per package — there is no full-rescan code path.
  * Every cordis `internal/plugin` emission (fiber construction/disposal) marks
@@ -19,9 +20,11 @@
  * {@link ClientModuleRegistry.rebuilt}.
  * @module @nomix-ai/nomix-client-modules
  */
-import { Service } from '@nomix-ai/cordis';
-import type { Context } from '@nomix-ai/cordis';
-import type { WebBootGraph } from './client/manifest.ts';
+import { Service } from '../../../cordis/lib/index.js';
+import type { Context } from '../../../cordis/lib/index.js';
+import type { IndexInjection } from '../../../host-webserver/lib/index.js';
+import type { WebBootEntry, WebBootGraph } from './client/manifest.ts';
+export { stripClientSuffix } from './client/manifest.ts';
 export type { BootManifest, BootModuleRow, BootPluginRow, WebBootEntry, WebBootGraph, } from './client/manifest.ts';
 declare module '@nomix-ai/cordis' {
     interface Context {
@@ -30,17 +33,30 @@ declare module '@nomix-ai/cordis' {
     }
 }
 /**
- * Inject the boot entry graph into index.html: `window.__NOMIX_BOOT__` as the
- * first script in <head> (before the shell bundle reads it). `<` is escaped in
- * the JSON so plugin-controlled strings cannot break out of the script element.
- * @param html - the index.html source.
+ * Order composed rows so every requested dynamic package precedes its
+ * consumers. An `external` specifier is either the package row it names
+ * (`<pkg>/client` aliases the bare package) or a static-table name that adds no
+ * graph edge.
+ * @param entries - composed rows in scan order.
+ * @returns the same rows reordered; scan order breaks every tie.
+ * @throws {Error} when a row requests itself or when the module graph has a
+ * cycle; the message lists the packages on it.
+ */
+export declare function orderByModuleGraph(entries: readonly WebBootEntry[]): WebBootEntry[];
+/**
+ * The boot protocol as index injection rows. The inline registration queue
+ * precedes blocking classic scripts for modules' and runtime's ordinary
+ * `lib/client.js` artifacts. Its `create()` method materializes the modules
+ * bundle, delegates construction to that bundle, and leaves the same facade
+ * in live-registration mode. The graph global follows before the shell reads
+ * it.
  * @param graph - the composed entry graph.
- * @returns the html with the graph script injected.
+ * @returns head rows in execution order: queue script, preload scripts, graph global.
  */
-export declare function injectBootManifest(html: string, graph: WebBootGraph): string;
+export declare function bootInjections(graph: WebBootGraph): IndexInjection[];
 /**
  * The web plugin table service: incremental `nomix.client` scan + wire composition
- * + bundle route + index tap. Construction runs the activation scan
+ * + bundle route + index injection rows. Construction runs the activation scan
  * synchronously — a malformed declaration or missing bundle among the
  * already-loaded entries aggregates into one loud throw (FAILED fiber; the
  * boot activation audit reports it).