@milpa/comal 0.2.6 → 0.2.8

package/src/plugin-candidate-runner.mjs

@@ -0,0 +1,419 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import { stat } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { StringDecoder } from 'node:string_decoder';
+import { verifyCandidate } from './plugin-workbench.mjs';
+import { operationName } from './plugin-catalog.mjs';
+import { digest } from './operations.mjs';
+import { childEnvironment } from './child-env.mjs';
+import { validateCases } from './plugin-contract.mjs';
+
+// The plugin workbench's runner: a candidate (plugin-workbench.mjs) is verified, then loaded,
+// activated, checked and replayed in a separate Node process (plugin-candidate-child.mjs) in
+// its own process group.
+//
+// What it guarantees: it contains a BROKEN candidate. A candidate that throws, hangs, exits,
+// floods stdout or stderr, or leaves children in its process group cannot take the session
+// down: the run ends at its deadline or at the first protocol violation, the whole group is
+// killed (also after every successful run), and what the parent does with the child's output
+// is bounded. runCandidate never rejects, and its report always serializes.
+//
+// What it is NOT: a sandbox. Candidate code runs as the user. It can read the user's files,
+// read /proc/<ppid>/environ (the session's environment, secrets included), signal the parent,
+// allocate memory off the V8 heap past the 512 MB heap cap, or start a process that calls
+// setsid and so outlives the group kill. Only the candidate's own environment is stripped.
+//
+// Whose account the report is: `loaded`, `operations`, `checks`, `replays` and `cleanup` are
+// what the child said, and candidate code shares the child's process, so it can forge any of
+// it. They are evidence for a human, never proof for promotion. The parent computes on its own
+// (report.parent_computed): the outcome when it is refused, timed_out, protocol_error or
+// exited; exit, ms, pid, group_kill; fingerprint and dynamic (from verifyCandidate, run
+// immediately before the spawn); and every `not_permitted` replay (the caller's judge decided
+// it and nothing was forwarded). A replay reaches the child only when the judge returns true,
+// and what is judged is the exact serialized request sent.
+//
+// What the child is given of the house: nothing live. `services` is plain data and `serviceFunctions` names,
+// per service, the members that are functions in the house; the child stands each one in with a function
+// that throws when called (hostServiceStandIns builds both from a runtime). When activation fails after
+// asking for a service that is not there, or after calling such a function, the candidate was not judged:
+// the outcome is `not_judged` with `unavailable_services`, never `activate_failed`.
+//
+// A run never outlives its caller's interest or this process: `signal` settles it at once as
+// `aborted` (parent-computed) and kills the group, and every group still running is killed
+// synchronously when this process exits (process 'exit') or the host calls killCandidateRuns
+// on its termination paths.
+
+const CHILD = fileURLToPath(new URL('./plugin-candidate-child.mjs', import.meta.url));
+const HEAP_FLAG = '--max-old-space-size=512';
+const PROTOCOL_LIMIT = 4 * 1024 * 1024;          // raw bytes on the child's stdout, all told
+const TEXT = 2000, STDERR_TAIL = 2000, MAX_OPERATIONS = 200, MAX_CHECKS = 200, MAX_NAMES = 32;
+const MAX_DEPTH = 32, MAX_ITEMS = 1000, FIELD_BYTES = 1024 * 1024;   // per schema or effects value
+const OUTPUT_BYTES = 256 * 1024;                  // a replay's output, as JSON, when asked for
+const OUTPUT_TOTAL = 2 * 1024 * 1024;             // all asked-for outputs of a run, together
+const MAX_CASES = 200, CASE_BYTES = 64 * 1024;
+const CLOSE_GRACE_MS = 1000, EXIT_GRACE_MS = 2000;
+const ENV_KEYS = ['PATH', 'HOME', 'LANG', 'LC_ALL', 'TMPDIR', ...(process.platform === 'win32' ? ['SystemRoot', 'TEMP', 'TMP', 'USERPROFILE'] : [])];
+const TRUST = 'candidate_reported';
+const PARENT_COMPUTED = Object.freeze(['outcome_when_refused_timed_out_protocol_error_exited', 'exit', 'ms', 'pid', 'group_kill', 'fingerprint', 'dynamic', 'not_permitted', 'outcome_when_aborted']);
+
+// The candidate processes running now: pid → whether it leads its own process group.
+const running = new Map();
+let exitHook = false;
+/** Kill every candidate process group still running, synchronously. Safe to call at any time. */
+export function killCandidateRuns() {
+  for (const [pid, group] of running) {
+    try { process.kill(group ? -pid : pid, 'SIGKILL'); } catch {}
+  }
+}
+function track(pid, group) {
+  if (!Number.isInteger(pid)) return;
+  running.set(pid, group);
+  if (!exitHook) { exitHook = true; process.on('exit', killCandidateRuns); }
+}
+
+class Bound extends Error {}
+// Text from the child is taken only when it is text; anything else is dropped, never stringified.
+const text = value => typeof value === 'string' ? value.slice(0, TEXT) : typeof value === 'number' || typeof value === 'boolean' ? String(value) : '';
+const message = error => text(error instanceof Error ? error.message : typeof error === 'string' ? error : 'Unknown error');
+const plain = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+// A JSON copy with at most MAX_DEPTH levels and MAX_ITEMS entries per array or object; a value
+// beyond those, a cycle, or something that is not JSON throws Bound.
+function jsonValue(value, depth = 0) {
+  if (depth > MAX_DEPTH) throw new Bound(`A value nests deeper than ${MAX_DEPTH} levels.`);
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
+  if (typeof value === 'number') { if (!Number.isFinite(value)) throw new Bound('A number is not finite.'); return value; }
+  if (Array.isArray(value)) {
+    if (value.length > MAX_ITEMS) throw new Bound(`An array holds more than ${MAX_ITEMS} items.`);
+    return value.map(item => jsonValue(item, depth + 1));
+  }
+  if (typeof value === 'object') {
+    const keys = Object.keys(value);
+    if (keys.length > MAX_ITEMS) throw new Bound(`An object holds more than ${MAX_ITEMS} keys.`);
+    const out = {};
+    for (const key of keys) Object.defineProperty(out, key, { value: jsonValue(value[key], depth + 1), enumerable: true, writable: true, configurable: true });
+    return out;
+  }
+  throw new Bound('A value is not JSON.');
+}
+function field(value) {
+  if (value === undefined || value === null) return null;
+  const copy = jsonValue(value);
+  if (Buffer.byteLength(JSON.stringify(copy)) > FIELD_BYTES) throw new Bound(`A field is larger than ${FIELD_BYTES} bytes.`);
+  return copy;
+}
+function list(value, cap, what) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) throw new Bound(`${what} is not a list.`);
+  if (value.length > cap) throw new Bound(`${what} holds more than ${cap} entries.`);
+  return value;
+}
+
+const operationsFrom = value => list(value, MAX_OPERATIONS, 'The operations list').map(op => {
+  if (!plain(op)) throw new Bound('An operation is not an object.');
+  return { name: text(op.name).slice(0, 128), description: text(op.description), input_schema: field(op.input_schema), output_schema: field(op.output_schema), effects: field(op.effects), audience: op.audience === 'human' ? 'human' : 'any' };
+});
+// The candidate's cases, as it reported them: bounded JSON, then the runtime's own case checks.
+const casesFrom = value => validateCases(list(value, MAX_CASES, 'The cases list').map(item => {
+  const copy = jsonValue(item);
+  if (Buffer.byteLength(JSON.stringify(copy)) > CASE_BYTES) throw new Bound(`A case is larger than ${CASE_BYTES} bytes.`);
+  return copy;
+}));
+const checksFrom = value => list(value, MAX_CHECKS, 'The checks list').map(check => {
+  if (!plain(check)) throw new Bound('A check is not an object.');
+  return { name: text(check.name), ok: check.ok === true, ...(check.ok === true ? {} : { error: text(check.error) }) };
+});
+const namesFrom = value => list(value, MAX_NAMES, 'The missing services list').map(name => text(name).slice(0, 128));
+// A code the candidate's error carried, when it looks like one.
+const codeFrom = value => typeof value === 'string' && /^[A-Za-z0-9_.:-]{1,128}$/.test(value) ? value : null;
+// A replay's output, only when it was asked for: a bounded JSON copy, omitted above OUTPUT_BYTES, or
+// once the run's outputs together would pass OUTPUT_TOTAL (budget.left, spent here).
+function outputFrom(answer, budget) {
+  if (['too_large', 'budget'].includes(answer.output_omitted)) return { output_omitted: answer.output_omitted };
+  if (!answer.has_output) return { output_omitted: 'not_reported' };
+  const copy = jsonValue(answer.output), bytes = Buffer.byteLength(JSON.stringify(copy));
+  if (bytes > OUTPUT_BYTES) return { output_omitted: 'too_large' };
+  if (bytes > budget.left) return { output_omitted: 'budget' };
+  budget.left -= bytes;
+  return { output: copy };
+}
+
+// Only the names a plugin legitimately needs; provider secrets are filtered once more.
+function candidateEnvironment(env = process.env) {
+  const picked = {};
+  for (const key of ENV_KEYS) if (env[key] !== undefined) picked[key] = env[key];
+  return childEnvironment(picked);
+}
+
+function emptyReport() {
+  return { outcome: null, trust: TRUST, parent_computed: [...PARENT_COMPUTED], exit: null, stderr_tail: '', ms: 0, pid: null, group_kill: process.platform !== 'win32', fingerprint: null, dynamic: [], packages: [], operations: [], cases: [], missing_services: [], checks: [], replays: [] };
+}
+
+// The last guard: a report that does not serialize degrades to protocol_error, keeping only
+// what the parent computed itself.
+function finished(report, started) {
+  report.ms = Math.round(performance.now() - started);
+  try { JSON.stringify(report); return report; }
+  catch (error) {
+    const safe = emptyReport();
+    for (const key of ['exit', 'ms', 'pid', 'group_kill', 'fingerprint', 'dynamic', 'packages']) try { safe[key] = jsonValue(report[key] ?? safe[key]); } catch {}
+    return Object.assign(safe, { outcome: 'protocol_error', error: `The report did not serialize: ${message(error)}` });
+  }
+}
+
+/**
+ * Load, activate, check and replay a candidate in a separate process. Resolves to a report:
+ * { outcome: 'loaded' | 'refused' | 'import_failed' | 'activate_failed' | 'timed_out' | 'exited' | 'protocol_error' | 'aborted',
+ *   trust: 'candidate_reported', parent_computed, exit, stderr_tail, ms, pid, group_kill, fingerprint,
+ *   dynamic, operations, missing_services, checks, replays, cleanup?, error?, code?, unavailable_services? }.
+ * The outcome can also be 'not_judged': activation needed something of the house this process cannot have.
+ * Never rejects. `signal` aborts the run: it settles at once as `aborted` and the group is killed.
+ * `spawn` is a seam for tests (the signature of child_process.spawn).
+ */
+export async function runCandidate(candidate, options = {}) {
+  const started = performance.now();
+  const report = emptyReport();
+  try { await run(candidate, options ?? {}, report); }
+  catch (error) { Object.assign(report, { outcome: 'protocol_error', error: message(error) }); }
+  return finished(report, started);
+}
+
+async function run(candidate, { config = {}, services = {}, serviceFunctions = {}, replay = [], timeoutMs = 20000, judge, cwd, spawn = nodeSpawn, signal }, report) {
+  const aborted = () => Object.assign(report, { outcome: 'aborted', error: 'The run was aborted by its caller.' });
+  if (signal?.aborted) return aborted();
+  const refuse = (error, code) => Object.assign(report, { outcome: 'refused', error: message(error), code: code ?? (typeof error?.code === 'string' ? error.code : null) });
+
+  let verified;
+  try { verified = await verifyCandidate(candidate); }
+  catch (error) { return refuse(error); }
+  report.fingerprint = text(verified.fingerprint);
+  report.dynamic = verified.dynamic.slice(0, MAX_OPERATIONS).map(item => ({ file: text(item.file), construct: text(item.construct) }));
+  report.packages = (verified.packages ?? []).slice(0, MAX_OPERATIONS).map(item => ({ file: text(item.file), specifier: text(item.specifier) }));
+
+  let init;
+  const workdir = cwd ?? candidate.dir;
+  try {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) throw new Error('timeoutMs must be a positive number.');
+    if (!Array.isArray(replay)) throw new Error('replay must be an array.');
+    init = JSON.stringify({ type: 'init', id: candidate.id, config, services, service_functions: serviceFunctions, deadline_ms: timeoutMs });
+  } catch (error) { return refuse(error, 'PLUGIN_CANDIDATE_OPTIONS'); }
+  let directory = null;
+  try { directory = await stat(workdir); } catch {}
+  if (!directory?.isDirectory()) return refuse(`The working directory does not exist or is not a directory: ${workdir}`, 'PLUGIN_CANDIDATE_OPTIONS');
+  if (signal?.aborted) return aborted();
+
+  await new Promise(resolve => {
+    let child, settled = false, closed = false, exited = false, resolved = false, declared = null;
+    let stdoutBytes = 0, buffer = '', pending = null, seq = 0;
+    let timer = null, deadlineLeft = timeoutMs, deadlineFrom = 0, closeTimer = null, endTimer = null;
+    const decoder = new StringDecoder('utf8'), errDecoder = new StringDecoder('utf8');
+    const streams = () => child ? [child.stdin, child.stdout, child.stderr] : [];
+    const started = () => streams().length === 3 && streams().every(Boolean);
+
+    const killGroup = () => {
+      if (!child?.pid) return;
+      try { if (report.group_kill) process.kill(-child.pid, 'SIGKILL'); else child.kill('SIGKILL'); } catch {}
+    };
+    let onAbort = null;
+    const done = () => {
+      if (resolved) return; resolved = true;
+      clearTimeout(timer); clearTimeout(closeTimer); clearTimeout(endTimer);
+      if (onAbort) signal.removeEventListener('abort', onAbort);
+      if (child?.pid) running.delete(child.pid);
+      for (const stream of streams()) try { stream?.destroy(); } catch {}
+      resolve();
+    };
+    // Resolved once the outcome is set and the process has closed its stdio and exited
+    // (or there is no process to wait for).
+    const maybeDone = () => { if (settled && (!started() || !child.pid || (closed && exited))) done(); };
+    const settle = (outcome, extra = {}) => {
+      if (settled) return; settled = true;
+      clearTimeout(timer);
+      report.outcome = outcome; Object.assign(report, extra);
+      killGroup();
+      if (pending) { const answer = pending; pending = null; answer(null); }
+      endTimer = setTimeout(done, EXIT_GRACE_MS);
+      maybeDone();
+    };
+    const fail = error => settle('protocol_error', { error: message(error) });
+    const guarded = fn => (...args) => { try { return fn(...args); } catch (error) { fail(error); } };
+    // The deadline belongs to the candidate: it is paused while the caller's judge decides.
+    const resumeDeadline = () => { deadlineFrom = performance.now(); timer = setTimeout(guarded(() => settle('timed_out')), Math.max(0, deadlineLeft)); };
+    const pauseDeadline = () => { clearTimeout(timer); deadlineLeft -= performance.now() - deadlineFrom; };
+    const write = line => { if (!settled) child.stdin.write(`${line}\n`); };
+
+    const budget = { left: OUTPUT_TOTAL };
+    async function replays() {
+      for (const item of replay) {
+        if (settled) return;
+        const operation = operationName(candidate.id, text(item?.operation).slice(0, 128));
+        const wantOutput = item?.want_output === true;
+        let input;
+        try { input = JSON.stringify(item?.input ?? {}); } catch { report.replays.push({ operation, outcome: 'threw', error: 'The replay input is not JSON-serializable.' }); continue; }
+        let permitted = false;
+        if (typeof judge === 'function') {
+          pauseDeadline();
+          try { permitted = await judge({ operation, input: JSON.parse(input) }) === true; } catch { permitted = false; }
+          if (settled) return;
+          resumeDeadline();
+        }
+        if (!permitted) { report.replays.push({ operation, outcome: 'not_permitted' }); continue; }
+        const id = ++seq;
+        const answer = await new Promise(answered => {
+          pending = answered;
+          write(`{"type":"replay","seq":${id},"operation":${JSON.stringify(operation)},"input":${input},"remaining_ms":${Math.max(1, Math.floor(deadlineLeft - (performance.now() - deadlineFrom)))}${wantOutput ? ',"want_output":true' : ''}}`);
+        });
+        if (!answer) return;
+        if (answer.seq !== id || !['returned', 'threw'].includes(answer.outcome)) return fail('A replay answer does not match its request.');
+        const output = typeof answer.output_sha256 === 'string' && /^[0-9a-f]{64}$/.test(answer.output_sha256) ? answer.output_sha256 : null;
+        const code = codeFrom(answer.code);
+        report.replays.push(answer.outcome === 'returned' ? { operation, outcome: 'returned', ...(output ? { output_sha256: output } : {}), ...(wantOutput ? outputFrom(answer, budget) : {}) } : { operation, outcome: 'threw', error: text(answer.error), ...(code ? { code } : {}) });
+      }
+      write('{"type":"done"}');
+    }
+
+    const phases = { import: ['imported', 'import_failed'], activate: ['activated', 'activate_failed'], checks: ['checks'], ready: ['ready'], replay: ['replayed', 'closed'], over: [] };
+    let phase = 'import';
+    const handle = received => {
+      if (!plain(received) || !phases[phase].includes(received.type)) return fail(`Unexpected message from the candidate process: ${text(received?.type)}`);
+      switch (received.type) {
+        case 'imported': report.missing_services = namesFrom(received.missing_services); phase = 'activate'; break;
+        case 'import_failed': declared = { outcome: 'import_failed', error: text(received.error) }; phase = 'over'; break;
+        case 'activate_failed': {
+          report.operations = operationsFrom(received.operations);
+          const unavailable = namesFrom(received.unavailable_services).filter(Boolean);
+          declared = unavailable.length ? { outcome: 'not_judged', error: text(received.error), unavailable_services: unavailable } : { outcome: 'activate_failed', error: text(received.error) };
+          phase = 'over'; break;
+        }
+        case 'activated': report.operations = operationsFrom(received.operations); report.cases = casesFrom(received.cases); phase = 'checks'; break;
+        case 'checks': report.checks = checksFrom(received.checks); phase = 'ready'; break;
+        case 'ready': phase = 'replay'; replays().catch(fail); break;
+        case 'replayed': { if (!pending) return fail('A replay answer arrived unasked.'); const answer = pending; pending = null; answer({ seq: received.seq, outcome: received.outcome, error: received.error, code: received.code, output_sha256: received.output_sha256, has_output: Object.hasOwn(received, 'output'), output: received.output, output_omitted: received.output_omitted }); break; }
+        case 'closed': report.cleanup = plain(received.cleanup) ? { ok: received.cleanup.ok === true, ...(received.cleanup.ok === true ? {} : { error: text(received.cleanup.error) }) } : { ok: false, error: 'No cleanup report.' }; declared = { outcome: 'loaded' }; phase = 'over'; break;
+      }
+    };
+    const onStdout = chunk => {
+      if (settled) return;
+      stdoutBytes += chunk.length;
+      if (stdoutBytes > PROTOCOL_LIMIT) return fail('The candidate process wrote more than 4 MB to stdout.');
+      buffer += decoder.write(chunk);
+      for (let newline; !settled && (newline = buffer.indexOf('\n')) !== -1;) {
+        const line = buffer.slice(0, newline); buffer = buffer.slice(newline + 1);
+        let received;
+        try { received = JSON.parse(line); } catch { return fail('The candidate process wrote a line that is not protocol JSON to stdout.'); }
+        handle(received);
+      }
+    };
+    const ended = () => { const { outcome = 'exited', ...extra } = declared ?? {}; settle(outcome, extra); };
+
+    try {
+      try {
+        child = spawn(process.execPath, [HEAP_FLAG, CHILD, candidate.module], { cwd: workdir, env: candidateEnvironment(), detached: report.group_kill, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
+      } catch (error) { Object.assign(report, { outcome: 'exited', error: message(error) }); settled = true; done(); return; }
+      if (!child || typeof child.on !== 'function') { Object.assign(report, { outcome: 'exited', error: 'spawn returned no child process.' }); settled = true; done(); return; }
+      let spawnError = null;
+      child.on('error', guarded(error => { spawnError = error; if (started()) settle('exited', { error: message(error) }); }));
+      report.pid = Number.isInteger(child.pid) ? child.pid : null;
+      track(child.pid, report.group_kill);
+      if (signal) {
+        onAbort = guarded(() => settle('aborted', { error: 'The run was aborted by its caller.' }));
+        if (signal.aborted) onAbort(); else signal.addEventListener('abort', onAbort, { once: true });
+      }
+      if (!started()) {
+        // No stdio: the spawn failed (e.g. EMFILE). Its error arrives on the next tick; report it.
+        setImmediate(() => settle('exited', { error: spawnError ? message(spawnError) : 'The candidate process started without stdio.' }));
+        return;
+      }
+      for (const stream of streams()) stream.on('error', () => {});
+      child.stdout.on('data', guarded(onStdout));
+      child.stderr.on('data', guarded(chunk => { report.stderr_tail = (report.stderr_tail + errDecoder.write(chunk)).slice(-STDERR_TAIL); }));
+      // Settle on close (stdio drained), not on exit: a final line may still be in the pipe at exit.
+      child.on('exit', guarded((code, signal) => {
+        exited = true; report.exit = { code: code ?? null, signal: signal ?? null };
+        killGroup();   // what stayed in the group goes now, so its copies of the pipes close too
+        if (!settled) closeTimer = setTimeout(guarded(ended), CLOSE_GRACE_MS);
+        maybeDone();
+      }));
+      child.on('close', guarded((code, signal) => {
+        closed = true;
+        if (!exited) { exited = true; report.exit = { code: code ?? null, signal: signal ?? null }; }
+        ended(); maybeDone();
+      }));
+      resumeDeadline();
+      write(init);
+    } catch (error) { fail(error); }
+  });
+}
+
+// A copy of plain data read through property descriptors only: no accessor runs, at any depth. Accessors,
+// functions, symbols and undefined are left out; the same depth and size bounds as jsonValue apply (Bound).
+function dataCopy(value, depth = 0) {
+  if (depth > MAX_DEPTH) throw new Bound(`A value nests deeper than ${MAX_DEPTH} levels.`);
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
+  if (typeof value === 'number') { if (!Number.isFinite(value)) throw new Bound('A number is not finite.'); return value; }
+  if (typeof value !== 'object') return undefined;
+  const keys = Object.keys(value);
+  if (keys.length > MAX_ITEMS) throw new Bound(`A value holds more than ${MAX_ITEMS} entries.`);
+  const own = key => { const property = Object.getOwnPropertyDescriptor(value, key); return property && !('get' in property) && !('set' in property) ? dataCopy(property.value, depth + 1) : undefined; };
+  if (Array.isArray(value)) return keys.map(own).map(item => item === undefined ? null : item);
+  const out = {};
+  for (const key of keys) { const copy = own(key); if (copy !== undefined) Object.defineProperty(out, key, { value: copy, enumerable: true, writable: true, configurable: true }); }
+  return out;
+}
+/**
+ * The house's own services of a runtime as the child can be given them: { services, functions }. For each
+ * service the host provides (never one a plugin provides): its own enumerable members that are JSON data,
+ * copied, and the names of its members that are functions. Everything is read through property
+ * descriptors: an accessor is never run, at any depth, and is left out. A member larger than FIELD_BYTES,
+ * or too deep, is left out too.
+ */
+export function hostServiceStandIns(runtime) {
+  const services = {}, functions = {};
+  const bounded = value => { const copy = dataCopy(value); if (copy !== undefined && Buffer.byteLength(JSON.stringify(copy)) > FIELD_BYTES) throw new Bound('too large'); return copy; };
+  let names = [];
+  try { names = runtime.status().services ?? []; } catch {}
+  for (const name of names.slice(0, MAX_NAMES)) {
+    let entry = null;
+    try { entry = runtime.service(name); } catch {}
+    if (!entry || entry.owner !== 'host') continue;
+    const value = entry.value;
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) { try { const copy = bounded(value); if (copy !== undefined) services[name] = copy; } catch {} continue; }
+    const data = {}, members = [];
+    for (const key of Object.keys(value).slice(0, MAX_OPERATIONS)) {
+      const property = Object.getOwnPropertyDescriptor(value, key);
+      if (!property || 'get' in property || 'set' in property) continue;
+      if (typeof property.value === 'function') { members.push(key); continue; }
+      try { const copy = bounded(property.value); if (copy !== undefined) data[key] = copy; } catch {}
+    }
+    services[name] = data;
+    if (members.length) functions[name] = members;
+  }
+  return { services, functions };
+}
+
+// An input-schema digest that never throws; a schema that cannot be read counts as changed.
+function schemaDigest(schema) {
+  try { return digest(jsonValue(schema ?? null)); } catch { return Symbol('unreadable'); }
+}
+
+/** What a candidate changes in the published contract: by operation name and input-schema digest. Never throws. */
+export function contractChanges(liveOperations = [], candidateOperations = []) {
+  const index = operations => {
+    const out = new Map();
+    if (!Array.isArray(operations)) return out;
+    for (const item of operations) {
+      try {
+        const op = item?.contract ?? item;
+        if (op && typeof op.name === 'string') out.set(op.name, schemaDigest(op.input_schema));
+      } catch {}
+    }
+    return out;
+  };
+  const live = index(liveOperations), next = index(candidateOperations);
+  const sort = values => [...values].sort();
+  return {
+    removed: sort([...live.keys()].filter(name => !next.has(name))),
+    changed: sort([...live.keys()].filter(name => next.has(name) && next.get(name) !== live.get(name))),
+    added: sort([...next.keys()].filter(name => !live.has(name))),
+  };
+}

package/src/plugin-config.mjs

@@ -1,4 +1,4 @@
-import { open, realpath } from 'node:fs/promises';
+import { open, realpath, readFile, rename, rm, mkdir } from 'node:fs/promises';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { createHash, randomUUID } from 'node:crypto';
@@ -18,7 +18,7 @@ function fields(value, allowed, subject) {
   for (const key of Object.keys(value)) if (!allowed.includes(key)) throw new Error(`${subject}: campo desconocido ${key}`);
 }
 
-function pluginId(value) {
+export function pluginId(value) {
   if (typeof value !== 'string' || value.length > 24 || !ID.test(value)) throw new Error('ID de plugin inválido: usa minúsculas, números y guiones (máximo 24 caracteres)');
 }
 
@@ -58,6 +58,12 @@ export async function readPluginConfig(file, { missing = false } = {}) {
     if (missing && error.code === 'ENOENT') return { file: absolute, hash: null, entries: [] };
     throw error;
   }
+  return parsePluginConfig(bytes, absolute);
+}
+
+/** The validation of readPluginConfig on bytes already in hand, as if they were the file `file`. */
+export function parsePluginConfig(bytes, file) {
+  const absolute = path.resolve(file);
   let config;
   try { config = JSON.parse(bytes.toString('utf8')); }
   catch (error) { throw new Error(t('Invalid plugin JSON: {detail}', {detail: error.message})); }
@@ -66,8 +72,10 @@ export async function readPluginConfig(file, { missing = false } = {}) {
   if (!Array.isArray(config.plugins) || config.plugins.length > 32) throw new Error('plugins debe ser un arreglo con máximo 32 entradas');
   const seen = new Set();
   const entries = config.plugins.map(entry => {
-    fields(entry, ['id', 'module', 'enabled', 'config'], 'Entrada de plugin');
+    fields(entry, ['id', 'module', 'enabled', 'config', 'repaired_from'], 'Entrada de plugin');
     pluginId(entry.id);
+    // repaired_from: the module a contract repair replaced (plugin-repair.mjs); a record for revert, never loaded.
+    if (entry.repaired_from !== undefined && (typeof entry.repaired_from !== 'string' || !entry.repaired_from || entry.repaired_from.length > 4096 || entry.repaired_from.includes('\0'))) throw new Error(`repaired_from debe ser una ruta: ${entry.id}`);
     if (seen.has(entry.id)) throw new Error(`ID de plugin duplicado: ${entry.id}`);
     seen.add(entry.id);
     if (entry.enabled !== undefined && typeof entry.enabled !== 'boolean') throw new Error(`enabled debe ser booleano: ${entry.id}`);
@@ -77,9 +85,30 @@ export async function readPluginConfig(file, { missing = false } = {}) {
   return { file: absolute, hash: hash(bytes), entries, ...(config.chrome_workflow ? { chrome_workflow: config.chrome_workflow } : {}) };
 }
 
-const MAX_CODE_FILES = 256;
+/** The raw JSON of a plugins.json, validated by the real reader; { plugins: [] } when it does not exist. */
+export async function readPluginConfigRaw(file) {
+  const source = await readPluginConfig(file, { missing: true }); // valida y acota
+  if (!source.hash) return { plugins: [] };
+  return JSON.parse(await readFile(file, 'utf8'));
+}
+
+/** Writes to a temporary file in the same directory, checks it with the real reader and publishes it with rename. */
+export async function writePluginConfigRaw(file, value) {
+  await mkdir(path.dirname(file), { recursive: true });
+  const temporary = path.join(path.dirname(file), `.plugins-${randomUUID()}.json`);
+  try {
+    const handle = await open(temporary, 'wx', 0o644);
+    try { await handle.writeFile(JSON.stringify(value, null, 2) + '\n'); await handle.sync(); } finally { await handle.close(); }
+    const checked = await readPluginConfig(temporary);
+    await rename(temporary, file);
+    return checked;
+  } catch (error) { await rm(temporary, { force: true }); throw error; }
+}
+
+export const MAX_CODE_FILES = 256;
 // Literal specifiers only. Computed imports and packages are reported, never followed.
-const SPECIFIERS = [/\bfrom\s*['"]([^'"\n]+)['"]/g, /\bimport\s*['"]([^'"\n]+)['"]/g, /\bimport\s*\(\s*['"]([^'"\n]+)['"]\s*\)/g, /\bnew\s+URL\s*\(\s*['"]([^'"\n]+)['"]\s*,\s*import\.meta\.url\s*\)/g];
+export const PLUGIN_SPECIFIERS = [/\bfrom\s*['"]([^'"\n]+)['"]/g, /\bimport\s*['"]([^'"\n]+)['"]/g, /\bimport\s*\(\s*['"]([^'"\n]+)['"]\s*\)/g, /\bnew\s+URL\s*\(\s*['"]([^'"\n]+)['"]\s*,\s*import\.meta\.url\s*\)/g];
+const SPECIFIERS = PLUGIN_SPECIFIERS;
 
 /**
  * Fingerprint the plugin code without importing it: the entry module plus every