@mokuyoaxis/dsh-iris 0.2.1 → 0.2.3

package/lib/command-service.js

@@ -20,6 +20,7 @@ import { GenerationInputError, normalizeGenerationInput } from './generation-inp
 import { videoTaskCandidates } from './video-input.js';
 import { waitForCoreTask } from './task-wait.js';
 import { planCoreDeletion, planCoreCleanup, quarantineCoreFiles, inspectCoreTransactions, restoreCoreTransaction } from './core-maintenance.js';
+import { deliveryCacheNeedsProvider } from './core-delivery-cache.js';
 
 export const COMMAND_CONTRACT_VERSION = 0;
 export const CORE_COMMANDS = Object.freeze([
@@ -366,16 +367,20 @@ export function createCommandService(runtime, ports = {}) {
       });
     }
     // task.redeliver：只对 outcome=succeeded / deliveryState=failed 的任务重新取回
-    // 已生成的远端产物（re-poll 拿产物清单，绝不 submit，也不会重新生成）。
+    // 已生成产物：同步结果读私有缓存，异步结果 re-poll；绝不 submit。
     if (name === 'task.redeliver') {
       exactInput(input, ['task_id']);
       return runtime.run('execute', async ({ dataRoot }) => {
         const before = inspectCoreTask(dataRoot, input.task_id);
-        if (before.outcome !== 'succeeded' || before.deliveryState !== 'failed' || !before.remoteTaskId) throw commandError('IRIS_TASK_NOT_REDELIVERABLE', 'Task 不处于可重新交付状态；不会重新生成');
+        if (before.outcome !== 'succeeded' || before.deliveryState !== 'failed' || (!before.remoteTaskId && !before.deliveryCache)) throw commandError('IRIS_TASK_NOT_REDELIVERABLE', 'Task 不处于可重新交付状态；不会重新生成');
+        if (before.deliveryCache && !deliveryCacheNeedsProvider(dataRoot, before)) {
+          const task = await createProviderTaskRunner(runtime).redeliver(input.task_id);
+          return Object.freeze({ contractVersion: COMMAND_CONTRACT_VERSION, command: name, taskId: task.id, task });
+        }
         if (typeof ports.resolveTaskAdapter !== 'function') throw commandError('IRIS_COMMAND_PROVIDER_REQUIRED', 'task.redeliver 需要宿主显式提供 Task Provider resolver');
         const adapter = await ports.resolveTaskAdapter(before);
         if (!adapter || adapter.id !== before.providerId || !adapter.capabilities?.includes(before.capability)) throw commandError('IRIS_PROVIDER_TASK_IDENTITY_MISMATCH', 'Task Provider resolver 返回了不匹配的 Adapter');
-        if (!hasProviderOperation(adapter, 'poll')) throw commandError('IRIS_PROVIDER_TASK_OBSERVE_UNSUPPORTED', 'Task 原 Provider 不支持 poll；不会重新生成');
+        if (!before.deliveryCache && !hasProviderOperation(adapter, 'poll')) throw commandError('IRIS_PROVIDER_TASK_OBSERVE_UNSUPPORTED', 'Task 原 Provider 不支持 poll；不会重新生成');
         const task = await createProviderTaskRunner(runtime).redeliver(input.task_id, adapter);
         return Object.freeze({ contractVersion: COMMAND_CONTRACT_VERSION, command: name, taskId: task.id, task });
       });
@@ -415,6 +420,10 @@ export function createCommandService(runtime, ports = {}) {
           throw commandError('IRIS_TASK_NOT_RETRYABLE', '只有终态且未成功交付的 Task 可以重试为新任务');
         }
         let normalized;
+        if (before.capability === 'music' && input.provider_input &&
+            ['retry_502', 'retry_delay_ms'].some(field => Object.hasOwn(input.provider_input, field))) {
+          throw commandError('IRIS_COMMAND_INPUT_INVALID', 'task.retry 只执行一次重新生成；502重试配置请使用Music生成入口');
+        }
         try { normalized = normalizeGenerationInput(before.capability, input.provider_input, { allowVideoPaths: before.capability === 'video' }); }
         catch (error) {
           if (error instanceof GenerationInputError) throw commandError('IRIS_COMMAND_INPUT_INVALID', error.message);

package/lib/config.js

@@ -11,7 +11,7 @@ import os from 'node:os';
 import * as cap from './capability.js';
 import * as models from './models.js';
 import { atomicWritePrivate, chmodPrivateFile, privateSibling } from './private-storage.js';
-import { selectMediaProtocol, selectImageProtocol, normalizeImageProtocol, isConfiguredProvider } from './provider-protocol.js';
+import { selectMediaProtocol, selectImageProtocol, normalizeImageProtocol, normalizeMusicProtocol, isConfiguredProvider } from './provider-protocol.js';
 import { redactProviderMessage } from './provider-contract.js';
 import {
   PROVIDER_HEALTH_FRESH_MS,
@@ -66,7 +66,7 @@ function normalizeStoredProvider(provider) {
   const changed = provider.mediaProtocol !== selected.mediaProtocol
     || (provider.protocolInferred === true) !== selected.protocolInferred;
   Object.assign(provider, selected);
-  return models.migrateProviderModels(provider) || changed;
+  return changed;
 }
 
 export function irisHome() {
@@ -196,7 +196,7 @@ export function pickFor(capability) {
     m = pool.find((x) => !x.rateLimited && x.ref === ref && x.capabilities.includes(capability));
     if (m) break;
   }
-  if (!m) m = models.pickModel(pool, capability);
+  if (!m && capability !== cap.CAPABILITIES.MUSIC) m = models.pickModel(pool, capability);
   if (!m) return null;
   const p = providerById(m.providerId);
   if (!p) return null;
@@ -489,6 +489,7 @@ export function upsert(provider) {
   if (rest.visionInput !== undefined) rest.visionInput = normalizeVisionInputLimits(rest.visionInput) || null;
   if (Array.isArray(rest.models)) rest.models = rest.models.map(model => typeof model === 'string' ? model : ({ ...model,
     ...(model?.imageProtocol !== undefined ? { imageProtocol: normalizeImageProtocol(model.imageProtocol) } : {}),
+    ...(model?.musicProtocol !== undefined ? { musicProtocol: normalizeMusicProtocol(model.musicProtocol) } : {}),
     ...(model?.visionInput !== undefined ? { visionInput: normalizeVisionInputLimits(model.visionInput) || null } : {}) }));
   if (id) {
     const i = c.providers.findIndex((p) => p.id === id);
@@ -541,6 +542,7 @@ export function setProviderModels(id, modelEntries) {
     p.models = modelEntries.map((m) => {
       const entry = typeof m === 'string' ? { id: m } : { id: m.id, capabilities: m.capabilities,
         ...(m.imageProtocol !== undefined ? { imageProtocol: normalizeImageProtocol(m.imageProtocol) } : {}),
+        ...(m.musicProtocol !== undefined ? { musicProtocol: normalizeMusicProtocol(m.musicProtocol) } : {}),
         ...(m.visionInput !== undefined ? { visionInput: normalizeVisionInputLimits(m.visionInput) || null } : {}) };
       const old = prev.get(entry.id);
       if (old) {
@@ -548,6 +550,7 @@ export function setProviderModels(id, modelEntries) {
         if (old.source) entry.source = old.source;
         if (old.source === 'manual' && Array.isArray(old.capabilities)) entry.capabilities = old.capabilities;
         if (m?.imageProtocol === undefined && old.imageProtocol !== undefined) entry.imageProtocol = old.imageProtocol;
+        if (m?.musicProtocol === undefined && old.musicProtocol !== undefined) entry.musicProtocol = old.musicProtocol;
         if (m?.visionInput === undefined && old.visionInput !== undefined) entry.visionInput = old.visionInput;
       }
       if (m && m.verified) entry.verified = m.verified;
@@ -565,10 +568,19 @@ export function setProviderModels(id, modelEntries) {
 export function mergeDiscoveredModels(id, modelEntries) {
   const provider = load().providers.find((p) => p.id === id);
   if (!provider) return null;
-  const merged = new Map(models.providerModels(provider).map((m) => [m.id, m]));
+  const merged = new Map(models.providerModels(provider).map((m) => {
+    const raw = provider.models?.find((entry) => String(typeof entry === 'string' ? entry : entry?.id || '').trim() === m.id);
+    // 读取投影的 [] 不能伪造成用户明确清空；未标注条目以后仍可接收可信元数据。
+    if (!Array.isArray(raw?.capabilities) && !models.hasConfiguredModelCapabilities(provider, m.id)) {
+      const entry = { ...m };
+      delete entry.capabilities;
+      return [m.id, entry];
+    }
+    return [m.id, m];
+  }));
   for (const model of modelEntries) {
     const previous = merged.get(model.id);
-    if (previous?.source === 'manual') continue;
+    if (previous && models.hasConfiguredModelCapabilities(provider, model.id)) continue;
     merged.set(model.id, { ...previous, ...model, source: 'discovered' });
   }
   return setProviderModels(id, [...merged.values()]);
@@ -581,6 +593,9 @@ function findModelEntry(p, modelId) {
 
 function resetChangedImageProtocolHealth(previous, next) {
   for (const model of models.providerModels(previous)) {
+    if (model.musicProtocol !== models.providerModels(next).find(item => item.id === model.id)?.musicProtocol) {
+      clearModelCapabilityHealth(next, model.id, cap.CAPABILITIES.MUSIC);
+    }
     if (selectImageProtocol(previous, model.id).mediaProtocol !== selectImageProtocol(next, model.id).mediaProtocol) {
       clearModelCapabilityHealth(next, model.id, cap.CAPABILITIES.IMAGE);
     }
@@ -606,6 +621,24 @@ export function setModelImageProtocol(id, modelId, value) {
   return true;
 }
 
+/** 音乐协议独立绑定到已配置模型，不覆盖账号生图协议。 */
+export function setModelMusicProtocol(id, modelId, value) {
+  const protocol = normalizeMusicProtocol(value);
+  const provider = load().providers.find(item => item.id === id);
+  if (!provider) return false;
+  const entries = Array.isArray(provider.models) ? provider.models
+    : models.providerModels(provider).map(({ id, capabilities }) => ({ id, capabilities }));
+  const index = entries.findIndex(model => (typeof model === 'string' ? model : model?.id)?.trim() === modelId);
+  if (index < 0) return false;
+  const entry = typeof entries[index] === 'string' ? { id: entries[index] } : entries[index];
+  entries[index] = entry;
+  provider.models = entries;
+  if (entry.musicProtocol !== protocol) clearModelCapabilityHealth(provider, modelId, cap.CAPABILITIES.MUSIC);
+  entry.musicProtocol = protocol;
+  persist();
+  return true;
+}
+
 /** 看图预算变更不会伪造实测成功、解除额度停用或改写原图。 */
 export function setModelVisionInput(id, modelId, value) {
   const limits = normalizeVisionInputLimits(value);
@@ -631,7 +664,7 @@ export function addProviderModel(id, modelId, capabilities) {
   if (!Array.isArray(p.models)) p.models = [];
   let entry = findModelEntry(p, name);
   if (!entry) {
-    entry = { id: name, capabilities: Array.isArray(capabilities) ? capabilities : [], source: 'manual' };
+    entry = { id: name, capabilities: Array.isArray(capabilities) ? capabilities : undefined, source: 'manual' };
     p.models.push(entry);
   } else if (Array.isArray(capabilities)) {
     entry.capabilities = capabilities;

package/lib/core-artifact-store.js

@@ -305,20 +305,46 @@ function finishObject(dataRoot, input) {
   const relations = normalizedRelations(input.relations);
   validateRelationTargets(dataRoot, relations);
   const metadata = jsonClone(input.metadata, 'metadata');
-  const id = 'artifact_' + crypto.randomBytes(12).toString('hex');
+  // 同步交付缓存预留的 ID 可重入提交，避免多产物交付或 Task 落盘中断后重复作品。
+  const resumable = input.artifactId !== undefined;
+  const id = resumable ? input.artifactId : 'artifact_' + crypto.randomBytes(12).toString('hex');
+  if (!ID.test(id) || (resumable && (!HASH.test(input.expectedDigest)
+      || !Number.isSafeInteger(input.expectedSize) || input.expectedSize < 1))) {
+    fail('IRIS_ARTIFACT_INPUT_INVALID', '可恢复 Artifact 身份或内容证据无效');
+  }
   const store = ensureStore(dataRoot);
   const objectName = id + extension;
   const object = path.join(store.objects, objectName);
+  const exists = (file) => {
+    try { fs.lstatSync(file); return true; }
+    catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+  };
+  if (resumable && exists(recordPath(dataRoot, id))) {
+    const previous = readArtifact(dataRoot, id).manifest;
+    if (previous.size !== input.expectedSize || previous.digest.value !== input.expectedDigest
+        || previous.kind !== kind || previous.mediaType !== mediaType
+        || JSON.stringify(previous.metadata) !== JSON.stringify(metadata)
+        || JSON.stringify(previous.relations) !== JSON.stringify(relations)) {
+      fail('IRIS_ARTIFACT_INPUT_INVALID', '可恢复 Artifact 与已提交内容不一致');
+    }
+    try { refreshIndex(dataRoot); } catch (_) { /* 不撤销已有提交 */ }
+    return publicArtifact(previous);
+  }
   let stat;
   try {
-    input.writeObject(object);
+    if (resumable && exists(object)) {
+      if (regularFile(object).size !== input.expectedSize || hashFile(object) !== input.expectedDigest) {
+        fail('IRIS_ARTIFACT_INPUT_INVALID', '未提交 Artifact 与恢复内容不一致');
+      }
+    } else input.writeObject(object);
     stat = regularFile(object);
-  } catch (_) {
+  } catch (error) {
+    if (resumable) throw error;
     try { fs.rmSync(object, { force: true }); } catch (_) { /* 当前随机 ID */ }
     fail('IRIS_ARTIFACT_WRITE_FAILED', 'Artifact 对象无法安全写入');
   }
   if (!stat.size) {
-    try { fs.rmSync(object, { force: true }); } catch (_) { /* 只清理当前随机 ID */ }
+    if (!resumable) try { fs.rmSync(object, { force: true }); } catch (_) { /* 只清理当前随机 ID */ }
     fail('IRIS_ARTIFACT_INPUT_INVALID', 'Artifact 内容不能为空');
   }
   const manifest = {
@@ -333,12 +359,23 @@ function finishObject(dataRoot, input) {
     relations,
     metadata
   };
+  if (resumable && (manifest.size !== input.expectedSize || manifest.digest.value !== input.expectedDigest)) {
+    fail('IRIS_ARTIFACT_INPUT_INVALID', 'Artifact 复制结果与恢复内容证据不一致');
+  }
+  if (resumable && exists(manifestPath(dataRoot, id))) {
+    const previous = validateManifest(jsonFile(manifestPath(dataRoot, id)), id);
+    if (JSON.stringify(previous) !== JSON.stringify(manifest)) {
+      fail('IRIS_ARTIFACT_INPUT_INVALID', '未提交 Artifact Manifest 与恢复内容不一致');
+    }
+  }
   try {
     writeManifest(dataRoot, manifest);
     commitRecord(dataRoot, id);
   } catch (_) {
-    try { fs.rmSync(object, { force: true }); } catch (_) { /* 当前 ID */ }
-    try { fs.rmSync(manifestPath(dataRoot, id), { force: true }); } catch (_) { /* 当前 ID */ }
+    if (!resumable) {
+      try { fs.rmSync(object, { force: true }); } catch (_) { /* 当前 ID */ }
+      try { fs.rmSync(manifestPath(dataRoot, id), { force: true }); } catch (_) { /* 当前 ID */ }
+    }
     fail('IRIS_ARTIFACT_WRITE_FAILED', 'Artifact 无法安全提交');
   }
   try { refreshIndex(dataRoot); } catch (_) { /* index 是可重建缓存，不撤销已提交 Artifact */ }
@@ -366,6 +403,7 @@ export function adoptCoreArtifactFile(dataRoot, input = {}) {
   return finishObject(dataRoot, {
     ...input,
     mediaType,
+    ...(input.artifactId ? { expectedSize: stat.size, expectedDigest: hashFile(source) } : {}),
     kind: input.kind || 'adopted',
     writeObject(object) {
       const tmp = privateSibling(object, 'adopt');

package/lib/core-delivery-cache.js

@@ -0,0 +1,145 @@
+'use strict';
+
+/** 同步完成结果的私有交付证据；来源 URL/字节不进入 Task、Manifest 或日志。 */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { atomicWritePrivate, ensurePrivateDir } from './private-storage.js';
+
+const TASK_ID = /^task_[a-f0-9]{24}$/;
+const ARTIFACT_ID = /^artifact_[a-f0-9]{24}$/;
+const PAYLOAD_FILE = /^payload-[a-f0-9]{24}\.bin$/;
+const HASH = /^[a-f0-9]{64}$/;
+
+export class DeliveryCacheError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'DeliveryCacheError';
+    this.code = 'IRIS_DELIVERY_CACHE_INVALID';
+  }
+}
+
+function invalid() { throw new DeliveryCacheError('同步交付缓存缺失、损坏或与 Task 身份不一致；不会重新生成'); }
+
+function directory(dataRoot, taskId, create = false) {
+  if (!TASK_ID.test(taskId)) invalid();
+  let current = dataRoot;
+  for (const part of ['delivery-cache', 'v0', taskId]) {
+    current = path.join(current, part);
+    if (create) {
+      try { fs.lstatSync(current); }
+      catch (error) { if (error.code !== 'ENOENT') throw error; ensurePrivateDir(current); }
+    }
+    const stat = fs.lstatSync(current);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) invalid();
+  }
+  return current;
+}
+
+function regular(file) {
+  const stat = fs.lstatSync(file);
+  if (!stat.isFile() || stat.isSymbolicLink()) invalid();
+  return stat;
+}
+
+function fingerprint(file) {
+  const stat = regular(file);
+  if (!stat.size) invalid();
+  const hash = crypto.createHash('sha256');
+  const chunk = Buffer.alloc(1024 * 1024);
+  const fd = fs.openSync(file, 'r');
+  try {
+    let count;
+    while ((count = fs.readSync(fd, chunk, 0, chunk.length, null))) hash.update(chunk.subarray(0, count));
+  } finally { fs.closeSync(fd); }
+  return { size: stat.size, sha256: hash.digest('hex') };
+}
+
+function save(dataRoot, cache) {
+  atomicWritePrivate(path.join(directory(dataRoot, cache.taskId), 'result.json'), JSON.stringify(cache, null, 2) + '\n');
+}
+
+export function createDeliveryCache(dataRoot, task, artifacts) {
+  if (!Array.isArray(artifacts) || !artifacts.length) invalid();
+  const root = directory(dataRoot, task.id, true);
+  try { fs.lstatSync(path.join(root, 'result.json')); invalid(); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  const cache = {
+    schemaVersion: 0, resultKind: 'completed', taskId: task.id, attemptId: task.activeAttemptId,
+    providerId: task.providerId, modelRef: task.modelRef, capability: task.capability,
+    ...(task.providerBinding ? { providerBinding: task.providerBinding } : {}),
+    createdAt: new Date().toISOString(), items: []
+  };
+  for (const remote of artifacts) {
+    const item = { artifactId: 'artifact_' + crypto.randomBytes(12).toString('hex') };
+    if (remote.kind === 'remote-url') {
+      item.source = { kind: 'remote-url', url: remote.url, ...(remote.mediaType ? { mediaType: remote.mediaType } : {}) };
+    } else if (remote.kind === 'inline-base64') {
+      const bytes = Buffer.from(remote.data, 'base64');
+      if (!bytes.length || bytes.toString('base64') !== remote.data) invalid();
+      const file = 'payload-' + crypto.randomBytes(12).toString('hex') + '.bin';
+      atomicWritePrivate(path.join(root, file), bytes);
+      item.payload = { file, size: bytes.length, sha256: crypto.createHash('sha256').update(bytes).digest('hex'),
+        ...(remote.mediaType ? { mediaType: remote.mediaType } : {}) };
+    } else invalid();
+    cache.items.push(item);
+  }
+  // result.json 是完整同步响应的提交证据；未发布的文件不作为可恢复结果。
+  save(dataRoot, cache);
+  return cache;
+}
+
+export function readDeliveryCache(dataRoot, task, { allowAbsent = false } = {}) {
+  let cache;
+  try {
+    const file = path.join(directory(dataRoot, task.id), 'result.json');
+    regular(file);
+    cache = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) {
+    if (allowAbsent && error.code === 'ENOENT') return null;
+    invalid();
+  }
+  if (!cache || cache.schemaVersion !== 0 || cache.resultKind !== 'completed'
+      || cache.taskId !== task.id || cache.attemptId !== task.activeAttemptId
+      || cache.providerId !== task.providerId || cache.modelRef !== task.modelRef
+      || cache.capability !== task.capability || cache.providerBinding !== task.providerBinding
+      || !Array.isArray(cache.items) || !cache.items.length
+      || typeof cache.createdAt !== 'string' || !Number.isFinite(Date.parse(cache.createdAt))) invalid();
+  const ids = new Set();
+  for (const item of cache.items) {
+    if (!item || !ARTIFACT_ID.test(item.artifactId) || ids.has(item.artifactId)) invalid();
+    ids.add(item.artifactId);
+    if (item.source && (item.source.kind !== 'remote-url' || typeof item.source.url !== 'string' || !item.source.url.trim()
+        || (item.source.mediaType !== undefined && typeof item.source.mediaType !== 'string'))) invalid();
+    if (item.payload && (!PAYLOAD_FILE.test(item.payload.file) || !HASH.test(item.payload.sha256)
+        || !Number.isSafeInteger(item.payload.size) || item.payload.size < 1
+        || (item.payload.mediaType !== undefined && typeof item.payload.mediaType !== 'string'))) invalid();
+    if (!item.payload && !item.source) invalid();
+  }
+  return cache;
+}
+
+export function deliveryCacheNeedsProvider(dataRoot, task) {
+  return readDeliveryCache(dataRoot, task).items.some(item => !item.payload);
+}
+
+export function newDeliveryPayloadPath(dataRoot, cache) {
+  return path.join(directory(dataRoot, cache.taskId), 'payload-' + crypto.randomBytes(12).toString('hex') + '.bin');
+}
+
+export function recordDeliveryPayload(dataRoot, cache, index, file, mediaType) {
+  const root = directory(dataRoot, cache.taskId);
+  if (path.dirname(file) !== root || !PAYLOAD_FILE.test(path.basename(file))) invalid();
+  cache.items[index].payload = { file: path.basename(file), ...fingerprint(file), mediaType };
+  delete cache.items[index].source;
+  save(dataRoot, cache);
+}
+
+export function readDeliveryPayload(dataRoot, cache, index) {
+  const payload = cache.items[index].payload;
+  const file = path.join(directory(dataRoot, cache.taskId), payload.file);
+  let actual;
+  try { actual = fingerprint(file); } catch (_) { invalid(); }
+  if (actual.size !== payload.size || actual.sha256 !== payload.sha256) invalid();
+  return file;
+}

package/lib/core-lease-recovery.js

@@ -3,11 +3,11 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
-import { CORE_CONTRACT_VERSION, CoreContractError, normalizeCoreOptions } from './core-contract.js';
-import { writePrivateFile } from './private-storage.js';
+import { CoreContractError, normalizeCoreOptions } from './core-contract.js';
+import { newWriterOwner, publishLeaseRecord, readWriterLease, recoveryClaimFile, removeWriterIntent,
+  retireLeaseDirectory, withdrawLeaseRecord,
+  writerOwnerStatus } from './core-writer-lease.js';
 
-const WRITER_LEASE_DIR = '.iris-runtime-writer-v0';
-const WRITER_OWNER_FILE = 'owner.json';
 const RECOVERY_AUDIT_DIR = '.iris-runtime-recovery-audit-v0';
 
 function fail(code, message) {
@@ -27,34 +27,6 @@ function physicalDataRoot(dataRoot) {
   }
 }
 
-function readLease(root) {
-  const directory = path.join(root, WRITER_LEASE_DIR);
-  const stat = fs.lstatSync(directory);
-  if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('invalid lease directory');
-  const entries = fs.readdirSync(directory);
-  if (entries.length !== 1 || entries[0] !== WRITER_OWNER_FILE) throw new Error('invalid lease contents');
-  const ownerFile = path.join(directory, WRITER_OWNER_FILE);
-  const ownerStat = fs.lstatSync(ownerFile);
-  if (!ownerStat.isFile() || ownerStat.isSymbolicLink() || ownerStat.size > 16384) throw new Error('invalid owner');
-  const serialized = fs.readFileSync(ownerFile, 'utf8');
-  const owner = JSON.parse(serialized);
-  const created = Date.parse(owner?.createdAt);
-  if (owner?.contractVersion !== CORE_CONTRACT_VERSION || !Number.isSafeInteger(owner.pid) || owner.pid <= 0
-      || !/^[a-f0-9-]{36}$/.test(String(owner.instanceId || '')) || !Number.isFinite(created)) {
-    throw new Error('incomplete owner');
-  }
-  return { directory, ownerFile, owner, serialized, created };
-}
-
-function ownerStatus(pid) {
-  try {
-    process.kill(pid, 0);
-    return 'alive';
-  } catch (error) {
-    return error?.code === 'ESRCH' ? 'missing' : 'unknown';
-  }
-}
-
 function auditDirectory(root) {
   const directory = path.join(root, RECOVERY_AUDIT_DIR);
   try {
@@ -68,15 +40,12 @@ function auditDirectory(root) {
   return directory;
 }
 
-function releaseRecoveryLease(lease) {
-  const stat = fs.lstatSync(lease.directory);
-  if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('invalid recovery lease');
-  const entries = fs.readdirSync(lease.directory);
-  if (entries.length !== 1 || entries[0] !== WRITER_OWNER_FILE) throw new Error('unexpected recovery lease contents');
-  const actual = JSON.parse(fs.readFileSync(lease.ownerFile, 'utf8'));
-  if (actual.instanceId !== lease.owner.instanceId) throw new Error('recovery owner changed');
-  fs.unlinkSync(lease.ownerFile);
-  fs.rmdirSync(lease.directory);
+function requireMissingOwners(lease) {
+  for (const owner of lease.owners) {
+    const status = writerOwnerStatus(owner.pid);
+    if (status === 'alive') fail('IRIS_CORE_LEASE_OWNER_ALIVE', '租约 owner PID 仍存活；拒绝恢复');
+    if (status !== 'missing') fail('IRIS_CORE_LEASE_OWNER_UNVERIFIED', '无法确认租约 owner PID 已退出；拒绝恢复');
+  }
 }
 
 /**
@@ -85,41 +54,45 @@ function releaseRecoveryLease(lease) {
  */
 export function recoverCoreWriterLease(dataRoot, { confirmStalePid } = {}) {
   const root = physicalDataRoot(dataRoot);
-  const leaseDirectory = path.join(root, WRITER_LEASE_DIR);
-  try { fs.lstatSync(leaseDirectory); }
-  catch (error) {
-    if (error?.code === 'ENOENT') fail('IRIS_CORE_LEASE_NOT_FOUND', '未发现可恢复的 Iris 写者租约');
-    fail('IRIS_CORE_LEASE_INVALID', 'Iris 写者租约证据无法读取；已保留现场');
-  }
   let lease;
-  try { lease = readLease(root); }
+  try { lease = readWriterLease(root); }
   catch (_) { fail('IRIS_CORE_LEASE_INVALID', 'Iris 写者租约证据不完整；已保留现场'); }
+  if (!lease) fail('IRIS_CORE_LEASE_NOT_FOUND', '未发现可恢复的 Iris 写者租约');
   if (!Number.isSafeInteger(confirmStalePid) || confirmStalePid <= 0 || confirmStalePid !== lease.owner.pid) {
     fail('IRIS_CORE_LEASE_CONFIRMATION_MISMATCH', '确认的 owner PID 与租约证据不一致；未执行恢复');
   }
-  const processStatus = ownerStatus(lease.owner.pid);
-  if (processStatus === 'alive') fail('IRIS_CORE_LEASE_OWNER_ALIVE', '租约 owner PID 仍存活；拒绝恢复');
-  if (processStatus !== 'missing') fail('IRIS_CORE_LEASE_OWNER_UNVERIFIED', '无法确认租约 owner PID 已退出；拒绝恢复');
+  requireMissingOwners(lease);
 
   const auditId = 'lease_recovery_' + crypto.randomBytes(12).toString('hex');
-  const instanceId = crypto.randomUUID();
   const recoveredAt = new Date().toISOString();
-  const recoveryOwner = Object.freeze({
-    contractVersion: CORE_CONTRACT_VERSION,
-    instanceId,
-    pid: process.pid,
-    createdAt: recoveredAt
-  });
-  const recoverySerialized = JSON.stringify(recoveryOwner, null, 2) + '\n';
-  const staleOwnerFile = path.join(lease.directory, `.owner.stale-${instanceId}.json`);
-  let tookLease = false;
+  const recoveryOwner = newWriterOwner();
+  const claimFile = recoveryClaimFile(root, lease.owner);
+  const claim = { schemaVersion: 1, previousInstanceId: lease.owner.instanceId, owner: recoveryOwner };
+  let published = false;
+  let retired = false;
   let auditFile = null;
   try {
-    // 租约目录始终存在；普通 writer 在接管窗口内仍会 fail-fast。
-    fs.renameSync(lease.ownerFile, staleOwnerFile);
-    if (fs.readFileSync(staleOwnerFile, 'utf8') !== lease.serialized) throw new Error('lease changed');
-    writePrivateFile(lease.ownerFile, recoverySerialized, { flag: 'wx' });
-    tookLease = true;
+    if (readWriterLease(root)?.fingerprint !== lease.fingerprint) throw new Error('lease changed');
+    if (!lease.intent) {
+      // 兼容旧 owner 目录；固定意图屏障使目录退役后的中断也可诊断和续办。
+      fs.linkSync(path.join(lease.directory, 'owner.json'), lease.intentFile);
+      lease = readWriterLease(root);
+      requireMissingOwners(lease);
+    }
+    if (!lease.stat) {
+      // 已原子发布意图，但在 mkdir 前被杀；建立占位后仍只允许显式恢复。
+      fs.mkdirSync(lease.directory, { mode: 0o700 });
+      lease = readWriterLease(root);
+    }
+    // 每一步以父 owner UUID 命名且独占发布；并发恢复只有一个能取得下一步。
+    // 前驱不删除，中断后可确认最近恢复 PID 并继续，证据不会消失。
+    publishLeaseRecord(root, claimFile, claim);
+    published = true;
+    const claimed = readWriterLease(root);
+    if (claimed?.owner.instanceId !== recoveryOwner.instanceId
+        || claimed.stat?.dev !== lease.stat.dev || claimed.stat?.ino !== lease.stat.ino
+        || claimed.intent?.serialized !== lease.intent.serialized) throw new Error('lease changed');
+    requireMissingOwners(lease);
 
     const directory = auditDirectory(root);
     auditFile = path.join(directory, auditId + '.json');
@@ -129,38 +102,37 @@ export function recoverCoreWriterLease(dataRoot, { confirmStalePid } = {}) {
       action: 'writer-lease-recovery',
       recoveredAt,
       confirmation: { ownerPid: confirmStalePid },
-      staleOwner: {
-        contractVersion: lease.owner.contractVersion,
-        instanceId: lease.owner.instanceId,
-        pid: lease.owner.pid,
-        createdAt: new Date(lease.created).toISOString()
-      },
-      recoveryOwner
+      staleOwner: lease.originalOwner,
+      recoveryOwner,
+      leasePhase: lease.phase,
+      evidenceDirectory: auditId + '.lease',
+      evidenceFingerprint: claimed.fingerprint,
+      recoveryClaims: claimed.claims.map(claim => claim.value),
+      authorization: 'retire-lease-directory'
     };
-    writePrivateFile(auditFile, JSON.stringify(audit, null, 2) + '\n', { flag: 'wx' });
-    fs.unlinkSync(staleOwnerFile);
-    releaseRecoveryLease({
-      directory: lease.directory,
-      ownerFile: lease.ownerFile,
-      owner: recoveryOwner
-    });
+    publishLeaseRecord(root, auditFile, audit);
+    if (readWriterLease(root)?.fingerprint !== claimed.fingerprint) throw new Error('lease changed');
+    // 审计先发布，完整目录再原子退役。只在最终步骤撤下意图屏障。
+    retireLeaseDirectory(lease.directory, path.join(directory, audit.evidenceDirectory));
+    retired = true;
+    removeWriterIntent(lease);
+    // 意图屏障解除后只整理 UUID 专属旧证据，不再触碰当前租约路径。
+    for (const claim of claimed.claims) {
+      try { fs.renameSync(claim.file, path.join(directory, audit.evidenceDirectory, path.basename(claim.file))); }
+      catch (_) { /* 未整理的记录仍在根中，不阻止新 UUID 的 writer */ }
+    }
     return Object.freeze({
       status: 'recovered',
       auditId,
-      staleOwner: Object.freeze({ pid: lease.owner.pid, createdAt: new Date(lease.created).toISOString() })
+      staleOwner: Object.freeze({ pid: lease.originalOwner.pid,
+        createdAt: new Date(Date.parse(lease.originalOwner.createdAt)).toISOString() })
     });
   } catch (error) {
-    // 恢复失败时尽力还原原 owner；绝不把不确定现场宣布为可写。
-    try {
-      if (tookLease && fs.existsSync(lease.ownerFile)) {
-        const actual = JSON.parse(fs.readFileSync(lease.ownerFile, 'utf8'));
-        if (actual.instanceId === instanceId) fs.unlinkSync(lease.ownerFile);
-      }
-      if (fs.existsSync(lease.directory) && !fs.existsSync(lease.ownerFile)) {
-        if (fs.existsSync(staleOwnerFile)) fs.renameSync(staleOwnerFile, lease.ownerFile);
-        else writePrivateFile(lease.ownerFile, lease.serialized, { flag: 'wx' });
-      }
-    } catch (_) { /* 保留现场，由 Doctor 报告 invalid */ }
+    // 可捕获的错误只撤回本次最后一条 claim；原 owner 与旧恢复证据保持。
+    if (published && !retired) {
+      try { withdrawLeaseRecord(claimFile, claim); }
+      catch (_) { /* 保留可识别的恢复链供进程退出后显式重试 */ }
+    }
     if (error instanceof CoreContractError) throw error;
     fail('IRIS_CORE_LEASE_RECOVERY_FAILED',
       auditFile && fs.existsSync(auditFile)

package/lib/core-maintenance.js

@@ -4,11 +4,12 @@ import crypto from 'node:crypto';
 import { inspectCoreArtifact, refreshCoreArtifactInventory } from './core-artifacts.js';
 import { inspectCoreTask, listCoreTasks } from './core-tasks.js';
 import { atomicWritePrivate } from './private-storage.js';
+import { readDeliveryCache } from './core-delivery-cache.js';
 
 const TASK = /^task_[a-f0-9]{24}$/;
 const ARTIFACT = /^artifact_[a-f0-9]{24}$/;
 const TRANSACTION = /^delete_[a-f0-9]{24}$/;
-const MANAGED = /^(?:task-store\/v0\/tasks\/task_[a-f0-9]{24}\.json|artifact-store\/v0\/(?:records|manifests)\/artifact_[a-f0-9]{24}\.json|artifact-store\/v0\/objects\/artifact_[a-f0-9]{24}\.(?:png|jpg|webp|gif|mp4|webm|wav|mp3|ogg|flac|txt|json)|provider-staging\/v0\/download-[1-9][0-9]*-[a-f0-9]{16}\.part)$/;
+const MANAGED = /^(?:task-store\/v0\/tasks\/task_[a-f0-9]{24}\.json|artifact-store\/v0\/(?:records|manifests)\/artifact_[a-f0-9]{24}\.json|artifact-store\/v0\/objects\/artifact_[a-f0-9]{24}\.(?:png|jpg|webp|gif|mp4|webm|wav|mp3|ogg|flac|txt|json)|provider-staging\/v0\/download-[1-9][0-9]*-[a-f0-9]{16}\.part|delivery-cache\/v0\/task_[a-f0-9]{24}\/(?:result\.json|payload-[a-f0-9]{24}\.bin))$/;
 const fail = (code, message) => { throw Object.assign(new Error(message), { code }); };
 function fileDigest(file) {
   const hash = crypto.createHash('sha256'), chunk = Buffer.allocUnsafe(1024 * 1024), fd = fs.openSync(file, 'r');
@@ -68,6 +69,8 @@ export function planCoreDeletion(root, input) {
     const task = inspectCoreTask(root, id);
     if (task.phase !== 'terminal' || task.acceptance === 'unknown' || task.outcome === 'unknown') blockers.push({ id, reason: 'task_not_settled' });
     files.push(managedFile(root, 'task-store/v0/tasks/' + id + '.json'));
+    const cache = 'delivery-cache/v0/' + id;
+    for (const name of names(root, cache)) files.push(managedFile(root, cache + '/' + name));
   }
   for (const id of artifactIds) {
     inspectCoreArtifact(root, id);
@@ -83,6 +86,11 @@ export function planCoreDeletion(root, input) {
   for (const task of existing.tasks) {
     if (selectedTasks.has(task.id)) continue;
     for (const id of task.artifactIds) if (selectedArtifacts.has(id)) blockers.push({ id, referencedBy: task.id, reason: 'task_artifact_reference' });
+    if (task.deliveryCache && task.deliveryState !== 'ready') {
+      for (const item of readDeliveryCache(root, task).items) {
+        if (selectedArtifacts.has(item.artifactId)) blockers.push({ id: item.artifactId, referencedBy: task.id, reason: 'delivery_cache_reference' });
+      }
+    }
     if (selectedArtifacts.has(task.sourceArtifactId)) blockers.push({ id: task.sourceArtifactId, referencedBy: task.id, reason: 'task_input_reference' });
     if (selectedTasks.has(task.retriedFrom)) blockers.push({ id: task.retriedFrom, referencedBy: task.id, reason: 'retry_reference' });
   }
@@ -109,6 +117,9 @@ export function planCoreCleanup(root, { older_than_ms = 3600000 } = {}) {
   const referenced = new Set(existing.artifacts.map(artifact => artifact.id));
   for (const artifact of existing.artifacts) for (const edge of artifact.relations) referenced.add(edge.artifactId);
   for (const task of existing.tasks) for (const id of task.artifactIds) referenced.add(id);
+  for (const task of existing.tasks) if (task.deliveryCache && task.deliveryState !== 'ready') {
+    for (const item of readDeliveryCache(root, task).items) referenced.add(item.artifactId);
+  }
   for (const task of existing.tasks) if (task.sourceArtifactId) referenced.add(task.sourceArtifactId);
   for (const name of names(root, 'artifact-store/v0/manifests')) {
     if (/^artifact_[a-f0-9]{24}\.json$/.test(name)) {