@mokuyoaxis/dsh-iris 0.1.3 → 0.2.0

package/lib/core-attention.js

@@ -0,0 +1,103 @@
+'use strict';
+/**
+ * Core 任务的注意力处置偏好（Host 侧，绝不写入 Core 数据根）。
+ *
+ * 语义（与 legacy attentionDisposition 对齐）：
+ * - acknowledged：「不再提醒」——attention 行静默，仍留在历史与高级诊断；
+ * - hidden：「移除」——从任务区/泡泡消失，Core 记录完整保留，诊断可查、可恢复；
+ * - 只存 Task ID 与时间戳，不存任务内容、Prompt、远端 ID 或路径。
+ *
+ * 存储：$DSH_HOME/iris/v1/core-attention.json（0600，原子写 + rename）。
+ * 读取纪律：文件缺失或损坏一律降级为"无偏好"，绝不报错；reader 路径不写文件。
+ * 自动静默（重试成功）不落偏好，由快照从 retriedFrom + 后继终态实时派生。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { irisHome } from './config.js';
+import { atomicWritePrivate } from './private-storage.js';
+
+export const CORE_ATTENTION_VERSION = 1;
+const TASK_ID = /^task_[a-f0-9]{24}$/;
+
+function attentionFile() {
+  return path.join(irisHome(), 'core-attention.json');
+}
+
+/** reader：缺失/损坏一律返回无偏好。绝不写文件。 */
+export function readCoreAttentionPrefs() {
+  try {
+    const raw = fs.readFileSync(attentionFile(), 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)
+        || !parsed.entries || typeof parsed.entries !== 'object' || Array.isArray(parsed.entries)) {
+      return { version: CORE_ATTENTION_VERSION, entries: {} };
+    }
+    const entries = {};
+    for (const [id, entry] of Object.entries(parsed.entries)) {
+      if (!TASK_ID.test(id) || !entry || typeof entry !== 'object' || Array.isArray(entry)) continue;
+      const cleaned = {};
+      for (const field of ['acknowledgedAt', 'hiddenAt', 'updatedAt']) {
+        if (typeof entry[field] === 'string' && entry[field]) cleaned[field] = entry[field];
+      }
+      if (Object.keys(cleaned).length) entries[id] = cleaned;
+    }
+    return { version: Number(parsed.version) || CORE_ATTENTION_VERSION, entries };
+  } catch (_) {
+    return { version: CORE_ATTENTION_VERSION, entries: {} };
+  }
+}
+
+/** 单条记录的处置态；hidden 优先（视觉上先消失）。 */
+export function attentionDispositionOf(entry) {
+  if (!entry || typeof entry !== 'object') return null;
+  if (entry.hiddenAt) return 'hidden';
+  if (entry.acknowledgedAt) return 'acknowledged';
+  return null;
+}
+
+/**
+ * writer：应用一个处置动作并原子落盘。幂等——同一动作重复执行内容不变时不写盘。
+ * 返回 { changed, entry }。
+ */
+export function applyCoreAttentionAction(taskId, action, { now = new Date().toISOString() } = {}) {
+  const id = String(taskId || '').trim();
+  if (!TASK_ID.test(id)) {
+    const error = new Error('Core Task ID 无效');
+    error.code = 'IRIS_DSH_TASK_INVALID';
+    throw error;
+  }
+  if (!['acknowledge', 'restore', 'hide', 'unhide'].includes(action)) {
+    const error = new Error('未知 Core 注意力处置动作：' + String(action));
+    error.code = 'IRIS_DSH_ATTENTION_INVALID';
+    throw error;
+  }
+  const prefs = readCoreAttentionPrefs();
+  const previous = prefs.entries[id] || null;
+  const entry = previous ? { ...previous } : {};
+  // 幂等：目标状态已达即无操作（不刷时间戳、不写盘）。
+  const noop = (action === 'acknowledge' && Boolean(entry.acknowledgedAt))
+    || (action === 'restore' && !entry.acknowledgedAt)
+    || (action === 'hide' && Boolean(entry.hiddenAt))
+    || (action === 'unhide' && !entry.hiddenAt);
+  if (!noop) {
+    if (action === 'acknowledge') entry.acknowledgedAt = now;
+    if (action === 'restore') delete entry.acknowledgedAt;
+    if (action === 'hide') entry.hiddenAt = now;
+    if (action === 'unhide') delete entry.hiddenAt;
+    // updatedAt 只随有效处置留存；两个戳都没有的条目视为空并整体移除。
+    if (entry.acknowledgedAt || entry.hiddenAt) entry.updatedAt = now;
+  }
+  const meaningful = Boolean(entry.acknowledgedAt || entry.hiddenAt);
+  const afterDisposition = attentionDispositionOf(entry);
+  const changed = !noop;
+  if (changed) {
+    const entries = { ...prefs.entries };
+    if (meaningful) entries[id] = entry;
+    else delete entries[id];
+    atomicWritePrivate(attentionFile(), JSON.stringify({
+      version: CORE_ATTENTION_VERSION,
+      entries
+    }, null, 2) + '\n');
+  }
+  return Object.freeze({ changed, entry: Object.freeze(entry), disposition: afterDisposition });
+}

package/lib/core-contract.js

@@ -0,0 +1,105 @@
+'use strict';
+
+import path from 'node:path';
+
+/** Iris Core Runtime 的内部候选契约；尚未作为 package export 发布。 */
+export const CORE_CONTRACT_VERSION = 0;
+
+export const CORE_ACCESS_MODES = Object.freeze(['reader', 'writer']);
+export const CORE_LIFECYCLE_STATES = Object.freeze(['created', 'started', 'disposing', 'disposed']);
+export const CORE_OPERATIONS = Object.freeze(['inspect', 'execute', 'recover']);
+
+const MODE_SET = new Set(CORE_ACCESS_MODES);
+const STATE_SET = new Set(CORE_LIFECYCLE_STATES);
+const OPERATION_SET = new Set(CORE_OPERATIONS);
+
+export class CoreContractError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'CoreContractError';
+    this.code = code;
+  }
+}
+
+function fail(code, message) {
+  throw new CoreContractError(code, message);
+}
+
+function plainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * Core 不推断 DSH_HOME、HOME 或 cwd。默认数据根只能由具体 Host/CLI 边界选择，
+ * 再以绝对路径显式传入。物理路径（realpath）与写者租约在 Runtime 实现阶段完成。
+ */
+export function normalizeCoreOptions(input) {
+  if (!plainObject(input)) fail('IRIS_CORE_OPTIONS_INVALID', 'Core Runtime 选项必须是对象');
+  const allowed = new Set(['dataRoot', 'mode']);
+  for (const key of Object.keys(input)) {
+    if (!allowed.has(key)) fail('IRIS_CORE_OPTIONS_INVALID', `Core Runtime 不允许选项：${key}`);
+  }
+
+  const dataRoot = typeof input.dataRoot === 'string' ? input.dataRoot.trim() : '';
+  if (!dataRoot || dataRoot.includes('\0') || !path.isAbsolute(dataRoot)) {
+    fail('IRIS_CORE_OPTIONS_INVALID', 'Core Runtime dataRoot 必须是显式绝对路径');
+  }
+  const mode = input.mode ?? 'writer';
+  if (!MODE_SET.has(mode)) fail('IRIS_CORE_OPTIONS_INVALID', `未知 Core Runtime 模式：${String(mode)}`);
+
+  return Object.freeze({
+    contractVersion: CORE_CONTRACT_VERSION,
+    dataRoot: path.normalize(dataRoot),
+    mode
+  });
+}
+
+export function createCoreLifecycle() {
+  return Object.freeze({ contractVersion: CORE_CONTRACT_VERSION, state: 'created' });
+}
+
+/** 纯状态转换；真正的资源获取、取消与释放由 Runtime 按文档顺序执行。 */
+export function transitionCoreLifecycle(snapshot, event) {
+  const state = snapshot && snapshot.state;
+  if (!STATE_SET.has(state)) fail('IRIS_CORE_STATE_INVALID', 'Core Runtime 生命周期快照无效');
+
+  if (event === 'start' && state === 'created') {
+    return Object.freeze({ contractVersion: CORE_CONTRACT_VERSION, state: 'started' });
+  }
+  if (event === 'dispose' && (state === 'created' || state === 'started')) {
+    return Object.freeze({ contractVersion: CORE_CONTRACT_VERSION, state: 'disposing' });
+  }
+  if (event === 'dispose' && (state === 'disposing' || state === 'disposed')) return snapshot;
+  if (event === 'finish-dispose' && state === 'disposing') {
+    return Object.freeze({ contractVersion: CORE_CONTRACT_VERSION, state: 'disposed' });
+  }
+  fail('IRIS_CORE_STATE_INVALID', `Core Runtime 不能在 ${state} 状态执行 ${String(event)}`);
+}
+
+/**
+ * reader 只允许不产生持久化副作用的 inspect；初始化、修复、索引接回与观察任务
+ * 都属于写者行为。此函数只冻结权限真值表，不替代后续的数据根租约。
+ */
+export function assertCoreOperation(options, lifecycle, operation) {
+  if (!options || options.contractVersion !== CORE_CONTRACT_VERSION || !MODE_SET.has(options.mode)) {
+    fail('IRIS_CORE_OPTIONS_INVALID', 'Core Runtime 选项未经过当前契约规范化');
+  }
+  if (!lifecycle || lifecycle.state !== 'started') {
+    fail('IRIS_CORE_STATE_INVALID', 'Core Runtime 仅能在 started 状态执行操作');
+  }
+  if (!OPERATION_SET.has(operation)) {
+    fail('IRIS_CORE_OPERATION_INVALID', `未知 Core Runtime 操作：${String(operation)}`);
+  }
+  if (options.mode === 'reader' && operation !== 'inspect') {
+    fail('IRIS_CORE_READ_ONLY', `只读 Core Runtime 不能执行 ${operation}`);
+  }
+  return true;
+}
+
+/** 供未来数据根租约实现统一返回稳定错误；不得暴露本机绝对路径。 */
+export function coreDataRootBusyError() {
+  return new CoreContractError(
+    'IRIS_CORE_DATA_ROOT_BUSY',
+    '该 Iris 数据根已有写者；先停止现有写者并运行 doctor --data-root 检查，只有 stale PID 才可显式执行 runtime recover'
+  );
+}

package/lib/core-doctor.js

@@ -0,0 +1,41 @@
+'use strict';
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { normalizeCoreOptions } from './core-contract.js';
+import { inspectCoreWriterLease } from './core-runtime.js';
+import { listCoreTasks } from './core-tasks.js';
+import { inspectCoreArtifactStore } from './core-artifact-store.js';
+
+/** 仅返回计数和状态，不返回 Task 内容、文件名或数据根路径。 */
+export function inspectCoreStorage(dataRoot) {
+  const options = normalizeCoreOptions({ dataRoot, mode: 'reader' });
+  let root;
+  try {
+    root = fs.realpathSync.native(options.dataRoot);
+    if (!fs.statSync(root).isDirectory()) return { status: 'invalid' };
+  } catch (error) { return { status: error?.code === 'ENOENT' ? 'absent' : 'invalid' }; }
+  const report = { status: 'present', lease: inspectCoreWriterLease(root) };
+  try {
+    const tasks = listCoreTasks(root, { limit: 1, skipInvalid: true });
+    let taskStatus = 'present';
+    let unresolved = 0;
+    for (const relative of ['task-store', 'task-store/v0', 'task-store/v0/tasks']) {
+      try { fs.lstatSync(path.join(root, relative)); }
+      catch (error) {
+        if (error?.code !== 'ENOENT') throw error;
+        // Entire store absent is valid for a new root; a partial tree needs diagnosis.
+        taskStatus = relative === 'task-store' ? 'absent' : 'invalid';
+        break;
+      }
+    }
+    if (taskStatus === 'present') {
+      unresolved = fs.readdirSync(path.join(root, 'task-store/v0/tasks'))
+        .filter((name) => !/^task_[a-f0-9]{24}\.json$/.test(name)).length;
+    }
+    report.tasks = { status: taskStatus, total: tasks.total, invalid: tasks.dropped, unresolved };
+  } catch (_) { report.tasks = { status: 'invalid' }; }
+  try { report.artifacts = inspectCoreArtifactStore(root); }
+  catch (_) { report.artifacts = { status: 'invalid' }; }
+  return report;
+}

package/lib/core-lease-recovery.js

@@ -0,0 +1,170 @@
+'use strict';
+
+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';
+
+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) {
+  throw new CoreContractError(code, message);
+}
+
+function physicalDataRoot(dataRoot) {
+  const options = normalizeCoreOptions({ dataRoot, mode: 'reader' });
+  try {
+    const root = fs.realpathSync.native(options.dataRoot);
+    if (!fs.statSync(root).isDirectory()) fail('IRIS_CORE_DATA_ROOT_UNAVAILABLE', 'Iris 数据根必须是目录');
+    return root;
+  } catch (error) {
+    if (error instanceof CoreContractError) throw error;
+    if (error?.code === 'ENOENT') fail('IRIS_CORE_DATA_ROOT_NOT_FOUND', 'Iris 数据根不存在；恢复不会自动创建');
+    fail('IRIS_CORE_DATA_ROOT_UNAVAILABLE', '无法访问 Iris 数据根');
+  }
+}
+
+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 {
+    const stat = fs.lstatSync(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('invalid audit directory');
+  } catch (error) {
+    if (error?.code !== 'ENOENT') fail('IRIS_CORE_LEASE_RECOVERY_FAILED', '租约恢复审计目录不安全；已保留现场');
+    try { fs.mkdirSync(directory, { mode: 0o700 }); }
+    catch (_) { fail('IRIS_CORE_LEASE_RECOVERY_FAILED', '无法创建租约恢复审计目录；已保留现场'); }
+  }
+  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);
+}
+
+/**
+ * 显式接管并释放一个可证明 owner PID 已不存在的 writer 租约。
+ * 调用方必须回显 Doctor 报告中的 PID；活跃、未知或损坏证据一律拒绝。
+ */
+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); }
+  catch (_) { fail('IRIS_CORE_LEASE_INVALID', '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 已退出；拒绝恢复');
+
+  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;
+  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;
+
+    const directory = auditDirectory(root);
+    auditFile = path.join(directory, auditId + '.json');
+    const audit = {
+      schemaVersion: 1,
+      id: auditId,
+      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
+    };
+    writePrivateFile(auditFile, JSON.stringify(audit, null, 2) + '\n', { flag: 'wx' });
+    fs.unlinkSync(staleOwnerFile);
+    releaseRecoveryLease({
+      directory: lease.directory,
+      ownerFile: lease.ownerFile,
+      owner: recoveryOwner
+    });
+    return Object.freeze({
+      status: 'recovered',
+      auditId,
+      staleOwner: Object.freeze({ pid: lease.owner.pid, createdAt: new Date(lease.created).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 */ }
+    if (error instanceof CoreContractError) throw error;
+    fail('IRIS_CORE_LEASE_RECOVERY_FAILED',
+      auditFile && fs.existsSync(auditFile)
+        ? '租约恢复未能安全完成；审计证据与现场均已保留'
+        : '租约恢复失败；原租约已尽力保留');
+  }
+}

package/lib/core-runtime.js

@@ -0,0 +1,232 @@
+'use strict';
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  CORE_CONTRACT_VERSION,
+  CoreContractError,
+  assertCoreOperation,
+  coreDataRootBusyError,
+  createCoreLifecycle,
+  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';
+
+/** 只读租约证据；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'; }
+    return {
+      status: 'present', ownerStatus, pid: owner.pid,
+      createdAt: new Date(created).toISOString(), ageMs: Math.max(0, Date.now() - created)
+    };
+  } catch (_) { return { status: 'invalid' }; }
+}
+
+function coreError(code, message) {
+  return new CoreContractError(code, message);
+}
+
+function physicalDataRoot(options) {
+  if (options.mode === 'writer') {
+    try { ensurePrivateDir(options.dataRoot); }
+    catch (_) { throw coreError('IRIS_CORE_DATA_ROOT_UNAVAILABLE', '无法创建或访问 Iris 数据根'); }
+  }
+  let root;
+  try { root = fs.realpathSync.native(options.dataRoot); }
+  catch (error) {
+    if (error && error.code === 'ENOENT') {
+      throw coreError('IRIS_CORE_DATA_ROOT_NOT_FOUND', 'Iris 数据根不存在；只读模式不会自动创建');
+    }
+    throw coreError('IRIS_CORE_DATA_ROOT_UNAVAILABLE', '无法访问 Iris 数据根');
+  }
+  try {
+    if (!fs.statSync(root).isDirectory()) {
+      throw coreError('IRIS_CORE_DATA_ROOT_UNAVAILABLE', 'Iris 数据根必须是目录');
+    }
+  } catch (error) {
+    if (error instanceof CoreContractError) throw error;
+    throw coreError('IRIS_CORE_DATA_ROOT_UNAVAILABLE', '无法检查 Iris 数据根');
+  }
+  return root;
+}
+
+function acquireWriterLease(root, instanceId) {
+  const directory = path.join(root, WRITER_LEASE_DIR);
+  const ownerFile = path.join(directory, WRITER_OWNER_FILE);
+  try {
+    fs.mkdirSync(directory, { mode: 0o700 });
+  } catch (error) {
+    if (error && error.code === 'EEXIST') throw coreDataRootBusyError();
+    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 (_) { /* 保留不确定租约比误删安全 */ }
+    throw coreError('IRIS_CORE_DATA_ROOT_UNAVAILABLE', '无法记录 Iris 数据根写者租约');
+  }
+  return Object.freeze({ directory, ownerFile, owner, serialized });
+}
+
+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'));
+  } catch (_) {
+    throw coreError('IRIS_CORE_LEASE_INVALID', 'Iris 写者租约无法安全释放；已保留现场');
+  }
+  if (actual.instanceId !== lease.owner.instanceId) {
+    throw coreError('IRIS_CORE_LEASE_INVALID', 'Iris 写者租约所有者不匹配；已保留现场');
+  }
+
+  try {
+    fs.unlinkSync(lease.ownerFile);
+    fs.rmdirSync(lease.directory);
+  } 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 写者租约释放失败；已保留现场');
+  }
+}
+
+function runtimeSnapshot(options, lifecycle, hasLease, inFlight) {
+  return Object.freeze({
+    contractVersion: CORE_CONTRACT_VERSION,
+    state: lifecycle.state,
+    mode: options.mode,
+    writerLease: Boolean(hasLease),
+    inFlight
+  });
+}
+
+/**
+ * 创建一个最小 Core Runtime 实例。它尚未迁移 0.1.4 的模块级存储；当前职责只有
+ * 显式数据根、单写者租约、操作权限、AbortSignal 与可验证释放顺序。
+ */
+export function createCoreRuntime(input) {
+  const options = normalizeCoreOptions(input);
+  const instanceId = crypto.randomUUID();
+  const abortController = new AbortController();
+  const inFlight = new Set();
+  const cleanup = [];
+  let lifecycle = createCoreLifecycle();
+  let root = null;
+  let lease = null;
+  let disposePromise = null;
+
+  function snapshot() {
+    return runtimeSnapshot(options, lifecycle, lease, inFlight.size);
+  }
+
+  function start() {
+    if (lifecycle.state !== 'created') {
+      return transitionCoreLifecycle(lifecycle, 'start');
+    }
+    const candidateRoot = physicalDataRoot(options);
+    const candidateLease = options.mode === 'writer' ? acquireWriterLease(candidateRoot, instanceId) : null;
+    root = candidateRoot;
+    lease = candidateLease;
+    lifecycle = transitionCoreLifecycle(lifecycle, 'start');
+    return snapshot();
+  }
+
+  function onDispose(callback) {
+    if (typeof callback !== 'function') throw new TypeError('Core Runtime cleanup 必须是函数');
+    if (lifecycle.state === 'disposing' || lifecycle.state === 'disposed') {
+      throw coreError('IRIS_CORE_STATE_INVALID', 'Core Runtime 已开始释放，不能注册 cleanup');
+    }
+    cleanup.push(callback);
+    let active = true;
+    return () => {
+      if (!active) return false;
+      active = false;
+      const index = cleanup.indexOf(callback);
+      if (index >= 0) cleanup.splice(index, 1);
+      return index >= 0;
+    };
+  }
+
+  function run(operation, callback) {
+    if (typeof callback !== 'function') throw new TypeError('Core Runtime 操作必须是函数');
+    assertCoreOperation(options, lifecycle, operation);
+    const context = Object.freeze({ dataRoot: root, signal: abortController.signal });
+    let result;
+    try { result = callback(context); }
+    catch (error) { result = Promise.reject(error); }
+    const promise = Promise.resolve(result);
+    inFlight.add(promise);
+    promise.then(
+      () => inFlight.delete(promise),
+      () => inFlight.delete(promise)
+    );
+    return promise;
+  }
+
+  function dispose() {
+    if (disposePromise) return disposePromise;
+    lifecycle = transitionCoreLifecycle(lifecycle, 'dispose');
+    abortController.abort();
+    disposePromise = (async () => {
+      await Promise.allSettled([...inFlight]);
+      for (const callback of [...cleanup].reverse()) await callback();
+      cleanup.length = 0;
+      if (lease) {
+        releaseWriterLease(lease);
+        lease = null;
+      }
+      root = null;
+      lifecycle = transitionCoreLifecycle(lifecycle, 'finish-dispose');
+      return snapshot();
+    })();
+    return disposePromise;
+  }
+
+  return Object.freeze({
+    start,
+    run,
+    onDispose,
+    dispose,
+    snapshot,
+    get signal() { return abortController.signal; }
+  });
+}