@validation-engineering/cordis-loader 0.0.0-stage → 0.1.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,225 @@
-# 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.
+
+## Explicit transactions for the official Harness Loader
+
+The separate `@validation-engineering/cordis-loader/harness` entry adapts the **installed,
+unchanged** official Harness `Loader` and `Include` classes. It does not replace
+this package's JSON API. `LoaderTransactions` offers explicit host operations;
+`installOfficialTransactions` additionally connects the official configuration UI
+and refresh/HMR queues when installed by the application before boot.
+The tested contract is Harness Cordis 4.0.4, Loader 1.0.5 and Include 1.0.9.
+Use the native Harness profile and a live, fully initialized tree:
+
+```js
+import { LoaderTransactions } from '@validation-engineering/cordis-loader/harness';
+
+// ctx and ctx.loader already belong to the booted official application.
+// Select an Include file owned by this host, not an unrelated profile overlay.
+const edits = new LoaderTransactions(ctx, ctx.loader.resolve('custom').subtree);
+await edits.update('greeting', { config: { prefix: 'Welcome' } });
+const id = await edits.create({ name: './another-plugin.mjs', config: {} });
+// create preserves the official fully qualified id; resolve it from the root.
+const rootEdits = new LoaderTransactions(ctx, ctx.loader);
+await rootEdits.remove(id);
+await edits.close(); // closes this adapter's admission; does not dispose the tree
+```
+
+`create`, `update` and `remove` enter the same domain FIFO as Fiber revisions,
+JSON Loader updates and Context shutdown **before** changing options or files.
+Cloneable options are snapshotted at admission, including `undefined` deletion
+values; functions and other non-cloneable values reject before admission.
+The adapter retains old and new Fibers, waits for official Loader and native
+lifecycle work, and observes the actual Include write queues, including writes
+scheduled by timers or teardown. This is conservatively a **whole Loader graph
+barrier**: sibling Includes and existing work may delay it or report failure.
+Use it from an external host operation, outside plugin setup/cleanup actions.
+
+Success means that the observed lifecycle and persistence work completed. It is
+not an atomic rollback mechanism or a guarantee of physical-disk durability after
+power loss. An `OFFICIAL_PERSISTENCE_FAILED` error names affected files and retains
+causes; running plugin changes may already have happened. A subsequent explicit
+revision can retry the official write queue. Cleanup failures still block new
+revisions until actual cleanup recovery succeeds. Pending dependencies retain
+upstream Pending semantics; completion does not certify every plugin Active.
+`revision` counts successful operations, `requestedRevision` counts admitted
+requests, and `lastFailure` retains the last failed request's operation and error.
+
+A cached adapter belongs to its tree owner's current episode. If that Include
+is removed or restarted, `STALE_LOADER` rejects old requests before mutation;
+obtain a new adapter for the new tree. Foreign domains, incompatible class shapes
+and methods replaced after construction are rejected. Nested removal selects the
+entry's owning tree and local id before invoking the unchanged official method.
+
+The bridge uses `MutationSteps.capture(callback)`, whose authority lasts only
+through the callback's synchronous call stack in that domain. A returned Promise
+does not extend that authority; plugin lifecycle callbacks and async update
+continuations cannot borrow it. Ignored lifecycle Promises are still joined.
+
+The explicit adapter does not intercept arbitrary direct object or file mutations.
+Applications can additionally call `installOfficialTransactions` with the pinned
+`Entry`, `EntryGroup`, `EntryTree`, `Hmr` and `ConfigEditor` classes **before boot**.
+The companion Harness application already installs it in its default preload.
+That host bridge admits ConfigEditor edits before acquiring the profile file lock,
+then keeps write/reconcile/rollback and Include refresh in the same domain slot.
+It also orders `hmr.runExclusive` with configuration and shutdown work. The original
+methods still implement the configuration semantics; no upstream source files
+are rewritten. See [official configuration transactions](../../docs/official-config-transactions.md)
+for setup, failure and callback contracts.
+
+A failed inverse is not automatically retried by rollback. Readiness and restart
+report the retained native barrier even when a transient JavaScript error has
+already been observed; explicit cleanup recovery is required. Event and edit
+callbacks cannot borrow transaction steps. `steps.observe(fiber, callback)` retains
+the callback's episode identity, and `steps.isCurrent()` lets a trusted bridge
+check its exact coordinator origin before capturing a synchronous continuation.
+These are host APIs, not a sandbox for arbitrary application code.
+
+Official main-thread `partialReload()` now performs dependency-closed ESM/CJS
+replacement in the existing Context. It waits for old cleanup before changing
+caches, preserves unrelated identities and retains a recovery journal when
+candidate cleanup or old restoration fails. The official watcher includes pure
+CJS leaves. See [in-place HMR](../../docs/official-in-place-hmr.md) for observed
+graph coverage, concurrency, failure and native-addon boundaries.
+[Worker module graphs](../../docs/module-graph-reloads.md) replace a complete
+captured environment; application native addons use `ProcessDomain` below.
+Runtime shape checks do not certify a different upstream version or arbitrary
+EntryTree subclass.
+
+The core gate checks admission contracts, callback isolation and type declarations;
+the companion `cordis-harness` gate executes installed official classes, default
+boot, real JSON/YAML edits, write/rollback failures, cleanup barriers and stale
+owner rejection. These are behavioral checks, not proofs of filesystem durability
+or arbitrary callback effects.
+
+## 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/harness.d.ts

@@ -0,0 +1,57 @@
+import type { Context } from '@validation-engineering/cordis';
+
+/** Structural surface of the pinned official Harness Loader/Include classes. */
+export interface OfficialEntryTree {
+  ctx: object;
+  root: { tree: OfficialEntryTree; data: unknown[] };
+  store: Record<string, { fiber?: object; subtree?: OfficialEntryTree }>;
+  entries(): Iterable<unknown>;
+  getTasks(): Promise<unknown>[];
+  await(): Promise<void>;
+  resolve(id: string): unknown;
+  resolveGroup(id: string | null): unknown;
+  create(options: { name: string; [key: string]: any }, parent?: string | null, position?: number): Promise<string>;
+  update(id: string, options: Record<string, any>, parent?: string | null, position?: number): Promise<void>;
+  remove(id: string): void;
+  write(): void;
+}
+export class LoaderTransactions {
+  constructor(ctx: Context, tree: OfficialEntryTree);
+  readonly ctx: Context;
+  readonly tree: OfficialEntryTree;
+  /** Number of successful create/update/remove operations. */
+  readonly revision: number;
+  /** Number of admitted operations, including queued or failed operations. */
+  readonly requestedRevision: number;
+  readonly lastFailure: { revision: number; operation: 'create' | 'update' | 'remove'; error: unknown } | undefined;
+  readonly closed: boolean;
+  /** Options are structured-cloned at admission. */
+  create(options: { name: string; [key: string]: any }, parent?: string | null, position?: number): Promise<string>;
+  update(id: string, options: Record<string, any>, parent?: string | null, position?: number): Promise<void>;
+  remove(id: string): Promise<void>;
+  /** Closes this adapter's admission and drains earlier work; does not dispose the tree. */
+  close(): Promise<void>;
+}
+
+/** Installs transparent host-only domain coordination before mounting pinned official classes. */
+export function installOfficialTransactions(classes: {
+  Entry: Function; EntryGroup: Function; EntryTree: Function; Hmr: Function; ConfigEditor: Function;
+}): void;
+
+/** Additional structural HMR surface installed on the pinned official service. */
+export interface OfficialHmrTransactions {
+  /** Current retained cleanup/restoration failure; cleared when its journal recovers. */
+  readonly lastReloadFailure: (Error & { code: string; details: { restored?: boolean; cacheChanged?: boolean } }) | undefined;
+  /** Canonical file URLs changed since the last admitted batch. */
+  readonly stashed: Set<string>;
+  /** Joins an existing official transaction or admits through the domain FIFO. */
+  partialReload(): Promise<void>;
+  runExclusive<T>(operation: () => T | Promise<T>): Promise<T>;
+}
+
+/** Admit one host revision around official ConfigEditor/HMR calls and readiness
+ * checks. Official methods join this exact coordinator after awaits; lifecycle
+ * and config-change callbacks remain observers and cannot borrow its authority.
+ * The callback must perform its own application-level restoration on failure.
+ */
+export function officialTransaction<T>(context: Context, execute: () => T | PromiseLike<T>): Promise<Awaited<T>>;