@mokuyoaxis/dsh-iris 0.2.1 → 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-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-writer-lease.js

@@ -0,0 +1,134 @@
+'use strict';
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { CORE_CONTRACT_VERSION } from './core-contract.js';
+import { privateSibling } from './private-storage.js';
+
+export const WRITER_LEASE_DIR = '.iris-runtime-writer-v0';
+export const WRITER_INTENT_FILE = '.iris-runtime-writer-v0.owner.json';
+export function recoveryClaimFile(root, owner) {
+  return path.join(root, WRITER_LEASE_DIR + '.recovery-' + owner.instanceId + '.json');
+}
+const UUID = /^[a-f0-9-]{36}$/;
+const STALE = /^\.owner\.stale-([a-f0-9-]{36})\.json$/;
+
+export function writerOwnerStatus(pid) {
+  try { process.kill(pid, 0); return 'alive'; }
+  catch (error) { return error?.code === 'ESRCH' ? 'missing' : 'unknown'; }
+}
+
+export function newWriterOwner() {
+  return { contractVersion: CORE_CONTRACT_VERSION, instanceId: crypto.randomUUID(),
+    pid: process.pid, createdAt: new Date().toISOString() };
+}
+
+function checkedOwner(owner) {
+  if (owner?.contractVersion !== CORE_CONTRACT_VERSION || !Number.isSafeInteger(owner.pid) || owner.pid <= 0
+      || !UUID.test(String(owner.instanceId || '')) || !Number.isFinite(Date.parse(owner.createdAt))) {
+    throw new Error('incomplete owner');
+  }
+  return owner;
+}
+
+function readRecord(file) {
+  const stat = fs.lstatSync(file);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 16384) throw new Error('invalid lease record');
+  const serialized = fs.readFileSync(file, 'utf8');
+  return { serialized, value: JSON.parse(serialized) };
+}
+
+function optionalRecord(file) {
+  try { return readRecord(file); }
+  catch (error) { if (error?.code === 'ENOENT') return null; throw error; }
+}
+
+/** 完整私有记录先在根中准备，再以 hard link 原子发布；已有目标绝不覆盖。 */
+export function publishLeaseRecord(root, target, value) {
+  const prepared = privateSibling(path.join(root, WRITER_INTENT_FILE), 'prepare');
+  let created = false;
+  try {
+    fs.writeFileSync(prepared, JSON.stringify(value, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+    created = true;
+    fs.linkSync(prepared, target);
+  } finally {
+    if (created) { try { fs.unlinkSync(prepared); } catch (_) { /* 未发布的准备文件不占有租约 */ } }
+  }
+}
+
+export function withdrawLeaseRecord(target, value) {
+  if (readRecord(target).serialized !== JSON.stringify(value, null, 2) + '\n') throw new Error('published record changed');
+  fs.unlinkSync(target);
+}
+
+export function retireLeaseDirectory(source, target) {
+  try { fs.lstatSync(target); throw new Error('retirement destination already exists'); }
+  catch (error) { if (error?.code !== 'ENOENT') throw error; }
+  fs.renameSync(source, target);
+}
+
+/** 只读识别完整 owner、创建/释放意图及恢复链；未知内容和缺失证据拒绝。 */
+export function readWriterLease(root) {
+  const directory = path.join(root, WRITER_LEASE_DIR);
+  const intentFile = path.join(root, WRITER_INTENT_FILE);
+  const intent = optionalRecord(intentFile);
+  if (intent) checkedOwner(intent.value);
+  let stat;
+  try { stat = fs.lstatSync(directory); }
+  catch (error) { if (error?.code !== 'ENOENT') throw error; }
+  if (!stat && !intent) return null;
+  if (stat && (!stat.isDirectory() || stat.isSymbolicLink())) throw new Error('invalid lease directory');
+  const entries = stat ? fs.readdirSync(directory).sort() : [];
+  const records = new Map();
+  for (const name of entries) {
+    if (name !== 'owner.json' && !STALE.test(name)) throw new Error('unexpected lease contents');
+    records.set(name, readRecord(path.join(directory, name)));
+  }
+  const ownerRecord = records.get('owner.json');
+  if (ownerRecord) checkedOwner(ownerRecord.value);
+  const staleRecords = entries.filter(name => STALE.test(name));
+  if (staleRecords.length > 1) throw new Error('ambiguous legacy recovery');
+  const staleRecord = staleRecords.length ? records.get(staleRecords[0]) : null;
+  if (staleRecord) checkedOwner(staleRecord.value);
+  if (staleRecord && !ownerRecord) throw new Error('legacy recovery PID unknown');
+  if (intent && ownerRecord && ownerRecord.serialized !== intent.serialized) {
+    throw new Error('intent owner mismatch');
+  }
+  if (staleRecord && ownerRecord && STALE.exec(staleRecords[0])[1] !== ownerRecord.value.instanceId) {
+    throw new Error('legacy recovery owner mismatch');
+  }
+  const original = staleRecord || ownerRecord || intent;
+  if (!original) throw new Error('owner evidence missing');
+  let owner = (ownerRecord || original).value;
+  const owners = [original.value];
+  if (owner.instanceId !== original.value.instanceId) owners.push(owner);
+  const claims = [];
+  for (;;) {
+    const file = recoveryClaimFile(root, owner);
+    const record = optionalRecord(file);
+    if (!record) break;
+    const claim = record.value;
+    if (claim?.schemaVersion !== 1 || claim.previousInstanceId !== owner.instanceId) throw new Error('invalid recovery claim');
+    claims.push({ file, ...record });
+    owner = checkedOwner(claim.owner);
+    if (owners.some(previous => previous.instanceId === owner.instanceId)) throw new Error('cyclic recovery chain');
+    owners.push(owner);
+    if (owners.length > 64) throw new Error('recovery chain too long');
+  }
+  const phase = owners.length > 1 || staleRecord ? 'recovering' : ownerRecord ? 'owned' : 'pending';
+  const fingerprint = crypto.createHash('sha256').update(JSON.stringify({
+    identity: stat ? [stat.dev, stat.ino] : null, intent: intent?.serialized,
+    records: [...records].map(([name, record]) => [name, record.serialized]),
+    claims: claims.map(record => [path.basename(record.file), record.serialized])
+  })).digest('hex');
+  return { directory, intentFile, intent, stat, entries, records, claims, owner, owners,
+    originalOwner: original.value, phase, fingerprint };
+}
+
+export function removeWriterIntent(lease) {
+  if (!lease.intent) return;
+  const actual = readRecord(lease.intentFile);
+  if (actual.serialized !== lease.intent.serialized) throw new Error('intent changed');
+  fs.unlinkSync(lease.intentFile);
+}

package/lib/models.js

@@ -3,16 +3,15 @@
  * Iris 模型发现规则（阶段 6）。
  *
  * 目标：把「账号（key）」与「能力」解耦——一个 key 提供模型池，能力从池里选模型。
- * 本模块是纯静态规则（零 API 调用）：模型名 → 能力标签。
+ * 名称规则仅为建议；实际模型能力来自明确标签或可信发现元数据。
  *
  * 池的来源：
  *   ① provider 显式 `models` 数组（未来配置，可带 capabilities 覆盖）
  *   ② 旧模型字段迁移：imageModel→image-gen、videoModel→video-gen、ttsModel→tts、
  *      transcribeModel→transcribe、visionModel→vision
- * 旧裸账号的已知目录仅由配置写入边界物化，不参与运行时回退。
+ * 裸账号不物化厂商默认模型，也不参与运行时回退。
  */
-import { CAPABILITIES } from './capability.js';
-import { isDashScopeBaseUrl, selectMediaProtocol } from './provider-protocol.js';
+import { CAPABILITIES, configuredModelCapabilities } from './capability.js';
 import { modelRateLimit } from './provider-health.js';
 
 /** 能力 → provider 上的模型字段（保持向后兼容的返回形状） */
@@ -64,29 +63,7 @@ const MODEL_CAP_RULES = [
   [/^gemini/i, [CAPABILITIES.VISION]] // Gemini 默认按视觉能力纳入（可被显式配置覆盖）
 ];
 
-/** 仅供配置写入时接回旧裸账号，不参与运行时选型。 */
-const KNOWN_MODELS_BY_PROTOCOL = { dashscope: [
-  { id: 'wan2.2-t2i-flash', caps: [CAPABILITIES.IMAGE] },
-  { id: 'wan2.2-t2v-flash', caps: [CAPABILITIES.VIDEO] },
-  { id: 'wan2.2-s2v-flash', caps: [CAPABILITIES.VIDEO] },
-  { id: 'qwen-vl-plus', caps: [CAPABILITIES.VISION] },
-  // VERIFY 2026-09-03 实证：locate grounding 零偏差（qwen-vl-plus 仅 25x25 框选）
-  { id: 'qwen3-vl-235b-a22b-thinking', caps: [CAPABILITIES.VISION] },
-  { id: 'qwen-tts-latest', caps: [CAPABILITIES.TTS] },
-  { id: 'qwen-audio-3.0-asr-flash-filetrans', caps: [CAPABILITIES.TRANSCRIBE] }
-] };
-
-export function migrateProviderModels(provider) {
-  if (Array.isArray(provider.models) || Object.values(CAP_FIELD).some((field) => provider[field])) return false;
-  const protocol = selectMediaProtocol(provider).mediaProtocol;
-  if (!isDashScopeBaseUrl(provider.baseUrl) || !Object.hasOwn(KNOWN_MODELS_BY_PROTOCOL, protocol)) return false;
-  provider.models = KNOWN_MODELS_BY_PROTOCOL[protocol].map((m) => ({
-    id: m.id, capabilities: [...m.caps], source: 'migration'
-  }));
-  return true;
-}
-
-/** 按模型名规则推断能力 */
+/** 模型名建议，仅用于提示；不能直接授权选型或落盘能力。 */
 export function capabilitiesOfModel(modelName) {
   const name = String(modelName || '');
   for (const [re, caps] of MODEL_CAP_RULES) {
@@ -103,14 +80,18 @@ const DISCOVERY_CAPABILITIES = Object.freeze({
   TRANSCRIBE: CAPABILITIES.TRANSCRIBE, VU: CAPABILITIES.VISION, VISION: CAPABILITIES.VISION
 });
 
-/** 发现元数据优先，名称规则兜底；用户保存后的显式 capabilities 仍是最终覆盖。 */
+/** 只映射明确发现元数据；名字、描述和未知代码不证明能力。 */
 export function capabilitiesOfDiscoveredModel(model) {
-  const id = String(typeof model === 'string' ? model : model?.id || '').trim();
-  const declared = Array.isArray(model?.capabilities)
+  return Array.isArray(model?.capabilities)
     ? [...new Set(model.capabilities.map((value) => DISCOVERY_CAPABILITIES[String(value).toUpperCase()]).filter(Boolean))]
     : [];
-  if (declared.length) return declared;
-  return capabilitiesOfModel(id);
+}
+
+/** 已存的明确配置优先于再发现；未标注名称仍可接收可信元数据。 */
+export function hasConfiguredModelCapabilities(provider, modelId) {
+  const entry = provider.models?.find((model) => String(typeof model === 'string' ? model : model?.id || '').trim() === modelId);
+  if (Array.isArray(entry?.capabilities)) return entry.source !== 'discovered';
+  return configuredModelCapabilities(provider, { id: modelId }).length > 0;
 }
 
 /** 一个 provider 的模型池条目列表：[{ id, providerId, capabilities:[], verified?, source? }] */
@@ -125,13 +106,13 @@ export function providerModels(p) {
   };
   // ① 显式 models 数组（带可选 capabilities 覆盖 + verified/source 透传）
   // 该字段一旦存在（含空数组）即为权威声明：用户可明确标记「此供应商没有可用模型」，
-  // 不得再落入 ② 旧字段迁移或 ③ 裸账号已知池。空数组曾因 `.length` 判定被穿透，
+  // 不得再落入 ② 旧字段绑定。空数组曾因 `.length` 判定被穿透，
   // 导致用户声明无模型却仍被注入 7 个厂商默认模型（见审计 B-5）。
   if (Array.isArray(p.models)) {
     for (const m of p.models) {
       const id = typeof m === 'string' ? m : m && m.id;
-      // 元素级空能力数组同样是权威覆盖：用户可明确标记“此模型无能力”。
-      const caps = Array.isArray(m && m.capabilities) ? m.capabilities : capabilitiesOfModel(id);
+      // 没有明确能力的名称保留为未标注模型，不进入候选链。
+      const caps = configuredModelCapabilities(p, m);
       const extra = typeof m === 'object' && m ? { verified: m.verified, source: m.source,
         ...(m.imageProtocol !== undefined ? { imageProtocol: m.imageProtocol } : {}),
         ...(m.visionInput !== undefined ? { visionInput: m.visionInput } : {}) } : {};
@@ -140,8 +121,9 @@ export function providerModels(p) {
     return out;
   }
   // ② 旧模型字段迁移
-  for (const [cap, field] of Object.entries(CAP_FIELD)) {
-    if (p[field]) push(p[field], [cap]);
+  for (const field of Object.values(CAP_FIELD)) {
+    const caps = configuredModelCapabilities(p, p[field]);
+    if (caps.length) push(p[field], caps);
   }
   return out;
 }

package/lib/prompt-optimizer-config.js

@@ -17,16 +17,26 @@ const DEFAULT_VALUE = {
   version: 1,
   enabled: true,
   systemPrompt: [
-    '你是 Iris 提示词编辑器。把用户草稿改写成一段可直接交给目标 AI 的高质量提示词。',
-    '必须保留原始意图、事实、专有名词、引号内原文、硬性约束和否定条件；不得臆造用户没有提供的事实。',
-    '只补充能提高可执行性、结构清晰度、风格一致性和验收明确度的具体信息。信息不足时保持克制，不替用户作关键决定。',
-    '默认沿用草稿的语言。只输出优化后的提示词正文，不解释、不加标题、不使用 Markdown 代码块。'
-  ].join('\n'),
+    '# Iris 提示词编辑器',
+    '## 职责',
+    '按用户选择的功能，把草稿整理为可直接交给目标 AI 的提示词。只编辑文字，不执行工具或媒体生成。',
+    '## 保留用户意图',
+    '保留原始目标、事实、专有名词、引号内原文、硬性约束和否定条件。尤其保留主体身份与数量、左右方位、颜色、数值与单位、构图、时序和明确指定的风格，不擅自替换或扩展。',
+    '逐项保留用户已写出的具体描述，不把这些细节当成冗余删去；明确否定条件不得用更宽泛的词概括、替换或扩大。没有依据时，不增加可被观察到的新属性、位置、声音、动作或光照。',
+    '用户明示的事实和硬性约束优先于通用模板建议；只有用户本次改写规则明确授权的具体内容可以改变，其余细节与约束继续保留。信息不足或存在冲突时保持未指定或待确认，不替用户作关键决定。',
+    '素材引用只是引用。没有看到图片、听到音频或读到文件时，不声称已分析其内容；不编造 Artifact ID、附件 ID、路径、模型、工具参数或执行结果。',
+    '## 组织方式',
+    '参照 Iris Skills 的任务组织：明确目标与必要输入，写清具体操作、必须保持和允许改变的部分，以及用户要求的输出和验收条件。只使用与本次功能有关的维度，不堆砌质量词或无依据的细节。',
+    '默认沿用草稿语言；只允许分段、标点和明确等义的措辞。缺失维度无需补齐；不把几个改为三五位，不增加低声聊天、背景模糊或清晰、书本位置等内容，不把人物左右推为画面左右。已有内容完整时允许不改写。条件、否定、指代与动作顺序不能拆散或擅自重排。',
+    '## 输出',
+    '遵守本次编辑策略指定的输出协议；普通改写只输出完整提示词正文，不解释、不加额外标题、不使用 Markdown 代码块或工具调用 JSON。补充建议不混入正文，未经用户采纳不视为用户要求。'
+  ].join('\n\n'),
   targets: {
-    general: '适用于一般对话任务：明确目标、必要背景、约束、期望输出和验收标准；避免无意义地拉长文本。',
-    image: '适用于图像生成：在原意允许的范围内明确主体、环境、构图、视角、光线、色彩、材质、风格和负面约束。',
-    video: '适用于视频生成：在原意允许的范围内明确主体动作、场景变化、镜头运动、景别、节奏、时长感、连续性和负面约束。',
-    s2v: '适用于首尾帧视频：明确首帧到尾帧之间的动作、镜头、空间关系和连续性，避免引入与两端画面冲突的新主体。'
+    general: '# 通用任务\n\n## 目标\n把用户任务整理为明确、可执行的指令。\n\n## 组织\n按需要写清目标、必要背景与输入、约束、期望输出和验收标准；不添加用户未要求的工作步骤或背景事实。',
+    image: '# 画图 · iris_draw_image\n\n## 目标\n整理已有的画图提示词文字，不执行画图。\n\n## 组织\n按已提供的主体与动作、环境、构图与视角、光影、色彩、材质和风格分组。分类维度不是待补全的要求，未指定内容继续未指定。不添加人物、物体、画风、画幅或新关系。\n\n## 保留\n准确保留数量、约数、年龄、左右方位、服装、颜色、程度、姿态及否定范围；仅用户明确授权改变的项目可以改变。文字里的尺寸要求仍是用户要求，不冒充工具参数已设置。',
+    'image-edit': '# 改图 · iris_edit_image\n\n## 目标\n以已有原图为基础，只修改用户明确指定的部分。\n\n## 组织\n写清需要改变的对象、属性或区域，以及必须保持的主体身份、构图、背景、风格和其余细节。修改范围越小，指令越聚焦。\n\n## 输入与约束\n原图未提供可见内容时，不猜测原图颜色、位置或人物细节；用户提供的来源 ID 保持为引用。不要把改图改写成重新画一张，也不擅自增加重绘、遮罩或多参考图工作流。',
+    video: '# 视频 · iris_generate_video\n\n## 目标\n描述用户要生成的文生或图生视频。\n\n## 组织\n围绕主体动作、动作先后、场景变化、镜头运动与景别、节奏和连续性组织可拍摄的过程。保留用户给出的时长、构图与负面约束，不擅自增加分镜、声音或时长参数。\n\n## 输入与约束\n已有首帧或参考图时，只依据用户明确提供的内容保持主体与空间关系；不虚构已经查看素材。不要用静态画质词替代动作和时间描述。',
+    s2v: '# 数字人 · iris_generate_video（S2V）\n\n## 输入\n此功能依据首帧图像与音频生成视频；S2V 不是首尾帧插值。\n\n## 目标与组织\n在既定人物和已有音频约束下，描述与用户要求一致的表情、口型、姿态、动作和镜头。保持身份、服装、背景及动作连续性，不擅自改写音频台词、添加声音或替换人物。\n\n## 约束\n音频内容或图像不可见时，不猜测台词、时长、情绪或外观细节；已有素材无需再次生成。'
   },
   route: {
     mode: 'session'