dsh-local-telemetry 0.1.0

package/src/config.mjs

@@ -0,0 +1,199 @@
+/**
+ * dsh-local-telemetry — 配置解析（计划 §11）。
+ *
+ * 规则：
+ * - 解析失败 → 采用「关闭」这一安全默认，不猜测用户意图；
+ * - 未知键忽略（前向兼容），类型错误逐条记录；
+ * - 环境变量不参与配置（密钥不属于遥测配置）。
+ */
+
+import { homedir } from "node:os";
+import { readFileSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+
+export const DEFAULT_CONFIG = Object.freeze({
+  enabled: true,
+  store: "jsonl", // jsonl | sqlite
+  path: "~/.dsh/telemetry",
+  sample_rate: 1, // 0..1，按 trace 整体采样
+  errors_always_sample: true,
+  slow_request_ms: 10000,
+  capture_metadata: "none", // none | safe
+  hash_names: false,
+  retention_days: 7,
+  max_file_mb: 100,
+  flush_interval_ms: 1000,
+  batch_size: 100,
+  max_queue_events: 1000,
+  price_catalog: null, // 版本化价格目录 JSON 路径
+  redact_rules: [], // 用户自定义正则（source 字符串），只保留规则名计数
+});
+
+/** 资源预算（计划 §7.2）——作为上限参与校准，配置不能超出这些硬上限。 */
+export const BUDGET_LIMITS = Object.freeze({
+  max_event_bytes: 64 * 1024,
+  max_queue_events: 1000,
+  max_batch_size: 1000,
+  min_flush_interval_ms: 50,
+});
+
+export function expandHome(p) {
+  if (typeof p !== "string" || p.length === 0) return p;
+  if (p === "~") return homedir();
+  if (p.startsWith("~/") || p.startsWith("~\\")) return resolve(homedir(), p.slice(2));
+  return p;
+}
+
+export function resolveDataPath(p, cwd = process.cwd()) {
+  const expanded = expandHome(p);
+  return isAbsolute(expanded) ? expanded : resolve(cwd, expanded);
+}
+
+/**
+ * 解析时长：`500ms` / `10s` / `30m` / `1h` / `7d` / `30d` → 毫秒；
+ * 也接受 ISO 8601 时间戳或 epoch 毫秒数（返回绝对毫秒，relative=false）。
+ */
+export function parseDurationOrTimestamp(value, now = Date.now()) {
+  if (value === null || value === undefined) return null;
+  if (typeof value === "number" && Number.isFinite(value)) return { absolute: value, relative: false };
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  const rel = trimmed.match(/^(\d+(?:\.\d+)?)(ms|s|m|h|d)$/);
+  if (rel) {
+    const n = Number.parseFloat(rel[1]);
+    const unit = rel[2];
+    const mult = { ms: 1, s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 }[unit];
+    return { absolute: Math.round(n * mult), relative: true };
+  }
+  if (/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/.test(trimmed)) {
+    const t = Date.parse(trimmed.endsWith("Z") || /[+-]\d{2}:\d{2}$/.test(trimmed) ? trimmed : `${trimmed}Z`);
+    if (Number.isFinite(t)) return { absolute: t, relative: false };
+    return null;
+  }
+  if (/^\d{10,13}$/.test(trimmed)) {
+    const n = Number.parseInt(trimmed, 10);
+    return { absolute: n < 10_000_000_000 ? n * 1000 : n, relative: false };
+  }
+  return null;
+}
+
+/** 计算 --since / --until 的绝对毫秒边界。 */
+export function sinceUntilRange(since, until, now = Date.now()) {
+  const s = parseDurationOrTimestamp(since, now);
+  const u = parseDurationOrTimestamp(until, now);
+  const from = s ? (s.relative ? now - s.absolute : s.absolute) : null;
+  const to = u ? (u.relative ? now - u.absolute : u.absolute) : null;
+  return { from, to };
+}
+
+function checkType(errors, config, key, type) {
+  const value = config[key];
+  if (value === undefined || value === null) return;
+  const actual = Array.isArray(value) ? "array" : typeof value;
+  if (actual !== type) {
+    errors.push(`${key} must be ${type}, got ${actual}`);
+    config[key] = DEFAULT_CONFIG[key]; // 回退安全默认而不是留空
+  }
+}
+
+/**
+ * 合并默认值 + 文件配置 + CLI 覆盖，产出冻结后的有效配置。
+ * 任何类型错误不中止：剔除坏键、记录原因，保持安全默认。
+ */
+export function resolveConfig({ file, overrides } = {}) {
+  const errors = [];
+  let fileConfig = {};
+  if (file) {
+    if (typeof file === "string") {
+      try {
+        fileConfig = JSON.parse(readFileSync(file, "utf8"));
+        if (fileConfig === null || typeof fileConfig !== "object" || Array.isArray(fileConfig)) {
+          errors.push("config file must contain a JSON object");
+          fileConfig = {};
+        }
+      } catch (error) {
+        errors.push(`config file unreadable (${error.code ?? error.message})`);
+        fileConfig = {};
+      }
+    } else if (typeof file === "object") {
+      fileConfig = file;
+    }
+  }
+
+  const merged = { ...DEFAULT_CONFIG, ...fileConfig, ...(overrides ?? {}) };
+  for (const key of Object.keys(merged)) {
+    if (!(key in DEFAULT_CONFIG)) delete merged[key]; // 未知键忽略
+  }
+
+  checkType(errors, merged, "enabled", "boolean");
+  checkType(errors, merged, "store", "string");
+  checkType(errors, merged, "path", "string");
+  checkType(errors, merged, "hash_names", "boolean");
+  checkType(errors, merged, "errors_always_sample", "boolean");
+  checkType(errors, merged, "slow_request_ms", "number");
+  checkType(errors, merged, "retention_days", "number");
+  checkType(errors, merged, "max_file_mb", "number");
+  checkType(errors, merged, "flush_interval_ms", "number");
+  checkType(errors, merged, "batch_size", "number");
+  checkType(errors, merged, "max_queue_events", "number");
+  checkType(errors, merged, "price_catalog", "string");
+  checkType(errors, merged, "sample_rate", "number");
+  checkType(errors, merged, "capture_metadata", "string");
+  checkType(errors, merged, "redact_rules", "array");
+
+  if (!["jsonl", "sqlite"].includes(merged.store)) {
+    errors.push(`store must be "jsonl" or "sqlite", got ${JSON.stringify(merged.store)}`);
+    merged.store = DEFAULT_CONFIG.store;
+  }
+  if (!["none", "safe"].includes(merged.capture_metadata)) {
+    errors.push(`capture_metadata must be "none" or "safe", got ${JSON.stringify(merged.capture_metadata)}`);
+    merged.capture_metadata = "none";
+  }
+  if (typeof merged.sample_rate === "number") {
+    if (!Number.isFinite(merged.sample_rate) || merged.sample_rate < 0 || merged.sample_rate > 1) {
+      errors.push(`sample_rate must be within [0,1], got ${merged.sample_rate}`);
+      merged.sample_rate = DEFAULT_CONFIG.sample_rate;
+    }
+  }
+  for (const key of ["slow_request_ms", "retention_days", "max_file_mb", "flush_interval_ms", "batch_size", "max_queue_events"]) {
+    if (typeof merged[key] === "number" && (!Number.isFinite(merged[key]) || merged[key] < 0)) {
+      errors.push(`${key} must be a non-negative number`);
+      merged[key] = DEFAULT_CONFIG[key];
+    }
+  }
+  // 硬预算上限（§7.2）：配置超出时钳制并记录
+  merged.batch_size = Math.min(Math.round(merged.batch_size), BUDGET_LIMITS.max_batch_size);
+  merged.max_queue_events = Math.min(Math.round(merged.max_queue_events), BUDGET_LIMITS.max_queue_events);
+  merged.flush_interval_ms = Math.max(Math.round(merged.flush_interval_ms), BUDGET_LIMITS.min_flush_interval_ms);
+  if (Array.isArray(merged.redact_rules)) {
+    merged.redact_rules = merged.redact_rules
+      .filter((rule) => rule && typeof rule === "object" && typeof rule.name === "string" && typeof rule.pattern === "string")
+      .map((rule) => {
+        try {
+          return { name: rule.name, regex: new RegExp(rule.pattern) };
+        } catch {
+          errors.push(`redact_rules: invalid pattern for ${rule.name}`);
+          return null;
+        }
+      })
+      .filter(Boolean);
+  }
+
+  return { ok: errors.length === 0, errors, config: Object.freeze(merged) };
+}
+
+/** 读取 --config 指定的文件；文件不存在/损坏时按「关闭」这一安全默认处理。 */
+export function loadConfigFile(path) {
+  let raw;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch (error) {
+    return { ok: false, errors: [`config file unreadable (${error.code ?? error.message})`], config: { ...DEFAULT_CONFIG, enabled: false } };
+  }
+  const result = resolveConfig({ file: raw ? path : null });
+  if (!result.ok && result.config) {
+    // 解析失败 → 关闭（安全默认），保留错误说明
+    return { ok: false, errors: result.errors, config: { ...result.config, enabled: false } };
+  }
+  return result;
+}

package/src/cost.mjs

@@ -0,0 +1,118 @@
+/**
+ * dsh-local-telemetry — 成本模型（计划 §5）。
+ *
+ * 价格不入代码：来自版本化目录文件（currency / effective_at / models）。
+ * 只有 模型名、Token 用量、价格 三者齐备才计算；否则 cost=null 并给出原因，
+ * 绝不编造（§5.2）。
+ */
+
+import { readFileSync } from "node:fs";
+
+/**
+ * 加载价格目录。
+ * @returns {{ ok: boolean, errors: string[], catalog: object|null }}
+ */
+export function loadPriceCatalog(path) {
+  if (!path || typeof path !== "string") {
+    return { ok: false, errors: ["price_catalog not configured"], catalog: null };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    return { ok: false, errors: [`price catalog unreadable (${error.code ?? error.message})`], catalog: null };
+  }
+  const errors = [];
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return { ok: false, errors: ["price catalog must be a JSON object"], catalog: null };
+  }
+  if (typeof parsed.currency !== "string" || parsed.currency.length !== 3) errors.push("currency must be a 3-letter code");
+  if (typeof parsed.effective_at !== "string" || parsed.effective_at.length === 0) errors.push("effective_at is required");
+  if (typeof parsed.models !== "object" || parsed.models === null) errors.push("models is required");
+  else {
+    for (const [name, price] of Object.entries(parsed.models)) {
+      if (typeof price !== "object" || price === null) {
+        errors.push(`models.${name} must be an object`);
+        continue;
+      }
+      for (const field of ["input_per_million", "output_per_million"]) {
+        const value = price[field];
+        if (typeof value !== "number" || !Number.isFinite(value) || value < 0) errors.push(`models.${name}.${field} must be a non-negative number`);
+      }
+      if (price.cached_input_per_million !== undefined && price.cached_input_per_million !== null) {
+        const value = price.cached_input_per_million;
+        if (typeof value !== "number" || !Number.isFinite(value) || value < 0) errors.push(`models.${name}.cached_input_per_million must be a non-negative number`);
+      }
+    }
+  }
+  if (errors.length > 0) return { ok: false, errors, catalog: null };
+  return { ok: true, errors, catalog: parsed };
+}
+
+function priceFor(catalog, modelName) {
+  if (!catalog || typeof modelName !== "string" || modelName.length === 0) return null;
+  if (Object.prototype.hasOwnProperty.call(catalog.models, modelName)) return catalog.models[modelName];
+  // 带前缀的模型名（如 provider/name）回退到末段匹配
+  const tail = modelName.split("/").pop();
+  if (tail !== modelName && Object.prototype.hasOwnProperty.call(catalog.models, tail)) return catalog.models[tail];
+  return null;
+}
+
+/**
+ * 计算单事件成本。
+ * @returns {{ amount: number|null, currency: string|null, effective_at: string|null, missing: string[] }}
+ *   amount 为 null 时 missing 给出原因（model_missing / usage_missing / price_missing / catalog_missing）。
+ */
+export function computeCost({ model, usage, catalog }) {
+  if (!catalog) {
+    return { amount: null, currency: null, effective_at: null, missing: ["catalog_missing"] };
+  }
+  const modelName = typeof model === "object" && model !== null ? model.name : null;
+  if (!modelName || typeof modelName !== "string") {
+    return { amount: null, currency: catalog.currency, effective_at: catalog.effective_at, missing: ["model_missing"] };
+  }
+  if (typeof usage !== "object" || usage === null) {
+    return { amount: null, currency: catalog.currency, effective_at: catalog.effective_at, missing: ["usage_missing"] };
+  }
+  const input = usage.input_tokens;
+  const output = usage.output_tokens;
+  if (!Number.isInteger(input) || !Number.isInteger(output)) {
+    return { amount: null, currency: catalog.currency, effective_at: catalog.effective_at, missing: ["usage_missing"] };
+  }
+  const price = priceFor(catalog, modelName);
+  if (!price) {
+    return { amount: null, currency: catalog.currency, effective_at: catalog.effective_at, missing: ["price_missing"] };
+  }
+  const cached = Number.isInteger(usage.cached_input_tokens) ? usage.cached_input_tokens : 0;
+  const cachedPrice = typeof price.cached_input_per_million === "number" ? price.cached_input_per_million : price.input_per_million;
+  const amount =
+    (input / 1_000_000) * price.input_per_million +
+    (cached / 1_000_000) * cachedPrice +
+    (output / 1_000_000) * price.output_per_million;
+  return {
+    amount: Math.round(amount * 1e9) / 1e9, // 去浮点噪声，保留纳级精度
+    currency: catalog.currency,
+    effective_at: catalog.effective_at,
+    missing: [],
+  };
+}
+
+/** 聚合级成本汇总：逐事件计算并合并，缺失原因计数；无已计价事件时 amount 为 null。 */
+export function sumCosts(costResults) {
+  let amount = 0;
+  let pricedEvents = 0;
+  const missing = {};
+  for (const result of costResults) {
+    if (result.amount === null) {
+      for (const reason of result.missing) missing[reason] = (missing[reason] ?? 0) + 1;
+    } else {
+      amount += result.amount;
+      pricedEvents += 1;
+    }
+  }
+  return {
+    amount: pricedEvents > 0 ? Math.round(amount * 1e9) / 1e9 : null,
+    priced_events: pricedEvents,
+    missing,
+  };
+}

package/src/index.mjs

@@ -0,0 +1,20 @@
+/**
+ * dsh-local-telemetry — 公共库接口（exports 子路径 `dsh-local-telemetry/telemetry`）。
+ *
+ * 上层插件（dsh-change-impact / dsh-test-insight 等）与宿主集成代码从这里
+ * 引入；插件入口（plugin/index.js）只负责 skills 注册与关闭时 flush。
+ */
+
+export { SCHEMA_VERSION, EVENT_NAMES, TERMINAL_EVENTS, validateEvent, serializeEvent, deserializeEvent, newId, nowIsoUtc, toIsoUtc, MAX_EVENT_BYTES } from "./schema.mjs";
+export { DEFAULT_CONFIG, BUDGET_LIMITS, resolveConfig, loadConfigFile, parseDurationOrTimestamp, sinceUntilRange, resolveDataPath } from "./config.mjs";
+export { createRedactor, hashName, getOrCreateSalt, defaultPrivacy, SECRET_FIELDS } from "./privacy.mjs";
+export { createSampler, SAMPLING_STRATEGY } from "./sampling.mjs";
+export { createEventBusAdapter, createCapabilities, detectCapabilities } from "./adapter.mjs";
+export { createRecorder } from "./recorder.mjs";
+export { JsonlSink, utcDateOf } from "./sink-jsonl.mjs";
+export { createSqliteSink, sqliteAvailable, isSqliteSupported } from "./sink-sqlite.mjs";
+export { openStore, createJsonlStore, createSqliteStore, matchesFilters, isFailureEvent } from "./store.mjs";
+export { aggregateEvents, aggregateGrouped, pairSpans, slowTraceIds, buildTraceView, listRequestRows, percentile } from "./aggregate.mjs";
+export { loadPriceCatalog, computeCost, sumCosts } from "./cost.mjs";
+export { renderTextSummary, renderMarkdownReport, renderTraceText, renderGroupedText } from "./report.mjs";
+export { createTelemetryServer } from "./server.mjs";

package/src/privacy.mjs

@@ -0,0 +1,208 @@
+/**
+ * dsh-local-telemetry — 隐私与脱敏（计划 §6）。
+ *
+ * 原则：内容字段默认不存在（不是采集后再脱敏）；仅当 capture_metadata="safe"
+ * 时才对可选 metadata 执行脱敏，且只保留规则名与命中数量，不保存原文。
+ * 名称哈希使用数据目录内随机 salt（SHA-256 截断），稳定但不可直接还原。
+ */
+
+import { createHash, randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** 内置敏感字段名（计划 §6.2）。metadata 的键命中即整体丢弃该键。 */
+export const SECRET_FIELDS = Object.freeze([
+  "authorization",
+  "proxy-authorization",
+  "cookie",
+  "set-cookie",
+  "token",
+  "access_token",
+  "refresh_token",
+  "id_token",
+  "session_token",
+  "password",
+  "passwd",
+  "secret",
+  "client_secret",
+  "private_key",
+  "api_key",
+  "apikey",
+  "api-key",
+  "x-api-key",
+]);
+
+const SECRET_FIELDS_RE = new RegExp(`^(${SECRET_FIELDS.map((f) => f.replace(/[-]/g, "\\-")).join("|")})$`, "i");
+
+/** 字符串内嵌的 `字段名: 值` / `字段名=值` 形态（含 header、query 风格）。 */
+const INLINE_SECRET_RE = new RegExp(
+  `\\b(${SECRET_FIELDS.map((f) => f.replace(/-/g, "[-_]?")).join("|")})\\b\\s*[:=]\\s*["']?([A-Za-z0-9._~+/=\\-]{4,})["']?`,
+  "gi"
+);
+
+const BEARER_RE = /\b(?:bearer|basic|token)\s+[A-Za-z0-9._~+/=\-]{6,}/gi;
+/** URL userinfo 凭据：scheme://user:pass@host / scheme://token@host。 */
+const URL_USERINFO_RE = /\b([a-z][a-z0-9+.-]*:\/\/)([^\s/@:]+)?:([^\s/@]+)@/gi;
+const URL_USERINFO_TOKEN_RE = /\b([a-z][a-z0-9+.-]*:\/\/)(ghp_[A-Za-z0-9]+|[A-Za-z0-9]{20,})@/gi;
+/** URL query 中的敏感参数值。 */
+const URL_QUERY_SECRET_RE = /([?&#](?:token|access_token|refresh_token|api_key|apikey|secret|password|sig|signature|client_secret|session_id)=)[^\s&"#]+/gi;
+/** 绝对路径：Windows 盘符路径与常见 Unix 前缀。 */
+const ABSOLUTE_PATH_RE = /(?:[A-Za-z]:\\[^\s"',:;)]+(?:\\[^\s"',:;)]*)*)|(?:\/(?:home|Users|root|var|tmp|etc|opt|mnt|srv)\/[^\s"',:;)]+)/g;
+
+/**
+ * 创建脱敏器。
+ * @param {object} opts
+ * @param {Array<{name:string, regex:RegExp}>} opts.customRules  用户自定义规则
+ * @param {"basename"|"hash"|null} [opts.absolutePaths] 绝对路径处理策略（默认 basename）
+ * @param {string} [opts.salt] 名称哈希 salt；未提供时 hashName 抛错前会给出明确提示
+ */
+export function createRedactor({ customRules = [], absolutePaths = "basename", salt = null } = {}) {
+  const stats = new Map(); // ruleName -> count
+
+  function hit(rule) {
+    stats.set(rule, (stats.get(rule) ?? 0) + 1);
+  }
+
+  function redactAbsolutePath(value) {
+    return value.replace(ABSOLUTE_PATH_RE, (match) => {
+      hit("absolute_path");
+      if (absolutePaths === "hash" && salt) return hashName(match, salt);
+      const normalized = match.replace(/\\+/g, "/");
+      const base = normalized.split("/").filter(Boolean).pop() ?? match;
+      return base;
+    });
+  }
+
+  /** 对单个字符串执行全部内置 + 自定义规则。 */
+  function redactString(value) {
+    if (typeof value !== "string" || value.length === 0) return value;
+    let out = value;
+    for (const rule of customRules) {
+      out = out.replace(rule.regex, () => {
+        hit(rule.name);
+        return `[redacted:${rule.name}]`;
+      });
+    }
+    out = out.replace(URL_USERINFO_RE, (_m, scheme) => {
+      hit("url_credentials");
+      return `${scheme}[redacted:url_credentials]@`;
+    });
+    out = out.replace(URL_USERINFO_TOKEN_RE, (_m, scheme) => {
+      hit("url_credentials");
+      return `${scheme}[redacted:url_credentials]@`;
+    });
+    out = out.replace(URL_QUERY_SECRET_RE, (_m, prefix) => {
+      hit("url_query_token");
+      return `${prefix}[redacted:url_query_token]`;
+    });
+    out = out.replace(BEARER_RE, () => {
+      hit("authorization");
+      return "[redacted:authorization]";
+    });
+    out = out.replace(INLINE_SECRET_RE, (_m, field) => {
+      const name = String(field).toLowerCase().replace(/[-_]?key$/, "_key").replace(/-/g, "_");
+      hit(name);
+      return `${field}=[redacted:${name}]`;
+    });
+    if (absolutePaths) out = redactAbsolutePath(out);
+    return out;
+  }
+
+  /**
+   * 对可选 metadata 对象脱敏：敏感键整体丢弃；字符串值走 redactString；
+   * 数字/布尔保留（大小、计数类安全信息）。返回 { value, redactions, rules }。
+   */
+  function redactMetadata(metadata) {
+    if (metadata === null || metadata === undefined) return { value: null, redactions: 0, rules: [] };
+    if (typeof metadata !== "object" || Array.isArray(metadata)) {
+      return { value: null, redactions: 0, rules: [] };
+    }
+    const before = new Map(stats);
+    const out = {};
+    for (const [key, value] of Object.entries(metadata)) {
+      if (SECRET_FIELDS_RE.test(key)) {
+        hit(key.toLowerCase().replace(/-/g, "_"));
+        continue; // 整键丢弃，不保留占位值
+      }
+      if (typeof value === "string") {
+        out[key] = redactString(value);
+      } else if (typeof value === "number" || typeof value === "boolean" || value === null) {
+        out[key] = value;
+      } else {
+        // 嵌套结构不递归展开：只保留安全原语，防内容夹带
+        hit("nested_metadata_dropped");
+      }
+    }
+    // 仅统计本次调用命中的规则
+    const rules = [];
+    let redactions = 0;
+    for (const [name, count] of stats.entries()) {
+      const delta = count - (before.get(name) ?? 0);
+      if (delta > 0) {
+        redactions += delta;
+        rules.push(name);
+      }
+    }
+    return { value: out, redactions, rules };
+  }
+
+  function totalHits() {
+    let sum = 0;
+    for (const count of stats.values()) sum += count;
+    return sum;
+  }
+
+  function summarize(before, value) {
+    const redactions = totalHits() - before;
+    const rules = [];
+    for (const [name, count] of stats.entries()) {
+      if (count > 0) rules.push(name);
+    }
+    return { value, redactions, rules };
+  }
+
+  /** 汇总自创建以来的命中（用于 privacy 块）。 */
+  function summary() {
+    return { redactions: totalHits(), rules: [...new Set(stats.keys())].filter((k) => (stats.get(k) ?? 0) > 0) };
+  }
+
+  function statsSnapshot() {
+    return Object.fromEntries(stats.entries());
+  }
+
+  return { redactString, redactMetadata, summary, statsSnapshot };
+}
+
+/**
+ * 名称哈希：SHA-256(salt + name) 截断 16 hex，加 `h:` 前缀。
+ * 稳定（同 salt 同名同结果），不可直接还原。
+ */
+export function hashName(name, salt) {
+  if (typeof name !== "string" || name.length === 0) return name;
+  return `h:${createHash("sha256").update(`${salt}\u0000${name}`).digest("hex").slice(0, 16)}`;
+}
+
+/**
+ * 获取或创建数据目录内的哈希 salt（`.salt` 文件，32 hex）。
+ * 目录不存在时惰性创建。创建失败返回进程内临时 salt（稳定性降级，可用性优先）。
+ */
+export function getOrCreateSalt(dataDir) {
+  try {
+    if (!existsSync(dataDir)) mkdirSync(dataDir, { recursive: true });
+    const saltPath = join(dataDir, ".salt");
+    if (existsSync(saltPath)) {
+      const existing = readFileSync(saltPath, "utf8").trim();
+      if (/^[0-9a-f]{32}$/.test(existing)) return existing;
+    }
+    const salt = randomBytes(16).toString("hex");
+    writeFileSync(saltPath, `${salt}\n`, { mode: 0o600 });
+    return salt;
+  } catch {
+    return randomBytes(16).toString("hex");
+  }
+}
+
+/** 事件级 privacy 块默认值：内容未采集，无脱敏命中。 */
+export function defaultPrivacy() {
+  return { content_captured: false, redactions: 0, rules: [] };
+}