@validation-engineering/cordis-loader 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 cordis-verus contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/NOTICE

@@ -0,0 +1,49 @@
+This is an independent Rust reimplementation of a subset of Cordis semantics.
+It is not an official Cordis, DeepSeek, or Verus distribution.
+
+Design and behavior references:
+- Cordis, https://github.com/cordiverse/cordis (MIT)
+- DeepSeek Harness, https://github.com/deepseek-ai/deepseek-harness (MIT)
+- A Programming Paradigm for Spatiotemporal Composability,
+  https://arxiv.org/abs/2608.25512v1 (https://github.com/validation-engineering/cordis-verus/blob/main/reference/README.md)
+
+The ignored upstream checkouts retain their own license and copyright files.
+The reference paper is not covered by this project's MIT license.
+Verus binaries and vstd retain their upstream licenses. Binary archives are
+downloaded into the ignored .tools directory. Project-managed toolchain archives
+preserve original upstream bytes with a source/notices companion; see
+https://github.com/validation-engineering/cordis-verus/blob/main/docs/toolchains/README.md.
+They are separate from Cordis runtime releases.
+
+The experimental JavaScript compatibility package adapts language-layer code
+from Cordis (Copyright (c) 2021-present Shigma, MIT). The original MIT notice
+is preserved in packages/compat-cordis/LICENSE.upstream. It does not embed the
+upstream Fiber lifecycle scheduler. Node-API dependencies retain their own licenses.
+
+The compatibility logger in packages/compat-cordis/logger.js is adapted from
+Cordis packages/core/src/logger.ts at the locked Cordis revision. Its formatting,
+exporter and traceable-caller behavior are ordinary JavaScript, outside the
+Verus proof boundary, and retain the same MIT attribution above.
+
+Windows configuration persistence uses atomicwrites 0.4.4
+(https://github.com/untitaker/rust-atomicwrites), under the MIT license:
+
+Copyright (c) 2015 Markus Unterwaditzer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,147 @@
-# Temporary Holding Version
+# Native Cordis JSON Loader
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+This experimental package loads real JS Cordis plugins through `compat-cordis` and the Rust native driver. It adds a **JSON configuration API** and an explicit **whole-Worker code replacement API**. It does not yet implement the upstream Loader/Include classes or Harness configuration language. A Loader can use either native Context profile; the Worker bootstrap selects the Cordis profile.
+
+Use the matching `@validation-engineering/cordis` package, which includes the precompiled native addon. No compiler or additional runtime dependencies are required beyond that package and Node 22.22+. Source contributors can rebuild it with `npm run build:native`.
+
+## Load a configuration in the current environment
+
+```js
+import { Context } from '@validation-engineering/cordis';
+import { Loader } from '@validation-engineering/cordis-loader';
+
+const context = new Context();
+const loader = new Loader(context);
+await loader.loadFile('./cordis.json');
+console.log(loader.diagnostics());
+await loader.update('greeting', { config: { prefix: 'Welcome' } });
+await loader.dispose();
+await context.dispose();
+```
+
+Start the program with `--import @validation-engineering/cordis/register` when plugin sources import the original `cordis` package name. The registered facade is still the only lifecycle implementation.
+
+```json
+[
+  {
+    "id": "greeting",
+    "name": "./plugins/greeting.mjs",
+    "config": { "prefix": "Hello" }
+  },
+  {
+    "id": "tools",
+    "include": "./tools.json",
+    "isolate": ["tools"]
+  }
+]
+```
+
+An input is an entry array or `{ "entries": [...] }`. Every entry has an explicit stable `id`. Module and include paths resolve relative to the configuration file that contains them. `include` adds a group; `group: true` with `entries` creates an inline group. Nested entry IDs use `/`, for example `tools/search`. IDs may contain letters, digits, `_`, `-` and `.`. Include cycles, duplicate IDs, unsupported fields and invalid JSON values fail before the active graph is stopped.
+
+Supported options are `id`, `name`, `config`, `disabled`, `group`, `entries`, `include`, `inject`, `isolate` and `intercept`. `inject` accepts service names or a name-to-config mapping. `isolate: ["service"]` creates an entry-specific realm; `isolate: {"service": "shared-label"}` intentionally shares that label between entries in this Loader. Groups own their child fibers. Disabled groups retain entry records while skipping module imports and activation for their descendants.
+
+Entries returned by `resolve()` keep their object identity across successful updates and restoration. A persistent Loader owner contains the configured tree. Updates compare each stable ID's canonical module URL, prepared plugin object identity and optional revision, JSON config, injection, isolation, interception, source base URL and parent. Unchanged fibers remain mounted; changed entries and descendants of changed parents are retired and recreated. Adding or removing children does not restart an unchanged group. JSON object key order and sibling reordering do not restart instances; sibling order governs newly mounted entries and diagnostics, while retained instances keep their original effect registration order.
+
+A preserved consumer can still run cleanup and setup again when its dependency changes: the shared native driver owns that transition, and the consumer keeps its Fiber ID while its episode changes. A group's dependency restart recreates its owned children from the latest committed recipe. Changing a group's isolation/injection/interception replaces its entire subtree. Config changes currently replace the changed plugin rather than invoke upstream in-place update hooks. Explicit entry inject metadata uses a forwarding plugin callback and is not an exact upstream registry-identity implementation. The application Context and unrelated plugins are not disposed by `loader.dispose()`.
+
+### Readiness, serialization and restoration
+
+`await ctx.plugin()` can settle Pending. The Loader therefore checks every enabled configured entry after settlement. By default a missing dependency rejects activation with `DEPENDENCIES_UNAVAILABLE` and structured `details.entries` diagnostics. `allowPending: true` accepts a partially available tree. Diagnostics cover configured entries; arbitrary plugin-created children retain their own lifecycle API.
+
+External `apply`, `loadFile`, `update`, `setEnabled`, `reload` and `dispose` calls enter the runtime domain's shared mutation queue at admission. All Loaders over the same Context domain share that queue with external Fiber updates, restarts, disposal and domain shutdown. Preparing a candidate is part of the transaction, so another Loader cannot activate a competing revision while its modules are being prepared. Independent Context domains keep separate queues.
+
+Plugin setup can immediately create and await `ctx.plugin()` children; effect registration and native completion continue during a transaction. Loader retirement, recovery and cleanup use scoped transaction steps, without queueing behind their own operation. Calling a Loader mutation from an active lifecycle callback or another transaction, including a different Loader's callback or module preparation, is rejected as `REENTRANT_MUTATION`. This also applies when the requested close is already queued; joining that Promise would wait on the action currently blocking it.
+
+`loader.dispose()` closes only that Loader and joins repeated external requests. `context.dispose()` closes admission for new domain revisions as soon as shutdown is requested, waits for previously admitted transactions, and then drains the graph. An admitted transaction can still finish plugin setup and cleanup. A cleanup failure anywhere in the domain blocks subsequent ordinary revisions; explicit cleanup retry and disposal remain available. This does not make module evaluation or external side effects atomic, add configuration write-back, or invalidate Node's module caches.
+
+The Loader imports modules and validates candidate JSON inputs before disturbing the old tree. Runtime plugin schema validation still occurs when the replacement is mounted. It retains the old module objects and an immutable JSON recipe. Each activation gets fresh configuration objects. The changed old subtrees and their dependent cleanup drain before replacements mount. If candidate setup fails, every candidate-created fiber and its children must be removed before the replaced part of the old recipe can restart. Unaffected siblings and parents remain mounted. Group controllers are restored to the old recipe as well, so a later dependency notification cannot reactivate rejected configuration. A retained consumer that failed while observing the candidate is explicitly restarted against the restored dependencies. A cleanup failure leaves the Loader `blocked`; it does not activate the old recipe or a queued replacement. After fixing the external cause, `retryCleanup()` retries failed inverses and drains the whole Loader, including retained siblings, returning to an empty state. The caller can then explicitly load a configuration. Successful inverses are not repeated.
+
+`RELOAD_FAILED` with `details.restored: true` means the replaced part of the old recipe was instantiated again; replaced live objects do not survive. Unchanged entries can keep their instances. Module evaluation, arbitrary global state and external file/network/database effects are not rolled back.
+
+`loader.reload()` re-reads its last file and included JSON files, then reconciles the changed subtrees. With unchanged configuration and factory identities, it does not remount the graph. After a programmatic `update()` the source is an in-memory recipe; subsequent `reload()` uses that recipe and asks the ModuleHost to prepare its factories again. There is no implicit write-back to the original configuration files and no background file watcher.
+
+## DeepSeek Harness application integration
+
+The pinned official Loader/Include, ConfigEditor and in-process HMR bridges are
+maintained and tested by the companion Harness application. Starting with Loader
+0.2.0, import those APIs from `@validation-engineering/harness-verus/official-loader-api`.
+The former `@validation-engineering/cordis-loader/harness` entry belongs to the
+published 0.1.0 release and is no longer exported by this package.
+
+The runtime still provides the shared domain transaction, callback isolation,
+cleanup and JSON Loader primitives. Application-specific method interception,
+module-cache recovery and official version checks live with the application.
+See [package boundaries](../../docs/package-boundaries.md) for the migration.
+
+## Replace code in a fresh Worker
+
+`ModuleHost` imports canonical file URLs. It **does not invalidate Node's ESM or CommonJS caches**. Changing a source file and calling `loader.reload()` is not code HMR. `ModuleHost.reset()` explicitly rejects with `DOMAIN_RESTART_REQUIRED`. A file edit at an already imported URL does not change the cached factory identity and is not a request for code replacement.
+
+An embedding host can supply an adapter for **already prepared factories**:
+
+```js
+import { ModuleHost } from '@validation-engineering/cordis-loader';
+
+const moduleHost = new ModuleHost({
+  loadModule: async canonicalURL => preparedFactories.get(canonicalURL),
+});
+// Each value is { plugin, namespace?, revision?: string | number }.
+const loader = new Loader(context, { moduleHost });
+```
+
+Resolution still requires an explicit existing file path and applies `rootDirectory` confinement. The adapter replaces only module loading; it does not bypass JSON validation or lifecycle cleanup. It must return the same plugin object and revision while the executable factory is unchanged. A changed identity or revision requests replacement of entries using that module. Revision is a comparison token, not a claim that Node's dependency cache was reset. Publish immutable factory snapshots: the retained old plugin object must remain executable for rollback. Building source, evaluating it in another environment, deciding the dependency closure and maintaining those factory snapshots remain the embedding host's responsibility. Use `WorkerDomain` or `ProcessDomain` when an ESM/CommonJS environment and its transitive dependencies must actually be replaced.
+
+Use a `WorkerDomain` for real code replacement, including changed transitive imports:
+
+```js
+import { WorkerDomain } from '@validation-engineering/cordis-loader/worker';
+
+const domain = new WorkerDomain({ entry: 'cordis.json' });
+await domain.load('./plugin-project');
+console.log(await domain.call('greeting', 'hello', 'Alice'));
+// Build/publish the candidate project directory first.
+await domain.reload('./plugin-project');
+await domain.dispose();
+```
+
+Each load captures the local project directory and its dependencies/assets into a retained artifact, with content hashes and permissions. Each Worker receives a separate launch copy. Mutating launch files cannot change the retained recovery recipe. A new Worker owns a new Node environment, native Driver and real module cache. No query suffix is used to simulate dependency-graph reload.
+
+Replacement follows this order:
+
+1. Capture the candidate artifact while the old Worker is available.
+2. Stop new requests and drain admitted service calls, then normally dispose the old native graph and exit the Worker.
+3. Start the candidate Worker and require configured entries to become ready.
+4. On startup failure, normally drain and exit that candidate; only then restart the retained old artifact in another fresh Worker.
+
+A cleanup failure or unknown timeout blocks replacement. An unexpected Worker exit is `abandoned`, not a successful shutdown. `abandon()` explicitly terminates remaining Workers and returns `{ abandoned: true, cleanupConfirmed: false }`; it never automatically restores the old artifact. The default operation timeout is 30 seconds and is only a failure detector, not a cancellation or cleanup proof.
+
+Objects/functions stay ordinary JS objects **inside** each Worker. `WorkerDomain.call(service, method, ...args)` is an explicit asynchronous JSON boundary between environments. It has no transparent callback/stream/object transport. A Worker is not an operating-system process or a security sandbox; a native crash can affect the whole process.
+
+### Replace an OS process
+
+Use `ProcessDomain` from `@validation-engineering/cordis-loader/process` for application
+native addons or a whole application process. It has the same captured-artifact
+load/reload/call workflow and adds a read-only PID. A successful replacement needs
+both a cleanup acknowledgement and exit code zero; a timeout or crash is not
+normal cleanup. An optional trusted `hostModule` can host the official Harness
+without creating another Context. See the [process contract and example](../../docs/module-graph-reloads.md#processdomain-application-native-addons-and-external-hosts)
+for adapter, provenance and failure boundaries. The companion Harness exposes an
+opt-in [official Web supervisor](https://github.com/validation-engineering/cordis-harness/blob/main/docs/process-supervisor.md).
+
+### Artifact contract
+
+Publish a complete, stable input directory before capture. Include all relative imports, installed dependencies, resources and configuration. The directory must not change during capture. `.git` is excluded; symlinks, special files and artifacts exceeding configured limits are rejected. Defaults are 256 MiB and 20,000 files. Materialize symlinked package dependencies before capture. The facade/addon and Node runtime come from the host installation, not the captured project.
+
+Keep persistent writable data outside the captured directory and pass its path explicitly in JSON config. Per-launch writable changes are discarded after shutdown. Entry modules and all JSON Include files must be inside the artifact. Arbitrary imports made by plugin code can still escape that directory; they are not a captured dependency or a sandboxed operation. Complete dependency discovery, package installation and signed release manifests remain future work.
+
+## Current compatibility boundary
+
+This package supports explicit file module paths and Node's normal execution of built JS/CJS. Bare npm plugin entry names, source TS transformation, YAML/custom tags, JS expressions, upstream Loader event/API compatibility, automatic config write-back, transparent in-process code HMR and Harness lazy/volatile configuration are not implemented. Plugin dependencies may use Node's normal package imports once installed in the project. A `cordis` import is routed by the existing facade bootstrap; embedded/private Cordis copies are not detected by this package.
+
+The implementation is ordinary JS host code. Its tests establish the listed behavior; they do not add Verus proofs for module loading, arbitrary plugin callbacks, Worker teardown or filesystem operations.
+
+Run `node --test --test-timeout=30000 tests/node-loader/*.test.mjs` from the repository root. The tests execute actual plugin files, nested JSON Include and isolated groups, candidate children, explicit readiness checks, code changes to a transitive import, snapshot recovery, cleanup failure, queued/reentrant updates, Worker crash and TypeScript usage.
+
+## Local distribution check
+
+`node scripts/check-npm-package.mjs --offline` stages the facade, Loader and Harness profile packages, includes the freshly recorded host-native addon and notices, runs `npm pack --ignore-scripts`, and installs the tarballs in a separate temporary project. It verifies that no workspace path or symlink supplies the packages, then runs native, Loader, Worker, Process (including an application native addon) and Harness profile examples from that installation. The report and local tarballs are written to `target/release-artifacts/npm`. Only the tested OS/architecture/Node combination is recorded as validated; this check uploads nothing and does not establish a prebuilt distribution matrix or registry publish eligibility.

package/artifact.js

@@ -0,0 +1,80 @@
+import { createHash } from 'node:crypto';
+import { lstat, mkdir, mkdtemp, readdir, readFile, rm, writeFile, chmod } from 'node:fs/promises';
+import { join, resolve, relative, isAbsolute } from 'node:path';
+import { tmpdir } from 'node:os';
+import { LoaderError } from './config.js';
+
+const managedLaunches = new Set();
+/** Release only a private directory allocated by Artifact.launch in this process. */
+export async function releaseLaunch(directory) {
+  if (!managedLaunches.has(directory)) throw new LoaderError('ARTIFACT_CLEANUP_TARGET', 'Only a registered private artifact launch may be released');
+  await rm(directory, { recursive: true, force: true });
+  managedLaunches.delete(directory);
+}
+
+/** Each isolated environment gets a private copy, never the retained restoration recipe. */
+export class Artifact {
+  static async capture(directory, options = {}) {
+    const source = resolve(directory);
+    if (!(await lstat(source)).isDirectory()) throw new LoaderError('ARTIFACT_DIRECTORY', 'Artifact source must be a directory');
+    const storage = await mkdtemp(join(tmpdir(), 'cordis-artifact-'));
+    const root = join(storage, 'project');
+    await mkdir(root);
+    const manifest = [];
+    const directories = [];
+    let bytes = 0;
+    const maxBytes = options.maxBytes ?? 256 * 1024 * 1024;
+    const maxFiles = options.maxFiles ?? 20000;
+    async function copy(folder = '') {
+      const entries = (await readdir(join(source, folder), { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
+      for (const entry of entries) {
+        if (entry.name === '.git') continue;
+        const name = join(folder, entry.name);
+        const stat = await lstat(join(source, name));
+        if (stat.isSymbolicLink()) throw new LoaderError('ARTIFACT_SYMLINK', `Artifact symlinks are not supported: ${name}; materialize dependencies first`);
+        if (stat.isDirectory()) { directories.push(name); await mkdir(join(root, name)); await copy(name); continue; }
+        if (!stat.isFile()) throw new LoaderError('ARTIFACT_FILE_TYPE', `Unsupported artifact file ${name}`);
+        if (bytes + stat.size > maxBytes || manifest.length >= maxFiles) throw new LoaderError('ARTIFACT_LIMIT', 'Artifact exceeds configured byte/file limit');
+        const content = await readFile(join(source, name));
+        bytes += content.length;
+        if (bytes > maxBytes) throw new LoaderError('ARTIFACT_LIMIT', 'Artifact changed beyond its byte limit during capture');
+        const mode = stat.mode & 0o777;
+        await writeFile(join(root, name), content);
+        await chmod(join(root, name), mode);
+        manifest.push({ name, mode, bytes: content.length, sha256: createHash('sha256').update(content).digest('hex') });
+      }
+    }
+    try {
+      await copy();
+      const digest = createHash('sha256').update(JSON.stringify({ files: manifest, directories })).digest('hex');
+      return new Artifact(storage, root, source, manifest, directories, digest);
+    } catch (error) { await rm(storage, { recursive: true, force: true }); throw error; }
+  }
+  constructor(storage, root, source, manifest, directories, digest) {
+    this.storage = storage; this.root = root; this.source = source;
+    this.manifest = Object.freeze(manifest.map(item => Object.freeze(item)));
+    this.directories = Object.freeze(directories);
+    this.digest = digest; this.closed = false;
+  }
+  async launch(entry) {
+    if (this.closed) throw new LoaderError('ARTIFACT_CLOSED', 'The retained artifact has been released');
+    const location = relative(this.root, resolve(this.root, entry));
+    if (!location || location === '..' || location.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`) || isAbsolute(location)) throw new LoaderError('ARTIFACT_ENTRY', 'entry must be a file inside the artifact');
+    const directory = await mkdtemp(join(tmpdir(), 'cordis-worker-'));
+    managedLaunches.add(directory);
+    try {
+      // Only captured entries are copied; later additions to retained storage
+      // cannot enter an artifact under its original digest.
+      for (const name of this.directories) await mkdir(join(directory, name));
+      for (const item of this.manifest) {
+        const content = await readFile(join(this.root, item.name));
+        if (createHash('sha256').update(content).digest('hex') !== item.sha256) throw new LoaderError('ARTIFACT_CHANGED', `Retained artifact changed: ${item.name}`);
+        await writeFile(join(directory, item.name), content);
+        await chmod(join(directory, item.name), item.mode);
+      }
+      return { directory, entry: location };
+    } catch (error) { await releaseLaunch(directory); throw error; }
+  }
+
+  async dispose() { if (!this.closed) { await rm(this.storage, { recursive: true, force: true }); this.closed = true; } }
+}

package/config.js

@@ -0,0 +1,102 @@
+import { readFile, realpath } from 'node:fs/promises';
+import { isAbsolute, resolve, relative } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+export class LoaderError extends Error {
+  constructor(code, message, details = {}, cause) {
+    super(message, cause === undefined ? undefined : { cause });
+    this.name = 'LoaderError';
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export function jsonValue(value, path = '$', seen = new Set()) {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value !== 'object' || seen.has(value)) throw new LoaderError('INVALID_CONFIG', `${path} must contain finite JSON values only`);
+  if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+    throw new LoaderError('INVALID_CONFIG', `${path} must be a plain JSON object`);
+  }
+  seen.add(value);
+  const result = Array.isArray(value) ? value.map((item, index) => jsonValue(item, `${path}[${index}]`, seen)) : Object.fromEntries(Object.entries(value).map(([key, item]) => [key, jsonValue(item, `${path}.${key}`, seen)]));
+  seen.delete(value);
+  return result;
+}
+
+function freezeJSON(value) {
+  if (value && typeof value === 'object') { for (const item of Object.values(value)) freezeJSON(item); Object.freeze(value); }
+  return value;
+}
+
+export function fileURL(input, baseURL = pathToFileURL(`${process.cwd()}/`).href) {
+  if (input instanceof URL) input = input.href;
+  if (typeof input !== 'string' || !input) throw new LoaderError('INVALID_PATH', 'Expected a file path or file URL');
+  const url = input.startsWith('file:') ? new URL(input) : isAbsolute(input) ? pathToFileURL(input) : new URL(input, baseURL);
+  if (url.protocol !== 'file:' || url.search || url.hash) throw new LoaderError('INVALID_PATH', 'Only ordinary file paths without query or fragment are supported');
+  return url;
+}
+
+function object(value, at) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new LoaderError('INVALID_CONFIG', `${at} must be an object`);
+}
+
+export async function readTree(input, options = {}) {
+  const baseURL = options.baseURL ?? pathToFileURL(`${resolve('.')}/`).href;
+  const root = options.rootDirectory ? await realpath(options.rootDirectory) : undefined;
+  const files = new Set();
+  const ids = new Set();
+  const stack = [];
+  async function fromFile(filename, parent, base) {
+    const url = fileURL(filename, base);
+    const canonicalPath = await realpath(fileURLToPath(url));
+    if (root) {
+      const location = relative(root, canonicalPath);
+      if (location === '..' || location.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`) || isAbsolute(location)) throw new LoaderError('CONFIG_OUTSIDE_ARTIFACT', `${canonicalPath} is outside artifact ${root}`);
+    }
+    const canonical = pathToFileURL(canonicalPath).href;
+    if (stack.includes(canonical)) throw new LoaderError('INCLUDE_CYCLE', `Include cycle: ${[...stack, canonical].join(' -> ')}`);
+    if (stack.length >= 64) throw new LoaderError('INCLUDE_DEPTH', 'Include nesting exceeds 64 files');
+    stack.push(canonical);
+    files.add(canonical);
+    let raw;
+    try { raw = JSON.parse(await readFile(new URL(canonical), 'utf8')); }
+    catch (cause) { throw new LoaderError('CONFIG_READ', `Cannot read JSON configuration ${canonical}`, { file: canonical }, cause); }
+    try { return await entries(raw, parent, canonical); } finally { stack.pop(); }
+  }
+  async function entries(tree, parent, base) {
+    if (!Array.isArray(tree)) {
+      object(tree, 'configuration');
+      if (Object.keys(tree).some(key => key !== 'entries')) throw new LoaderError('INVALID_CONFIG', 'The config object supports only entries');
+      tree = tree.entries;
+    }
+    if (!Array.isArray(tree)) throw new LoaderError('INVALID_CONFIG', 'Configuration must be an entries array');
+    const result = [];
+    for (const raw of tree) {
+      object(raw, 'entry');
+      const item = freezeJSON(jsonValue(raw));
+      const allowed = ['id', 'name', 'config', 'inject', 'isolate', 'intercept', 'disabled', 'group', 'entries', 'include'];
+      const unknown = Object.keys(item).filter(key => !allowed.includes(key));
+      if (unknown.length) throw new LoaderError('INVALID_CONFIG', `Unknown entry fields: ${unknown.join(', ')}`);
+      if (typeof item.id !== 'string' || !/^[A-Za-z0-9_.-]+$/.test(item.id)) throw new LoaderError('INVALID_CONFIG', 'Every entry needs a stable id containing letters, digits, _, - or .');
+      const id = parent ? `${parent}/${item.id}` : item.id;
+      if (ids.has(id)) throw new LoaderError('DUPLICATE_ENTRY', `Duplicate entry id ${id}`);
+      ids.add(id);
+      if (item.disabled !== undefined && typeof item.disabled !== 'boolean') throw new LoaderError('INVALID_CONFIG', `${id}.disabled must be boolean`);
+      if (item.group !== undefined && typeof item.group !== 'boolean') throw new LoaderError('INVALID_CONFIG', `${id}.group must be boolean`);
+      if (item.inject !== undefined && !(Array.isArray(item.inject) ? item.inject.every(name => typeof name === 'string' && name.length) : item.inject && typeof item.inject === 'object')) throw new LoaderError('INVALID_CONFIG', `${id}.inject must be service names or a config object`);
+      if (item.intercept !== undefined) object(item.intercept, `${id}.intercept`);
+      if (item.isolate !== undefined && !(Array.isArray(item.isolate) ? item.isolate.every(name => typeof name === 'string' && name.length) : item.isolate && typeof item.isolate === 'object' && Object.values(item.isolate).every(label => label === true || typeof label === 'string'))) throw new LoaderError('INVALID_CONFIG', `${id}.isolate must be service names or name-to-label mapping`);
+      const group = item.group === true || item.include !== undefined;
+      if (group) {
+        if (item.name !== undefined || item.config !== undefined) throw new LoaderError('INVALID_CONFIG', `${id}: a group cannot have name or config`);
+        if (item.include !== undefined && item.entries !== undefined) throw new LoaderError('INVALID_CONFIG', `${id}: include and entries are mutually exclusive`);
+      } else if (typeof item.name !== 'string' || !item.name || item.entries !== undefined) throw new LoaderError('INVALID_CONFIG', `${id}: a plugin requires name; children require group: true`);
+      const children = group ? item.include !== undefined ? await fromFile(item.include, id, base) : await entries(item.entries ?? [], id, base) : [];
+      result.push({ id, options: item, baseURL: base, group, children });
+    }
+    return result;
+  }
+  const tree = typeof input === 'string' || input instanceof URL ? await fromFile(input, '', baseURL) : await entries(jsonValue(input), '', baseURL);
+  return { tree, files: [...files] };
+}

package/domain-entry.js

@@ -0,0 +1,85 @@
+import { join } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { LoaderError, jsonValue } from './config.js';
+import { ModuleGraph } from './module-graph.js';
+
+const serialize = (error, depth = 0) => ({ name: error?.name ?? 'Error', message: error?.message ?? String(error), code: error?.code, details: error?.details, cause: depth < 8 && error?.cause ? serialize(error.cause, depth + 1) : undefined });
+
+/** One runtime per child. The transport has no lifecycle scheduler of its own. */
+export function startEndpoint(channel, launch, options = {}) {
+  let graph;
+  let host, startupError, closing = false, shutdown;
+  const calls = new Set();
+  const startup = (async () => {
+    if (options.hostModule) {
+      const { url, sha256 } = options.hostModule;
+      const verify = async () => {
+        if (createHash('sha256').update(await readFile(new URL(url))).digest('hex') !== sha256) throw new LoaderError('HOST_CHANGED', 'The trusted host module changed after it was pinned');
+      };
+      await verify();
+      const module = await import(url);
+      await verify();
+      if (typeof module.createHost !== 'function') throw new LoaderError('HOST_CONTRACT', 'Trusted host must export synchronous createHost(options)');
+      graph = new ModuleGraph(launch.directory, options).install();
+      const candidate = module.createHost({ directory: launch.directory, entry: launch.entry, allowPending: launch.allowPending });
+      if (!candidate || typeof candidate.then === 'function' || typeof candidate.ready?.then !== 'function' || ['call', 'diagnostics', 'close'].some(key => typeof candidate[key] !== 'function')) throw new LoaderError('HOST_CONTRACT', 'createHost must immediately expose call(), diagnostics(), close(), and a ready Promise');
+      host = candidate;
+      await host.ready;
+    } else {
+      await import('@validation-engineering/cordis/register');
+      graph = new ModuleGraph(launch.directory, options).install();
+      const { Context } = await import('@validation-engineering/cordis');
+      const { Loader, ModuleHost } = await import('./index.js');
+      const ctx = new Context();
+      const loader = new Loader(ctx, { moduleHost: new ModuleHost({ rootDirectory: launch.directory }), allowPending: launch.allowPending });
+      host = {
+        diagnostics: () => JSON.parse(JSON.stringify(loader.diagnostics())),
+        call: async (service, member, args) => {
+          const value = ctx.get(service);
+          if (value === undefined || typeof value[member] !== 'function') throw new LoaderError('SERVICE_METHOD', `Missing service method ${service}.${member}`);
+          return Reflect.apply(value[member], value, args);
+        },
+        close: async () => { await loader.dispose(); await ctx.dispose(); },
+      };
+      await loader.loadFile(join(launch.directory, launch.entry));
+    }
+    await channel.send({ type: 'ready', diagnostics: jsonValue(await host.diagnostics()) });
+  })().catch(async error => {
+    startupError = error;
+    await channel.send({ type: 'startup-error', error: serialize(error) });
+  });
+  startup.catch(() => {});
+  channel.listen(request => {
+    if (!request || typeof request !== 'object' || Array.isArray(request) || !Number.isSafeInteger(request.id) || typeof request.method !== 'string') return;
+    const execute = async () => {
+      if (request.method === 'shutdown') {
+        closing = true;
+        shutdown ??= (async () => {
+          await startup;
+          await Promise.allSettled([...calls]);
+          if (!host) throw new LoaderError('CLEANUP_BLOCKED', 'Startup did not expose a host cleanup controller; explicit abandonment is required', {}, startupError);
+          await host.close();
+          return { disposed: true };
+        })();
+        try { return await shutdown; } catch (error) { shutdown = undefined; throw error; }
+      }
+      if (closing) throw new LoaderError('DOMAIN_CLOSING', 'The isolated domain is closing');
+      await startup;
+      if (startupError) throw startupError;
+      if (request.method === 'diagnostics') return jsonValue(await host.diagnostics());
+      if (request.method === 'moduleGraph') return graph.snapshot();
+      if (request.method !== 'call') throw new LoaderError('DOMAIN_METHOD', 'Unsupported isolated domain request');
+      const { service, member, args } = request;
+      if (['constructor', '__proto__', 'prototype'].includes(member)) throw new LoaderError('SERVICE_METHOD', 'Reserved service method');
+      return jsonValue(await host.call(service, member, args));
+    };
+    const task = execute();
+    if (request.method !== 'shutdown') calls.add(task);
+    task.then(async result => {
+      await channel.send({ type: 'reply', id: request.id, result });
+      if (request.method === 'shutdown') channel.close();
+    }, error => channel.send({ type: 'reply', id: request.id, error: serialize(error) }))
+      .catch(() => {}).finally(() => calls.delete(task));
+  });
+}

package/index.d.ts

@@ -0,0 +1,83 @@
+import type { Context, Fiber, Plugin } from '@validation-engineering/cordis';
+export type JSONValue = null | boolean | number | string | JSONValue[] | { [key: string]: JSONValue };
+export type Injection = string[] | Record<string, JSONValue>;
+export type Isolation = string[] | Record<string, true | string>;
+export interface EntryOptions {
+  id: string;
+  name?: string;
+  config?: JSONValue;
+  inject?: Injection;
+  isolate?: Isolation;
+  intercept?: Record<string, JSONValue>;
+  disabled?: boolean;
+  group?: boolean;
+  entries?: EntryOptions[];
+  include?: string;
+}
+export type ConfigTree = EntryOptions[] | { entries: EntryOptions[] };
+export type EntryState = 'pending' | 'loading' | 'active' | 'failed' | 'disposed' | 'unloading' | 'disabled';
+export interface EntryDiagnostic {
+  id: string;
+  parentId: string | null;
+  moduleURL: string | null;
+  state: EntryState;
+  unavailableServices: string[];
+  fiberId?: string;
+}
+/** Already prepared executable factory; this does not invalidate Node module caches. */
+export interface PreparedModule { plugin: Plugin; namespace?: unknown; revision?: string | number; }
+export interface LoadedModule extends PreparedModule { url: string; directory: string; }
+export interface EntryNode {
+  id: string;
+  options: EntryOptions;
+  baseURL: string;
+  group: boolean;
+  children: EntryNode[];
+  disabled?: boolean;
+  module?: LoadedModule;
+}
+export interface Recipe { tree: EntryNode[]; files: string[]; }
+export class LoaderError extends Error {
+  readonly code: string;
+  readonly details: Record<string, unknown>;
+  constructor(code: string, message: string, details?: Record<string, unknown>, cause?: unknown);
+}
+export class ModuleHost {
+  constructor(options?: { rootDirectory?: string; loadModule?: (canonicalURL: string) => PreparedModule | Promise<PreparedModule> });
+  resolve(specifier: string, baseURL: string): Promise<string>;
+  load(specifier: string, baseURL: string): Promise<LoadedModule>;
+  prepare(input: Recipe): Promise<Recipe>;
+  reset(): never;
+}
+export function readConfig(input: string | URL | ConfigTree, options?: { baseURL?: string; rootDirectory?: string }): Promise<Recipe>;
+export class Include {
+  static read(filename: string | URL, options?: { baseURL?: string; rootDirectory?: string }): Promise<Recipe>;
+}
+export class Entry {
+  readonly id: string;
+  readonly parentId?: string;
+  readonly options: Readonly<EntryOptions>;
+  readonly disabled: boolean;
+  readonly moduleURL?: string;
+  readonly fiber?: Fiber;
+  readonly context?: Context;
+  readonly state: EntryState;
+}
+export class Loader {
+  constructor(context?: Context, options?: { moduleHost?: ModuleHost; baseURL?: string; allowPending?: boolean });
+  readonly ctx: Context;
+  readonly moduleHost: ModuleHost;
+  readonly state: 'empty' | 'reloading' | 'active' | 'blocked' | 'closed';
+  readonly revision: number;
+  readonly lastRecovery?: { restored: true; cause: unknown };
+  entries(): IterableIterator<Entry>;
+  resolve(id: string): Entry;
+  apply(tree: ConfigTree, options?: { baseURL?: string }): Promise<EntryDiagnostic[]>;
+  loadFile(filename: string | URL): Promise<EntryDiagnostic[]>;
+  reload(): Promise<EntryDiagnostic[]>;
+  update(id: string, patch: Partial<Pick<EntryOptions, 'name' | 'config' | 'inject' | 'isolate' | 'intercept' | 'disabled'>>): Promise<EntryDiagnostic[]>;
+  setEnabled(id: string, enabled: boolean): Promise<EntryDiagnostic[]>;
+  diagnostics(): EntryDiagnostic[];
+  retryCleanup(): Promise<void>;
+  dispose(): Promise<void>;
+}