@mokuyoaxis/dsh-iris 0.2.7 → 0.3.0-beta.1

package/lib/network-routing.js

@@ -0,0 +1,283 @@
+// Instance-owned routing. CONNECT preflight never sends a business request.
+import net from 'node:net';
+import crypto from 'node:crypto';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { readNetworkConfig } from './network-config-service.js';
+import { networkNodeCredentialStatus, NETWORK_ROUTING_CONFIG_VERSION } from './network-config.js';
+import { checkedNetworkRequirement, networkPolicyError, createNetworkAttemptBudget } from './network-policy.js';
+import { createProviderNetworkClient, inheritedProviderFetch } from './provider-network.js';
+import { ProviderContractError } from './provider-contract.js';
+
+const hash = value => crypto.createHash('sha256').update(JSON.stringify(value)).digest('hex');
+const authority = url => `${url.hostname}:${url.port || (url.protocol === 'https:' ? 443 : 80)}`;
+const nodeUri = node => `${node.protocol}://${net.isIP(node.host) === 6 ? '[' + node.host + ']' : node.host}:${node.port}`;
+const PREFLIGHT_ERRORS = new Set([
+  'ECONNREFUSED', 'ECONNRESET', 'ECONNABORTED', 'EHOSTUNREACH', 'ENETUNREACH', 'ENETDOWN', 'EAI_AGAIN', 'ENOTFOUND',
+  'ETIMEDOUT', 'EPIPE', 'EADDRNOTAVAIL', 'EACCES', 'EPERM', 'IRIS_NETWORK_CONNECT_REJECTED',
+  'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_HEADERS_TIMEOUT', 'UND_ERR_HEADERS_OVERFLOW', 'UND_ERR_SOCKET', 'UND_ERR_ABORTED', 'UND_ERR_PRX_TLS',
+  'DEPTH_ZERO_SELF_SIGNED_CERT', 'SELF_SIGNED_CERT_IN_CHAIN', 'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
+  'UNABLE_TO_GET_ISSUER_CERT', 'UNABLE_TO_GET_ISSUER_CERT_LOCALLY', 'CERT_HAS_EXPIRED', 'CERT_NOT_YET_VALID', 'CERT_REVOKED',
+  'ERR_TLS_CERT_ALTNAME_INVALID', 'ERR_TLS_HANDSHAKE_TIMEOUT'
+]);
+const preflightUnavailable = error => PREFLIGHT_ERRORS.has(error.code) || /^(?:ERR_SSL_|HPE_)[A-Z0-9_]+$/.test(error.code || '')
+  || ['AbortError', 'TimeoutError'].includes(error.name);
+function failure(context, code, message, category = 'network') {
+  const operation = context.operation || 'submit';
+  const notAccepted = ['submit', 'prepareInput', 'discover', 'vision'].includes(operation);
+  return Object.assign(new ProviderContractError(message, { providerCode: code, category, stage: notAccepted ? 'prepare' : operation,
+    acceptance: notAccepted ? 'not_accepted' : 'accepted' }), { code });
+}
+
+async function directPreflight(url, signal, timeoutMs) {
+  signal?.throwIfAborted();
+  const combined = signal ? AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)]) : AbortSignal.timeout(timeoutMs);
+  await new Promise((resolve, reject) => {
+    const socket = net.connect({ host: url.hostname.replace(/^\[|\]$/g, ''), port: Number(url.port || (url.protocol === 'https:' ? 443 : 80)) });
+    const aborted = () => socket.destroy(combined.reason);
+    combined.addEventListener('abort', aborted, { once: true });
+    const cleanup = () => combined.removeEventListener('abort', aborted);
+    socket.once('error', error => { cleanup(); reject(error); });
+    socket.once('connect', () => { cleanup(); socket.destroy(); resolve(); });
+    if (combined.aborted) aborted();
+  });
+}
+
+function transportFetchInput(transport, input, options) {
+  // Node's built-in fetch and the installed Undici use different Web IDL brands.
+  // Convert only at the explicit transport boundary; inherited fetch stays native.
+  if (input instanceof Request) {
+    const request = new Request(input, options);
+    return { input: new transport.Request(request.url, request), options: { signal: request.signal } };
+  }
+  if (options.body instanceof FormData) {
+    const body = new transport.FormData();
+    for (const [name, value] of options.body) body.append(name, value);
+    return { input, options: { ...options, body } };
+  }
+  return { input, options };
+}
+
+export function createProviderNetworkManager({ networkConfigPath, onRoute, tls, proxyTls, scheduler, preflightTimeoutMs = 3000,
+  loadTransport = () => {
+    // Initialize Node's own fetch classes/default dispatcher without a request.
+    // Undici must inherit an existing dispatcher rather than create its own default.
+    void globalThis.Request;
+    return import('undici');
+  } } = {}) {
+  if (onRoute !== undefined && typeof onRoute !== 'function') throw new TypeError('onRoute 必须是函数');
+  if (typeof loadTransport !== 'function' || !Number.isInteger(preflightTimeoutMs) || preflightTimeoutMs < 1 || preflightTimeoutMs > 30000) throw new TypeError('网络客户端装配参数无效');
+  const clients = new Map(), retiring = new Set();
+  let closing = false, disposal, transport, revision, cleanupFailed = false;
+  function retire(client) {
+    const pending = client.dispose();
+    retiring.add(pending);
+    void pending.then(() => retiring.delete(pending), () => { cleanupFailed = true; retiring.delete(pending); });
+  }
+  function remember(slot, key, client, routed = false) {
+    const previous = clients.get(slot);
+    clients.set(slot, { key, client, routed });
+    if (previous) retire(previous.client);
+    return client;
+  }
+  const library = () => transport ||= Promise.resolve().then(loadTransport).catch(() => {
+    throw failure({ operation: 'discover' }, 'IRIS_NETWORK_CLIENT_UNAVAILABLE', '代理客户端未安装或无法加载；请使用包含所需生产依赖的完整 Iris 安装，不会退回直连', 'invalid_request');
+  });
+  async function scheduledFetch(fetch, dispatcher, input, options, context) {
+    const managed = scheduler.dispatcher(dispatcher, context, options.signal);
+    try { return await fetch(input, { ...options, dispatcher: managed }); }
+    catch (error) {
+      const queuedFailure = [error, error.cause].some(value => typeof value?.code === 'string' && value.code.startsWith('IRIS_SCHEDULER_'));
+      if (managed.dispatches === 0 && (queuedFailure || options.signal?.aborted)) {
+        const original = typeof error.cause?.code === 'string' && error.cause.code.startsWith('IRIS_SCHEDULER_') ? error.cause : error;
+        throw failure(context, typeof original.code === 'string' && original.code.startsWith('IRIS_SCHEDULER_') ? original.code : 'IRIS_SCHEDULER_ABORTED',
+          '请求在本地调度期间停止，业务请求尚未派发', options.signal?.aborted ? 'aborted' : 'rate_limit');
+      }
+      throw error;
+    }
+  }
+
+  function resolveProviderNetwork({ providerId, modelRef, networkRequirement } = {}) {
+    if (closing) throw networkPolicyError('IRIS_PROVIDER_NETWORK_CLOSED', '网络管理实例已关闭');
+    if (networkRequirement === undefined) {
+      if (!scheduler) return undefined;
+      const key = JSON.stringify(['scheduled-inherit', providerId, modelRef]);
+      if (clients.has(key)) return clients.get(key).client;
+      const scope = new AsyncLocalStorage();
+      const base = createProviderNetworkClient({ async fetchPort(input, options = {}) {
+        const context = scope.getStore();
+        if (!context) throw networkPolicyError('IRIS_NETWORK_OPERATION_REQUIRED', '调度客户端必须在完整操作内调用');
+        const { getGlobalDispatcher } = await library();
+        return scheduledFetch(inheritedProviderFetch, getGlobalDispatcher(), input, options, context);
+      } });
+      const client = Object.freeze({ ...base, run(action, context = {}) {
+        return base.run(fetch => scope.run({ providerId, modelRef, ...context }, () => action(fetch)));
+      } });
+      return remember(key, key, client);
+    }
+    const requirement = Object.freeze(checkedNetworkRequirement(networkRequirement));
+    if (typeof providerId !== 'string' || !providerId.trim() || providerId.length > 256 || /[\x00-\x1f\x7f]/.test(providerId)) throw networkPolicyError('IRIS_NETWORK_CONTEXT_REQUIRED', '网络解析需要明确的供应商身份');
+    if (!networkConfigPath) throw networkPolicyError('IRIS_NETWORK_CONTEXT_REQUIRED', '此供应商配置需要明确的 network-config，不会使用默认出口');
+    const saved = readNetworkConfig(networkConfigPath), config = saved.config;
+    if (config.schemaVersion !== NETWORK_ROUTING_CONFIG_VERSION || config.configId !== requirement.configId) {
+      throw networkPolicyError('IRIS_NETWORK_CONFIG_MISMATCH', '网络配置版本或身份与供应商目录不符，不会借用其他配置');
+    }
+    if (revision !== saved.revision) {
+      revision = saved.revision;
+      for (const [slot, entry] of clients) if (entry.routed) {
+        clients.delete(slot); retire(entry.client);
+      }
+    }
+    const binding = config.bindings.find(value => value.catalogId === requirement.catalogId && value.providerId === providerId);
+    const pool = binding ? config.pools.find(value => value.id === binding.poolId) : undefined;
+    if (binding && (!pool?.enabled || !pool.candidates.length)) throw networkPolicyError('IRIS_NETWORK_POOL_UNAVAILABLE', '显式绑定的出口池为空或已停用，不会隐式继承或直连');
+    const secrets = pool ? pool.candidates.flatMap(candidate => {
+      const node = candidate.kind === 'node' && config.nodes.find(value => value.id === candidate.nodeId);
+      return node?.auth ? [process.env[node.auth.usernameEnv], process.env[node.auth.passwordEnv]] : [];
+    }) : [];
+    const slot = hash([requirement, providerId, ...(scheduler ? [modelRef] : [])]);
+    const key = hash([saved.revision, requirement, providerId, ...(scheduler ? [modelRef] : []), secrets]);
+    const cached = clients.get(slot);
+    if (cached?.key === key) return cached.client;
+    const scope = new AsyncLocalStorage(), dispatchers = new Map();
+    // Capture only this client's explicitly referenced values; later resolutions
+    // use a new client if credentials rotate, while admitted operations can drain.
+    const nodeIds = new Set(pool?.candidates.filter(candidate => candidate.kind === 'node').map(candidate => candidate.nodeId) || []);
+    const nodes = new Map(config.nodes.filter(node => nodeIds.has(node.id)).map(node => [node.id, { ...node, credentialStatus: networkNodeCredentialStatus(node),
+      ...(node.auth ? { token: `Basic ${Buffer.from(`${process.env[node.auth.usernameEnv] || ''}:${process.env[node.auth.passwordEnv] || ''}`).toString('base64')}` } : {}) }]));
+
+    async function choose(url, options, context) {
+      if (!pool) return { route: 'inherit' };
+      const budget = context.networkBudget || createNetworkAttemptBudget();
+      for (const candidate of pool.candidates) {
+        if (options.signal?.aborted) throw failure(context, 'IRIS_NETWORK_ABORTED', '业务请求发送前已取消出口预检', 'aborted');
+        const probeKey = JSON.stringify([key, url.origin, candidate]);
+        if (budget.probes.has(probeKey)) {
+          const previous = await budget.probes.get(probeKey);
+          if (previous) return previous;
+          continue;
+        }
+        const node = candidate.kind === 'node' ? nodes.get(candidate.nodeId) : undefined;
+        if (candidate.kind === 'node' && (!node?.enabled || !['none', 'ready'].includes(node.credentialStatus))) {
+          budget.probes.set(probeKey, Promise.resolve(null)); continue;
+        }
+        if (!budget.remaining) continue;
+        budget.remaining--;
+        let complete;
+        const result = new Promise(resolve => { complete = resolve; });
+        budget.probes.set(probeKey, result);
+        try {
+          if (candidate.kind === 'direct') {
+            await directPreflight(url, options.signal, preflightTimeoutMs);
+            const selected = { route: 'direct', poolId: pool.id }; complete(selected); return selected;
+          }
+          const { Client } = await library();
+          const probe = new Client(nodeUri(node), { connect: proxyTls, connectTimeout: preflightTimeoutMs });
+          try {
+            const signal = options.signal ? AbortSignal.any([options.signal, AbortSignal.timeout(preflightTimeoutMs)]) : AbortSignal.timeout(preflightTimeoutMs);
+            const connected = await probe.connect({ path: authority(url), signal,
+              headers: { ...(node.token ? { 'proxy-authorization': node.token } : {}), host: authority(url) } });
+            connected.socket.destroy();
+            if (connected.statusCode !== 200) throw Object.assign(new Error('CONNECT rejected'), { code: 'IRIS_NETWORK_CONNECT_REJECTED' });
+          } finally { await probe.destroy(); }
+          const selected = { route: 'proxy', poolId: pool.id, nodeId: node.id }; complete(selected); return selected;
+        } catch (error) {
+          complete(null);
+          if (options.signal?.aborted) throw failure(context, 'IRIS_NETWORK_ABORTED', '业务请求发送前已取消出口预检', 'aborted');
+          if (error.code === 'IRIS_NETWORK_CLIENT_UNAVAILABLE') throw error;
+          if (!preflightUnavailable(error)) throw error;
+          // Only the independent connection preflight may select another route.
+        }
+      }
+      throw failure(context, 'IRIS_NETWORK_POOL_EXHAUSTED', '出口池没有通过连接预检的候选；未发送业务请求，也未隐式直连');
+    }
+
+    async function dispatcherFor(selected) {
+      const id = selected.nodeId || 'direct';
+      if (!dispatchers.has(id)) {
+        const pending = library().then(({ Agent, ProxyAgent }) => {
+          const node = selected.nodeId && nodes.get(selected.nodeId);
+          return node ? new ProxyAgent({ uri: nodeUri(node), token: node.token, requestTls: tls, proxyTls,
+            connectTimeout: preflightTimeoutMs, proxyTunnel: true }) : new Agent({ connect: tls, connectTimeout: preflightTimeoutMs });
+        });
+        dispatchers.set(id, pending);
+        void pending.catch(() => { if (dispatchers.get(id) === pending) dispatchers.delete(id); });
+      }
+      return dispatchers.get(id);
+    }
+
+    const base = createProviderNetworkClient({
+      async fetchPort(input, options = {}) {
+        const state = scope.getStore();
+        if (!state) throw networkPolicyError('IRIS_NETWORK_OPERATION_REQUIRED', '显式网络客户端必须在完整操作内调用');
+        if (state.context.taskId && typeof state.context.recordNetworkRoute !== 'function') {
+          throw failure(state.context, 'IRIS_NETWORK_EVIDENCE_REQUIRED', 'Task 出站需要 Core 提供路线持久化端口，已停止派发', 'local_io');
+        }
+        if (input instanceof Request && options.signal === undefined) options = { ...options, signal: input.signal };
+        const url = new URL(input instanceof Request ? input.url : input);
+        if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password) throw failure(state.context, 'IRIS_NETWORK_TARGET_INVALID', '出站目标需要不含认证信息的 HTTP(S) 地址', 'invalid_request');
+        state.selection ||= choose(url, options, state.context);
+        const selected = await state.selection;
+        const dispatcher = selected.route === 'inherit' ? undefined : await dispatcherFor(selected);
+        const fact = { ...requirement, configGeneration: config.generation, configRevision: saved.revision, providerId,
+          operation: state.context.operation || 'discover', ...selected, ...(state.context.attemptId ? { attemptId: state.context.attemptId } : {}) };
+        if (state.context.recordNetworkRoute) {
+          try { await state.context.recordNetworkRoute(fact); }
+          catch (error) {
+            throw failure(state.context, /^IRIS_(?:TASK|NETWORK)_/.test(error.code || '') ? error.code : 'IRIS_NETWORK_ROUTE_WRITE_FAILED',
+              error.code === 'IRIS_NETWORK_ROUTE_LIMIT' ? '原 Task 的路线事实已达限额，已停止派发并保留历史'
+                : '路线事实未能持久化，已停止出站；请检查存储和原 Task 身份', 'local_io');
+          }
+        }
+        if (onRoute) {
+          try { await onRoute(fact, state.context); }
+          catch (error) {
+            if (!/^IRIS_(?:TASK|NETWORK)_/.test(error.code || '')) throw error;
+            throw failure(state.context, error.code, error.code === 'IRIS_NETWORK_ROUTE_LIMIT'
+              ? '原 Task 的路线事实已达限额，已停止派发并保留历史'
+              : '路线事实未能持久化，已停止出站；请检查存储和原 Task 身份', 'local_io');
+          }
+        }
+        // Once business dispatch starts, errors remain conservatively ambiguous.
+        // Neither the next proxy nor a direct connection may replay this request.
+        try {
+          if (!dispatcher) {
+            if (!scheduler) return await inheritedProviderFetch(input, options);
+            const { getGlobalDispatcher } = await library();
+            return await scheduledFetch(inheritedProviderFetch, getGlobalDispatcher(), input, options, { providerId, modelRef, ...state.context });
+          }
+          const transport = await library(), request = transportFetchInput(transport, input, options);
+          if (scheduler) return await scheduledFetch(transport.fetch, dispatcher, request.input, request.options, { providerId, modelRef, ...state.context });
+          return await transport.fetch(request.input, { ...request.options, dispatcher });
+        } catch (error) {
+          if (typeof error.code === 'string' && error.code.startsWith('IRIS_SCHEDULER_')) throw error;
+          if (options.signal?.aborted) throw options.signal.reason;
+          throw Object.assign(new TypeError('出站请求失败；出口已选定，未自动重放请求'), { code: 'IRIS_NETWORK_TRANSPORT', cause: error });
+        }
+      },
+      async close() {
+        const results = await Promise.allSettled([...dispatchers.values()].map(async value => (await value).close()));
+        if (results.some(value => value.status === 'rejected')) throw new Error('部分网络连接未能正常释放');
+      }
+    });
+    const client = Object.freeze({ ...base, networkRequirement: requirement, providerId, ...(pool ? { poolId: pool.id } : {}),
+      run(action, context = {}) {
+        return base.run(fetch => scope.run({ context, selection: null }, () => action(fetch)));
+      } });
+    return remember(slot, key, client, true);
+  }
+
+  function dispose() {
+    if (!disposal) {
+      closing = true;
+      disposal = (async () => {
+        const results = await Promise.allSettled([
+          ...[...clients.values()].map(entry => entry.client.dispose()), ...retiring
+        ]);
+        clients.clear();
+        if (cleanupFailed || results.some(value => value.status === 'rejected')) throw new Error('网络管理实例释放失败');
+      })();
+    }
+    return disposal;
+  }
+  return Object.freeze({ resolveProviderNetwork, dispose, scheduler });
+}

package/lib/operation-runner.js

@@ -0,0 +1,281 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createApplicationRuntime } from './application-runtime.js';
+import { normalizeCoreOptions } from './core-contract.js';
+import { createCoreRuntime } from './core-runtime.js';
+import { createImageFlowService } from './image-flow.js';
+import { inspectRunnerArea } from './execution-ownership.js';
+import { requestDirectory } from './local-request-root.js';
+import { inspectCoreWriterLease } from './core-runtime.js';
+import { recoverCoreWriterLease } from './core-lease-recovery.js';
+import { acceptOperation, inspectExecutionRoot, operationId, readOperation, readAllOperations,
+  transitionOperation, projectOperation, operationFail, MAX_ACTIVE_OPERATIONS } from './operation-store.js';
+import { reservePluginOperation } from './plugin-operations.js';
+import { invokeReservedPlugin } from './plugin-execution.js';
+import { acceptPluginOperation, pluginInputDigest, pluginSourceArtifacts, reservePluginArtifact } from './plugin-operation-store.js';
+import { readFlowRun } from './flow-store.js';
+import { findFlowTask } from './core-tasks.js';
+
+const activeState = record => ['queued', 'running'].includes(record.state);
+const busy = () => operationFail('IRIS_CORE_DATA_ROOT_BUSY', '当前写者正在执行，请用原 Key 稍后明确重试');
+
+export function executionRunnerDirectory(root) {
+  return requestDirectory(root, inspectExecutionRoot(root), 'runner');
+}
+export function inspectExecutionLease(root) {
+  return inspectCoreWriterLease(executionRunnerDirectory(root));
+}
+export function recoverExecutionLease(root, options) {
+  return recoverCoreWriterLease(executionRunnerDirectory(root), options);
+}
+
+/** One execution owner, one finite continue per accepted Operation. Construction performs no I/O. */
+export function createOperationRunner({ dataRoot, application: suppliedApplication, resolveImageCandidates, resolveAudioCandidates, resolveVideoCandidates, resolveTaskAdapter, onExecutionError,
+  pluginRegistry, allowedOperations = [] } = {}) {
+  const root = normalizeCoreOptions({ dataRoot }).dataRoot;
+  const application = suppliedApplication || createApplicationRuntime({ dataRoot: root, resolveImageCandidates, resolveAudioCandidates, resolveVideoCandidates, resolveTaskAdapter });
+  const ports = { resolveImageCandidates, resolveAudioCandidates, resolveVideoCandidates, resolveTaskAdapter };
+  if (onExecutionError !== undefined && typeof onExecutionError !== 'function') throw new TypeError('执行错误报告器须为函数');
+  const queue = [], active = new Map(), finalizing = new Map();
+  const scheduled = Boolean(application.scheduler);
+  const transaction = (action, options) => application.transaction ? application.transaction(action, options) : application.run('writer', action);
+  let state = 'new', physicalRoot, directory, ownership, lease, ownerInstanceId, draining, disposal, failure, wake;
+
+  function snapshot() {
+    return Object.freeze({ state, queued: queue.length, active: active.keys().next().value || null,
+      ...(scheduled ? { activeOperations: [...active.keys()] } : {}),
+      executionEnabled: state === 'open', failed: Boolean(failure) });
+  }
+  function requireOwner() {
+    if (state !== 'open' && state !== 'closing') operationFail('IRIS_EXECUTION_UNAVAILABLE', '执行服务未就绪或已停止');
+    if (inspectRunnerArea(directory)?.fingerprint !== ownership.fingerprint) {
+      operationFail('IRIS_EXECUTION_OWNERSHIP_LOST', '执行所有权已改变，停止执行并保留现场');
+    }
+  }
+  function writable() {
+    requireOwner();
+    if (state !== 'open') operationFail('IRIS_EXECUTION_UNAVAILABLE', '执行服务正在关闭');
+  }
+  function failRunner(error) {
+    failure ||= error; state = 'failed';
+    for (const job of active.values()) job.controller.abort();
+  }
+  function finishIfActive(id, terminal, failureCode) {
+    if (finalizing.has(id)) return finalizing.get(id);
+    const completion = transaction(runtime => runtime.run('execute', ({ dataRoot }) => {
+      requireOwner();
+      const record = readOperation(dataRoot, id);
+      if (!record || !activeState(record)) return record;
+      if (record.ownerInstanceId !== ownerInstanceId) operationFail('IRIS_EXECUTION_OWNERSHIP_LOST', 'Operation 不属于本次执行实例');
+      return transitionOperation(dataRoot, { id, expectedRevision: record.revision, state: terminal,
+        ...(failureCode ? { failureCode } : {}) });
+    }), { finalize: true }).finally(() => { finalizing.delete(id); });
+    finalizing.set(id, completion);
+    return completion;
+  }
+  async function perform(job) {
+    let admitted = false;
+    try {
+      const saved = readOperation(physicalRoot, job.id);
+      job.runId = saved?.runId;
+      const execute = saved?.action === 'flow.continue' && application.runMedia ? application.runMedia : (action, options) => application.run('writer', action, options);
+      await execute(runtime => { admitted = true; return runtime.run('execute', async ({ dataRoot }) => {
+        requireOwner();
+        let record = readOperation(dataRoot, job.id);
+        if (!record || !activeState(record)) return;
+        if (record.ownerInstanceId !== ownerInstanceId) operationFail('IRIS_EXECUTION_OWNERSHIP_LOST', 'Operation 执行归属不一致');
+        if (job.stopReason) {
+          transitionOperation(dataRoot, { id: job.id, expectedRevision: record.revision, state: job.stopReason }); return;
+        }
+        if (record.action === 'plugin.execute') {
+          let reservation, result, executionError;
+          try {
+            job.authorize?.();
+            reservation = reservePluginOperation(pluginRegistry, record.operationId, record.input, allowedOperations, record.dependency);
+            record = transitionOperation(dataRoot, { id: job.id, expectedRevision: record.revision, state: 'running' });
+            result = await invokeReservedPlugin(runtime, reservation, { imports: { operationId: record.id, sources: record.sourceArtifactIds,
+              authorize: job.authorize, reserve: () => reservePluginArtifact(dataRoot, inspectExecutionRoot(dataRoot), job.id) } });
+          } catch (error) { executionError = error; }
+          finally { reservation?.release(); }
+          const current = readOperation(dataRoot, job.id);
+          const dependencyError = /IRIS_PLUGIN_(?:CLOSED|CONTRIBUTION_MISSING|DEPENDENCY_MISMATCH)/.test(executionError?.code || '');
+          const denied = /(?:DENIED|HANDSHAKE_REQUIRED|AUTH_REQUIRED|REVOKED)$/.test(executionError?.code || '');
+          transitionOperation(dataRoot, { id: job.id, expectedRevision: current.revision, state: job.stopReason || (executionError ? 'failed' : 'succeeded'),
+            ...(executionError && !job.stopReason ? { failureCode: dependencyError ? 'dependency_unavailable' : denied ? 'permission_denied' : 'execution_failed' } : {}),
+            ...(!executionError && !job.stopReason ? { value: result.value } : {}) });
+          if (executionError && !job.stopReason) onExecutionError?.(executionError, job.id);
+          return;
+        }
+        try { record = transitionOperation(dataRoot, { id: job.id, expectedRevision: record.revision, state: 'running' }); }
+        catch (error) {
+          if (error.code !== 'IRIS_OPERATION_RUN_CHANGED') throw error;
+          transitionOperation(dataRoot, { id: job.id, expectedRevision: record.revision, state: 'failed', failureCode: 'run_changed' }); return;
+        }
+        let executionError;
+        try { await createImageFlowService(runtime, ports).execute('flow.continue', { run_id: record.runId }); }
+        catch (error) { executionError = error; }
+        // The operation-scoped writer is still held, including after its signal aborts.
+        // Persist only local execution facts; Provider Task outcome remains authoritative.
+        transitionOperation(dataRoot, { id: job.id, expectedRevision: record.revision,
+          state: job.stopReason || (executionError ? 'failed' : 'succeeded'),
+          ...(executionError && !job.stopReason ? { failureCode: 'execution_failed' } : {}) });
+        if (executionError && !job.stopReason) onExecutionError?.(executionError, job.id);
+      }); }, { signal: job.controller.signal, ...(saved?.runId ? { key: `run:${saved.runId}` } : {}) });
+    } catch (error) {
+      if (job.stopReason && error.name === 'AbortError' && !application.snapshot().cleanupFailed) {
+        await finishIfActive(job.id, job.stopReason);
+      } else if (scheduled && !admitted && !application.snapshot().cleanupFailed
+          && ['IRIS_SCHEDULER_QUEUE_TIMEOUT', 'IRIS_SCHEDULER_QUEUE_FULL'].includes(error.code)) {
+        await finishIfActive(job.id, job.stopReason || 'failed', job.stopReason ? undefined : 'execution_failed');
+        if (!job.stopReason) onExecutionError?.(error, job.id);
+      } else throw error;
+    }
+  }
+  function pump() {
+    if (draining) { wake?.(); return; }
+    if (state !== 'open') return;
+    let blocked = false;
+    draining = (async () => {
+      while ((state === 'open' && queue.length && !blocked) || active.size) {
+        while (state === 'open' && queue.length && !blocked && active.size < (scheduled ? MAX_ACTIVE_OPERATIONS : 1)) {
+          const job = queue.shift(); active.set(job.id, job);
+          job.done = perform(job).catch(error => {
+            if (error.code !== 'IRIS_CORE_DATA_ROOT_BUSY') throw error;
+            queue.unshift(job); blocked = true; // Explicit retry only; no lease stealing or polling timer.
+          }).finally(() => { active.delete(job.id); });
+        }
+        if (active.size) {
+          const added = new Promise(resolve => { wake = resolve; });
+          await Promise.race([...active.values()].map(job => job.done).concat(added));
+          wake = null;
+        }
+      }
+    })();
+    void draining.then(() => { draining = null; if (state === 'open' && queue.length && !blocked) queueMicrotask(pump); },
+      error => { draining = null; failRunner(error); });
+  }
+  async function start() {
+    if (state !== 'new') operationFail('IRIS_EXECUTION_LIFECYCLE', '执行服务只能显式启动一次');
+    state = 'starting';
+    try {
+      physicalRoot = fs.realpathSync(root); directory = executionRunnerDirectory(physicalRoot);
+      lease = createCoreRuntime({ dataRoot: directory, mode: 'writer' }); lease.start();
+      ownership = inspectRunnerArea(directory); ownerInstanceId = ownership.owner.instanceId;
+      state = 'open';
+      await transaction(runtime => runtime.run('execute', ({ dataRoot }) => {
+        requireOwner();
+        for (const record of readAllOperations(dataRoot).filter(activeState)) {
+          transitionOperation(dataRoot, { id: record.id, expectedRevision: record.revision, state: 'interrupted' });
+        }
+      }));
+      return snapshot();
+    } catch (error) {
+      state = 'failed'; failure = error;
+      if (lease) await lease.dispose();
+      throw error;
+    }
+  }
+  async function submit(input, { authorize } = {}) {
+    writable();
+    if (input?.operationId !== undefined) {
+      if (!input || Object.keys(input).sort().join(',') !== 'dependency,input,key,operationId') operationFail('IRIS_OPERATION_INPUT_INVALID', '业务执行需要原 Key、准确贡献依赖及输入');
+      authorize?.();
+      const marker = inspectExecutionRoot(physicalRoot), id = operationId(marker, input.key), previous = readOperation(physicalRoot, id, marker);
+      const fingerprint = pluginInputDigest(input.operationId, input.input, input.dependency, previous?.sourceArtifactIds);
+      if (previous) {
+        if (previous.action !== 'plugin.execute' || previous.inputDigest !== fingerprint) operationFail('IRIS_OPERATION_KEY_CONFLICT', '该 Key 已绑定另一业务或输入');
+        if (previous.state === 'queued' && previous.ownerInstanceId === ownerInstanceId) queueMicrotask(pump);
+        return { contractVersion: 0, operation: projectOperation(previous), idempotentReplay: true };
+      }
+      if (!scheduled && (application.snapshot().activeWrites || application.snapshot().queuedWrites)) busy();
+      const reservation = reservePluginOperation(pluginRegistry, input.operationId, input.input, allowedOperations, input.dependency);
+      let record, replay = false;
+      try {
+        record = await transaction(runtime => runtime.run('execute', ({ dataRoot }) => {
+          writable(); authorize?.();
+          const current = readOperation(dataRoot, id, marker);
+          if (current) {
+            if (current.action !== 'plugin.execute' || current.inputDigest !== pluginInputDigest(input.operationId, input.input, input.dependency, current.sourceArtifactIds)) {
+              operationFail('IRIS_OPERATION_KEY_CONFLICT', '该 Key 已绑定另一业务或输入');
+            }
+            replay = true; return current;
+          }
+          if (readAllOperations(dataRoot).filter(activeState).length >= MAX_ACTIVE_OPERATIONS - Number(scheduled)) operationFail('IRIS_OPERATION_QUEUE_FULL', '未结束的 Operation 已达上限；调度模式保留一个位置供原任务恢复');
+          return acceptPluginOperation(dataRoot, marker, id, { ...input, input: reservation.input,
+            sourceArtifactIds: pluginSourceArtifacts(reservation.input, reservation.artifactInputs), ownerInstanceId });
+        }));
+      } finally { reservation.release(); }
+      if (!replay) queue.push({ id, controller: new AbortController(), stopReason: null, authorize });
+      if (!replay || record.state === 'queued' && record.ownerInstanceId === ownerInstanceId) queueMicrotask(pump);
+      return { contractVersion: 0, operation: projectOperation(record), idempotentReplay: replay };
+    }
+    if (!input || typeof input !== 'object' || Array.isArray(input) || Object.keys(input).length !== 3
+        || !['key', 'runId', 'expectedRunRevision'].every(key => Object.hasOwn(input, key))) {
+      operationFail('IRIS_OPERATION_INPUT_INVALID', '需要明确 Key、Run 和预期 revision');
+    }
+    const marker = inspectExecutionRoot(physicalRoot), id = operationId(marker, input.key);
+    const previous = readOperation(physicalRoot, id, marker);
+    if (previous) {
+      if (previous.runId !== input.runId || previous.expectedRunRevision !== input.expectedRunRevision) {
+        operationFail('IRIS_OPERATION_KEY_CONFLICT', '该 Key 已绑定其他操作输入');
+      }
+      if (previous.state === 'queued' && previous.ownerInstanceId === ownerInstanceId) queueMicrotask(pump);
+      return { contractVersion: 0, operation: projectOperation(previous), idempotentReplay: true };
+    }
+    if (!scheduled && (application.snapshot().activeWrites || application.snapshot().queuedWrites)) busy();
+    const accepted = await transaction(runtime => runtime.run('execute', ({ dataRoot }) => {
+      writable();
+      if (scheduled && !readOperation(dataRoot, id) && readAllOperations(dataRoot).filter(activeState).length >= MAX_ACTIVE_OPERATIONS - 1
+          && !findFlowTask(dataRoot, readFlowRun(dataRoot, input.runId))?.attempts.length) {
+        operationFail('IRIS_OPERATION_QUEUE_FULL', '新提交队列已满；保留一个位置用于原任务查询和交付');
+      }
+      return acceptOperation(dataRoot, { ...input, ownerInstanceId });
+    }));
+    if (!accepted.idempotentReplay) {
+      queue.push({ id: accepted.operation.id, controller: new AbortController(), stopReason: null });
+      queueMicrotask(pump);
+    }
+    return { contractVersion: 0, operation: projectOperation(accepted.operation), idempotentReplay: accepted.idempotentReplay };
+  }
+  async function stop(id) {
+    writable();
+    const record = readOperation(physicalRoot, id);
+    if (!record) operationFail('IRIS_OPERATION_NOT_FOUND', 'Operation 不存在');
+    if (activeState(record)) {
+      if (record.ownerInstanceId !== ownerInstanceId) operationFail('IRIS_EXECUTION_OWNERSHIP_LOST', '不能停止另一执行实例的操作');
+      const job = active.get(id) || queue.find(job => job.id === id);
+      if (job) { job.stopReason = 'canceled'; job.controller.abort(); }
+      if (active.has(id)) await job.done;
+      else {
+        await finishIfActive(id, 'canceled');
+        const index = queue.indexOf(job);
+        if (index >= 0) queue.splice(index, 1);
+      }
+    }
+    const saved = readOperation(physicalRoot, id);
+    if (activeState(saved)) operationFail('IRIS_EXECUTION_STOP_UNSAVED', '停止尚未持久保存，请查询原 Operation');
+    return { contractVersion: 0, operation: projectOperation(saved),
+      localStopped: saved.state === 'canceled', remoteCancellation: 'not_requested' };
+  }
+  async function idle() { if (draining) await draining; if (failure) throw failure; return snapshot(); }
+  function dispose() {
+    if (disposal) return disposal;
+    if (state === 'new') { state = 'closed'; return disposal = suppliedApplication ? Promise.resolve(snapshot()) : application.dispose().then(snapshot); }
+    if (state === 'closed') return Promise.resolve(snapshot());
+    if (state !== 'failed') state = 'closing';
+    for (const job of active.values()) { job.stopReason ||= 'interrupted'; job.controller.abort(); }
+    disposal = (async () => {
+      if (draining) await draining;
+      if (failure) throw failure;
+      for (const job of queue.splice(0)) await finishIfActive(job.id, 'interrupted');
+      if (!suppliedApplication) await application.dispose();
+      await lease?.dispose(); state = 'closed'; return snapshot();
+    })();
+    return disposal;
+  }
+  return Object.freeze({ start, submit, stop, idle, dispose, snapshot,
+    scheduling(id) {
+      const job = active.get(id), phase = job?.runId && application.schedulingPhase(`run:${job.runId}`);
+      return scheduled && phase ? { phase } : undefined;
+    } });
+}