@youzan-cloud/zan-saas-cli 0.1.0-beta.3 → 0.1.0-beta.7

package/src/commands/system/shop-contracts.js

@@ -0,0 +1,66 @@
+'use strict';
+
+const object = properties => ({
+  type: 'object', additionalProperties: false, required: Object.keys(properties), properties
+});
+const id = { type: 'string', pattern: '^[1-9][0-9]*$', description: '正整数 ID 文本。' };
+const nullableText = { type: ['string', 'null'], description: '已核实的名称或时间；缺失为 null。' };
+const context = object({
+  userId: { type: 'string', minLength: 1, description: '已核实的账号 ID，不是客户或员工记录 ID。' },
+  hq: { ...id, description: '租户根组织 ID；单店取自身。' },
+  shopId: { ...id, description: '当前操作组织 ID，不自动代表全部连锁。' },
+  orgType: { enum: ['hq', 'shop'], description: '总部位置或受支持的非总部位置，不是详细组织角色。' }
+});
+const selection = object({
+  tenantRootKdtId: id, tenantName: nullableText, currentUnitKdtId: id, unitName: nullableText,
+  position: { enum: ['hq', 'shop'], description: '总部或非总部执行位置。' },
+  role: { type: ['integer', 'null'], minimum: 0, description: '有来源的组织角色：0单店、1总部、2001门店、2002网店；未知或未核实为null。' }
+});
+const binding = object({
+  mode: { enum: ['session', 'shared'], description: '宿主独立会话或本机共享选择。' },
+  sessionRef: { type: ['string', 'null'], description: '会话摘要短引用，共享模式为null。' },
+  state: { enum: ['uninitialized', 'needs_selection', 'ready', 'cleared', 'identity_pending', 'invalid'],
+    description: '分别为尚未初始化、待选店、就绪、已清除、待核实账号、无效。只有就绪的保存绑定提供上下文。' },
+  revision: { type: ['integer', 'null'], minimum: 1, maximum: Number.MAX_SAFE_INTEGER,
+    description: '绑定版本；无记录为null，冲突不覆盖较新选择。' },
+  origin: { enum: ['explicit', 'inherited', 'legacy_import', 'none'],
+    description: '明确选择、初始化继承、旧共享记录导入或无位置来源。' },
+  initializedAt: nullableText, selectedAt: nullableText
+});
+const nullable = value => ({ anyOf: [value, { type: 'null' }] });
+const effect = action => object({
+  action: { const: action },
+  currentChanged: { type: 'boolean', description: '本次是否改变当前会话绑定。' },
+  recentChanged: { type: 'boolean', description: '本次是否改变供新会话继承的位置。' }
+});
+const chosenOutput = action => object({
+  context: nullable(context), selection: nullable(selection), binding, effect: effect(action)
+});
+const notes = [
+  '上下文及本地保存不证明员工权限；账号、组织关系和业务授权分别核验。失败后不自动换店、换身份或重放。',
+  '会话模式由宿主逐次注入 ZAN_SAAS_SESSION_ID。已有会话不跟随其他会话，查询和恢复不更新最近位置。'
+];
+const switchInput = {
+  kdtId: id, sessionOnly: { type: 'boolean', description: '仅更新本会话，需要宿主会话标识；省略为false。' }
+};
+const optionalInput = properties => ({ ...object(properties), required: [] });
+const contracts = {
+  'shop.session.init': {
+    input: optionalInput({ resume: { type: 'boolean', description: '恢复原会话，缺记录则失败；省略为false。' } }),
+    output: chosenOutput('init'), notes: [...notes,
+      '显式初始化可核实当前账号并创建绑定。首次继承一次；无最近位置返回needs_selection；恢复已有记录不改时间和最近位置。']
+  },
+  'shop.unit.use': {
+    input: { ...object(switchInput), required: ['kdtId'] },
+    output: chosenOutput('use_unit'), notes: [...notes,
+      '需要已初始化会话及当前租户。只支持已核实的当前连锁总部、门店或网店，不改变租户根。']
+  },
+  'shop.resolve': {
+    input: { ...object({ kdtId: id, rootKdtId: { ...id, description: '目标所属根组织；省略时目标须为账号层根。' } }),
+      required: ['kdtId'] },
+    output: object({ context, selection, effect: effect('resolve'), revision: { type: 'null' } }),
+    notes: [...notes, '不保存当前位置。把返回context固定为本次任务每次调用的显式上下文；任务结束后丢弃。']
+  }
+};
+
+module.exports = { binding, selection, chosenOutput, contracts };

package/src/commands/system/shop.js

@@ -10,12 +10,31 @@ const {
 const { withSystemSchema } = require('./contracts');
 const { createPrinter, formatOption } = require('./printer');
 const { shopSelectionHint } = require('./shop-guidance');
+const sessions = require('../../identity/session-store');
+const locations = require('../../identity/shop-location');
+const { snapshotApiIdentity } = require('../../transport/api');
+const { withFileLock } = require('../../auth/credential-store');
 
 const idPattern = /^[1-9]\d*$/;
-const orgLabels = { hq: '总部', shop: '单店' };
+const orgLabels = { hq: '总部', shop: '非总部组织' };
 const roleLabel = role => account.shopRoles[role] || '未知类型';
 const envNote = '环境变量 ZAN_SAAS_CONTEXT 已设置，业务命令仍以它为准。';
 
+function sharedResult(value, savedEntry) {
+  const context = value.context;
+  const same = context && savedEntry && ['userId', 'hq', 'shopId', 'orgType']
+    .every(field => context[field] === savedEntry.context[field]);
+  return { ...value,
+    binding: { mode: 'shared', sessionRef: null, state: savedEntry ? 'ready' : 'needs_selection',
+      revision: null, origin: savedEntry ? 'explicit' : 'none',
+      initializedAt: null, selectedAt: savedEntry?.savedAt ?? null },
+    selection: context ? locations.selection(context, {
+      tenantName: same && context.hq === context.shopId ? savedEntry.shopName : null,
+      unitName: same ? savedEntry.shopName : null
+    }) : null
+  };
+}
+
 function positiveInteger(name, max = Number.MAX_SAFE_INTEGER) {
   return value => {
     if (!idPattern.test(value) || Number(value) > max) {
@@ -65,10 +84,11 @@ async function checkStaffStatuses(items, env, concurrency = 5) {
 // Hides the shops where the user's staff account is disabled, unless --all; total stays the server's count.
 async function listShops(options = {}, env = process.env) {
   const name = typeof options.name === 'string' ? options.name.trim() : '';
+  const { environment } = await snapshotApiIdentity(env);
   const page = await account.listShops({
     ...(name ? { name } : {}), pageNum: options.pageNo ?? 1, pageSize: options.pageSize ?? 20,
     lineOfBusinesses: options.lineOfBusiness ?? account.defaultLineOfBusinesses
-  }, env);
+  }, environment);
   // Staff filtering may hide the entire page; only the server's unfiltered total determines continuation.
   const hasMore = page.total === null ? null :
     BigInt(page.pageNum) * BigInt(page.pageSize) < BigInt(page.total);
@@ -77,7 +97,7 @@ async function listShops(options = {}, env = process.env) {
     windowLimitReached: hasMore !== false && page.pageNum === Number.MAX_SAFE_INTEGER });
   if (options.all) return { ...page, totalScope: 'before_staff_filter', hidden: 0,
     hiddenReason: null, nextStep: null, unchecked: [], uncheckedReason: null };
-  const checks = await checkStaffStatuses(page.items, env);
+  const checks = await checkStaffStatuses(page.items, environment);
   const items = page.items.filter((_, index) => checks[index].status !== account.staffStatuses.disabled);
   const unchecked = page.items.filter((_, index) => checks[index].error).map(item => item.kdtId);
   const failed = checks.find(check => check.error);
@@ -92,12 +112,15 @@ async function listShops(options = {}, env = process.env) {
 }
 
 // Confirms the shop through the user's own shop list before saving it as the context.
-async function useShop(kdtId, env = process.env) {
+async function useShop(kdtId, env = process.env, options = {}, explicitContext) {
+  if (sessions.sessionId(env)) return locations.select(kdtId, options, env, explicitContext);
+  if (options.sessionOnly) throw sessions.fail('session_missing', '--session-only 需要宿主会话标识。');
   if (typeof kdtId !== 'string' || !idPattern.test(kdtId) || !Number.isSafeInteger(Number(kdtId))) {
     throw new Error('kdtId 必须是正整数店铺 ID。');
   }
-  const user = await account.whoami(env);
-  const page = await account.listShops({ includeKdtIds: [kdtId], pageNum: 1, pageSize: 1 }, env);
+  const actor = await locations.identify(env);
+  const user = actor.user;
+  const page = await account.listShops({ includeKdtIds: [kdtId], pageNum: 1, pageSize: 1 }, actor.pinned);
   const shop = page.items.find(item => item.kdtId === kdtId);
   if (!shop) {
     throw new Error(`当前账号下没有可选店铺 ${kdtId}。执行 zan-saas shop list 查看可选店铺。`);
@@ -106,28 +129,54 @@ async function useShop(kdtId, env = process.env) {
     throw new Error(`店铺 ${kdtId} 是${roleLabel(shop.shopRole)}，暂时只能选择总部或单店。`);
   }
   // A failed check does not block: the business gateway still verifies the user against the shop.
-  const status = await account.staffStatus(kdtId, env).catch(() => null);
+  const status = await account.staffStatus(kdtId, actor.pinned).catch(() => null);
   if (status === account.staffStatuses.disabled) {
     throw new Error(`你在店铺 ${kdtId} 的员工账号已停用，不能选择。`);
   }
-  const context = saveContext({ userId: user.userId, hq: kdtId, shopId: kdtId, orgType: shop.orgType },
-    { shopName: shop.shopName }, env);
+  const context = await withFileLock(env, async () => {
+    locations.assertIdentity(actor, env);
+    return saveContext({ userId: user.userId, hq: kdtId, shopId: kdtId, orgType: shop.orgType },
+      { shopName: shop.shopName }, env);
+  });
   return { context, shopName: shop.shopName, overriddenByEnv: Boolean(env.ZAN_SAAS_CONTEXT) };
 }
 
-function currentShop(env = process.env) {
+function currentShop(env = process.env, explicitContext) {
+  if (sessions.sessionId(env)) {
+    const snapshot = sessions.snapshot(env);
+    const location = snapshot.binding?.location;
+    const saved = location ? { context: location.context, shopName: locations.displayName(location) } : null;
+    const source = explicitContext !== undefined ? 'program' :
+      env.ZAN_SAAS_CONTEXT ? 'env' : saved ? 'saved' : 'missing';
+    const state = readContext(source === 'program' ? explicitContext :
+      source === 'env' ? env.ZAN_SAAS_CONTEXT : location?.context);
+    const context = state.context ?? null;
+    return { source, status: state.status, context, saved, requestShopId: requestShopIdOf(env),
+      binding: sessions.publicBinding(snapshot),
+      selection: context ? (location && ['userId', 'hq', 'shopId', 'orgType']
+        .every(field => context[field] === location.context[field])
+        ? location.selection : locations.selection(context)) : null };
+  }
   const savedEntry = readSavedContext(env);
   const saved = savedEntry ? { context: savedEntry.context, shopName: savedEntry.shopName } : null;
   const requestShopId = requestShopIdOf(env);
-  if (env.ZAN_SAAS_CONTEXT) {
-    const state = readContext(env.ZAN_SAAS_CONTEXT);
-    return { source: 'env', status: state.status, context: state.context ?? null, saved, requestShopId };
+  if (explicitContext !== undefined || env.ZAN_SAAS_CONTEXT) {
+    const state = readContext(explicitContext !== undefined ? explicitContext : env.ZAN_SAAS_CONTEXT);
+    return sharedResult({ source: explicitContext !== undefined ? 'program' : 'env',
+      status: state.status, context: state.context ?? null, saved, requestShopId }, savedEntry);
   }
-  return saved ? { source: 'saved', status: 'ready', context: saved.context, saved, requestShopId } :
-    { source: 'missing', status: 'missing', context: null, saved: null, requestShopId };
+  return sharedResult(saved ? { source: 'saved', status: 'ready', context: saved.context, saved, requestShopId } :
+    { source: 'missing', status: 'missing', context: null, saved: null, requestShopId }, savedEntry);
 }
 
-function clearShop(env = process.env) {
+function clearShop(env = process.env, options = {}, explicitContext) {
+  if (sessions.sessionId(env)) {
+    locations.rejectOverride(env, explicitContext);
+    const effect = sessions.clear(options, env);
+    return { ...effect, server: oauthConfig(env).server,
+      binding: sessions.publicBinding(sessions.snapshot(env)) };
+  }
+  if (options.recent) throw sessions.fail('session_missing', '--recent 需要宿主会话标识。');
   return { cleared: deleteContext(env), server: oauthConfig(env).server };
 }
 
@@ -154,42 +203,71 @@ const text = {
     if (value.items.some(item => item.orgType)) lines.push(shopSelectionHint);
     return lines.join('\n');
   },
-  use: value => `${value.overriddenByEnv ? '已保存店铺' : '已切换到店铺'} ${describe(value.context, value.shopName)}。` +
+  use: value => value.effect
+    ? `已切换到店铺 ${locations.displayName(value) || value.context.shopId}。\n` +
+      `${value.effect.recentChanged ? '已更新供新会话继承的位置。' : '其他会话保持各自位置。'}\n确认当前店铺：zan-saas shop current`
+    : `${value.overriddenByEnv ? '已保存店铺' : '已切换到店铺'} ${describe(value.context, value.shopName)}。` +
     (value.overriddenByEnv ? `\n${envNote}` : '') +
     '\n确认当前店铺：zan-saas shop current',
   current: value => {
+    if (value.binding?.mode === 'session') {
+      const name = value.selection && locations.displayName({ selection: value.selection });
+      const states = { uninitialized: '尚未初始化', identity_pending: '当前账号尚未核实',
+        needs_selection: '尚未选择店铺', cleared: '已清除选择', invalid: '记录无效', ready: '就绪' };
+      return `${value.context ? `当前店铺：${name || value.context.shopId}` : '当前没有有效店铺。'}\n` +
+        `会话状态：${states[value.binding.state]}；位置来源：${value.source}。` +
+        (value.source === 'env' || value.source === 'program' ? '\n显式上下文覆盖保存的位置。' : '') +
+        (value.requestShopId ? `\n请求店铺头覆盖：${value.requestShopId}，具体目标须按命令核验。` : '');
+    }
     const requestNote = value.requestShopId
       ? `\n环境变量 ZAN_SAAS_KDT_ID 设置为 ${value.requestShopId}；具体请求店铺以所用命令和目标参数为准。`
       : '';
-    if (value.source === 'env') {
+    if (value.source === 'env' || value.source === 'program') {
       const head = value.status === 'ready'
-        ? `当前上下文来自环境变量 ZAN_SAAS_CONTEXT（kdtId ${value.context.shopId}，${orgLabels[value.context.orgType]}）。`
+        ? `当前上下文来自${value.source === 'env' ? '环境变量 ZAN_SAAS_CONTEXT' : '程序注入'}（kdtId ${value.context.shopId}，${orgLabels[value.context.orgType]}）。`
         : '环境变量 ZAN_SAAS_CONTEXT 无效，业务命令会拒绝执行。';
       return `${value.saved ? `${head}\n已保存的店铺 ${describe(value.saved.context, value.saved.shopName)} 被它覆盖。` : head}${requestNote}`;
     }
     if (value.source === 'saved') {
-      return `当前店铺：${describe(value.context, value.saved.shopName)}${requestNote}\n${shopSelectionHint}`;
+      return `当前店铺：${describe(value.context, value.saved.shopName)}${requestNote}\n${shopSelectionHint}\n当前使用本机共享选店，其他会话切店可能影响后续调用。`;
     }
     return `未选择店铺。${requestNote}\n${shopSelectionHint}`;
   },
-  clear: value => (value.cleared ? '已清除保存的店铺。' : '没有保存的店铺。')
+  clear: value => (value.cleared ? '已清除保存的店铺。' : '没有保存的店铺。') +
+    (value.binding ? '\n本会话保留清除状态，不会自动继承最近位置。' : ''),
+  init: value => value.context
+    ? `本会话当前店铺：${locations.displayName(value) || value.context.shopId}。`
+    : '本会话已初始化，请明确选择店铺。',
+  resolve: value => `本次目标：${locations.displayName(value) || value.context.shopId}。\n当前位置和最近位置均未改变。`
 };
 const printer = createPrinter(text);
 
 const defaults = {
-  list: options => listShops(options), use: kdtId => useShop(kdtId), current: () => currentShop(),
-  clear: () => clearShop(), currentShopId: () => shopIdOf(process.env)
+  list: options => listShops(options), use: (kdtId, options) => useShop(kdtId, process.env, options),
+  current: () => currentShop(), clear: options => clearShop(process.env, options),
+  init: options => locations.initialize(options),
+  unit: (kdtId, options) => locations.select(kdtId, { ...options, unit: true }),
+  resolve: (kdtId, options) => locations.resolve(kdtId, options),
+  currentShopId: () => shopIdOf(process.env)
 };
 
-function createShopCommand(impl = defaults) {
+function createShopCommand(impl, { context } = {}) {
+  impl ||= { ...defaults,
+    use: (kdtId, options) => useShop(kdtId, process.env, options, context),
+    unit: (kdtId, options) => locations.select(kdtId, { ...options, unit: true }, process.env, context),
+    current: () => currentShop(process.env, context),
+    clear: options => clearShop(process.env, options, context) };
   const shop = new Command('shop').description('查看可用店铺并设置当前店铺')
     .addHelpText('after', `
-登录成功后，首次选店或切换店铺使用同一流程，无需重新登录：
+登录成功后查看当前位置，再按本次意图选路，无需重新登录：
+  会话首次使用：zan-saas shop session init；恢复时加 --resume
   1. 查看可选店铺：zan-saas shop list
   2. 用户选定目标后：zan-saas shop use <kdtId>
   3. 确认当前店铺：zan-saas shop current
 将 <kdtId> 替换为目标店铺 ID；店铺较多时可用 shop list --name <keyword> 查找。
 浏览器中切换店铺不会改变 CLI 保存的选择。
+连锁内切换组织：zan-saas shop unit use <kdtId>
+临时查询其他店铺：zan-saas shop resolve <kdtId>，使用返回的 context 执行本次任务。
 ZAN_SAAS_CONTEXT 会覆盖保存的店铺，切换后以 shop current 显示的实际来源为准。
 `);
   withSystemSchema(shop.command('list')
@@ -216,21 +294,44 @@ windowLimitReached 为 true 表示达到 CLI 可表示的页码上限，请缩
   withSystemSchema(shop.command('use')
     .description('选择当前用户的店铺并保存为上下文')
     .argument('<kdtId>', 'shop list 返回的总部或单店 kdtId')
+    .option('--session-only', '只改变本会话，不更新新会话继承的位置')
     .addOption(formatOption())
     .addHelpText('after', `
 先确认店铺属于当前账号，再把 userId、hq、shopId、orgType 保存到本地；业务命令随后用它选择店铺。
 已有有效上下文时沿用当前店铺；用户按店名明确选择且唯一匹配，或确认候选后，使用对应 kdtId 执行；本地上下文不是业务接口授权证明。
 环境变量 ZAN_SAAS_CONTEXT 设置时优先于保存的店铺。
 `)
-    .action(async (kdtId, options) => { printer('use', options.format)(await impl.use(kdtId)); }), 'shop.use');
+    .action(async (kdtId, options) => { printer('use', options.format)(await impl.use(kdtId, options)); }), 'shop.use');
   withSystemSchema(shop.command('current')
     .description('查看业务命令使用的店铺上下文，不访问网络')
     .addOption(formatOption())
     .action(options => { printer('current', options.format)(impl.current()); }), 'shop.current');
   withSystemSchema(shop.command('clear')
     .description('清除本机保存的店铺上下文，不访问网络')
+    .option('--recent', '同时清除供新会话继承的位置；需要会话模式')
+    .addOption(formatOption())
+    .action(options => { printer('clear', options.format)(impl.clear(options)); }), 'shop.clear');
+  const session = shop.command('session').description('初始化或恢复宿主会话的选店记录');
+  withSystemSchema(session.command('init')
+    .description('首次继承最近位置；已有会话保持自己的选择')
+    .option('--resume', '恢复原会话；记录缺失时失败，不重新继承')
+    .addOption(formatOption())
+    .action(async options => printer('init', options.format)(await impl.init(options))), 'shop.session.init');
+  const unit = shop.command('unit').description('切换当前连锁内的操作组织');
+  withSystemSchema(unit.command('use')
+    .description('保留当前连锁根，切换到已核实的门店、网店或总部')
+    .argument('<kdtId>', '当前连锁内目标组织的正整数 ID')
+    .option('--session-only', '只改变本会话，不更新新会话继承的位置')
+    .addOption(formatOption())
+    .action(async (kdtId, options) => printer('use', options.format)(await impl.unit(kdtId, options))),
+  'shop.unit.use');
+  withSystemSchema(shop.command('resolve')
+    .description('核实本次临时目标并返回上下文，不改变保存的位置')
+    .argument('<kdtId>', '目标店铺根或组织的正整数 ID')
+    .option('--root-kdt-id <id>', '目标所属连锁根 ID；省略时目标须为账号层根')
     .addOption(formatOption())
-    .action(options => { printer('clear', options.format)(impl.clear()); }), 'shop.clear');
+    .action(async (kdtId, options) => printer('resolve', options.format)(await impl.resolve(kdtId, options))),
+  'shop.resolve');
   return shop;
 }
 

package/src/identity/context-store.js

@@ -1,7 +1,8 @@
 'use strict';
 
 const { oauthConfig } = require('../auth/config');
-const { readStore, storePath, writeStore } = require('../auth/credential-store');
+const { storePath } = require('../auth/credential-store');
+const { readFileStore, updateFileStore } = require('./file-store');
 const { createContext, readContext } = require('./context');
 
 const fileName = 'context.json';
@@ -12,7 +13,7 @@ function contextPath(env = process.env) {
 
 // The selected shop is kept per oauth origin, like the credential it was chosen with.
 function readSavedContext(env = process.env) {
-  const entry = readStore(fileName, env)[oauthConfig(env).server];
+  const entry = readFileStore(contextPath(env))[oauthConfig(env).server];
   const state = readContext(entry?.context);
   if (state.status !== 'ready') return null;
   return Object.freeze({
@@ -25,24 +26,27 @@ function readSavedContext(env = process.env) {
 function saveContext(input, { shopName } = {}, env = process.env) {
   const context = createContext(input);
   const { server } = oauthConfig(env);
-  const data = readStore(fileName, env);
-  data[server] = { context, ...(shopName ? { shopName } : {}), savedAt: new Date().toISOString() };
-  writeStore(fileName, data, env);
+  updateFileStore(contextPath(env), data => {
+    data[server] = { context, ...(shopName ? { shopName } : {}), savedAt: new Date().toISOString() };
+  });
   return context;
 }
 
 function deleteContext(env = process.env) {
   const { server } = oauthConfig(env);
-  const data = readStore(fileName, env);
-  if (!Object.hasOwn(data, server)) return false;
-  delete data[server];
-  writeStore(fileName, data, env);
-  return true;
+  return updateFileStore(contextPath(env), data => {
+    if (!Object.hasOwn(data, server)) return false;
+    delete data[server];
+    return true;
+  });
 }
 
 // ZAN_SAAS_CONTEXT wins, even when invalid; otherwise the shop chosen with `shop use`.
 function contextInput(env = process.env) {
   if (env.ZAN_SAAS_CONTEXT) return env.ZAN_SAAS_CONTEXT;
+  if (env.ZAN_SAAS_SESSION_ID !== undefined) {
+    return require('./session-store').sessionContext(env);
+  }
   try {
     return readSavedContext(env)?.context;
   } catch {

package/src/identity/file-store.js

@@ -0,0 +1,147 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { createHash, randomUUID } = require('node:crypto');
+
+const pause = new Int32Array(new SharedArrayBuffer(4));
+const digest = text => createHash('sha256').update(text).digest('hex');
+
+function reclaim(lock, previous) {
+  const guard = `${lock}.reclaim`;
+  let fd;
+  try { fd = fs.openSync(guard, 'wx', 0o600); }
+  catch (error) {
+    if (error.code === 'EEXIST') return false;
+    throw storageError();
+  }
+  try {
+    if (readText(lock) !== previous) return false;
+    fs.unlinkSync(lock);
+    return true;
+  } finally {
+    fs.closeSync(fd);
+    fs.unlinkSync(guard);
+  }
+}
+
+function storageError(reason = 'context_store_invalid') {
+  const error = new Error(reason === 'context_lock_timeout'
+    ? '选店记录正在被其他调用更新，请稍后核对当前位置。'
+    : '选店记录损坏或无法读取，请核对本机上下文文件；未回退到其他店铺。');
+  error.diagnosticReason = reason;
+  return error;
+}
+
+function readText(filename) {
+  try {
+    const fd = fs.openSync(filename, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+    try {
+      if (!fs.fstatSync(fd).isFile()) throw storageError();
+      return fs.readFileSync(fd, 'utf8');
+    } finally { fs.closeSync(fd); }
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw storageError();
+  }
+}
+
+function withLock(filename, action) {
+  const lock = `${filename}.lock`;
+  const started = Date.now();
+  const owner = JSON.stringify({ pid: process.pid, nonce: randomUUID() });
+  let fd;
+  for (;;) {
+    try {
+      fd = fs.openSync(lock, 'wx', 0o600);
+      fs.writeFileSync(fd, owner);
+      break;
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw storageError();
+      const previous = readText(lock);
+      try {
+        const { pid } = JSON.parse(previous);
+        if (Number.isSafeInteger(pid) && pid > 0) {
+          try { process.kill(pid, 0); }
+          catch (dead) {
+            if (dead.code === 'ESRCH' && readText(lock) === previous) {
+              if (reclaim(lock, previous)) continue;
+            }
+          }
+        }
+      } catch { /* An incomplete lock is never stolen from a live writer. */ }
+      if (Date.now() - started >= 5000) throw storageError('context_lock_timeout');
+      Atomics.wait(pause, 0, 0, 10);
+    }
+  }
+  try { return action(); }
+  finally {
+    fs.closeSync(fd);
+    if (readText(lock) === owner) fs.unlinkSync(lock);
+  }
+}
+
+function parse(text) {
+  try {
+    const value = JSON.parse(text);
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw storageError();
+    return value;
+  } catch { throw storageError(); }
+}
+
+function readUnlocked(filename) {
+  const pending = readText(`${filename}.journal`);
+  if (pending?.endsWith('\n')) {
+    const record = parse(pending);
+    if (typeof record.payload !== 'string' || digest(record.payload) !== record.sha256) {
+      throw storageError();
+    }
+    return parse(record.payload);
+  }
+  const text = readText(filename);
+  return text === null ? {} : parse(text);
+}
+
+// Keep the existing inode: permissions granted to a file remain attached to that file.
+function rewrite(filename, text) {
+  let fd;
+  try {
+    fd = fs.openSync(filename, fs.constants.O_RDWR | fs.constants.O_CREAT |
+      (fs.constants.O_NOFOLLOW || 0), 0o600);
+    if (!fs.fstatSync(fd).isFile()) throw storageError();
+    const bytes = Buffer.from(text);
+    let offset = 0;
+    while (offset < bytes.length) {
+      offset += fs.writeSync(fd, bytes, offset, bytes.length - offset, offset);
+    }
+    fs.ftruncateSync(fd, bytes.length);
+    fs.fsyncSync(fd);
+    fs.fchmodSync(fd, 0o600);
+  } finally { if (fd !== undefined) fs.closeSync(fd); }
+}
+
+function readFileStore(filename) {
+  if (!fs.existsSync(path.dirname(filename))) return {};
+  return withLock(filename, () => readUnlocked(filename));
+}
+
+function updateFileStore(filename, update) {
+  fs.mkdirSync(path.dirname(filename), { recursive: true, mode: 0o700 });
+  return withLock(filename, () => {
+    const data = readUnlocked(filename);
+    const result = update(data);
+    const payload = `${JSON.stringify(data, null, 2)}\n`;
+    // Finish a previously committed rewrite before reusing its journal.
+    if (readText(`${filename}.journal`)?.endsWith('\n')) {
+      rewrite(filename, `${JSON.stringify(readUnlocked(filename), null, 2)}\n`);
+    }
+    rewrite(`${filename}.journal`, '');
+    // A durable redo record is the commit point. Readers can use it after an interrupted rewrite.
+    rewrite(`${filename}.journal`, `${JSON.stringify({ payload, sha256: digest(payload) })}\n`);
+    rewrite(filename, payload);
+    rewrite(`${filename}.journal`, '');
+    return result;
+  });
+}
+
+module.exports = { digest, readFileStore, updateFileStore, storageError };