@mokuyoaxis/dsh-iris 0.2.0 → 0.2.2

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

@@ -0,0 +1,213 @@
+import fs from 'node:fs';
+import path from 'node:path';
+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';
+
+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 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');
+  try { let size; while ((size = fs.readSync(fd, chunk, 0, chunk.length, null))) hash.update(chunk.subarray(0, size)); }
+  finally { fs.closeSync(fd); }
+  return hash.digest('hex');
+}
+
+function directory(root, relative, create = false) {
+  let current = root;
+  for (const segment of relative.split('/')) {
+    current = path.join(current, segment);
+    if (create && !fs.existsSync(current)) fs.mkdirSync(current, { mode: 0o700 });
+    const stat = fs.lstatSync(current);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) fail('IRIS_CORE_MAINTENANCE_UNSAFE', 'Core 管理目录不安全');
+  }
+  return current;
+}
+
+function managedFile(root, relative) {
+  if (!MANAGED.test(relative)) fail('IRIS_CORE_MAINTENANCE_UNSAFE', '不是可管理的 Core 文件');
+  directory(root, path.posix.dirname(relative));
+  const file = path.join(root, relative);
+  const stat = fs.lstatSync(file);
+  if (!stat.isFile() || stat.isSymbolicLink()) fail('IRIS_CORE_MAINTENANCE_UNSAFE', 'Core 文件不是普通文件');
+  return { path: relative, size: stat.size, digest: fileDigest(file) };
+}
+
+function names(root, relative) {
+  if (!fs.existsSync(path.join(root, relative))) return [];
+  return fs.readdirSync(directory(root, relative));
+}
+
+function inventory(root) {
+  const tasks = [];
+  for (let offset = 0; ; offset += 200) {
+    const page = listCoreTasks(root, { offset, limit: 200 }); tasks.push(...page.tasks);
+    if (offset + 200 >= page.total) break;
+  }
+  const artifacts = names(root, 'artifact-store/v0/records').filter(name => ARTIFACT.test(name.slice(0, -5)) && name.endsWith('.json'))
+    .map(name => inspectCoreArtifact(root, name.slice(0, -5)));
+  return { tasks, artifacts };
+}
+
+function ids(value, pattern, label) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.length > 200 || !value.every(id => typeof id === 'string' && pattern.test(id)) || new Set(value).size !== value.length) fail('IRIS_COMMAND_INPUT_INVALID', label + ' 必须是不重复的 Core ID 数组，最多 200 条');
+  return value;
+}
+
+export function planCoreDeletion(root, input) {
+  const taskIds = ids(input.task_ids, TASK, 'task_ids'), artifactIds = ids(input.artifact_ids, ARTIFACT, 'artifact_ids');
+  if (!taskIds.length && !artifactIds.length) fail('IRIS_COMMAND_INPUT_INVALID', '请明确指定 Task 或 Artifact ID');
+  const existing = inventory(root), selectedTasks = new Set(taskIds), selectedArtifacts = new Set(artifactIds);
+  const blockers = [], files = [];
+  for (const id of taskIds) {
+    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'));
+  }
+  for (const id of artifactIds) {
+    inspectCoreArtifact(root, id);
+    const recordPath = 'artifact-store/v0/records/' + id + '.json';
+    const recordFile = managedFile(root, recordPath);
+    const record = JSON.parse(fs.readFileSync(path.join(root, recordPath)));
+    const manifestPath = 'artifact-store/v0/manifests/' + id + '.json';
+    const manifest = record.schemaVersion === 1 ? JSON.parse(fs.readFileSync(path.join(root, manifestPath))) : record;
+    files.push(recordFile);
+    if (record.schemaVersion === 1) files.push(managedFile(root, manifestPath));
+    files.push(managedFile(root, 'artifact-store/v0/objects/' + manifest.object));
+  }
+  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 (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' });
+  }
+  for (const artifact of existing.artifacts) {
+    if (selectedArtifacts.has(artifact.id)) continue;
+    if (selectedTasks.has(artifact.metadata.taskId)) blockers.push({ id: artifact.metadata.taskId, referencedBy: artifact.id, reason: 'artifact_task_reference' });
+    for (const edge of artifact.relations) if (selectedArtifacts.has(edge.artifactId)) blockers.push({ id: edge.artifactId, referencedBy: artifact.id, reason: 'artifact_relation' });
+  }
+  // 未提交 Manifest 也可能仍引用目标；未知或损坏的条目保留并阻止误判。
+  const committed = new Set(existing.artifacts.map(artifact => artifact.id));
+  for (const name of names(root, 'artifact-store/v0/manifests')) {
+    if (!/^artifact_[a-f0-9]{24}\.json$/.test(name) || committed.has(name.slice(0, -5))) continue;
+    const relative = 'artifact-store/v0/manifests/' + name; managedFile(root, relative);
+    const manifest = JSON.parse(fs.readFileSync(path.join(root, relative)));
+    for (const edge of manifest.relations || []) if (selectedArtifacts.has(edge.artifactId)) blockers.push({ id: edge.artifactId, referencedBy: name.slice(0, -5), reason: 'uncommitted_relation' });
+  }
+  return { operation: 'delete', task_ids: taskIds, artifact_ids: artifactIds, allowed: !blockers.length, blockers,
+    entries: files, bytes: files.reduce((sum, entry) => sum + entry.size, 0) };
+}
+
+export function planCoreCleanup(root, { older_than_ms = 3600000 } = {}) {
+  if (!Number.isSafeInteger(older_than_ms) || older_than_ms < 60000) fail('IRIS_COMMAND_INPUT_INVALID', 'older_than_ms 至少为 60000');
+  const existing = inventory(root);
+  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.sourceArtifactId) referenced.add(task.sourceArtifactId);
+  for (const name of names(root, 'artifact-store/v0/manifests')) {
+    if (/^artifact_[a-f0-9]{24}\.json$/.test(name)) {
+      referenced.add(name.slice(0, -5));
+      const relative = 'artifact-store/v0/manifests/' + name; managedFile(root, relative);
+      const manifest = JSON.parse(fs.readFileSync(path.join(root, relative)));
+      for (const edge of manifest.relations || []) referenced.add(edge.artifactId);
+    }
+  }
+  const candidates = [];
+  for (const relativeDirectory of ['provider-staging/v0', 'artifact-store/v0/objects']) {
+    for (const name of names(root, relativeDirectory)) {
+      const relative = relativeDirectory + '/' + name;
+      if (!MANAGED.test(relative)) continue;
+      const stat = fs.lstatSync(path.join(root, relative));
+      if (!stat.isFile() || stat.isSymbolicLink() || Date.now() - stat.mtimeMs < older_than_ms) continue;
+      if (relativeDirectory === 'provider-staging/v0') {
+        const pid = Number(name.split('-')[1]);
+        try { process.kill(pid, 0); continue; } catch (error) { if (error.code !== 'ESRCH') continue; }
+      } else if (referenced.has(name.slice(0, name.lastIndexOf('.')))) continue;
+      candidates.push(managedFile(root, relative));
+    }
+  }
+  return { operation: 'cleanup', candidates, bytes: candidates.reduce((sum, entry) => sum + entry.size, 0) };
+}
+
+const transactionDirectory = (root, id, create = false) => {
+  if (!TRANSACTION.test(id)) fail('IRIS_COMMAND_INPUT_INVALID', '隔离事务 ID 无效');
+  return directory(root, 'maintenance/v0/quarantine/' + id, create);
+};
+const refresh = root => { if (fs.existsSync(path.join(root, 'artifact-store/v0'))) refreshCoreArtifactInventory(root); };
+
+/** 写前清单 + rename；失败时补偿，保留事务用于检查/恢复，绝不永久 unlink 媒体。 */
+export function quarantineCoreFiles(root, plan) {
+  if (!plan.allowed || !plan.entries.length) fail('IRIS_CORE_DELETE_BLOCKED', '删除计划为空或仍被引用，不能执行');
+  const id = 'delete_' + crypto.randomBytes(12).toString('hex'), base = transactionDirectory(root, id, true);
+  const journal = { schemaVersion: 0, id, state: 'prepared', createdAt: new Date().toISOString(), operation: plan.operation, entries: plan.entries };
+  const journalFile = path.join(base, 'transaction.json');
+  atomicWritePrivate(journalFile, JSON.stringify(journal, null, 2) + '\n');
+  const moved = [];
+  try {
+    for (const entry of journal.entries) {
+      const actual = managedFile(root, entry.path);
+      if (actual.digest !== entry.digest || actual.size !== entry.size) fail('IRIS_CORE_MAINTENANCE_CHANGED', '预览后文件发生变化');
+      directory(base, path.posix.dirname(entry.path), true);
+      fs.renameSync(path.join(root, entry.path), path.join(base, entry.path)); moved.push(entry);
+    }
+    refresh(root);
+    journal.state = 'committed'; atomicWritePrivate(journalFile, JSON.stringify(journal, null, 2) + '\n');
+    return { transactionId: id, state: journal.state, files: moved.length, bytes: moved.reduce((sum, entry) => sum + entry.size, 0), recoverable: true };
+  } catch (error) {
+    try {
+      for (const entry of [...moved].reverse()) fs.renameSync(path.join(base, entry.path), path.join(root, entry.path));
+      refresh(root); journal.state = 'rolled-back';
+    } catch (_) { journal.state = 'interrupted'; }
+    atomicWritePrivate(journalFile, JSON.stringify(journal, null, 2) + '\n');
+    throw Object.assign(new Error('Core 隔离操作未完成，已保留恢复清单：' + id + '（' + journal.state + '）'), { code: 'IRIS_CORE_MAINTENANCE_FAILED', transactionId: id, state: journal.state, cause: error });
+  }
+}
+
+export function inspectCoreTransactions(root) {
+  return names(root, 'maintenance/v0/quarantine').filter(id => TRANSACTION.test(id)).map(id => {
+    const base = transactionDirectory(root, id);
+    const file = path.join(base, 'transaction.json'), stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink()) fail('IRIS_CORE_MAINTENANCE_UNSAFE', '隔离清单不是普通文件');
+    const journal = JSON.parse(fs.readFileSync(file));
+    return { transactionId: id, state: journal.state, operation: journal.operation, createdAt: journal.createdAt, files: journal.entries.length };
+  });
+}
+
+export function restoreCoreTransaction(root, id) {
+  const base = transactionDirectory(root, id), journalFile = path.join(base, 'transaction.json');
+  const stat = fs.lstatSync(journalFile);
+  if (!stat.isFile() || stat.isSymbolicLink()) fail('IRIS_CORE_MAINTENANCE_UNSAFE', '隔离清单不安全');
+  const journal = JSON.parse(fs.readFileSync(journalFile));
+  if (journal.schemaVersion !== 0 || journal.id !== id || !Array.isArray(journal.entries)
+      || !['prepared', 'committed', 'interrupted'].includes(journal.state)) fail('IRIS_CORE_RESTORE_INVALID', '事务不处于可恢复状态');
+  const restoring = [];
+  for (const entry of journal.entries) {
+    if (!MANAGED.test(entry.path)) fail('IRIS_CORE_MAINTENANCE_UNSAFE', '隔离清单包含不支持的路径');
+    if (fs.existsSync(path.join(base, entry.path))) {
+      const actual = managedFile(base, entry.path);
+      if (actual.digest !== entry.digest || actual.size !== entry.size) fail('IRIS_CORE_MAINTENANCE_CHANGED', '隔离文件哈希或大小改变');
+      if (fs.existsSync(path.join(root, entry.path))) fail('IRIS_CORE_RESTORE_CONFLICT', '恢复目标已存在，不覆盖已有数据');
+      directory(root, path.posix.dirname(entry.path)); restoring.push(entry);
+    } else {
+      const actual = managedFile(root, entry.path);
+      if (actual.digest !== entry.digest) fail('IRIS_CORE_MAINTENANCE_CHANGED', '事务原位置文件改变');
+    }
+  }
+  const moved = [];
+  try {
+    for (const entry of restoring) { fs.renameSync(path.join(base, entry.path), path.join(root, entry.path)); moved.push(entry); }
+    refresh(root);
+    journal.state = 'restored'; atomicWritePrivate(journalFile, JSON.stringify(journal, null, 2) + '\n');
+    return { transactionId: id, state: 'restored', files: moved.length };
+  } catch (_) {
+    for (const entry of [...moved].reverse()) fs.renameSync(path.join(root, entry.path), path.join(base, entry.path));
+    refresh(root);
+    fail('IRIS_CORE_RESTORE_FAILED', '恢复失败，文件已回到隔离目录');
+  }
+}

package/lib/core-runtime.js

@@ -12,36 +12,20 @@ import {
   normalizeCoreOptions,
   transitionCoreLifecycle
 } from './core-contract.js';
-import { ensurePrivateDir, writePrivateFile } from './private-storage.js';
-
-const WRITER_LEASE_DIR = '.iris-runtime-writer-v0';
-const WRITER_OWNER_FILE = 'owner.json';
+import { ensurePrivateDir } from './private-storage.js';
+import { WRITER_LEASE_DIR, WRITER_INTENT_FILE, publishLeaseRecord, readWriterLease,
+  removeWriterIntent, retireLeaseDirectory, writerOwnerStatus } from './core-writer-lease.js';
 
 /** 只读租约证据；PID 缺失不等于已经获准恢复，绝不自动夺取租约。 */
 export function inspectCoreWriterLease(dataRoot) {
   const options = normalizeCoreOptions({ dataRoot, mode: 'reader' });
-  const directory = path.join(options.dataRoot, WRITER_LEASE_DIR);
-  let stat;
-  try { stat = fs.lstatSync(directory); }
-  catch (error) { return { status: error?.code === 'ENOENT' ? 'absent' : 'invalid' }; }
   try {
-    if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('invalid lease');
-    const entries = fs.readdirSync(directory);
-    if (entries.length !== 1 || entries[0] !== WRITER_OWNER_FILE) throw new Error('invalid 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 owner = JSON.parse(fs.readFileSync(ownerFile, 'utf8'));
-    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');
-    }
-    let ownerStatus = 'alive';
-    try { process.kill(owner.pid, 0); }
-    catch (error) { ownerStatus = error?.code === 'ESRCH' ? 'missing' : 'unknown'; }
+    const lease = readWriterLease(options.dataRoot);
+    if (!lease) return { status: 'absent' };
+    const owner = lease.owner;
+    const created = Date.parse(owner.createdAt);
     return {
-      status: 'present', ownerStatus, pid: owner.pid,
+      status: 'present', ownerStatus: writerOwnerStatus(owner.pid), pid: owner.pid, phase: lease.phase,
       createdAt: new Date(created).toISOString(), ageMs: Math.max(0, Date.now() - created)
     };
   } catch (_) { return { status: 'invalid' }; }
@@ -77,56 +61,70 @@ function physicalDataRoot(options) {
 
 function acquireWriterLease(root, instanceId) {
   const directory = path.join(root, WRITER_LEASE_DIR);
-  const ownerFile = path.join(directory, WRITER_OWNER_FILE);
+  const ownerFile = path.join(directory, 'owner.json');
+  const intentFile = path.join(root, WRITER_INTENT_FILE);
   try {
-    fs.mkdirSync(directory, { mode: 0o700 });
+    fs.lstatSync(directory);
+    throw coreDataRootBusyError();
   } catch (error) {
-    if (error && error.code === 'EEXIST') throw coreDataRootBusyError();
-    throw coreError('IRIS_CORE_DATA_ROOT_UNAVAILABLE', '无法取得 Iris 数据根写者租约');
+    if (error?.code !== 'ENOENT') {
+      if (error instanceof CoreContractError) throw error;
+      throw coreError('IRIS_CORE_DATA_ROOT_UNAVAILABLE', '无法检查 Iris 数据根写者租约');
+    }
   }
-
   const owner = Object.freeze({
     contractVersion: CORE_CONTRACT_VERSION,
     instanceId,
     pid: process.pid,
     createdAt: new Date().toISOString()
   });
-  const serialized = JSON.stringify(owner, null, 2) + '\n';
   try {
-    writePrivateFile(ownerFile, serialized, { flag: 'wx' });
-  } catch (_) {
-    try { fs.unlinkSync(ownerFile); } catch (_) { /* owner 文件可能尚未建立 */ }
-    try { fs.rmdirSync(directory); } catch (_) { /* 保留不确定租约比误删安全 */ }
+    // 创建目录之前已有完整 owner；SIGKILL 不会留下无法确认 PID 的新空锁。
+    publishLeaseRecord(root, intentFile, owner);
+  } catch (error) {
+    if (error?.code === 'EEXIST') throw coreDataRootBusyError();
     throw coreError('IRIS_CORE_DATA_ROOT_UNAVAILABLE', '无法记录 Iris 数据根写者租约');
   }
-  return Object.freeze({ directory, ownerFile, owner, serialized });
+  let madeDirectory = false;
+  try {
+    fs.mkdirSync(directory, { mode: 0o700 });
+    madeDirectory = true;
+    fs.linkSync(intentFile, ownerFile);
+    return Object.freeze({ root, directory, ownerFile, owner, evidence: readWriterLease(root) });
+  } catch (error) {
+    // 仅撤回本次创建的空目录和意图；不碰其他 writer 或未知目录内容。
+    let withdrawn = !madeDirectory;
+    if (madeDirectory) {
+      try { fs.rmdirSync(directory); withdrawn = true; } catch (_) { /* owner/目录证据保留 */ }
+    }
+    if (withdrawn) { try { fs.unlinkSync(intentFile); } catch (_) { /* 保留 owner 供显式恢复 */ } }
+    if (error?.code === 'EEXIST') throw coreDataRootBusyError();
+    throw coreError('IRIS_CORE_DATA_ROOT_UNAVAILABLE', '无法取得 Iris 数据根写者租约');
+  }
 }
 
 function releaseWriterLease(lease) {
   let actual;
   try {
-    const stat = fs.lstatSync(lease.directory);
-    if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('lease is not a directory');
-    const entries = fs.readdirSync(lease.directory);
-    if (entries.length !== 1 || entries[0] !== WRITER_OWNER_FILE) throw new Error('unexpected lease contents');
-    actual = JSON.parse(fs.readFileSync(lease.ownerFile, 'utf8'));
+    actual = readWriterLease(lease.root);
+    if (!actual || actual.fingerprint !== lease.evidence.fingerprint || actual.phase !== 'owned') throw new Error('lease changed');
   } catch (_) {
     throw coreError('IRIS_CORE_LEASE_INVALID', 'Iris 写者租约无法安全释放；已保留现场');
   }
-  if (actual.instanceId !== lease.owner.instanceId) {
+  if (actual.owner.instanceId !== lease.owner.instanceId) {
     throw coreError('IRIS_CORE_LEASE_INVALID', 'Iris 写者租约所有者不匹配；已保留现场');
   }
 
+  const retired = path.join(lease.root, WRITER_LEASE_DIR + '.released-' + lease.owner.instanceId);
   try {
-    fs.unlinkSync(lease.ownerFile);
-    fs.rmdirSync(lease.directory);
+    // 整体移开非空目录；owner 从不在占位目录中先被删除。
+    retireLeaseDirectory(lease.directory, retired);
+    removeWriterIntent(actual);
   } catch (_) {
-    // 若目录删除失败，尽力恢复 owner 证据；绝不把仍不确定的根宣布为可写。
-    if (fs.existsSync(lease.directory) && !fs.existsSync(lease.ownerFile)) {
-      try { writePrivateFile(lease.ownerFile, lease.serialized, { flag: 'wx' }); } catch (_) { /* 保持失败 */ }
-    }
     throw coreError('IRIS_CORE_LEASE_INVALID', 'Iris 写者租约释放失败；已保留现场');
   }
+  // 退役目录已不占有租约。中断或清理失败只留下可读证据，不阻止后续 writer。
+  try { fs.unlinkSync(path.join(retired, 'owner.json')); fs.rmdirSync(retired); } catch (_) { /* 保留退役现场 */ }
 }
 
 function runtimeSnapshot(options, lifecycle, hasLease, inFlight) {

package/lib/core-tasks.js

@@ -11,6 +11,7 @@ import { deriveLegacyStatus, semanticViolations } from './task-semantics.js';
 const STORE_DIR = 'task-store';
 const STORE_VERSION = 'v0';
 const TASK_ID = /^task_[a-f0-9]{24}$/;
+const ARTIFACT_ID = /^artifact_[a-f0-9]{24}$/;
 const ATTEMPT_ID = /^attempt_[a-f0-9]{24}$/;
 const PROVIDER_BINDING = /^sha256:[a-f0-9]{64}$/;
 const CAPABILITIES = new Set(['image', 'video', 'tts', 'transcribe']);
@@ -106,7 +107,8 @@ function validateRecord(record, expectedId) {
       || !Number.isSafeInteger(record.revision) || record.revision < 1
       || typeof record.createdAt !== 'string' || typeof record.updatedAt !== 'string'
       || (record.providerBinding !== undefined && !PROVIDER_BINDING.test(record.providerBinding))
-      || (record.retriedFrom !== undefined && !TASK_ID.test(record.retriedFrom))) {
+      || (record.retriedFrom !== undefined && !TASK_ID.test(record.retriedFrom))
+      || (record.sourceArtifactId !== undefined && (record.capability !== 'image' || !ARTIFACT_ID.test(record.sourceArtifactId)))) {
     fail('IRIS_TASK_INVALID', 'Task 记录结构无效');
   }
   if (record.attempts.some((attempt, index) => !attempt || !ATTEMPT_ID.test(attempt.id)
@@ -170,6 +172,8 @@ export function createCoreTask(dataRoot, input = {}) {
   if (!CAPABILITIES.has(capability)) fail('IRIS_TASK_INPUT_INVALID', 'Task capability 无效');
   const retriedFrom = input.retriedFrom === undefined ? undefined : String(input.retriedFrom);
   if (retriedFrom !== undefined && !TASK_ID.test(retriedFrom)) fail('IRIS_TASK_INPUT_INVALID', 'retriedFrom 必须是合法 Task ID');
+  const sourceArtifactId = input.sourceArtifactId;
+  if (sourceArtifactId !== undefined && (capability !== 'image' || !ARTIFACT_ID.test(sourceArtifactId))) fail('IRIS_TASK_INPUT_INVALID', '改图 sourceArtifactId 必须是合法 Artifact ID');
   const now = new Date().toISOString();
   return writeRecord(dataRoot, {
     schemaVersion: 0,
@@ -189,7 +193,8 @@ export function createCoreTask(dataRoot, input = {}) {
     createdAt: now,
     updatedAt: now,
     // D4 retry as new task：显式单向关系（新任务指向旧任务），绝不复制 Prompt。
-    ...(retriedFrom !== undefined ? { retriedFrom } : {})
+    ...(retriedFrom !== undefined ? { retriedFrom } : {}),
+    ...(sourceArtifactId !== undefined ? { sourceArtifactId } : {})
   });
 }
 
@@ -202,7 +207,7 @@ export function inspectCoreTask(dataRoot, id) {
  * skipInvalid 只服务用户侧只读投影：单条损坏记录跳过并计入 dropped，
  * 其余记录照常返回；默认严格模式不变，损坏记录仍使整体读取失败。
  */
-export function listCoreTasks(dataRoot, { offset = 0, limit = 50, skipInvalid = false } = {}) {
+export function listCoreTasks(dataRoot, { offset = 0, limit = 50, skipInvalid = false, status, capability, provider_id, model_ref, outcome, delivery_state } = {}) {
   const start = Math.max(0, Math.trunc(Number(offset) || 0));
   const size = Math.max(1, Math.min(200, Math.trunc(Number(limit) || 50)));
   const directory = taskDirectory(dataRoot);
@@ -236,9 +241,11 @@ export function listCoreTasks(dataRoot, { offset = 0, limit = 50, skipInvalid =
     }
   }
   records.sort((a, b) => String(b.updatedAt).localeCompare(String(a.updatedAt)));
+  const matches = records.filter(record => Object.entries({ status, capability, providerId: provider_id, modelRef: model_ref, outcome, deliveryState: delivery_state })
+    .every(([field, value]) => value === undefined || record[field] === value));
   return Object.freeze({
-    schemaVersion: 0, total: records.length, offset: start, limit: size, dropped,
-    tasks: Object.freeze(records.slice(start, start + size).map(publicTask))
+    schemaVersion: 0, total: matches.length, offset: start, limit: size, dropped,
+    tasks: Object.freeze(matches.slice(start, start + size).map(publicTask))
   });
 }
 

package/lib/core-user-projection.js

@@ -150,6 +150,7 @@ export function projectCoreTaskUserRow(record, artifacts = []) {
     updatedAt: String(record && record.updatedAt || ''),
     revision: Number.isSafeInteger(record && record.revision) ? record.revision : 0,
     artifactIds: Object.freeze(artifactIds),
+    ...(record && record.sourceArtifactId ? { sourceArtifactId: record.sourceArtifactId } : {}),
     mediaReady,
     observable: coreTaskObservable(record),
     redeliverable: coreTaskRedeliverable(record),