@dshtrading/dsh-home 0.6.1 → 0.6.3

package/lib/file-lease.d.ts

@@ -0,0 +1,8 @@
+//#region src/file-lease.d.ts
+interface HomeFileLease {
+  dispose(): void;
+}
+/** 取得该数据文件的 writer lease；已被活实例持有时返回 undefined（明确失败）。 */
+declare function tryAcquireHomeFileLeaseSync(filePath: string): HomeFileLease | undefined;
+//#endregion
+export { HomeFileLease, tryAcquireHomeFileLeaseSync };

package/lib/file-lease.js

@@ -0,0 +1,57 @@
+import { createRequire } from "node:module";
+import { chmodSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+//#region src/file-lease.ts
+/**
+* 本地文件系统的 writer lease（SQLite 进程锁）。业务状态仍是 JSON，这个稳定
+* sidecar 只承载内核级互斥：持锁进程退出即自动释放，不依赖按路径 rename 冒充
+* CAS。Node >=22.19 内置 node:sqlite，无需新增依赖；运行时不提供该能力时
+* fail-closed 报明确错误，绝不退回「先检查后覆盖」的不安全路径。
+*
+* 只在可能有活实例时保留 `*.writer-lease.sqlite` 侧文件：删除它等于放弃互斥。
+*/
+const require = createRequire(import.meta.url);
+let cachedSqlite;
+function loadSqlite() {
+	if (cachedSqlite !== void 0) return cachedSqlite;
+	try {
+		cachedSqlite = require("node:sqlite");
+		return cachedSqlite;
+	} catch (error) {
+		throw new Error("this runtime provides no node:sqlite writer lease; refusing to run the task ledger without kernel-level mutual exclusion: " + (error instanceof Error ? error.message : String(error)));
+	}
+}
+/** SQLITE_BUSY(5) / SQLITE_LOCKED(6)：另一个活实例正持有该文件的 writer lease。 */
+function isBusy(error) {
+	const code = typeof error === "object" && error !== null ? error.errcode : void 0;
+	return typeof code === "number" && (code & 255) === 5 || code === 6;
+}
+/** 取得该数据文件的 writer lease；已被活实例持有时返回 undefined（明确失败）。 */
+function tryAcquireHomeFileLeaseSync(filePath) {
+	const leasePath = `${filePath}.writer-lease.sqlite`;
+	mkdirSync(dirname(leasePath), { recursive: true });
+	const database = new (loadSqlite()).DatabaseSync(leasePath);
+	try {
+		database.exec("PRAGMA busy_timeout = 0");
+		database.exec("BEGIN IMMEDIATE");
+	} catch (error) {
+		database.close();
+		if (isBusy(error)) return void 0;
+		throw error;
+	}
+	try {
+		chmodSync(leasePath, 384);
+	} catch {}
+	let disposed = false;
+	return { dispose() {
+		if (disposed) return;
+		disposed = true;
+		try {
+			database.exec("ROLLBACK");
+		} finally {
+			database.close();
+		}
+	} };
+}
+//#endregion
+export { tryAcquireHomeFileLeaseSync };

package/lib/file-lock.d.ts

@@ -2,16 +2,34 @@
 interface HomeFileLockOptions {
   /** 等锁上限（毫秒）；超时抛错，不静默降级。 */
   readonly timeoutMs?: number;
-  /** 锁文件 mtime 超过该毫秒数视为陈旧（持锁者已崩溃），可被后来者回收。 */
+  /** 锁文件 mtime 超过该毫秒数视为可能陈旧；仍需 owner 已死才回收。 */
   readonly staleMs?: number;
 }
+/** 锁文件记录的 owner 身份：pid + host + 每次获取唯一的 token + 获取时刻。 */
+interface HomeFileLockOwner {
+  readonly pid: number;
+  readonly host: string;
+  readonly token: string;
+  readonly at: number;
+}
 /** 等锁超时：本次调用按「明确失败」处理，磁盘上的数据保持持锁者的版本。 */
 declare class HomeFileLockTimeoutError extends Error {
   readonly lockPath: string;
   readonly timeoutMs: number;
   constructor(lockPath: string, timeoutMs: number);
 }
+/** 提交前复核发现锁已不归本实例（被回收/顶替）：本次写入放弃，不覆盖新 owner。 */
+declare class HomeFileLockLostError extends Error {
+  readonly lockPath: string;
+  constructor(lockPath: string);
+}
+/** 临界区句柄：进入后可在提交前复核归属。 */
+interface HomeFileLock {
+  readonly owner: HomeFileLockOwner;
+  /** 复核此刻仍持有该锁（token 未变）；被顶替时抛 {@link HomeFileLockLostError}。 */
+  assertOwned(): Promise<void>;
+}
 /** 在跨进程锁内执行 work；无论成功失败都释放锁（进程崩溃时由陈旧阈值兜底）。 */
-declare function withHomeFileLock<T>(filePath: string, work: () => Promise<T>, options?: HomeFileLockOptions): Promise<T>;
+declare function withHomeFileLock<T>(filePath: string, work: (lock: HomeFileLock) => Promise<T>, options?: HomeFileLockOptions): Promise<T>;
 //#endregion
-export { HomeFileLockOptions, HomeFileLockTimeoutError, withHomeFileLock };
+export { HomeFileLock, HomeFileLockLostError, HomeFileLockOptions, HomeFileLockOwner, HomeFileLockTimeoutError, withHomeFileLock };

package/lib/file-lock.js

@@ -1,13 +1,26 @@
+import { tryAcquireHomeFileLeaseSync } from "./file-lease.js";
 import { hostname } from "node:os";
 import { dirname } from "node:path";
-import { mkdir, open, rename, stat, unlink, utimes } from "node:fs/promises";
+import { link, mkdir, open, readFile, rename, stat, unlink, utimes } from "node:fs/promises";
 //#region src/file-lock.ts
 /**
 * home 数据文件的跨进程排他锁（2026-10-09 事故「多进程整表回写互相覆盖」的机制基座）。
 *
-* 为什么不是 flock/fcntl：Node 无内建 flock，Windows 与网络盘语义不一致；锁文件
-* （O_EXCL 创建 + pid/host/心跳 mtime）三平台一致，且持锁进程崩溃后可由后来者按
-* 陈旧阈值回收——不依赖持锁者自己清理。
+* 本地文件系统由 Node 内置 SQLite 的进程锁持有临界区，获取/接管/释放均在
+* 同一内核排他边界内；业务状态仍是 JSON。持有进程退出自动释放内核租约，
+* owner 标记继续按可证明的进程死亡与心跳证据回收，不靠路径 rename 冒充 CAS。
+* 不支持跨机器共 home；writer-lease.sqlite 侧文件在可能有活实例时不得删除。
+*
+* owner 身份（2026-10-12 补强）：锁路径一旦出现就带有完整身份（pid + host + 每次
+* 获取唯一的 token），不经过「先创建空锁、再补写身份」的未知窗口。
+*
+* 回收判据不是「mtime 旧就抢」：只有 owner 在本机（host 相同）、其 pid **确认已不
+* 存在**、且 mtime 已过陈旧阈值，才允许回收。活着的 owner、别的机器的 owner、读不出
+* 身份的锁一律不回收（等锁明确超时）——宁可按明确错误失败，也绝不冒双写风险。
+*
+* 归属纪律：临界区内提交前（{@link HomeFileLock.assertOwned}）与释放时都按 token
+* 复核「这把锁现在是不是我的」。被回收/顶替的实例既不会再写盘，也不会删掉新
+* owner 的锁（按路径盲删会让互斥失效）。
 *
 * 语义：进入临界区前必得锁；拿不到时等待（缺省 5s），仍拿不到抛
 * {@link HomeFileLockTimeoutError}——「明确告知失败」这条出路，绝不静默按陈旧
@@ -24,17 +37,106 @@ var HomeFileLockTimeoutError = class extends Error {
 		this.timeoutMs = timeoutMs;
 	}
 };
+/** 提交前复核发现锁已不归本实例（被回收/顶替）：本次写入放弃，不覆盖新 owner。 */
+var HomeFileLockLostError = class extends Error {
+	lockPath;
+	constructor(lockPath) {
+		super(`home file lock ${lockPath} is no longer owned by this process (it was reclaimed or replaced); this process wrote nothing`);
+		this.name = "HomeFileLockLostError";
+		this.lockPath = lockPath;
+	}
+};
 const DEFAULT_TIMEOUT_MS = 5e3;
 const DEFAULT_STALE_MS = 3e4;
 const RETRY_MS = 15;
+/** 文件系统不支持硬链接时，退回 O_EXCL 创建 + 写身份的 errno。 */
+const LINK_UNSUPPORTED_CODES = /* @__PURE__ */ new Set([
+	"EPERM",
+	"EACCES",
+	"ENOTSUP",
+	"ENOSYS",
+	"EOPNOTSUPP",
+	"EXDEV"
+]);
 const delay = (ms) => new Promise((resolve) => {
 	setTimeout(resolve, ms);
 });
+function errorCode(error) {
+	return typeof error === "object" && error !== null ? error.code : void 0;
+}
+function randomToken() {
+	return `${process.pid.toString(36)}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+/** 读出锁的 owner 身份；锁不存在、内容不是合法身份 JSON 都返回 undefined（身份未知）。 */
+async function readOwner(lockPath) {
+	let text;
+	try {
+		text = await readFile(lockPath, "utf8");
+	} catch {
+		return;
+	}
+	try {
+		const parsed = JSON.parse(text);
+		if (typeof parsed?.pid === "number" && Number.isInteger(parsed.pid) && parsed.pid > 0 && typeof parsed.host === "string" && parsed.host.length > 0 && typeof parsed.token === "string" && parsed.token.length > 0) return {
+			pid: parsed.pid,
+			host: parsed.host,
+			token: parsed.token,
+			at: typeof parsed.at === "number" ? parsed.at : 0
+		};
+	} catch {}
+}
+/** 本机 pid 是否仍存在（EPERM = 存在但无权限，同样算活着）。 */
+function isProcessAlive(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return errorCode(error) === "EPERM";
+	}
+}
+/**
+* 创建「带身份」的锁：先把完整身份写进唯一 staging 文件，再原子 link 到锁路径。
+* 锁路径一旦存在，内容就是完整身份——不存在「空锁 / 半截身份」的未知窗口，也就
+* 不会出现「未知 owner 永远无法回收」的死锁。返回 false 表示锁已被别人持有。
+*/
+async function createLockWithOwner(lockPath, owner) {
+	const stagingPath = `${lockPath}.owner-${owner.token}`;
+	const text = JSON.stringify(owner);
+	const staging = await open(stagingPath, "wx");
+	try {
+		await staging.writeFile(text, "utf8");
+	} finally {
+		await staging.close();
+	}
+	try {
+		await link(stagingPath, lockPath);
+		return true;
+	} catch (error) {
+		const code = errorCode(error);
+		if (code === "EEXIST") return false;
+		if (code === void 0 || !LINK_UNSUPPORTED_CODES.has(code)) throw error;
+		try {
+			const fallback = await open(lockPath, "wx");
+			try {
+				await fallback.writeFile(text, "utf8");
+			} finally {
+				await fallback.close().catch(() => {});
+			}
+			return true;
+		} catch (fallbackError) {
+			if (errorCode(fallbackError) === "EEXIST") return false;
+			throw fallbackError;
+		}
+	} finally {
+		await unlink(stagingPath).catch(() => {});
+	}
+}
 /**
 * 陈旧锁回收：返回 true 表示可立刻重试拿锁（锁已不在，或已被本次回收）。
 *
-* 抢占用 rename 做原子裁决（同一陈旧 inode 只可能被一个进程搬走）；搬走后复核
-* mtime，若发现抢到的是别人刚重建的新锁（极窄窗口），原样搬回，避免误删活锁。
+* 只有「本机 owner + pid 确认不存在 + mtime 超过陈旧阈值」才回收。抢占用 rename
+* 做原子裁决，抢到后复核 token：若抢到的是窗口里被重建的新锁（尤其是活着的
+* owner），用 link 原样放回（link 遇已存在不覆盖），绝不误删活锁。
 */
 async function reclaimIfStale(lockPath, staleMs) {
 	let ageMs;
@@ -44,19 +146,25 @@ async function reclaimIfStale(lockPath, staleMs) {
 		return true;
 	}
 	if (ageMs <= staleMs) return false;
-	const claimPath = `${lockPath}.stale-${process.pid}-${Date.now()}`;
+	const observed = await readOwner(lockPath);
+	if (observed === void 0) return false;
+	if (observed.host !== hostname()) return false;
+	if (isProcessAlive(observed.pid)) return false;
+	const claimPath = `${lockPath}.stale-${process.pid.toString(36)}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
 	try {
 		await rename(lockPath, claimPath);
 	} catch {
 		return true;
 	}
-	const claimed = await stat(claimPath).catch(() => void 0);
-	if (claimed !== void 0 && Date.now() - claimed.mtimeMs <= staleMs) {
-		await rename(claimPath, lockPath).catch(() => unlink(claimPath).catch(() => {}));
+	const claimed = await readOwner(claimPath);
+	const claimedIsObserved = claimed !== void 0 && claimed.token === observed.token;
+	const claimedIsLiveHere = claimed !== void 0 && claimed.host === hostname() && isProcessAlive(claimed.pid);
+	if (!claimedIsObserved || claimedIsLiveHere) {
+		if (await link(claimPath, lockPath).then(() => true, () => false) || !claimedIsLiveHere) await unlink(claimPath).catch(() => {});
 		return false;
 	}
 	await unlink(claimPath).catch(() => {});
-	console.warn(`[dsh-home] reclaimed stale home file lock ${lockPath} (mtime older than ${staleMs}ms; the holding process likely crashed)`);
+	console.warn(`[dsh-home] reclaimed stale home file lock ${lockPath} (owner pid ${observed.pid} on this host is gone; mtime older than ${staleMs}ms)`);
 	return true;
 }
 /** 在跨进程锁内执行 work；无论成功失败都释放锁（进程崩溃时由陈旧阈值兜底）。 */
@@ -65,36 +173,65 @@ async function withHomeFileLock(filePath, work, options = {}) {
 	const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
 	const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
 	await mkdir(dirname(filePath), { recursive: true });
+	const owner = {
+		pid: process.pid,
+		host: hostname(),
+		token: randomToken(),
+		at: Date.now()
+	};
 	const deadline = Date.now() + timeoutMs;
-	let handle;
-	while (handle === void 0) {
-		try {
-			handle = await open(lockPath, "wx");
-		} catch (error) {
-			if (error.code !== "EEXIST") throw error;
+	let lease;
+	for (;;) {
+		lease = tryAcquireHomeFileLeaseSync(filePath);
+		if (lease !== void 0) {
+			try {
+				if (await createLockWithOwner(lockPath, owner)) break;
+				if (await reclaimIfStale(lockPath, staleMs) && await createLockWithOwner(lockPath, owner)) break;
+			} catch (error) {
+				lease.dispose();
+				throw error;
+			}
+			lease.dispose();
+			lease = void 0;
 		}
-		if (handle !== void 0) break;
 		if (Date.now() >= deadline) throw new HomeFileLockTimeoutError(lockPath, timeoutMs);
-		if (await reclaimIfStale(lockPath, staleMs)) continue;
 		await delay(RETRY_MS);
 	}
+	const stillOurs = async () => {
+		const current = await readOwner(lockPath);
+		return current !== void 0 && current.token === owner.token;
+	};
+	const heartbeatJobs = /* @__PURE__ */ new Set();
 	const heartbeat = setInterval(() => {
-		const now = /* @__PURE__ */ new Date();
-		utimes(lockPath, now, now).catch(() => {});
+		const job = (async () => {
+			if (!await stillOurs()) return;
+			const now = /* @__PURE__ */ new Date();
+			await utimes(lockPath, now, now).catch(() => {});
+		})();
+		heartbeatJobs.add(job);
+		job.finally(() => {
+			heartbeatJobs.delete(job);
+		});
 	}, Math.max(1e3, Math.floor(staleMs / 3)));
 	heartbeat.unref?.();
+	const lock = {
+		owner,
+		async assertOwned() {
+			if (!await stillOurs()) throw new HomeFileLockLostError(lockPath);
+		}
+	};
 	try {
-		await handle.writeFile(JSON.stringify({
-			pid: process.pid,
-			host: hostname(),
-			at: Date.now()
-		}), "utf8");
-		return await work();
+		return await work(lock);
 	} finally {
 		clearInterval(heartbeat);
-		await handle.close().catch(() => {});
-		await unlink(lockPath).catch(() => {});
+		await Promise.all(heartbeatJobs);
+		try {
+			if (await stillOurs()) await unlink(lockPath).catch(() => {});
+			else console.warn(`[dsh-home] home file lock ${lockPath} was reclaimed or replaced while held by pid ${owner.pid}; leaving the current owner's lock in place`);
+		} finally {
+			lease.dispose();
+		}
 	}
 }
 //#endregion
-export { HomeFileLockTimeoutError, withHomeFileLock };
+export { HomeFileLockLostError, HomeFileLockTimeoutError, withHomeFileLock };

package/lib/fs-atomic.js

@@ -1,5 +1,5 @@
 import { dirname } from "node:path";
-import { mkdir, rename, unlink, writeFile } from "node:fs/promises";
+import { mkdir, open, rename, unlink } from "node:fs/promises";
 //#region src/fs-atomic.ts
 /**
 * home 数据文件原子写单一实现（2026-09-09 收敛，原为 7 个包的 9+ 处同体副本）：
@@ -7,29 +7,104 @@ import { mkdir, rename, unlink, writeFile } from "node:fs/promises";
 * 重试耗尽或任何失败保留旧文件、清理 tmp、log + throw——目标文件永远只被
 * 原子 rename 触碰，绝不非原子直写（半截写会损坏 JSON 导致 load 静默重置）。
 *
+* 耐久性（2026-10-12 补强）：rename 前对 tmp 的**文件描述符** fsync，rename 后对
+* **父目录** fsync——新内容与「改名已发生」各有明确同步点，而不是只把数据交给
+* 页缓存。同步失败不静默降级：目录 fsync 只在平台/文件系统**明确不支持**时
+* （Windows 无法以句柄打开目录；部分网络盘）记一行告警后跳过，其余同步错误一律
+* 上抛——「无法确认耐久」必须响亮，不能装成功。
+*
 * logPrefix 是失败日志在文件路径之前的完整前缀，逐字保留各调用方既有日志
 * （如 '[dsh-trading/knowledge] failed to atomic flush knowledge cards to'）。
 */
+/** rename 目标被占用（Windows 常见）时可退避重试的 errno。 */
+const RENAME_BUSY_CODES = /* @__PURE__ */ new Set(["EPERM", "EBUSY"]);
+/**
+* 目录 fsync 在平台/文件系统层面不支持时的 errno：Windows 无法以文件句柄打开
+* 目录（EISDIR/EPERM/EINVAL），部分网络盘/容器返回 ENOTSUP/ENOSYS。只有这类
+* 「能力缺失」可容忍；EACCES/ENOENT/IO 错误等真正的同步失败一律上抛。
+*/
+const DIR_SYNC_UNSUPPORTED_CODES = /* @__PURE__ */ new Set([
+	"EISDIR",
+	"EPERM",
+	"EINVAL",
+	"ENOTSUP",
+	"ENOSYS"
+]);
+function errorCode(error) {
+	return typeof error === "object" && error !== null ? error.code : void 0;
+}
+let warnedDirSyncUnsupported = false;
+/** 平台不支持目录 fsync 时明确告知一次（明确受限 ≠ 静默吞掉所有错误）。 */
+function warnDirSyncUnsupported(dir, code) {
+	if (warnedDirSyncUnsupported) return;
+	warnedDirSyncUnsupported = true;
+	console.warn(`[dsh-home] directory fsync is unsupported on this platform/fs (${code ?? "unknown"}) for ${dir}; rename durability is limited to the file fsync (other sync errors are still surfaced)`);
+}
+const delay = (ms) => new Promise((resolve) => {
+	setTimeout(resolve, ms);
+});
+/** 对父目录 fsync，让 rename 本身持久化；不支持的平台明确受限，其余错误上抛。 */
+async function fsyncDirectory(dir) {
+	let handle;
+	try {
+		handle = await open(dir, "r");
+	} catch (error) {
+		if (!DIR_SYNC_UNSUPPORTED_CODES.has(errorCode(error) ?? "")) throw error;
+		warnDirSyncUnsupported(dir, errorCode(error));
+		return;
+	}
+	let failure;
+	try {
+		await handle.sync();
+	} catch (error) {
+		if (DIR_SYNC_UNSUPPORTED_CODES.has(errorCode(error) ?? "")) warnDirSyncUnsupported(dir, errorCode(error));
+		else failure = error;
+	}
+	try {
+		await handle.close();
+	} catch (error) {
+		failure ??= error;
+	}
+	if (failure !== void 0) throw failure;
+}
 async function writeJsonAtomic(filePath, data, logPrefix) {
 	const dir = dirname(filePath);
-	const tmpPath = `${filePath}.tmp.${Date.now()}.${Math.random().toString(36).slice(2, 8)}`;
+	const tmpPath = `${filePath}.tmp.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}`;
 	const text = JSON.stringify(data, null, 2);
+	let tmpPresent = false;
 	try {
 		await mkdir(dir, { recursive: true });
-		await writeFile(tmpPath, text, "utf8");
-		let lastError;
-		for (let attempt = 0; attempt < 3; attempt++) try {
+		const handle = await open(tmpPath, "wx");
+		tmpPresent = true;
+		let failure;
+		try {
+			await handle.writeFile(text, "utf8");
+			await handle.sync();
+		} catch (error) {
+			failure = error;
+		}
+		try {
+			await handle.close();
+		} catch (error) {
+			failure ??= error;
+		}
+		if (failure !== void 0) throw failure;
+		let renameError;
+		let renamed = false;
+		for (let attempt = 0; attempt < 3 && !renamed; attempt++) try {
 			await rename(tmpPath, filePath);
-			return;
-		} catch (err) {
-			if (err?.code !== "EPERM" && err?.code !== "EBUSY") throw err;
-			lastError = err;
-			await new Promise((resolve) => setTimeout(resolve, 25 * (attempt + 1)));
+			renamed = true;
+		} catch (error) {
+			if (!RENAME_BUSY_CODES.has(errorCode(error) ?? "")) throw error;
+			renameError = error;
+			await delay(25 * (attempt + 1));
 		}
-		throw lastError;
+		if (!renamed) throw renameError;
+		tmpPresent = false;
+		await fsyncDirectory(dir);
 	} catch (error) {
 		console.error(`${logPrefix} ${filePath}:`, error);
-		await unlink(tmpPath).catch(() => {});
+		if (tmpPresent) await unlink(tmpPath).catch(() => {});
 		throw error;
 	}
 }

package/lib/index.d.ts

@@ -1,6 +1,8 @@
 import { writeJsonAtomic } from "./fs-atomic.js";
-import { HomeFileLockOptions, HomeFileLockTimeoutError, withHomeFileLock } from "./file-lock.js";
-import { SKIP_WRITE, SkipWrite, TransactStoreOptions, transactStore } from "./store-transaction.js";
+import { HomeFileLock, HomeFileLockLostError, HomeFileLockOptions, HomeFileLockOwner, HomeFileLockTimeoutError, withHomeFileLock } from "./file-lock.js";
+import { SKIP_WRITE, SkipWrite, StoreCache, TransactStoreOptions, createStoreCache, transactStore } from "./store-transaction.js";
+import { RecordStoreAdapter, RecordStoreAdapterOptions, RecordStoreMutate, createRecordStoreAdapter, readStoreText } from "./record-store.js";
+import { HomeFileLease, tryAcquireHomeFileLeaseSync } from "./file-lease.js";
 //#region src/index.d.ts
 /**
  * 解析 dsh home 根目录。
@@ -61,4 +63,4 @@ interface LegacyHomeMigrationResult {
  */
 declare function migrateLegacyTradingHome(options?: LegacyHomeMigrationOptions): LegacyHomeMigrationResult | null;
 //#endregion
-export { HOME_MIGRATION_MARKER, type HomeFileLockOptions, HomeFileLockTimeoutError, LegacyHomeMigrationOptions, LegacyHomeMigrationResult, SKIP_WRITE, type SkipWrite, TRADING_HOME_ENTRIES, type TransactStoreOptions, defaultDshHome, dshHomeDir, migrateLegacyTradingHome, transactStore, withHomeFileLock, writeJsonAtomic };
+export { HOME_MIGRATION_MARKER, type HomeFileLease, type HomeFileLock, HomeFileLockLostError, type HomeFileLockOptions, type HomeFileLockOwner, HomeFileLockTimeoutError, LegacyHomeMigrationOptions, LegacyHomeMigrationResult, type RecordStoreAdapter, type RecordStoreAdapterOptions, type RecordStoreMutate, SKIP_WRITE, type SkipWrite, type StoreCache, TRADING_HOME_ENTRIES, type TransactStoreOptions, createRecordStoreAdapter, createStoreCache, defaultDshHome, dshHomeDir, migrateLegacyTradingHome, readStoreText, transactStore, tryAcquireHomeFileLeaseSync, withHomeFileLock, writeJsonAtomic };

package/lib/index.js

@@ -1,6 +1,8 @@
 import { writeJsonAtomic } from "./fs-atomic.js";
-import { HomeFileLockTimeoutError, withHomeFileLock } from "./file-lock.js";
-import { SKIP_WRITE, transactStore } from "./store-transaction.js";
+import { tryAcquireHomeFileLeaseSync } from "./file-lease.js";
+import { HomeFileLockLostError, HomeFileLockTimeoutError, withHomeFileLock } from "./file-lock.js";
+import { SKIP_WRITE, createStoreCache, transactStore } from "./store-transaction.js";
+import { createRecordStoreAdapter, readStoreText } from "./record-store.js";
 import { cpSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
@@ -141,4 +143,4 @@ function migrateLegacyTradingHome(options = {}) {
 	};
 }
 //#endregion
-export { HOME_MIGRATION_MARKER, HomeFileLockTimeoutError, SKIP_WRITE, TRADING_HOME_ENTRIES, defaultDshHome, dshHomeDir, migrateLegacyTradingHome, transactStore, withHomeFileLock, writeJsonAtomic };
+export { HOME_MIGRATION_MARKER, HomeFileLockLostError, HomeFileLockTimeoutError, SKIP_WRITE, TRADING_HOME_ENTRIES, createRecordStoreAdapter, createStoreCache, defaultDshHome, dshHomeDir, migrateLegacyTradingHome, readStoreText, transactStore, tryAcquireHomeFileLeaseSync, withHomeFileLock, writeJsonAtomic };

package/lib/record-store.d.ts

@@ -0,0 +1,56 @@
+import { SkipWrite } from "./store-transaction.js";
+//#region src/record-store.d.ts
+/** mutate 的返回形态，与 {@link transactStore} 的 mutate 完全一致。 */
+type RecordStoreMutate<T> = (onDisk: T) => T | SkipWrite | Promise<T | SkipWrite>;
+interface RecordStoreAdapterOptions<T> {
+  /** 目标 JSON 文件。 */
+  readonly filePath: string;
+  /**
+   * 写失败的日志前缀，逐字透传给 {@link transactStore}（各 store 文案不同，属可观察行为）。
+   */
+  readonly logPrefix: string;
+  /**
+   * **纯读**：把文件读成文本。无文件（ENOENT）与读失败都以 `undefined` 上报，
+   * 由 decode 决定降级成什么。不得回传内存缓存，也不得借它发布缓存。
+   */
+  readonly readFromDisk: () => Promise<string | undefined>;
+  /**
+   * 文本 → 内存值：解析 + 校验 + 降级（坏 JSON / 形状不符 / 无文件的口径由各 store 决定，
+   * 领域类型与降级纪律都不出包）。
+   */
+  readonly decode: (text: string | undefined) => T;
+  /** 内存值 → 落盘形状（数组、Set、容器包裹皆可）。 */
+  readonly encode: (value: T) => unknown;
+  /** 等锁上限（毫秒），透传 {@link transactStore}。 */
+  readonly timeoutMs?: number;
+  /** 陈旧锁回收阈值（毫秒），透传 {@link transactStore}。 */
+  readonly staleMs?: number;
+}
+interface RecordStoreAdapter<T> {
+  /** 取当前新鲜值：磁盘签名未变时用缓存，变了（或没发布过签名）则重新纯读 + decode。 */
+  load(): Promise<T>;
+  /**
+   * 跨进程锁内：新鲜纯读 + decode → mutate → encode + 原子写 → **落盘成功后才** replace
+   * 缓存。落盘失败时抛出且缓存保持旧值（未确认的值绝不提前进入缓存）。
+   */
+  commit(mutate: RecordStoreMutate<T>): Promise<T>;
+}
+/**
+ * 纯读一个 store 文件为文本。
+ *
+ * - ENOENT（首启的正常路径）静默返回 `undefined`；
+ * - 其他读失败按 `errorMessage` 记一条 error 后同样返回 `undefined`（降级值由 decode 决定，
+ *   与各 store 原来的读盘口径逐字一致）；
+ * - 不做任何解析，也不发布缓存——调用链上唯一的发布点是 {@link RecordStoreAdapter.commit}
+ *   成功之后。
+ */
+declare function readStoreText(filePath: string, errorMessage: string): Promise<string | undefined>;
+/**
+ * 建一个文件版记录 store 的适配器：缓存 + 跨进程事务 + 「成功才发布」三件事一次装好。
+ *
+ * @param options - 文件路径、写失败日志前缀与三个回调（纯读 / decode / encode）。
+ * @returns {@link RecordStoreAdapter}：`load()` 供各 store 的 list/get 用，`commit()` 供写路径用。
+ */
+declare function createRecordStoreAdapter<T>(options: RecordStoreAdapterOptions<T>): RecordStoreAdapter<T>;
+//#endregion
+export { RecordStoreAdapter, RecordStoreAdapterOptions, RecordStoreMutate, createRecordStoreAdapter, readStoreText };

package/lib/record-store.js

@@ -0,0 +1,68 @@
+import { createStoreCache, transactStore } from "./store-transaction.js";
+import { readFile } from "node:fs/promises";
+//#region src/record-store.ts
+/**
+* 「记录 store 适配器」：把各包文件版 store 各自复制的同一段骨架收敛成一处——
+* **锁内新鲜读盘 → 事务写 → 落盘成功后才发布缓存**（{@link transactStore} 与
+* {@link createStoreCache} 的组合形态，2026-10-09 跨进程覆盖事故 + 2026-10-12
+* 读新鲜度两次修复的共享入口）。
+*
+* 分工（本模块刻意不认识任何领域类型，也不 import 任何业务包）：
+* - dsh-home 只拥有「怎么读、怎么写、什么时候发布缓存」的骨架；
+* - 三个回调由各 store 提供：{@link RecordStoreAdapterOptions.readFromDisk} 是
+*   **纯读**（把文件读成文本，不发布缓存、不就地改缓存对象），
+*   {@link RecordStoreAdapterOptions.decode} 把文本变成内存值（解析 + 校验 +
+*   **各自 store 的降级口径**），{@link RecordStoreAdapterOptions.encode} 把内存值
+*   变回落盘形状。
+* - 因此 knowledge 的作者别名归一、chart-activations 的 sanitizeInstance、holdings
+*   的三字段形状校验、tombstones 的 Set 形态、watchlist 的多文件形态，全部留在各包
+*   decode 里，逐字不变。
+*
+* 为什么读盘要拆成「纯读 + decode」两半：坏 JSON 与非 ENOENT 读失败在各 store 里都
+* 是同一条 catch 分支（同一条日志文案、同一个降级值），所以「读失败日志」由纯读一侧
+* 负责（{@link readStoreText}），「解析失败降级」由 decode 一侧负责，两半合起来与
+* 各 store 原来的单函数逐分支等价。
+*/
+/**
+* 纯读一个 store 文件为文本。
+*
+* - ENOENT（首启的正常路径）静默返回 `undefined`；
+* - 其他读失败按 `errorMessage` 记一条 error 后同样返回 `undefined`（降级值由 decode 决定，
+*   与各 store 原来的读盘口径逐字一致）；
+* - 不做任何解析，也不发布缓存——调用链上唯一的发布点是 {@link RecordStoreAdapter.commit}
+*   成功之后。
+*/
+async function readStoreText(filePath, errorMessage) {
+	try {
+		return await readFile(filePath, "utf8");
+	} catch (error) {
+		if (error.code !== "ENOENT") console.error(errorMessage, error);
+		return;
+	}
+}
+/**
+* 建一个文件版记录 store 的适配器：缓存 + 跨进程事务 + 「成功才发布」三件事一次装好。
+*
+* @param options - 文件路径、写失败日志前缀与三个回调（纯读 / decode / encode）。
+* @returns {@link RecordStoreAdapter}：`load()` 供各 store 的 list/get 用，`commit()` 供写路径用。
+*/
+function createRecordStoreAdapter(options) {
+	const { filePath, logPrefix, readFromDisk, decode, encode } = options;
+	const lockOptions = {
+		...options.timeoutMs !== void 0 ? { timeoutMs: options.timeoutMs } : {},
+		...options.staleMs !== void 0 ? { staleMs: options.staleMs } : {}
+	};
+	/** 新鲜读：纯读 + decode，不发布缓存；缓存与锁内重读共用同一入口。 */
+	const fresh = async () => decode(await readFromDisk());
+	const cache = createStoreCache(filePath, fresh);
+	return {
+		load: () => cache.load(),
+		async commit(mutate) {
+			const next = await transactStore(filePath, fresh, mutate, encode, logPrefix, lockOptions);
+			cache.replace(next);
+			return next;
+		}
+	};
+}
+//#endregion
+export { createRecordStoreAdapter, readStoreText };

package/lib/store-transaction.d.ts

@@ -13,8 +13,8 @@ interface TransactStoreOptions {
  * 在跨进程锁内读-改-写一份 JSON 表。
  *
  * @param filePath - 目标 JSON 文件
- * @param readFromDisk - **新鲜**读盘（不得回传内存缓存）；由各 store 提供 parse
- *   感知的读取，使坏形/坏 JSON 的降级口径与自身 load() 一致
+ * @param readFromDisk - **新鲜**读盘（不得回传内存缓存，也不得借它发布缓存）；由各
+ *   store 提供 parse 感知的读取，使坏形/坏 JSON 的降级口径与自身 load() 一致
  * @param mutate - 在锁内新鲜值上做本次修改；返回新内存值，或 {@link SKIP_WRITE}
  *   表示无变化不落盘
  * @param serialize - 新内存值 → 落盘形状（数组、按 id 为键的对象、容器包裹皆可）
@@ -22,5 +22,31 @@ interface TransactStoreOptions {
  * @returns 落盘后的当前值（SKIP_WRITE 时即锁内新鲜值）
  */
 declare function transactStore<T>(filePath: string, readFromDisk: () => Promise<T>, mutate: (onDisk: T) => T | SkipWrite | Promise<T | SkipWrite>, serialize: (value: T) => unknown, logPrefix: string, options?: TransactStoreOptions): Promise<T>;
+/**
+ * 跨实例读新鲜度缓存：进程内内存缓存 + 每次读前核对磁盘签名。
+ *
+ * 为什么不能只 `if (cache !== null) return cache`（2026-10-12 补强）：整表 store 的
+ * 缓存是「本实例上次读盘的值」，另一实例（桌面端/CLI）确认落盘的新行永远进不来，
+ * list() 会一直返回陈旧快照。此缓存每次 load() 先 stat 目标文件，签名（dev/ino/
+ * size/mtimeNs/ctimeNs）变了就重新读盘；因此「别人已确认的写」在下一次读取可见，
+ * 缓存只省重复读，不会永久命中。
+ *
+ * 写失败的发布纪律：只有 {@link transactStore} 成功返回后才 replace()；写失败时缓存
+ * 保持旧值，且 replace() 之后的下一次 load() 仍会核对磁盘签名——即使发布的值没真正
+ * 落盘也会被磁盘纠正，不会出现「缓存里有、盘上没有」。
+ */
+interface StoreCache<T> {
+  /** 取当前新鲜值：磁盘签名未变时用缓存，变了（或被 replace/invalidate）则重新读盘。 */
+  load(): Promise<T>;
+  /** 一次成功落盘后发布本次值；签名置为待核对，下次 load 仍以磁盘为准。 */
+  replace(value: T): void;
+  /** 丢弃缓存，下次 load 必定重新读盘。 */
+  invalidate(): void;
+}
+/**
+ * 建一个「每次读前核对磁盘签名」的缓存。readFromDisk 必须是**纯读**（不发布缓存、
+ * 不就地改缓存对象），这样写失败时未确认的值不会提前进入缓存。
+ */
+declare function createStoreCache<T>(filePath: string, readFromDisk: () => Promise<T>): StoreCache<T>;
 //#endregion
-export { SKIP_WRITE, SkipWrite, TransactStoreOptions, transactStore };
+export { SKIP_WRITE, SkipWrite, StoreCache, TransactStoreOptions, createStoreCache, transactStore };

package/lib/store-transaction.js

@@ -1,8 +1,10 @@
 import { writeJsonAtomic } from "./fs-atomic.js";
 import { withHomeFileLock } from "./file-lock.js";
+import { stat } from "node:fs/promises";
 //#region src/store-transaction.ts
 /**
-* 整表 JSON 的跨进程「锁内读 - 改 - 原子写」（2026-10-09 事故修复的共享入口）。
+* 整表 JSON 的跨进程「锁内读 - 改 - 原子写」（2026-10-09 事故修复的共享入口），
+* 以及跨实例读新鲜度缓存 {@link createStoreCache}（2026-10-12 补强）。
 *
 * 背景：下列 store 都是「进程内内存缓存 + 整表回写」，两个宿主进程共用同一
 * DSH_HOME 时后写者用自己那份陈旧快照覆盖先写者（last-writer-wins，静默丢数据；
@@ -12,13 +14,14 @@ import { withHomeFileLock } from "./file-lock.js";
 * 1. 取该文件的跨进程排他锁（{@link withHomeFileLock}）；
 * 2. 锁内**新鲜重读磁盘**（readFromDisk，不是进临界区前的缓存）；
 * 3. mutate 在这份新鲜值上做本次修改并返回新的内存值；
-* 4. tmp+rename 原子写落盘，返回值即调用方应缓存的当前值。
+* 4. **提交前复核锁仍归本实例**（临界区较长时锁可能已被回收/顶替），再 tmp+rename
+*    原子写落盘，返回值即调用方应缓存的当前值。
 *
 * 「读 - 改」整体在锁内，所以两个进程各自的**新增、删除**都不丢：后到者是在先到者的
 * 结果上继续改，而不是用陈旧快照覆盖。这是「先读回并合并双方数据」的具体形态，
 * 而不是「拒绝第二实例写」——本机桌面端与 CLI 长期共用同一 home，拒绝写会让第二
-* 实例完全存不了设置。等锁超时抛 {@link HomeFileLockTimeoutError}：那是明确失败，
-* 绝不静默按陈旧快照覆盖。
+* 实例完全存不了设置。等锁超时抛 {@link HomeFileLockTimeoutError}，提交前发现锁被
+* 顶替抛 {@link HomeFileLockLostError}：两种都是明确失败，绝不静默按陈旧快照覆盖。
 *
 * 合并粒度是条目（行表按 id、嵌套表按各自键）：同一条目被两个进程同时改时，后写者
 * 在该条目上的整条值胜出（不做字段级三方合并，见 note 的 Residue）。
@@ -41,8 +44,8 @@ function lockOptionsOf(options) {
 * 在跨进程锁内读-改-写一份 JSON 表。
 *
 * @param filePath - 目标 JSON 文件
-* @param readFromDisk - **新鲜**读盘（不得回传内存缓存）；由各 store 提供 parse
-*   感知的读取，使坏形/坏 JSON 的降级口径与自身 load() 一致
+* @param readFromDisk - **新鲜**读盘（不得回传内存缓存，也不得借它发布缓存）；由各
+*   store 提供 parse 感知的读取，使坏形/坏 JSON 的降级口径与自身 load() 一致
 * @param mutate - 在锁内新鲜值上做本次修改；返回新内存值，或 {@link SKIP_WRITE}
 *   表示无变化不落盘
 * @param serialize - 新内存值 → 落盘形状（数组、按 id 为键的对象、容器包裹皆可）
@@ -50,13 +53,56 @@ function lockOptionsOf(options) {
 * @returns 落盘后的当前值（SKIP_WRITE 时即锁内新鲜值）
 */
 async function transactStore(filePath, readFromDisk, mutate, serialize, logPrefix, options = {}) {
-	return withHomeFileLock(filePath, async () => {
+	return withHomeFileLock(filePath, async (lock) => {
 		const onDisk = await readFromDisk();
 		const next = await mutate(onDisk);
 		if (next === SKIP_WRITE) return onDisk;
+		await lock.assertOwned();
 		await writeJsonAtomic(filePath, serialize(next), logPrefix);
 		return next;
 	}, lockOptionsOf(options));
 }
+/**
+* 磁盘签名：路径不存在为 'missing'。stat 的其他失败给出永不匹配的签名，强制本次
+* 重新读盘——读盘自身的错误/降级口径由各 store 的 readFromDisk 决定，这里不引入
+* 新的读语义。
+*/
+async function fileSignature(filePath) {
+	try {
+		const info = await stat(filePath, { bigint: true });
+		return `${info.dev}:${info.ino}:${info.size}:${info.mtimeNs}:${info.ctimeNs}`;
+	} catch (error) {
+		if (error.code === "ENOENT") return "missing";
+		return `unavailable:${Date.now()}:${Math.random()}`;
+	}
+}
+/**
+* 建一个「每次读前核对磁盘签名」的缓存。readFromDisk 必须是**纯读**（不发布缓存、
+* 不就地改缓存对象），这样写失败时未确认的值不会提前进入缓存。
+*/
+function createStoreCache(filePath, readFromDisk) {
+	let entry;
+	return {
+		async load() {
+			const signature = await fileSignature(filePath);
+			if (entry !== void 0 && entry.signature !== void 0 && entry.signature === signature) return entry.value;
+			const value = await readFromDisk();
+			entry = {
+				value,
+				signature
+			};
+			return value;
+		},
+		replace(value) {
+			entry = {
+				value,
+				signature: void 0
+			};
+		},
+		invalidate() {
+			entry = void 0;
+		}
+	};
+}
 //#endregion
-export { SKIP_WRITE, transactStore };
+export { SKIP_WRITE, createStoreCache, transactStore };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dshtrading/dsh-home",
   "description": "dsh home 根目录解析（$DSH_HOME 环境变量感知，缺省 ~/.dsh，对齐宿主 dsh-home-paths 语义）——dsh-trading 各包 home 数据文件的唯一路径来源",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "type": "module",
   "main": "lib/index.js",
   "types": "./lib/index.d.ts",