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

package/lib/mcp-server.js

@@ -0,0 +1,47 @@
+import { bridgeToolsForScopes, callCoreBridgeTool } from './core-bridge-tools.js';
+import { projectedMcpClient } from './core-connections.js';
+import { coreConnectionDiagnostic } from './core-connection-diagnostics.js';
+
+/** Client labels are optional observations. Their failure must not delay a Core
+ * command or discard its receipt; command authorization remains in Core. */
+export async function reportMcpClientInfo(client, clientInfo, transport) {
+  try { await client.reportClientInfo(clientInfo, transport); }
+  catch (error) {
+    console.error('[iris] MCP client declaration not recorded: ' + (/^IRIS_[A-Z_]+$/.test(error?.code) ? error.code : 'IRIS_MCP_METADATA_FAILED'));
+  }
+}
+
+/** One official-SDK tool factory for both standard transports and protocol eras. */
+export async function createMcpServerFactory({ client, version, transport = 'stdio' }) {
+  const [{ McpServer }, { z }] = await Promise.all([import('@modelcontextprotocol/server'), import('zod')]);
+  const snapshot = client.snapshot();
+  const tools = bridgeToolsForScopes(snapshot.scopes, snapshot.capabilities, snapshot.tools, snapshot.pluginOperations);
+  const factory = () => {
+    const server = new McpServer({ name: 'iris-core', version }, { capabilities: { tools: {} },
+      instructions: 'Iris is a proxy to an explicitly started Core. Inspect the granted catalog first. Execute only a user-selected operation; preserve its request UUID and exact dependency. An Operation receipt is not completion. After interruption or lost responses, inspect/lookup the original Operation; never automatically replay a write or start another Core. Display actual saved image content only after reading it.' });
+    if (transport === 'stdio') server.server.oninitialized = () => {
+      void reportMcpClientInfo(client, projectedMcpClient(server.server.getClientVersion()), transport);
+    };
+    for (const tool of tools) server.registerTool(tool.name, {
+      description: tool.description, inputSchema: z.fromJSONSchema(tool.parameters),
+      annotations: { readOnlyHint: tool.scope === 'read', destructiveHint: tool.scope === 'stop',
+        idempotentHint: true, openWorldHint: tool.scope !== 'read' }
+    }, async (args, context) => {
+      try {
+        void reportMcpClientInfo(client, projectedMcpClient(context.mcpReq.envelope?.['io.modelcontextprotocol/clientInfo'] || server.server.getClientVersion()), transport);
+        const result = await callCoreBridgeTool(client, tool.name, args, { signal: context.mcpReq.signal });
+        if (result.image) return { content: [{ type: 'image', data: result.image.bytes.toString('base64'), mimeType: result.image.mediaType },
+          { type: 'text', text: JSON.stringify({ artifactId: result.image.artifactId, bytes: result.image.bytes.length }) }] };
+        if (result.audio) return { content: [{ type: 'audio', data: result.audio.bytes.toString('base64'), mimeType: result.audio.mediaType },
+          { type: 'text', text: JSON.stringify({ artifactId: result.audio.artifactId, bytes: result.audio.bytes.length }) }] };
+        return { content: [{ type: 'text', text: JSON.stringify(result.value) }], structuredContent: result.value };
+      } catch (error) {
+        const diagnostic = coreConnectionDiagnostic(error, { stage: 'tool', references: args });
+        return { isError: true, content: [{ type: 'text', text: diagnostic.code + ' [' + diagnostic.stage + ']: ' + diagnostic.message + ' ' + diagnostic.action
+          + (diagnostic.requestId ? ' Request ID: ' + diagnostic.requestId : '') }], structuredContent: { contractVersion: 0, error: diagnostic } };
+      }
+    });
+    return server;
+  };
+  return { factory, tools: tools.map(tool => tool.name) };
+}

package/lib/model-directory-service.js

@@ -1,14 +1,17 @@
 import { listModels } from './adapters.js';
 import { capabilitiesOfDiscoveredModel } from './models.js';
-import { providerApiKey, providerMediaBaseUrl, selectMediaProtocol } from './provider-protocol.js';
+import { providerApiKey, providerMediaBaseUrl, selectMediaProtocol, providerProtocolDescriptor } from './provider-protocol.js';
+import { createConfiguredProviderAdapter } from './provider-adapters.js';
+import { invokeProviderOperation } from './provider-adapter.js';
 import { redactProviderMessage } from './provider-contract.js';
 import { MODEL_DIRECTORY_TTL_MS, MODEL_DIRECTORY_RETRY_MS, currentModelDirectory, modelDirectoryBinding } from './model-directory.js';
 
 const pending = new Map();
+const registryPending = new WeakMap();
 
 /** 只有完整发现成功才替换快照；相同连接合并网络读取，各调用方保存自己的配置。 */
-export async function refreshModelDirectory(provider, { force = false, signal, save, discover = listModels, now = Date.now() } = {}) {
-  if (!['dashscope', 'openai-images', 'openai-chat-images', 'openai-responses-images', 'gemini-web-music'].includes(selectMediaProtocol(provider).mediaProtocol)) {
+export async function refreshModelDirectory(provider, { force = false, signal, save, discover = listModels, now = Date.now(), registry } = {}) {
+  if (!providerProtocolDescriptor(selectMediaProtocol(provider).mediaProtocol, registry)) {
     return { refreshed: false, error: '当前协议未提供模型目录发现' };
   }
   const previous = currentModelDirectory(provider);
@@ -20,14 +23,21 @@ export async function refreshModelDirectory(provider, { force = false, signal, s
     }
   }
   signal?.throwIfAborted();
+  let calls = pending;
+  if (registry) {
+    if (!registryPending.has(registry)) registryPending.set(registry, new Map());
+    calls = registryPending.get(registry);
+    discover = async ({ signal, timeoutMs }) => (await invokeProviderOperation(
+      createConfiguredProviderAdapter(provider, { registry }), 'discover', { signal, timeoutMs })).models;
+  }
   const binding = modelDirectoryBinding(provider);
-  let job = pending.get(binding);
+  let job = calls.get(binding);
   if (!job) {
     const budget = AbortSignal.timeout(15000);
     job = discover({ key: providerApiKey(provider), baseUrl: providerMediaBaseUrl(provider),
       signal: signal ? AbortSignal.any([signal, budget]) : budget, timeoutMs: 15000 });
-    pending.set(binding, job);
-    job.finally(() => { if (pending.get(binding) === job) pending.delete(binding); }).catch(() => {});
+    calls.set(binding, job);
+    job.finally(() => { if (calls.get(binding) === job) calls.delete(binding); }).catch(() => {});
   }
   let discovered;
   try {

package/lib/model-directory.js

@@ -1,6 +1,6 @@
 import crypto from 'node:crypto';
 import { isKnownCapability } from './capability.js';
-import { providerApiKey, providerMediaBaseUrl, selectMediaProtocol, providerForImageModel, providerForMusicModel } from './provider-protocol.js';
+import { providerApiKey, providerMediaBaseUrl, selectMediaProtocol, providerForModelBinding } from './provider-protocol.js';
 
 export const MODEL_DIRECTORY_TTL_MS = 10 * 60 * 1000;
 export const MODEL_DIRECTORY_RETRY_MS = 30 * 1000;
@@ -35,9 +35,9 @@ export function currentModelDirectory(provider, { allowUnresolvedConnections = f
 }
 
 export function modelAvailabilityBinding(provider, modelId, capability) {
-  if (capability === 'image-gen') return modelDirectoryBinding(providerForImageModel(provider, modelId));
+  if (capability === 'image-gen') return modelDirectoryBinding(providerForModelBinding(provider, modelId, capability));
   if (capability === 'music-gen' && provider.models?.some(model => model?.id === modelId && model.musicProtocol)) {
-    return modelDirectoryBinding(providerForMusicModel(provider, modelId));
+    return modelDirectoryBinding(providerForModelBinding(provider, modelId, capability));
   }
   return modelDirectoryBinding(provider);
 }

package/lib/models.js

@@ -207,14 +207,14 @@ export function savedAssignmentRefs(pool, capability, values) {
 }
 
 /** Automatic pools reject known protocol gaps before constructing any adapter. */
-export function functionModelPool(providers, capability, assignment, { includeHostVision = false, allowUnresolvedConnections = false } = {}) {
+export function functionModelPool(providers, capability, assignment, { includeHostVision = false, allowUnresolvedConnections = false, registry } = {}) {
   const policy = functionPolicy(assignment, capability);
   return modelPool(providers, { includeHostVision }).filter(model => {
     if (!model.capabilities.includes(capability)) return false;
     if (policy.mode !== 'auto' || model.ref === HOST_VISION_REF) return true;
     const provider = providers.find(provider => provider.id === model.providerId);
     return supportsModelCapability(provider, model.id, capability, {
-      checkEndpoint: !allowUnresolvedConnections || !provider?.dshProvider
+      checkEndpoint: !allowUnresolvedConnections || !provider?.dshProvider, registry
     });
   });
 }

package/lib/music-transport.js

@@ -1,4 +1,5 @@
 import { ProviderContractError } from './provider-contract.js';
+import { readProviderText, PROVIDER_RESPONSE_LIMITS } from './provider-response.js';
 
 function responseError(message) {
   return new ProviderContractError(message, { stage: 'response', category: 'protocol', acceptance: 'unknown' });
@@ -32,7 +33,7 @@ export async function generateMusic({ key, baseUrl, model, prompt, timeoutMs = 3
     signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
     body: JSON.stringify({ model, stream: false, messages: [{ role: 'user', content: prompt }] })
   });
-  const text = await response.text();
+  const text = await readProviderText(response, { maxBytes: response.ok ? PROVIDER_RESPONSE_LIMITS.mediaJson : PROVIDER_RESPONSE_LIMITS.json });
   let body;
   try { body = JSON.parse(text); }
   catch (error) { if (response.ok) throw responseError('Music 响应不是有效 JSON'); }

package/lib/operation-runner.js

@@ -0,0 +1,236 @@
+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';
+
+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, resolveTaskAdapter, onExecutionError,
+  pluginRegistry, allowedOperations = [] } = {}) {
+  const root = normalizeCoreOptions({ dataRoot }).dataRoot;
+  const application = suppliedApplication || createApplicationRuntime({ dataRoot: root, resolveImageCandidates, resolveAudioCandidates, resolveTaskAdapter });
+  const ports = { resolveImageCandidates, resolveAudioCandidates, resolveTaskAdapter };
+  if (onExecutionError !== undefined && typeof onExecutionError !== 'function') throw new TypeError('执行错误报告器须为函数');
+  const queue = [];
+  let state = 'new', physicalRoot, directory, ownership, lease, ownerInstanceId, active, draining, disposal, failure;
+
+  function snapshot() {
+    return Object.freeze({ state, queued: queue.length, active: active?.id || null,
+      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';
+    active?.controller.abort();
+  }
+  async function finishIfActive(id, terminal) {
+    return application.run('writer', 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 });
+    }));
+  }
+  async function perform(job) {
+    try {
+      await application.run('writer', runtime => 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 });
+    } catch (error) {
+      if (job.stopReason && error.name === 'AbortError' && !application.snapshot().cleanupFailed) {
+        await finishIfActive(job.id, job.stopReason);
+      } else throw error;
+    }
+  }
+  function pump() {
+    if (draining || state !== 'open') return;
+    draining = (async () => {
+      while (state === 'open' && queue.length) {
+        active = queue.shift();
+        active.done = perform(active);
+        try { await active.done; }
+        catch (error) {
+          if (error.code !== 'IRIS_CORE_DATA_ROOT_BUSY') throw error;
+          queue.unshift(active); active = null; break; // No timer or lease stealing; explicit retry wakes this queue.
+        }
+        active = null;
+      }
+    })();
+    void draining.then(() => { draining = null; }, 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 application.run('writer', 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 (application.snapshot().activeWrites || application.snapshot().queuedWrites) busy();
+      const reservation = reservePluginOperation(pluginRegistry, input.operationId, input.input, allowedOperations, input.dependency);
+      let record;
+      try {
+        record = await application.run('writer', runtime => runtime.run('execute', ({ dataRoot }) => {
+          writable(); authorize?.();
+          if (readAllOperations(dataRoot).filter(activeState).length >= MAX_ACTIVE_OPERATIONS) 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(); }
+      queue.push({ id, controller: new AbortController(), stopReason: null, authorize }); queueMicrotask(pump);
+      return { contractVersion: 0, operation: projectOperation(record), idempotentReplay: false };
+    }
+    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 (application.snapshot().activeWrites || application.snapshot().queuedWrites) busy();
+    const accepted = await application.run('writer', runtime => runtime.run('execute', ({ dataRoot }) => {
+      writable(); 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?.id === id ? active : queue.find(job => job.id === id);
+      if (job) { job.stopReason = 'canceled'; job.controller.abort(); }
+      if (active?.id === id) await job.done;
+      else await finishIfActive(id, 'canceled');
+    }
+    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';
+    if (active) { active.stopReason ||= 'interrupted'; active.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 });
+}

package/lib/operation-store.js

@@ -0,0 +1,216 @@
+// Durable, non-executing local intentions. Call mutations under the supplied Core writer.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { atomicCreatePrivate, atomicWritePrivate } from './private-storage.js';
+import { inspectLocalRequestRoot, initializeLocalRequestRoot, requestDirectory } from './local-request-root.js';
+import { listCreationRequests } from './creation-request-store.js';
+import { readFlowRun, flowStep } from './flow-store.js';
+import { findFlowTask } from './core-tasks.js';
+import { findCoreArtifactMetadata } from './core-artifacts.js';
+import { validatePluginOperation, validatePluginBinding, transitionPluginOperation, projectPluginOperation } from './plugin-operation-store.js';
+
+const ID = /^op_[a-f0-9]{64}$/;
+const RUN = /^run_[a-f0-9]{24}$/;
+const TASK = /^task_[a-f0-9]{24}$/;
+const ARTIFACT = /^artifact_[a-f0-9]{24}$/;
+const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/;
+const DIGEST = /^sha256:[a-f0-9]{64}$/;
+const STATES = new Set(['queued', 'running', 'succeeded', 'failed', 'canceled', 'interrupted']);
+const ACTIVE = new Set(['queued', 'running']);
+const FAILURE_CODES = new Set(['run_changed', 'execution_failed']);
+export const MAX_ACTIVE_OPERATIONS = 8;
+export function operationFail(code, message) { throw Object.assign(new Error(message), { code }); }
+const invalid = () => operationFail('IRIS_OPERATION_STORE_INVALID', 'Operation 记录未知、损坏或与请求容器不一致');
+const hash = value => crypto.createHash('sha256').update(value).digest('hex');
+const iso = value => typeof value === 'string' && Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value;
+const positive = value => Number.isSafeInteger(value) && value >= 1;
+function keys(value, allowed, required = allowed) {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value)
+    && Object.keys(value).every(key => allowed.includes(key)) && required.every(key => Object.hasOwn(value, key)));
+}
+function input(value, allowed, required = allowed) {
+  if (!keys(value, allowed, required)) operationFail('IRIS_OPERATION_INPUT_INVALID', 'Operation 输入包含缺失或不支持的字段');
+}
+export function inspectExecutionRoot(root) {
+  const marker = inspectLocalRequestRoot(root, { allowAbsent: true });
+  if (![1, 2, 3].includes(marker?.schemaVersion)) operationFail('IRIS_OPERATION_ROOT_REQUIRED', 'Operation 需要新的专用执行根，请显式执行 execution init；不转换原根');
+  return marker;
+}
+export function initializeExecutionRoot(root, { imageGeneration = false, audio = false } = {}) {
+  const marker = initializeLocalRequestRoot(root, audio ? 3 : imageGeneration ? 2 : 1);
+  listCreationRequests(root); readAllOperations(root);
+  return marker;
+}
+export function operationId(marker, key) {
+  if (!UUID.test(key)) operationFail('IRIS_OPERATION_KEY_INVALID', 'Operation Key 须为小写 UUIDv4');
+  return 'op_' + hash(JSON.stringify(['operation/v0', marker.rootId, key]));
+}
+function inputDigest(runId, revision) {
+  return 'sha256:' + hash(JSON.stringify(['operation-call/v0', 'flow.continue', runId, revision]));
+}
+const bindingFor = run => ({ taskId: flowStep(run).taskId, sourceArtifactId: run.source?.artifactId ?? null,
+  comparisonArtifactId: run.compare?.artifactId ?? null, inputDigest: run.inputDigest });
+const artifactsFor = run => [...new Set([run.source?.artifactId, run.output?.artifactId, run.comparison?.artifactId, run.selection?.artifactId].filter(Boolean))];
+function validate(record, id, marker) {
+  if (record?.schemaVersion === 1) return validatePluginOperation(record, id, marker);
+  if (!keys(record, ['schemaVersion', 'id', 'rootId', 'revision', 'action', 'runId', 'expectedRunRevision', 'inputDigest',
+    'ownerInstanceId', 'binding', 'createdAt', 'updatedAt', 'state', 'cancelRequested', 'startedAt', 'finishedAt', 'result', 'failureCode'],
+  ['schemaVersion', 'id', 'rootId', 'revision', 'action', 'runId', 'expectedRunRevision', 'inputDigest',
+    'ownerInstanceId', 'binding', 'createdAt', 'updatedAt', 'state', 'cancelRequested'])
+      || record.schemaVersion !== 0 || !ID.test(id) || record.id !== id || record.rootId !== marker.rootId
+      || !positive(record.revision) || record.action !== 'flow.continue' || !RUN.test(record.runId)
+      || !positive(record.expectedRunRevision) || record.inputDigest !== inputDigest(record.runId, record.expectedRunRevision)
+      || !UUID.test(record.ownerInstanceId) || !STATES.has(record.state) || typeof record.cancelRequested !== 'boolean'
+      || !iso(record.createdAt) || !iso(record.updatedAt) || record.updatedAt < record.createdAt
+      || !keys(record.binding, ['taskId', 'sourceArtifactId', 'comparisonArtifactId', 'inputDigest'])
+      || !TASK.test(record.binding.taskId) || !(marker.schemaVersion === 3 && (record.binding.sourceArtifactId === null || ARTIFACT.test(record.binding.sourceArtifactId))
+        && (record.binding.comparisonArtifactId === null || ARTIFACT.test(record.binding.comparisonArtifactId))
+        || record.binding.sourceArtifactId === null && record.binding.comparisonArtifactId === null && marker.schemaVersion === 2
+        || ARTIFACT.test(record.binding.sourceArtifactId) && ARTIFACT.test(record.binding.comparisonArtifactId))
+      || !DIGEST.test(record.binding.inputDigest)) invalid();
+  const hasStarted = Object.hasOwn(record, 'startedAt');
+  if (record.revision !== (record.state === 'queued' ? 1 : record.state === 'running' || !hasStarted ? 2 : 3)) invalid();
+  if (hasStarted && (!iso(record.startedAt) || record.startedAt < record.createdAt || record.startedAt > record.updatedAt)) invalid();
+  if (record.state === 'queued' && (record.revision !== 1 || record.updatedAt !== record.createdAt || hasStarted || record.cancelRequested)
+      || record.state === 'running' && (!hasStarted || record.cancelRequested)
+      || record.state === 'succeeded' && (!hasStarted || record.cancelRequested)
+      || record.cancelRequested !== (record.state === 'canceled')
+      || record.state === 'failed' && (!FAILURE_CODES.has(record.failureCode) || !hasStarted && record.failureCode !== 'run_changed')
+      || record.state !== 'failed' && Object.hasOwn(record, 'failureCode')) invalid();
+  if (ACTIVE.has(record.state)) {
+    if (Object.hasOwn(record, 'finishedAt') || Object.hasOwn(record, 'result')) invalid();
+  } else {
+    if (!iso(record.finishedAt) || record.finishedAt !== record.updatedAt || record.finishedAt < record.createdAt
+        || !keys(record.result, ['runRevision', 'taskId', 'artifactIds']) || !positive(record.result.runRevision)
+        || record.result.runRevision < record.expectedRunRevision
+        || record.result.taskId !== null && record.result.taskId !== record.binding.taskId
+        || !Array.isArray(record.result.artifactIds) || record.binding.sourceArtifactId !== null && !record.result.artifactIds.length
+        || new Set(record.result.artifactIds).size !== record.result.artifactIds.length
+        || !record.result.artifactIds.every(value => ARTIFACT.test(value))
+        || record.binding.sourceArtifactId !== null && !record.result.artifactIds.includes(record.binding.sourceArtifactId)
+        || record.state === 'succeeded' && !record.result.taskId) invalid();
+  }
+  return record;
+}
+function validateBinding(root, record) {
+  if (record.action === 'plugin.execute') return validatePluginBinding(root, record);
+  const run = readFlowRun(root, record.runId), task = findFlowTask(root, run);
+  if (Object.entries(bindingFor(run)).some(([key, value]) => record.binding[key] !== value) || run.revision < record.expectedRunRevision
+      || record.result && (record.result.runRevision > run.revision || record.result.taskId && !task
+        || record.result.artifactIds.some(id => !artifactsFor(run).includes(id)))) {
+    operationFail('IRIS_OPERATION_BINDING_CONFLICT', 'Operation 与原 Run/Task/作品绑定冲突，停止操作并保留原记录');
+  }
+  return { run, task };
+}
+function fileFor(root, marker, id) {
+  if (!ID.test(id)) operationFail('IRIS_OPERATION_INPUT_INVALID', 'Operation ID 格式无效');
+  return path.join(requestDirectory(root, marker, 'operations'), id + '.json');
+}
+export function readOperation(root, id, marker = inspectExecutionRoot(root)) {
+  const file = fileFor(root, marker, id);
+  let record;
+  try {
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 256 * 1024) invalid();
+    try { record = JSON.parse(fs.readFileSync(file, 'utf8')); } catch (_) { invalid(); }
+  } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+  validate(record, id, marker); validateBinding(root, record);
+  return structuredClone(record);
+}
+export function readAllOperations(root) {
+  const marker = inspectLocalRequestRoot(root, { allowAbsent: true });
+  if (!marker || marker.schemaVersion === 0) return [];
+  const records = [];
+  for (const name of fs.readdirSync(requestDirectory(root, marker, 'operations'))) {
+    if (/^op_[a-f0-9]{64}\.json\.tmp-[1-9][0-9]*-[a-f0-9]{12}$/.test(name)) continue;
+    if (!/^op_[a-f0-9]{64}\.json$/.test(name)) invalid();
+    const record = readOperation(root, name.slice(0, -5), marker);
+    if (!record) invalid();
+    records.push(record);
+  }
+  const active = records.filter(record => ACTIVE.has(record.state));
+  if (active.length > MAX_ACTIVE_OPERATIONS || new Set(active.filter(record => record.action === 'flow.continue').map(record => record.runId)).size !== active.filter(record => record.action === 'flow.continue').length) invalid();
+  return records;
+}
+
+export function acceptOperation(root, value) {
+  input(value, ['key', 'runId', 'expectedRunRevision', 'ownerInstanceId']);
+  if (!RUN.test(value.runId) || !positive(value.expectedRunRevision) || !UUID.test(value.ownerInstanceId)) {
+    operationFail('IRIS_OPERATION_INPUT_INVALID', '需要明确 Run、正整数 revision 与 owner 实例 UUID');
+  }
+  const marker = inspectExecutionRoot(root), id = operationId(marker, value.key);
+  const fingerprint = inputDigest(value.runId, value.expectedRunRevision), previous = readOperation(root, id, marker);
+  if (previous) {
+    if (previous.inputDigest !== fingerprint) operationFail('IRIS_OPERATION_KEY_CONFLICT', '该 Key 已绑定其他操作输入');
+    return { operation: previous, idempotentReplay: true };
+  }
+  const run = readFlowRun(root, value.runId); findFlowTask(root, run);
+  if (run.revision !== value.expectedRunRevision) operationFail('IRIS_OPERATION_RUN_CHANGED', 'Run revision 已改变，请读取原流程后明确操作');
+  const active = readAllOperations(root).filter(record => ACTIVE.has(record.state));
+  const conflicting = active.find(record => record.runId === run.id);
+  if (conflicting) throw Object.assign(new Error('此 Run 已有未结束的 Operation'), { code: 'IRIS_OPERATION_RUN_BUSY', operationId: conflicting.id });
+  if (active.length >= MAX_ACTIVE_OPERATIONS) operationFail('IRIS_OPERATION_QUEUE_FULL', '未结束的 Operation 已达上限，本次未接收');
+  const now = new Date().toISOString();
+  const record = { schemaVersion: 0, id, rootId: marker.rootId, revision: 1, action: 'flow.continue', runId: run.id,
+    expectedRunRevision: value.expectedRunRevision, inputDigest: fingerprint, ownerInstanceId: value.ownerInstanceId,
+    binding: bindingFor(run), createdAt: now, updatedAt: now, state: 'queued', cancelRequested: false };
+  validate(record, id, marker);
+  atomicCreatePrivate(fileFor(root, marker, id), JSON.stringify(record, null, 2) + '\n');
+  return { operation: structuredClone(record), idempotentReplay: false };
+}
+
+/** Store-only CAS. It neither runs flow.continue nor delivers an abort signal or remote cancel. */
+export function transitionOperation(root, value) {
+  input(value, ['id', 'expectedRevision', 'state', 'failureCode', 'value'], ['id', 'expectedRevision', 'state']);
+  if (!positive(value.expectedRevision) || !STATES.has(value.state)) operationFail('IRIS_OPERATION_INPUT_INVALID', 'Operation 状态或 revision 无效');
+  const marker = inspectExecutionRoot(root), current = readOperation(root, value.id, marker);
+  if (!current) operationFail('IRIS_OPERATION_NOT_FOUND', 'Operation 不存在');
+  if (current.action === 'plugin.execute') return transitionPluginOperation(root, marker, value);
+  if (Object.hasOwn(value, 'value')) operationFail('IRIS_OPERATION_INPUT_INVALID', '媒体流程不接受插件业务结果');
+  if (current.revision !== value.expectedRevision) operationFail('IRIS_OPERATION_REVISION_CONFLICT', 'Operation 已改变，请先读取原记录');
+  const allowed = current.state === 'queued' ? ['running', 'canceled', 'interrupted', 'failed']
+    : current.state === 'running' ? ['succeeded', 'failed', 'canceled', 'interrupted'] : [];
+  if (!allowed.includes(value.state)) operationFail('IRIS_OPERATION_TRANSITION_INVALID', '不允许此 Operation 状态转换；结束记录不重新排队');
+  if (value.state === 'failed' ? !FAILURE_CODES.has(value.failureCode) || current.state === 'queued' && value.failureCode !== 'run_changed'
+    : Object.hasOwn(value, 'failureCode')) operationFail('IRIS_OPERATION_INPUT_INVALID', '失败记录只接受有限错误类别，不保存异常原文');
+  const { run, task } = validateBinding(root, current);
+  if (value.state === 'running' && run.revision !== current.expectedRunRevision) operationFail('IRIS_OPERATION_RUN_CHANGED', 'Run revision 已改变，未开始本次调用');
+  if (value.state === 'succeeded' && !task) operationFail('IRIS_OPERATION_RESULT_INVALID', '没有原 Task 事实，不能记录调用成功');
+  const now = new Date(Math.max(Date.now(), Date.parse(current.updatedAt))).toISOString();
+  const next = { ...current, revision: current.revision + 1, state: value.state, updatedAt: now,
+    cancelRequested: value.state === 'canceled',
+    ...(value.state === 'running' ? { startedAt: now } : { finishedAt: now,
+      result: { runRevision: run.revision, taskId: task?.id || null, artifactIds: artifactsFor(run) } }),
+    ...(value.state === 'failed' ? { failureCode: value.failureCode } : {}) };
+  validate(next, next.id, marker);
+  atomicWritePrivate(fileFor(root, marker, next.id), JSON.stringify(next, null, 2) + '\n');
+  return structuredClone(next);
+}
+
+export function listOperations(root, value = {}) {
+  input(value, ['runId', 'limit', 'cursor'], []);
+  if (value.runId !== undefined && !RUN.test(value.runId) || value.limit !== undefined && (!positive(value.limit) || value.limit > 30)
+      || value.cursor !== undefined && !ID.test(value.cursor)) operationFail('IRIS_OPERATION_INPUT_INVALID', 'Operation 列表参数无效');
+  inspectExecutionRoot(root);
+  const ordered = readAllOperations(root).filter(record => value.runId === undefined || record.runId === value.runId)
+    .sort((a, b) => b.createdAt.localeCompare(a.createdAt) || b.id.localeCompare(a.id));
+  const offset = value.cursor === undefined ? 0 : ordered.findIndex(record => record.id === value.cursor) + 1;
+  if (value.cursor !== undefined && offset === 0) operationFail('IRIS_OPERATION_INPUT_INVALID', 'Operation 游标不属于当前列表');
+  const page = ordered.slice(offset, offset + (value.limit ?? 20));
+  return { operations: page, total: ordered.length, nextCursor: offset + page.length < ordered.length ? page.at(-1).id : null };
+}
+export function operationReferences(root) {
+  return readAllOperations(root).map(record => record.action === 'plugin.execute' ? { operationId: record.id, runId: null, taskIds: [],
+    artifactIds: [...new Set([...record.sourceArtifactIds, ...record.reservedArtifactIds.filter(id => findCoreArtifactMetadata(root, id))])] } : ({ operationId: record.id, runId: record.runId,
+    taskIds: [record.binding.taskId], artifactIds: [...new Set([record.binding.sourceArtifactId,
+      record.binding.comparisonArtifactId, ...(record.result?.artifactIds || [])].filter(Boolean))] }));
+}
+export function projectOperation(record) {
+  if (record.action === 'plugin.execute') return projectPluginOperation(record);
+  return { contractVersion: 0, id: record.id, action: record.action, runId: record.runId,
+    revision: record.revision, expectedRunRevision: record.expectedRunRevision, state: record.state,
+    createdAt: record.createdAt, updatedAt: record.updatedAt, cancelRequested: record.cancelRequested,
+    ...(record.startedAt ? { startedAt: record.startedAt } : {}), ...(record.finishedAt ? { finishedAt: record.finishedAt } : {}),
+    ...(record.result ? { result: structuredClone(record.result) } : {}), ...(record.failureCode ? { failureCode: record.failureCode } : {}) };
+}