@validation-engineering/cordis-loader 0.1.0 → 0.2.1

package/README.md

@@ -60,96 +60,18 @@ The Loader imports modules and validates candidate JSON inputs before disturbing
 
 `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.
+## 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
 

package/module-graph.js

@@ -12,8 +12,8 @@ const facadeURLs = new Set([
 ]);
 const harnessURLs = new Set();
 try {
-  harnessURLs.add(import.meta.resolve('@validation-engineering/cordis-harness'));
-  harnessURLs.add(pathToFileURL(require.resolve('@validation-engineering/cordis-harness')).href);
+  harnessURLs.add(import.meta.resolve('@validation-engineering/cordis-compat-deepseek'));
+  harnessURLs.add(pathToFileURL(require.resolve('@validation-engineering/cordis-compat-deepseek')).href);
 } catch { /* Harness is optional for the default Cordis host. */ }
 
 /** Observed Node module edges in one Worker, not a static parser or cache reset. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@validation-engineering/cordis-loader",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "Experimental JSON module loader over the native Cordis facade",
   "engines": {
@@ -15,10 +15,6 @@
       "types": "./worker.d.ts",
       "import": "./worker.js"
     },
-    "./harness": {
-      "types": "./harness.d.ts",
-      "import": "./harness.js"
-    },
     "./process": {
       "types": "./process.d.ts",
       "import": "./process.js"
@@ -33,7 +29,7 @@
     }
   },
   "peerDependencies": {
-    "@validation-engineering/cordis": "0.1.0"
+    "@validation-engineering/cordis": "0.2.0"
   },
   "license": "MIT",
   "publishConfig": {

package/harness.d.ts

@@ -1,57 +0,0 @@
-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>>;

package/harness.js

@@ -1,394 +0,0 @@
-import { AsyncLocalStorage } from 'node:async_hooks';
-import { FiberState, assertDomainMutation, domainMutation } from '@validation-engineering/cordis';
-import { LoaderError } from './config.js';
-import { installModuleObservation, reloadModules } from './official-hmr.js';
-
-const methods = ['entries', 'getTasks', 'await', 'resolve', 'resolveGroup', 'create', 'update', 'remove', 'write'];
-const incompatible = message => new LoaderError('INCOMPATIBLE_OFFICIAL_LOADER', message);
-const thenable = value => value && typeof value.then === 'function';
-
-// This deliberately recognizes the pinned Harness Loader/Include contract. It
-// does not turn an arbitrary EntryTree subclass into a durable configuration API.
-function canonicalTree(tree) {
-  // Cordis exposes services through context-bound tracing proxies. EntryGroup
-  // retains the actual tree, so use that identity without changing its methods.
-  const original = tree?.root?.tree;
-  if (original && original !== tree && original.store === tree.store) return original;
-  return tree;
-}
-
-function isInclude(tree) {
-  return tree?.constructor?.name === 'Include' || tree?.constructor?.name === 'HostResolvedRootInclude'
-    && Object.getPrototypeOf(tree.constructor.prototype)?.constructor?.name === 'Include';
-}
-
-function inspectTree(tree, domain, allowRetired = false) {
-  if (!tree || typeof tree !== 'object' || !tree.ctx?.fiber?._domain) throw incompatible('Expected an official Harness Loader or Include tree');
-  if (tree.ctx.fiber._domain !== domain) throw new LoaderError('FOREIGN_DOMAIN', 'Loader tree belongs to another execution domain');
-  if (!(tree.constructor?.name === 'Loader' || isInclude(tree))
-    || methods.some(name => typeof tree[name] !== 'function')
-    || tree.root?.tree !== tree || !Array.isArray(tree.root.data) || !tree.store || typeof tree.store !== 'object') {
-    throw incompatible('Unsupported official Loader tree contract');
-  }
-  if (!allowRetired && (tree.ctx.fiber.uid === null || tree.ctx.fiber._removedFlag
-    || [FiberState.DISPOSED, FiberState.UNLOADING].includes(tree.ctx.fiber.state))) {
-    throw new LoaderError('STALE_LOADER', 'The official tree owner has been disposed or is unloading');
-  }
-  const include = isInclude(tree);
-  if (include && (typeof tree.filename !== 'string' || typeof tree.flushWrite !== 'function'
-    || typeof tree._writeFile !== 'function' || typeof tree.readonly !== 'boolean' || !thenable(tree.writeQueue)
-    || !Object.hasOwn(tree, 'pendingWrite') || !Object.hasOwn(tree, 'writeTask'))) {
-    throw incompatible('Include requires the pinned pendingWrite/flushWrite/writeQueue persistence contract');
-  }
-  return include;
-}
-
-function optionsCopy(options) {
-  if (!options || typeof options !== 'object' || Array.isArray(options)) throw new TypeError('Loader options must be an object');
-  // The official methods mutate their options. Give each queued revision its own
-  // copy, including undefined values used by Entry.update to delete fields.
-  return structuredClone(options);
-}
-
-/** Explicit transactions around the unchanged, pinned Harness EntryTree API. */
-export class LoaderTransactions {
-  constructor(ctx, tree) {
-    const domain = ctx?.fiber?._domain;
-    if (!domain || domain.profile !== 'harness') throw incompatible('LoaderTransactions requires a native Harness-profile Context');
-    tree = canonicalTree(tree);
-    inspectTree(tree, domain);
-    this.ctx = ctx;
-    this.tree = tree;
-    this.revision = 0;
-    this.requestedRevision = 0;
-    this.lastFailure = undefined;
-    this.closed = false;
-    this._accepting = true;
-    this._domain = domain;
-    this._ownerGeneration = tree.ctx.fiber._generation;
-    this._contract = new Map(methods.map(name => [name, tree[name]]));
-  }
-
-  create(options, parent = null, position = Infinity) {
-    return this._submit('create', () => [optionsCopy(options), parent, position]);
-  }
-  update(id, options, parent, position) {
-    return this._submit('update', () => [id, optionsCopy(options), parent, position]);
-  }
-  remove(id) { return this._submit('remove', () => [id]); }
-
-  _check() {
-    inspectTree(this.tree, this._domain);
-    if (this.tree.ctx.fiber._generation !== this._ownerGeneration) throw new LoaderError('STALE_LOADER', 'The official tree belongs to a previous owner activation');
-    for (const [name, original] of this._contract) {
-      if (this.tree[name] !== original) throw incompatible(`Official tree method ${name} changed after adapter creation`);
-    }
-  }
-
-  _invoke(operation, args) {
-    if (operation !== 'remove') return Reflect.apply(this._contract.get(operation), this.tree, args);
-    const entry = this.tree.resolve(args[0]);
-    const owner = canonicalTree(entry?.parent?.tree);
-    inspectTree(owner, this._domain);
-    const id = entry.options?.id;
-    if (typeof id !== 'string' || owner.store[id] !== entry) throw incompatible('Entry removal requires its original containing tree and local id');
-    // The pinned root remove() forwards a qualified id into a local store. Use
-    // the same official method on the owning tree with its actual local id.
-    return owner.remove(id);
-  }
-
-  _submit(operation, prepare) {
-    let args, request;
-    try {
-      assertDomainMutation(this.ctx);
-      if (!this._accepting) throw new LoaderError('LOADER_CLOSED', 'Loader transaction adapter is closing or closed');
-      this._check();
-      args = prepare();
-      request = ++this.requestedRevision;
-    } catch (error) { return Promise.reject(error); }
-    const task = domainMutation(this.ctx, async steps => {
-      this._check();
-      return this._run(steps, () => this._invoke(operation, args));
-    });
-    return task.then(value => {
-      this.revision++;
-      this.lastFailure = undefined;
-      return value;
-    }, error => {
-      this.lastFailure = { revision: request, operation, error };
-      throw error;
-    });
-  }
-
-  async _run(steps, invoke, closing = false) {
-    const trees = new Set(), fibers = new Set(), hooks = new Map();
-    const writes = new Map(), failures = [], writeFailures = [];
-    const remember = error => { if (!failures.includes(error)) failures.push(error); };
-    const observe = (tree, promise, prior = false) => {
-      if (!thenable(promise)) throw incompatible('Include.flushWrite must return its persistence promise');
-      if (!writes.has(promise)) writes.set(promise, Promise.resolve(promise).catch(error => { writeFailures.push({ tree, error, promise, prior }); }));
-      return promise;
-    };
-    const hook = tree => {
-      if (hooks.has(tree)) return;
-      const descriptor = Object.getOwnPropertyDescriptor(tree, 'flushWrite');
-      if (descriptor && (!('value' in descriptor) || !descriptor.configurable)) throw incompatible('Include.flushWrite cannot be observed safely');
-      const original = tree.flushWrite;
-      const wrapped = function (...args) {
-        try { return observe(tree, Reflect.apply(original, this, args)); }
-        catch (error) { writeFailures.push({ tree, error }); throw error; }
-      };
-      Object.defineProperty(tree, 'flushWrite', { value: wrapped, configurable: true, writable: true });
-      hooks.set(tree, { descriptor, wrapped });
-      observe(tree, tree.writeQueue, true);
-    };
-    const visit = source => {
-      const tree = canonicalTree(source);
-      const include = inspectTree(tree, this._domain, trees.has(tree));
-      trees.add(tree);
-      if (include) hook(tree);
-      for (const entry of Object.values(tree.store)) {
-        if (entry.fiber) {
-          if (entry.fiber._domain !== this._domain) throw new LoaderError('FOREIGN_DOMAIN', 'Entry fiber belongs to another execution domain');
-          fibers.add(entry.fiber);
-        }
-        if (entry.subtree && !scanned.has(entry.subtree)) { scanned.add(entry.subtree); visit(entry.subtree); }
-      }
-    };
-    let scanned;
-    const discover = () => {
-      scanned = new Set();
-      for (const tree of [this.tree, canonicalTree(this.tree.ctx.loader)]) {
-        if (tree && !scanned.has(tree)) { scanned.add(tree); visit(tree); }
-      }
-    };
-    const flush = () => {
-      for (const tree of hooks.keys()) {
-        try { observe(tree, tree.flushWrite()); } catch (error) { remember(error); }
-      }
-    };
-    const drainWrites = async () => {
-      // Timers and stop() may have added another queued write while an earlier
-      // filesystem operation was pending. Keep the slot until all observed runs
-      // have landed, including failures followed by a successful retry.
-      while (true) {
-        flush();
-        const count = writes.size;
-        await Promise.all(writes.values());
-        if (writes.size === count && [...hooks.keys()].every(tree => tree.pendingWrite === undefined && tree.writeTask === undefined)) break;
-      }
-    };
-    let listener, value;
-    try {
-      discover();
-      // Include emits this before scheduling its timer. Discover newly created
-      // Include subtrees in time to observe their first ordinary write as well.
-      if (!closing) listener = this.ctx.on('loader/config-update', discover, { global: true });
-      let result;
-      try { result = steps.capture(invoke); } catch (error) { remember(error); }
-      // Flush the synchronous revision before yielding: a following revision
-      // cannot overtake this write even if plugin cleanup is asynchronous.
-      try { discover(); } catch (error) { remember(error); }
-      flush();
-      try { value = await result; } catch (error) { remember(error); }
-      try { discover(); } catch (error) { remember(error); }
-      for (const tree of trees) {
-        try { await tree.await(); } catch (error) { remember(error); }
-      }
-      try { await this.ctx.settle(); } catch (error) { remember(error); }
-      try { discover(); } catch (error) { remember(error); }
-      for (const fiber of fibers) {
-        // HMR explicitly joined this disposal; a removed prior generation's
-        // historical setup error must not poison a successful recovery.
-        if (fiber._removedFlag && scoped(this.ctx)?.retired.has(fiber)) continue;
-        try { await fiber.await(); } catch (error) { remember(error); }
-      }
-    } catch (error) { remember(error); }
-    finally {
-      try { await drainWrites(); } catch (error) { remember(error); }
-      try { listener?.(); } catch (error) { remember(error); }
-      for (const [tree, { descriptor, wrapped }] of hooks) {
-        try {
-          if (tree.flushWrite !== wrapped) throw incompatible('Include.flushWrite changed during a transaction');
-          if (descriptor) Object.defineProperty(tree, 'flushWrite', descriptor);
-          else delete tree.flushWrite;
-        } catch (error) { remember(error); }
-      }
-    }
-    // The previous revision may have left a rejected queue. Include explicitly
-    // retries through that rejection when a new write is scheduled. A successful
-    // new write recovers that historical failure, but never hides a failure of
-    // any write started during this revision.
-    const persistenceFailures = writeFailures.filter(({ tree, promise, prior }) => !prior || tree.writeQueue === promise);
-    if (persistenceFailures.length) {
-      const errors = [...new Set([...failures, ...persistenceFailures.map(({ error }) => error)])];
-      throw new LoaderError('OFFICIAL_PERSISTENCE_FAILED', 'Official Include persistence failed; in-memory changes have not been rolled back',
-        { files: [...new Set(persistenceFailures.map(({ tree }) => tree.filename))] }, new AggregateError(errors, 'Loader revision and persistence errors'));
-    }
-    if (failures.length > 1 && failures[0] instanceof LoaderError && failures[0].code.startsWith('OFFICIAL_HMR_')) {
-      const first = failures[0];
-      throw new LoaderError(first.code, first.message, first.details, new AggregateError(failures, 'HMR revision and lifecycle errors'));
-    }
-    if (failures.length === 1) throw failures[0];
-    if (failures.length) throw new AggregateError(failures, 'Official Loader revision failed');
-    return value;
-  }
-
-  /** Stop admission and wait for earlier revisions; does not dispose the tree. */
-  close() {
-    try { assertDomainMutation(this.ctx, { recovery: true }); }
-    catch (error) { return Promise.reject(error); }
-    if (this._closeTask) return this._closeTask;
-    this._accepting = false;
-    const task = domainMutation(this.ctx, async steps => {
-      this._check();
-      await this._run(steps, () => undefined, true);
-      this.closed = true;
-    }, { recovery: true }).catch(error => { this._closeTask = undefined; throw error; });
-    this._closeTask = task;
-    return task;
-  }
-}
-
-
-// The scope carries no authority by itself. Every bridge checks the runtime's
-// exact coordinator origin again, including after official asynchronous I/O.
-const officialScope = new AsyncLocalStorage();
-const installedContracts = new WeakMap();
-const refreshedTrees = new WeakMap();
-
-function scoped(ctx) {
-  const scope = officialScope.getStore();
-  if (!scope?.steps.isCurrent()) return;
-  if (ctx?.fiber?._domain !== scope.domain) throw new LoaderError('FOREIGN_DOMAIN', 'Official operation crossed execution domains');
-  return scope;
-}
-
-function serviceCheck(service, name) {
-  const ctx = service.ownerContext;
-  const fiber = ctx?.fiber;
-  const original = value => value?.[Symbol.for('cordis.original')] ?? value;
-  if (!fiber || fiber.uid === null || fiber._removedFlag || fiber.state !== FiberState.ACTIVE
-    || original(ctx.get(name)) !== original(service)) {
-    throw new LoaderError('STALE_OFFICIAL_SERVICE', `Official ${name} belongs to an inactive or replaced service`);
-  }
-  return ctx;
-}
-
-function coordinate(ctx, execute) {
-  try { assertDomainMutation(ctx); }
-  catch (error) { return Promise.reject(error); }
-  return domainMutation(ctx, steps => {
-    const adapter = new LoaderTransactions(ctx.root, canonicalTree(ctx.loader));
-    return officialScope.run({ domain: ctx.fiber._domain, steps, retired: new Set() }, () => adapter._run(steps, execute));
-  });
-}
-
-/** Compose official host operations and application readiness checks in one
- * domain revision. Managed callbacks cannot borrow this transaction's authority.
- */
-export function officialTransaction(ctx, execute) {
-  if (typeof execute !== 'function') return Promise.reject(new TypeError('officialTransaction requires a callback'));
-  return coordinate(ctx, execute);
-}
-
-function installRefresh(tree) {
-  if (!isInclude(tree) || refreshedTrees.has(tree)) return;
-  const original = tree.refresh;
-  if (typeof original !== 'function') throw incompatible('Official Include.refresh is unavailable');
-  const owner = tree.ctx.fiber, generation = owner._generation;
-  const check = () => {
-    if (owner.uid === null || owner._removedFlag || owner._generation !== generation
-      || [FiberState.DISPOSED, FiberState.UNLOADING].includes(owner.state)) {
-      throw new LoaderError('STALE_LOADER', 'Cannot refresh an Include from a previous owner activation');
-    }
-  };
-  const wrapped = function (...args) {
-    const invoke = () => { check(); return Reflect.apply(original, this, args); };
-    try {
-      check();
-      return scoped(tree.ctx) ? invoke() : coordinate(tree.ctx.root, invoke);
-    } catch (error) { return Promise.reject(error); }
-  };
-  Object.defineProperty(tree, 'refresh', { value: wrapped, configurable: true, writable: true });
-  refreshedTrees.set(tree, { original, wrapped });
-}
-
-/**
- * Install host-only bridges on the pinned official classes before mounting the
- * application. Official methods, filesystem locks, rollback, watcher dispatch
- * and config semantics still execute unchanged. The domain queue is outermost.
- */
-export function installOfficialTransactions({ Entry, EntryGroup, EntryTree, Hmr, ConfigEditor }) {
-  const classes = [Entry, EntryGroup, EntryTree, Hmr, ConfigEditor];
-  if (classes.some(value => typeof value !== 'function' || !value.prototype)) throw incompatible('All five pinned official classes are required');
-  const previous = classes.map(value => installedContracts.get(value)).find(Boolean);
-  if (previous) {
-    if (classes.some((value, index) => value !== previous[index])) throw incompatible('Official transaction installation changed class identities');
-    return;
-  }
-  const contracts = [
-    [Entry.prototype, ['update'], entry => entry.ctx],
-    [EntryGroup.prototype, ['update', 'create', 'remove', 'stop'], group => group.ctx],
-    [EntryTree.prototype, ['create', 'update', 'remove'], tree => tree.ctx],
-  ];
-  for (const [prototype, names] of contracts) for (const name of names) {
-    if (typeof prototype[name] !== 'function') throw incompatible(`Official Loader contract lacks ${name}`);
-  }
-  if (typeof Hmr.prototype.runExclusive !== 'function' || typeof ConfigEditor.prototype.edit !== 'function') {
-    throw incompatible('Official HMR/ConfigEditor transaction entrypoints are unavailable');
-  }
-  for (const [prototype, names, context] of contracts) for (const name of names) {
-    const original = prototype[name];
-    prototype[name] = function (...args) {
-      installRefresh(this.tree ?? this.parent?.tree ?? this);
-      const scope = scoped(context(this));
-      return scope ? scope.steps.capture(() => Reflect.apply(original, this, args)) : Reflect.apply(original, this, args);
-    };
-  }
-  const exclusive = Hmr.prototype.runExclusive;
-  Hmr.prototype.runExclusive = function (operation) {
-    try {
-      const ctx = serviceCheck(this, 'hmr');
-      const generation = ctx.fiber._generation;
-      const invoke = () => {
-        serviceCheck(this, 'hmr');
-        if (ctx.fiber._generation !== generation) throw new LoaderError('STALE_OFFICIAL_SERVICE', 'HMR changed while its operation was queued');
-        return Reflect.apply(exclusive, this, [operation]);
-      };
-      return scoped(ctx) ? invoke() : coordinate(ctx.root, invoke);
-    } catch (error) { return Promise.reject(error); }
-  };
-  installModuleObservation(Hmr);
-  Hmr.prototype.partialReload = function () {
-    try {
-      const ctx = serviceCheck(this, 'hmr');
-      const changed = [...this.stashed];
-      const execute = () => {
-        const scope = scoped(ctx);
-        if (!scope) throw incompatible('HMR escaped its admitted transaction');
-        return reloadModules(this, scope.steps, changed, scope.retired);
-      };
-      return scoped(ctx) ? execute() : this.runExclusive(execute);
-    } catch (error) { return Promise.reject(error); }
-  };
-  const edit = ConfigEditor.prototype.edit;
-  ConfigEditor.prototype.edit = function (entry, change) {
-    try {
-      const ctx = serviceCheck(this, 'configEditor');
-      const generation = ctx.fiber._generation;
-      if (typeof change !== 'function') throw new TypeError('ConfigEditor.edit requires a change callback');
-      const invoke = () => {
-        serviceCheck(this, 'configEditor');
-        if (ctx.fiber._generation !== generation) throw new LoaderError('STALE_OFFICIAL_SERVICE', 'ConfigEditor changed while its edit was queued');
-        return Reflect.apply(edit, this, [entry, (...args) => {
-          const scope = scoped(ctx);
-          if (!scope) throw incompatible('ConfigEditor callback escaped its admitted transaction');
-          return scope.steps.observe(entry.fiber, () => change(...args));
-        }]);
-      };
-      return scoped(ctx) ? invoke() : coordinate(ctx.root, invoke);
-    } catch (error) { return Promise.reject(error); }
-  };
-  for (const value of classes) installedContracts.set(value, classes);
-}

package/official-hmr.js

@@ -1,304 +0,0 @@
-import { AsyncLocalStorage } from 'node:async_hooks';
-import { createRequire, registerHooks } from 'node:module';
-import { realpathSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-import { FiberState, Service } from '@validation-engineering/cordis';
-import { LoaderError } from './config.js';
-
-const require = createRequire(import.meta.url);
-const observed = new Map(), hosts = new Set(), pending = new WeakMap();
-const candidateScope = new AsyncLocalStorage();
-const original = value => value?.[Symbol.for('cordis.original')] ?? value;
-let installed = false, active, tail = Promise.resolve();
-const file = url => typeof url === 'string' && url.startsWith('file:');
-const native = url => file(url) && fileURLToPath(url).endsWith('.node');
-const fail = (code, message, details, cause) => new LoaderError(code, message, details, cause);
-const add = (graph, parent, child) => {
-  if (!file(parent) || !file(child)) return;
-  if (!graph.has(parent)) graph.set(parent, new Set());
-  graph.get(parent).add(child);
-};
-const clone = graph => new Map([...graph].map(([key, values]) => [key, new Set(values)]));
-function boundary(url) {
-  const bootstrap = globalThis[Symbol.for('cordis-verus.compat-cordis.bootstrap.v1')];
-  return url === bootstrap?.facade || url === bootstrap?.facade?.replace(/index\.js$/, 'index.cjs');
-}
-
-/** Install once before application imports, recording dynamic import/createRequire edges too. */
-export function installModuleObservation(Hmr) {
-  if (!installed) {
-    installed = true;
-    registerHooks({ resolve(specifier, context, next) {
-      const result = next(specifier, context);
-      const candidate = candidateScope.getStore();
-      const ours = candidate && candidate === active && candidate.active;
-      if (active && !ours && file(result.url)) {
-        if (active.affected.has(result.url)) throw fail('OFFICIAL_HMR_MODULE_BUSY', 'An affected module is being replaced', { url: result.url });
-        active.foreignURLs.add(result.url);
-        active.foreignEdges.add(JSON.stringify([context.parentURL, result.url]));
-      }
-      if (ours && candidate.urls.has(context.parentURL) && file(result.url) && !boundary(result.url)) {
-        if (native(result.url)) throw fail('OFFICIAL_HMR_NATIVE_ADDON', 'Native addons require a process restart', { url: result.url });
-        candidate.urls.add(result.url);
-        if (!observed.get(context.parentURL)?.has(result.url)) candidate.addedEdges.push([context.parentURL, result.url]);
-      }
-      add(observed, context.parentURL, result.url);
-      return result;
-    } });
-  }
-  Object.defineProperty(Hmr.prototype, 'lastReloadFailure', { configurable: true, get() { return pending.get(original(this))?.error; } });
-  const init = Hmr.prototype[Service.init];
-  if (typeof init !== 'function') return; // Contract-only fixtures have no runtime.
-  Hmr.prototype[Service.init] = async function* () {
-    hosts.add(this);
-    yield () => { hosts.delete(this); };
-    yield* Reflect.apply(init, this, []);
-    // The official watcher only tests ESM loadCache.has(). Pure require() leaves
-    // must also enter its existing stashed batch, before the debounce fires.
-    const changed = path => {
-      let filename = resolve(this.baseDir, path);
-      try { filename = realpathSync(filename); } catch { /* deleted file */ }
-      if (require.cache[filename]) this.stashed.add(pathToFileURL(filename).href);
-    };
-    this.watcher.on('change', changed);
-    yield () => { this.watcher.off('change', changed); };
-  };
-}
-
-async function graphOf(cache) {
-  const graph = clone(observed);
-  // Cache values differ across supported Node internals; use the official get
-  // API for the job and retain raw Map values only for exact restoration.
-  for (const url of cache.keys()) {
-    const job = cache.get(url);
-    if (!job?.module || !file(url)) continue;
-    const children = await job.linked;
-    for (const child of Array.from(children ?? [])) add(graph, url, child.url);
-  }
-  for (const module of Object.values(require.cache)) {
-    if (!module?.filename) continue;
-    for (const child of module.children ?? []) if (child.filename) add(graph,
-      pathToFileURL(module.filename).href, pathToFileURL(child.filename).href);
-  }
-  return graph;
-}
-function closure(roots, graph) {
-  const result = new Set(), queue = [...roots];
-  for (const url of queue) {
-    if (result.has(url) || boundary(url)) continue;
-    result.add(url);
-    queue.push(...graph.get(url) ?? []);
-  }
-  return result;
-}
-async function entriesOf(hmr) {
-  const result = new Map();
-  for (const entry of hmr.ownerContext.loader.entries()) {
-    if (!entry.fiber || entry.fiber.uid === null || entry.options.name.startsWith('cordis:')) continue;
-    const resolved = await hmr._resolve(entry.options.name, entry.parent.tree.ctx.baseUrl, {});
-    if (!file(resolved?.url)) continue;
-    const job = hmr.internal.loadCache.get(resolved.url);
-    const plugin = hmr.ownerContext.loader.unwrapExports(job?.module?.getNamespace());
-    if (!plugin) throw fail('OFFICIAL_HMR_GRAPH_UNAVAILABLE', 'A live entry has no evaluated module job', { url: resolved.url });
-    result.set(resolved.url, { url: resolved.url, plugin, runtime: hmr.ownerContext.registry.get(plugin) });
-  }
-  return result;
-}
-async function plan(hmr, changed) {
-  const cache = hmr.internal?.loadCache;
-  try { Map.prototype.has.call(cache, ''); }
-  catch { throw fail('OFFICIAL_HMR_GRAPH_UNAVAILABLE', 'Supported Node module internals are required'); }
-  if (changed.some(url => boundary(url) || native(url))) throw fail('OFFICIAL_HMR_HOST_BOUNDARY', 'Native runtime and facade changes require a process restart');
-  const graph = await graphOf(cache), entries = await entriesOf(hmr);
-  const owned = closure(entries.keys(), graph), reverse = new Map();
-  for (const [parent, children] of graph) for (const child of children) add(reverse, child, parent);
-  const affected = closure(changed.filter(url => cache.has(url) || file(url) && require.cache[fileURLToPath(url)]), reverse);
-  if (!affected.size) return { cache, graph, affected, generations: [] };
-  const loaded = url => cache.has(url) || file(url) && !!require.cache[fileURLToPath(url)];
-  for (const url of affected) {
-    if (boundary(url) || hmr.externals?.has(url) || loaded(url) && !owned.has(url)) {
-      throw fail('OFFICIAL_HMR_HOST_BOUNDARY', `A changed module is retained outside the configured plugin graph: ${url}`, { url });
-    }
-  }
-  // Node caches are process-global. Another native domain retaining a factory
-  // cannot silently inherit this domain's replacement.
-  for (const host of hosts) if (host.ownerContext.fiber !== hmr.ownerContext.fiber && host.ownerContext.fiber.uid !== null) {
-    const other = closure((await entriesOf(host)).keys(), graph);
-    if ([...affected].some(url => other.has(url))) throw fail('OFFICIAL_HMR_HOST_BOUNDARY', 'Another application domain retains the changed module');
-  }
-  const generations = [...entries.values()].filter(entry => affected.has(entry.url));
-  if (!generations.length) throw fail('OFFICIAL_HMR_HOST_BOUNDARY', 'Changed modules have no configured live plugin owner');
-  const dependencies = closure(generations.map(entry => entry.url), graph);
-  const addon = [...dependencies].find(native);
-  if (addon) throw fail('OFFICIAL_HMR_NATIVE_ADDON', 'A plugin with native addon dependencies requires a process restart', { url: addon });
-  const represented = new Set(generations.map(entry => entry.runtime?.callback));
-  const all = new Set(generations.flatMap(entry => [...entry.runtime?.fibers ?? []]));
-  const ownedByReplacement = fiber => {
-    for (let parent = fiber.parent.fiber; parent && parent !== parent.parent.fiber; parent = parent.parent.fiber) if (all.has(parent)) return true;
-    return false;
-  };
-  for (const url of affected) {
-    const job = cache.get(url);
-    let namespace;
-    try { namespace = job?.module?.getNamespace() ?? (file(url) && require.cache[fileURLToPath(url)] ? { default: require.cache[fileURLToPath(url)].exports } : undefined); } catch { continue; }
-    if (!namespace) continue;
-    for (const value of Object.values(namespace)) {
-      const runtime = hmr.ownerContext.registry.get(value);
-      if (runtime?.fibers.length && !represented.has(runtime.callback) && ![...runtime.fibers].every(ownedByReplacement)) throw fail('OFFICIAL_HMR_HOST_BOUNDARY',
-        'A loaded factory retained outside named Loader entries depends on the changed module', { url });
-    }
-  }
-  for (let owner = hmr.ownerContext.fiber; owner; owner = owner === owner.parent.fiber ? undefined : owner.parent.fiber) {
-    if (all.has(owner)) throw fail('OFFICIAL_HMR_HOST_BOUNDARY', 'HMR cannot replace its own lifecycle coordinator');
-  }
-  for (const generation of generations) generation.fibers = [...generation.runtime?.fibers ?? []].filter(fiber => {
-    return !ownedByReplacement(fiber);
-  }).map(fiber => ({ fiber, parent: fiber.parent, entry: fiber.entry?.fiber === fiber ? fiber.entry : undefined,
-    parentGeneration: fiber.parent.fiber._generation, config: fiber.entry?.fiber === fiber ? fiber.entry.options.config : fiber._config }));
-  return { cache, graph, affected: new Set([...affected].filter(loaded)), generations };
-}
-
-async function landAll(tasks, message) {
-  const result = await Promise.allSettled(tasks), errors = result.filter(item => item.status === 'rejected').map(item => item.reason);
-  if (errors.length) throw new AggregateError(errors, message);
-}
-function cacheJournal(cache, affected) {
-  const esm = new Map(cache), cjs = new Map(Object.entries(require.cache));
-  const edges = clone(observed);
-  const children = new Map([...cjs.values()].map(module => [module, [...module.children ?? []]]));
-  const urls = new Set(affected);
-  const addedEdges = [], foreignURLs = new Set(), foreignEdges = new Set();
-  return { urls, affected, addedEdges, foreignURLs, foreignEdges, active: true,
-    release() {
-      // Live timers/promises inherit candidateScope. Do not retain complete old
-      // module caches through the successful generation's asynchronous work.
-      this.active = false;
-      esm.clear(); cjs.clear(); edges.clear(); children.clear();
-      urls.clear(); addedEdges.length = 0; foreignURLs.clear(); foreignEdges.clear(); affected.clear();
-    },
-    invalidate() {
-      for (const url of affected) {
-        Map.prototype.delete.call(cache, url); observed.delete(url);
-        if (file(url)) delete require.cache[fileURLToPath(url)];
-      }
-    },
-    restore() {
-      for (const url of urls) {
-        if (affected.has(url) || !esm.has(url) && !foreignURLs.has(url)) {
-          if (esm.has(url)) Map.prototype.set.call(cache, url, esm.get(url));
-          else Map.prototype.delete.call(cache, url);
-        }
-        if (file(url)) {
-          const path = fileURLToPath(url);
-          if (affected.has(url) || !cjs.has(path) && !foreignURLs.has(url)) {
-            if (cjs.has(path)) require.cache[path] = cjs.get(path);
-            else delete require.cache[path];
-          }
-        }
-        if (affected.has(url)) {
-          if (edges.has(url)) observed.set(url, new Set(edges.get(url))); else observed.delete(url);
-        }
-      }
-      for (const [parent, child] of addedEdges) {
-        if (!edges.get(parent)?.has(child) && !foreignEdges.has(JSON.stringify([parent, child]))) observed.get(parent)?.delete(child);
-      }
-      for (const [module, prior] of children) {
-        // Remove only this candidate's new child links; concurrent unrelated
-        // imports and their cache identities remain untouched.
-        module.children = [...prior, ...(module.children ?? []).filter(child => !prior.includes(child)
-          && (!child.filename || !urls.has(pathToFileURL(child.filename).href) || foreignURLs.has(pathToFileURL(child.filename).href)))];
-      }
-    },
-  };
-}
-async function activate(hmr, generations, restored, created) {
-  for (const generation of generations) {
-    const plugin = restored ? generation.plugin : generation.replacement;
-    for (const record of generation.fibers) {
-      if (record.parent.fiber.uid === null || record.parent.fiber._generation !== record.parentGeneration
-        || record.entry && (record.entry.parent.tree.store[record.entry.options.id] !== record.entry || record.entry.options.config !== record.config)) throw fail('OFFICIAL_HMR_OWNER_REMOVED', 'Plugin owner disappeared during replacement');
-      const fiber = record.parent.registry.plugin(plugin, record.config, hmr.getOuterStack).ctx.fiber;
-      created.add(fiber);
-      if (record.entry) { fiber.entry = record.entry; record.entry.fiber = fiber; }
-    }
-  }
-  await landAll([...created].map(async fiber => {
-    await fiber.await();
-    if (fiber.state !== FiberState.ACTIVE) throw fail('OFFICIAL_HMR_NOT_ACTIVE', 'Replacement did not reach Active', { fiber: fiber.id, state: fiber.state });
-  }), 'Plugin activation failed');
-}
-
-/** Caller already owns both the native domain coordinator and official HMR queue. */
-export function reloadModules(hmr, steps, changed, retired) {
-  const task = tail.then(() => performReload(hmr, steps, changed, retired));
-  tail = task.catch(() => {});
-  return task;
-}
-async function recover(hmr, steps, state, retired) {
-  try {
-    await landAll([...state.created].map(fiber => steps.dispose(fiber).then(() => { retired.add(fiber); })), 'Retained generation cleanup failed');
-  } catch (cause) {
-    state.error = fail('OFFICIAL_HMR_RECOVERY_BLOCKED', 'Retained cleanup remains unconfirmed; explicitly retry failed inverses first',
-      { restored: false, cacheChanged: state.invalidated }, new AggregateError([state.cause, cause]));
-    throw state.error;
-  }
-  if (state.invalidated) state.journal.restore();
-  state.invalidated = false;
-  // A later old-activation failure retains only factories/ownership recipes:
-  // the cache itself has already been restored and no longer needs a backup.
-  state.journal?.release();
-  state.created = new Set();
-  try { await activate(hmr, state.generations, true, state.created); }
-  catch (cause) {
-    state.error = fail('OFFICIAL_HMR_RESTORE_FAILED', 'Old cache restored but old activation failed',
-      { restored: false, cacheChanged: false }, new AggregateError([state.cause, cause], 'Reload and restoration failed'));
-    throw state.error;
-  }
-  pending.delete(original(hmr));
-}
-async function performReload(hmr, steps, changed, retired) {
-  if (!steps.isCurrent()) throw fail('REENTRANT_MUTATION', 'Module replacement lost its coordinator');
-  const retained = pending.get(original(hmr));
-  if (retained) await recover(hmr, steps, retained, retired);
-  const { cache, affected, generations } = await plan(hmr, changed);
-  if (!generations.length) { for (const url of changed) hmr.stashed.delete(url); return; }
-  const old = generations.flatMap(generation => generation.fibers.map(record => record.fiber));
-  const created = new Set();
-  try { await landAll(old.map(fiber => steps.dispose(fiber).then(() => { retired.add(fiber); })), 'Old plugin cleanup failed'); }
-  catch (cause) {
-    const error = fail('OFFICIAL_HMR_CLEANUP_FAILED', 'Old cleanup is unconfirmed; module caches were not changed', { cacheChanged: false, restored: false }, cause);
-    pending.set(original(hmr), { generations, created: new Set(old), invalidated: false, cause, error });
-    throw error;
-  }
-  // Old inverses may import modules. Their completed imports are part of the
-  // pre-candidate baseline and must survive a later candidate failure.
-  const journal = cacheJournal(cache, affected);
-  journal.invalidate(); active = journal;
-  return candidateScope.run(journal, async () => {
-    try {
-      for (const generation of generations) generation.replacement = hmr.ownerContext.loader.unwrapExports(
-        await hmr.ownerContext.loader.import(generation.url, hmr.getOuterStack));
-      const candidateGraph = await graphOf(cache);
-      const addon = [...closure(generations.map(generation => generation.url), candidateGraph)].find(native);
-      if (addon) throw fail('OFFICIAL_HMR_NATIVE_ADDON', 'Candidate contains a native addon dependency', { url: addon });
-      await activate(hmr, generations, false, created);
-    } catch (cause) {
-      // Include roots created by a synchronous plugin() exception, which may not
-      // have returned a handle. Their retained runtime remains observable.
-      for (const generation of generations) if (generation.replacement) {
-        for (const fiber of hmr.ownerContext.registry.get(generation.replacement)?.fibers ?? []) created.add(fiber);
-      }
-      const state = { generations, journal, created, invalidated: true, cause };
-      pending.set(original(hmr), state);
-      await recover(hmr, steps, state, retired);
-      active = undefined;
-      throw fail('OFFICIAL_HMR_RELOAD_FAILED', 'Candidate failed; old module identities and plugins were restored',
-        { restored: true, cacheChanged: false }, cause);
-    } finally { journal.active = false; active = undefined; }
-    for (const url of changed) hmr.stashed.delete(url);
-    hmr.accepted = new Set(affected);
-    journal.release();
-    hmr.ownerContext.emit('hmr/reload', new Map(generations.map(generation => [generation.plugin, { filename: generation.url, runtime: generation.runtime }])));
-  });
-}