@h-ai/core 1.0.0-beta.2 → 1.0.0-beta.20

package/dist/node.js

@@ -1,13 +1,13 @@
-import { installRequestLocales, installRequestContext, createCore, i18n, err, HaiConfigError, ok, RequestAccessConfigSchema, RequestAccessPolicySchema, AccessConditionSchema, requestContext, sanitize, emitLogRecord, sanitizeLogFields, typeUtils, CoreConfigSchema } from './chunk-BEGTB6GL.js';
-export { AccessConditionSchema, CoreConfigSchema, EnvSchema, HaiCommonError, HaiConfigError, LogFormatSchema, LogLevelSchema, LoggingConfigSchema, RequestAccessConfigSchema, RequestAccessPolicySchema, TrustedProxiesSchema, err, ok } from './chunk-BEGTB6GL.js';
+import { installRequestLocales, installRequestContext, createCore, i18n, err, HaiConfigError, ok, RequestAccessConfigSchema, RequestAccessPolicySchema, AccessConditionSchema, requestContext, sanitize, emitLogRecord, sanitizeLogFields, CoreConfigSchema } from './chunk-WU6HUTBO.js';
+export { AccessConditionSchema, CoreConfigSchema, EnvSchema, HaiCommonError, HaiConfigError, LogFormatSchema, LogLevelSchema, LoggingConfigSchema, RequestAccessConfigSchema, RequestAccessPolicySchema, TrustedProxiesSchema, err, ok } from './chunk-WU6HUTBO.js';
 import { AsyncLocalStorage } from 'async_hooks';
 import { Buffer } from 'buffer';
 import { timingSafeEqual } from 'crypto';
 import { existsSync, readFileSync, openSync, constants, fstatSync, readSync, closeSync, readdirSync, watch } from 'fs';
-import path, { join } from 'path';
+import path, { join, resolve, basename, dirname } from 'path';
 import { BlockList, isIP } from 'net';
 import { networkInterfaces } from 'os';
-import process3 from 'process';
+import process4 from 'process';
 import { parse } from 'yaml';
 import { parseEnv } from 'util';
 import { execSync } from 'child_process';
@@ -36,13 +36,14 @@ function addAddress(list, entry) {
     return;
   }
   const bits = Number(prefix);
-  if (!/^\d+$/.test(prefix) || bits < 0 || bits > (family === 4 ? 32 : 128))
+  if (!/^\d+$/.test(prefix) || bits < 0 || bits > (family === 4 ? 32 : 128)) {
     throw new Error("Invalid CIDR prefix");
+  }
   list.addSubnet(address, bits, type);
 }
 function createClientIpResolver(trustedProxies = "auto") {
-  const entries = trustedProxies === "auto" ? process3.env.HAI_DEPLOY_PRIVATE_PROXY === "1" ? Object.values(networkInterfaces()).flatMap((interfaces) => interfaces?.filter((value) => !value.internal && value.cidr && !value.cidr.includes("%")).map((value) => value.cidr) ?? []) : [] : trustedProxies;
-  if (trustedProxies === "auto" && process3.env.HAI_DEPLOY_PRIVATE_PROXY === "1" && !entries.length)
+  const entries = trustedProxies === "auto" ? process4.env.HAI_DEPLOY_PRIVATE_PROXY === "1" ? Object.values(networkInterfaces()).flatMap((interfaces) => interfaces?.filter((value) => !value.internal && value.cidr && !value.cidr.includes("%")).map((value) => value.cidr) ?? []) : [] : trustedProxies;
+  if (trustedProxies === "auto" && process4.env.HAI_DEPLOY_PRIVATE_PROXY === "1" && !entries.length)
     throw new Error("Private proxy mode requires an isolated container network");
   const proxies = new BlockList();
   for (const entry of entries)
@@ -73,8 +74,22 @@ function createClientIpResolver(trustedProxies = "auto") {
   };
 }
 function timeReader(timezone) {
-  const formatter = new Intl.DateTimeFormat("en-US", { timeZone: timezone, weekday: "short", hour: "2-digit", minute: "2-digit", hourCycle: "h23" });
-  const weekdays = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"];
+  const formatter = new Intl.DateTimeFormat("en-US", {
+    timeZone: timezone,
+    weekday: "short",
+    hour: "2-digit",
+    minute: "2-digit",
+    hourCycle: "h23"
+  });
+  const weekdays = [
+    "Mon",
+    "Tue",
+    "Wed",
+    "Thu",
+    "Fri",
+    "Sat",
+    "Sun"
+  ];
   let lastMinute = Number.NaN;
   let local;
   return (now) => {
@@ -120,7 +135,7 @@ function createConditionCheck(input) {
   const condition = AccessConditionSchema.parse(input);
   return compileCondition(condition, condition.windows.length ? timeReader(condition.timezone) : void 0);
 }
-function loadPolicy(input = false, baseDirectory = process3.cwd()) {
+function loadPolicy(input = false, baseDirectory = process4.cwd()) {
   const config2 = RequestAccessConfigSchema.parse(input);
   if (config2 === false || !("file" in config2))
     return config2;
@@ -180,8 +195,12 @@ function normalizeRequestPath(value) {
 }
 function createRequestCheck(input = false) {
   const policy = loadPolicy(input);
-  if (policy === false)
-    return Object.assign(() => allowed, { encryption: () => void 0, requiresEncryption: false });
+  if (policy === false) {
+    return Object.assign(() => allowed, {
+      encryption: () => void 0,
+      requiresEncryption: false
+    });
+  }
   const clocks = /* @__PURE__ */ new Map();
   const compile = (condition, id) => {
     let readTime;
@@ -193,12 +212,29 @@ function createRequestCheck(input = false) {
   };
   const globalCheck = policy.global ? compile(policy.global) : () => allowed;
   const exact = /* @__PURE__ */ new Map();
-  const prefixes = { children: /* @__PURE__ */ new Map(), rules: [] };
-  const allMethods = ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "CONNECT", "TRACE", "*"];
+  const prefixes = {
+    children: /* @__PURE__ */ new Map(),
+    rules: []
+  };
+  const allMethods = [
+    "GET",
+    "HEAD",
+    "POST",
+    "PUT",
+    "PATCH",
+    "DELETE",
+    "OPTIONS",
+    "CONNECT",
+    "TRACE",
+    "*"
+  ];
   let requiresEncryption = false;
   let hasEncryption = false;
   for (const rule of policy.rules) {
-    const compiled = { methods: new Set(rule.methods), check: compile(rule, rule.id) };
+    const compiled = {
+      methods: new Set(rule.methods),
+      check: compile(rule, rule.id)
+    };
     for (const pattern of new Set(rule.paths)) {
       if (rule.encryption) {
         hasEncryption = true;
@@ -207,11 +243,14 @@ function createRequestCheck(input = false) {
         const nodes = [prefixes];
         let node = prefixes;
         const path2 = normalizeRequestPath(prefix ? pattern.slice(0, -3) || "/" : pattern);
-        for (const segment of path2.split("/").filter(Boolean)) {
-          let child = node.children.get(segment);
+        for (const segment2 of path2.split("/").filter(Boolean)) {
+          let child = node.children.get(segment2);
           if (!child) {
-            child = { children: /* @__PURE__ */ new Map(), rules: [] };
-            node.children.set(segment, child);
+            child = {
+              children: /* @__PURE__ */ new Map(),
+              rules: []
+            };
+            node.children.set(segment2, child);
           }
           node = child;
           nodes.push(node);
@@ -233,11 +272,14 @@ function createRequestCheck(input = false) {
       }
       if (pattern.endsWith("/**")) {
         let node = prefixes;
-        for (const segment of pattern.slice(0, -3).split("/").filter(Boolean)) {
-          let child = node.children.get(segment);
+        for (const segment2 of pattern.slice(0, -3).split("/").filter(Boolean)) {
+          let child = node.children.get(segment2);
           if (!child) {
-            child = { children: /* @__PURE__ */ new Map(), rules: [] };
-            node.children.set(segment, child);
+            child = {
+              children: /* @__PURE__ */ new Map(),
+              rules: []
+            };
+            node.children.set(segment2, child);
           }
           node = child;
         }
@@ -273,8 +315,8 @@ function createRequestCheck(input = false) {
       }
     }
     if (node.children.size) {
-      for (const segment of path2.split("/").filter(Boolean)) {
-        node = node.children.get(segment);
+      for (const segment2 of path2.split("/").filter(Boolean)) {
+        node = node.children.get(segment2);
         if (!node)
           break;
         for (const rule of node.rules) {
@@ -294,87 +336,303 @@ function createRequestCheck(input = false) {
       return void 0;
     let node = prefixes;
     let mode = node.encryption?.get(method) ?? node.encryption?.get("*");
-    for (const segment of path2.split("/").filter(Boolean)) {
-      node = node.children.get(segment);
+    for (const segment2 of path2.split("/").filter(Boolean)) {
+      node = node.children.get(segment2);
       if (!node)
         return mode;
       mode ??= node.encryption?.get(method) ?? node.encryption?.get("*");
     }
     return mode ?? node?.exactEncryption?.get(method) ?? node?.exactEncryption?.get("*");
   };
-  return Object.assign(check, { encryption: hasEncryption ? encryption : () => void 0, requiresEncryption });
+  return Object.assign(check, {
+    encryption: hasEncryption ? encryption : () => void 0,
+    requiresEncryption
+  });
+}
+var access = {
+  normalizeClientIp,
+  createClientIpResolver,
+  createConditionCheck,
+  createRequestCheck,
+  loadPolicy
+};
+function object(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function segment(value) {
+  return value.replace(/[^a-z0-9]+/gi, "_").replace(/^_|_$/g, "").toUpperCase();
+}
+function shapes(node, root, value, depth = 0) {
+  if (depth > 32)
+    return [];
+  const result = [node];
+  if (typeof node.$ref === "string" && node.$ref.startsWith("#/")) {
+    let target = root;
+    for (const key of node.$ref.slice(2).split("/").map((item) => item.replaceAll("~1", "/").replaceAll("~0", "~")))
+      target = object(target)?.[key];
+    if (object(target))
+      result.push(...shapes(object(target), root, value, depth + 1));
+  }
+  for (const keyword of ["anyOf", "oneOf", "allOf"]) {
+    if (!Array.isArray(node[keyword]))
+      continue;
+    for (const item of node[keyword]) {
+      const branch = object(item);
+      if (!branch)
+        continue;
+      const fields = object(branch.properties);
+      const input = object(value);
+      if (fields && input && Object.entries(fields).some(([key, field]) => input[key] !== void 0 && object(field)?.const !== void 0 && object(field).const !== input[key]))
+        continue;
+      result.push(...shapes(branch, root, value, depth + 1));
+    }
+  }
+  return result;
 }
-var access = { normalizeClientIp, createClientIpResolver, createConditionCheck, createRequestCheck, loadPolicy };
-var ENV_VAR_PATTERN = /\$\{([^}:]+)(?::([^}]*))?\}/g;
-var FULL_VAR_PATTERN = /^\$\{[^}:]+(?::[^}]*)?\}$/;
-function parseEnvValue(value) {
-  if (value === "")
+function combined(nodes) {
+  const entries = nodes.map(object).filter((item) => item !== void 0);
+  return entries.length === 1 ? entries[0] : { anyOf: entries };
+}
+function scalar(text, node, root) {
+  const types = new Set(shapes(node, root).flatMap((item) => Array.isArray(item.type) ? item.type : typeof item.type === "string" ? [item.type] : []));
+  if (types.has("string") && [...types].every((type) => type === "string" || type === "null") && !(text === "null" && types.has("null")))
+    return text;
+  if (text === "")
     return "";
   try {
-    const parsed = parse(value);
-    return parsed === void 0 ? value : parsed;
+    return parse(text) ?? (text === "null" ? null : text);
   } catch {
-    return value;
+    return text;
+  }
+}
+function mergeEnv(layers) {
+  const values = {};
+  for (const layer of layers) {
+    for (const name of Object.keys(layer).sort((left, right) => left.length - right.length || left.localeCompare(right))) {
+      if (layer[name] === void 0)
+        continue;
+      if (name.startsWith("HAI_")) {
+        for (const previous of Object.keys(values)) {
+          if (previous !== "HAI_SERV_REFRESH_COOKIE_SECURE" && previous.startsWith(`${name}_`))
+            delete values[previous];
+        }
+      }
+      values[name] = layer[name];
+    }
   }
+  return values;
 }
-function normalizeEnvSegment(segment) {
-  return segment.replace(/[^a-z0-9]+/gi, "_").replace(/^_+|_+$/g, "").toUpperCase();
+function parseEnvironment(text) {
+  const result = parseEnv(text);
+  const names = /* @__PURE__ */ new Set();
+  const assignments = /^[ \t]*(?:export[ \t]+)?([A-Z_]\w*)[ \t]*=[ \t]*('[^']*'|"(?:[^"\\]|\\.)*"|`[^`]*`|[^\r\n]*)/gim;
+  for (const match of text.matchAll(assignments)) {
+    const name = match[1];
+    if (names.has(name))
+      throw new Error(`Duplicate environment variable: ${name}`);
+    names.add(name);
+    if (match[2].startsWith('"') && (match[2].includes('\\"') || match[2].includes("\\u0027"))) {
+      try {
+        result[name] = JSON.parse(match[2]);
+      } catch {
+      }
+    }
+  }
+  return Object.fromEntries(Object.entries(result).filter((entry) => entry[1] !== void 0));
 }
-function buildConventionEnvName(name, path2) {
-  return ["HAI", name, ...path2].map(normalizeEnvSegment).filter(Boolean).join("_");
+function stringifyEnv(values, options = {}) {
+  return `${Object.keys(values).sort().map((name) => {
+    if (!/^[A-Z_]\w*$/i.test(name))
+      throw new Error("Invalid environment variable name");
+    const value = values[name];
+    let literal;
+    if (!value.includes("'"))
+      literal = `'${value}'`;
+    else if (options.target === "compose")
+      literal = JSON.stringify(value).replaceAll("$", () => "$$");
+    else literal = JSON.stringify(value).replaceAll("'", "\\u0027");
+    return `${name}=${literal}`;
+  }).join("\n")}
+`;
 }
-function resolveEnv(value, name, path2 = []) {
-  const conventionEnvValue = process3.env[buildConventionEnvName(name, path2)];
-  if (conventionEnvValue !== void 0)
-    return ok(parseEnvValue(conventionEnvValue));
-  if (typeof value === "string") {
-    ENV_VAR_PATTERN.lastIndex = 0;
-    const hasExplicitEnv = ENV_VAR_PATTERN.test(value);
-    ENV_VAR_PATTERN.lastIndex = 0;
-    if (!hasExplicitEnv)
-      return ok(value);
-    let result = value;
-    while (true) {
-      const match = ENV_VAR_PATTERN.exec(value);
-      if (!match)
+function resolveEnvironment(options, literal = false) {
+  const environment = options.environment ?? process4.env;
+  const missingNames = /* @__PURE__ */ new Set();
+  let root;
+  try {
+    root = options.schema ? options.schema.toJSONSchema({ io: "input", unrepresentable: "any" }) : options.shape ?? {};
+  } catch {
+    root = {};
+  }
+  const prefix = `HAI_${segment(options.name)}`;
+  function visit(original, name, node, inheritedLiteral, depth, declaration = original) {
+    if (depth > 32)
+      throw new Error(name);
+    let value = original;
+    let fromEnvironment = inheritedLiteral;
+    if (environment[name] !== void 0) {
+      value = scalar(environment[name], node, root);
+      fromEnvironment = true;
+    }
+    const alternatives = shapes(node, root);
+    const discriminators = /* @__PURE__ */ new Map();
+    for (const candidate of alternatives) {
+      for (const [key, field] of Object.entries(object(candidate.properties) ?? {})) {
+        if (shapes(object(field) ?? {}, root).some((item) => Object.hasOwn(item, "const"))) {
+          discriminators.set(key, [
+            ...discriminators.get(key) ?? [],
+            field
+          ]);
+        }
+      }
+    }
+    const selection = {
+      ...object(value)
+    };
+    for (const [key, fields] of discriminators) {
+      const text = environment[`${name}_${segment(key)}`];
+      if (text !== void 0)
+        selection[key] = scalar(text, combined(fields), root);
+    }
+    const candidates = shapes(node, root, Object.keys(selection).length ? selection : value);
+    const synthesized = value === void 0;
+    const valueType = typeof value;
+    const primitiveOverride = value === void 0 || candidates.some((candidate) => value !== null && candidate.type === valueType || candidate.const === value || value === null && candidate.type === "null");
+    if (primitiveOverride && !object(value) && !Array.isArray(value)) {
+      const declared = /* @__PURE__ */ new Set([
+        ...Object.keys(object(declaration) ?? {}),
+        ...candidates.flatMap((candidate) => Object.keys(object(candidate.properties) ?? {}))
+      ]);
+      const specified = [...declared].filter((key) => Object.keys(environment).some((candidate) => environment[candidate] !== void 0 && (candidate === `${name}_${segment(key)}` || candidate.startsWith(`${name}_${segment(key)}_`))));
+      if (specified.length)
+        value = Object.fromEntries(specified.map((key) => [key, void 0]));
+    }
+    if (value === void 0 && Object.keys(environment).some((key) => environment[key] !== void 0 && key.startsWith(`${name}_`))) {
+      if (candidates.some((item) => item.type === "object" || object(item.properties)))
+        value = {};
+    }
+    const indexed = Object.keys(environment).filter((key) => environment[key] !== void 0 && key.startsWith(`${name}_`) && /^\d+(?:_|$)/.test(key.slice(name.length + 1)));
+    if (value === void 0 && indexed.length && candidates.some((candidate) => candidate.type === "array")) {
+      const defaults = candidates.find((candidate) => Array.isArray(candidate.default))?.default;
+      if (!Array.isArray(defaults))
+        throw new TypeError(indexed[0]);
+      value = structuredClone(defaults);
+    }
+    if (Array.isArray(value)) {
+      const itemShape = combined(candidates.map((item) => item.items));
+      for (const key of indexed) {
+        const index = key.slice(name.length + 1).split("_")[0];
+        if (/^\d+$/.test(index) && (String(Number(index)) !== index || Number(index) >= value.length))
+          throw new Error(key);
+      }
+      return value.map((item, index) => visit(item, `${name}_${index}`, itemShape, fromEnvironment, depth + 1, Array.isArray(declaration) ? declaration[index] : void 0));
+    }
+    const input = object(value);
+    if (input) {
+      const properties = /* @__PURE__ */ new Map();
+      for (const candidate of candidates) {
+        for (const [key, field] of Object.entries(object(candidate.properties) ?? {})) {
+          properties.set(key, [
+            ...properties.get(key) ?? [],
+            field
+          ]);
+        }
+      }
+      const declaredKeys = /* @__PURE__ */ new Set([
+        ...Object.keys(object(declaration) ?? {}),
+        ...properties.keys()
+      ]);
+      const keys = /* @__PURE__ */ new Set([
+        ...Object.keys(input),
+        ...[...declaredKeys].filter((key) => Object.keys(environment).some((nameInEnv) => environment[nameInEnv] !== void 0 && (nameInEnv === `${name}_${segment(key)}` || nameInEnv.startsWith(`${name}_${segment(key)}_`))))
+      ]);
+      const entries = [...keys].map((key) => {
+        if (["__proto__", "prototype", "constructor"].includes(key))
+          throw new Error(name);
+        return [
+          key,
+          visit(input[key], `${name}_${segment(key)}`, combined(properties.get(key) ?? candidates.map((candidate) => candidate.additionalProperties)), fromEnvironment, depth + 1, object(declaration)?.[key])
+        ];
+      }).filter(([, child]) => child !== void 0);
+      return synthesized && !entries.length ? void 0 : Object.fromEntries(entries);
+    }
+    if (typeof value !== "string" || fromEnvironment)
+      return value;
+    const parts = [];
+    let consumed = 0;
+    let search = 0;
+    let full = false;
+    while (search < value.length) {
+      const start = value.indexOf("${", search);
+      if (start < 0)
+        break;
+      if (value[start + 2] === ":" || value[start + 2] === "}") {
+        search = start + 2;
+        continue;
+      }
+      const end = value.indexOf("}", start + 2);
+      if (end < 0)
         break;
-      const [fullMatch, varName, defaultValue] = match;
-      const envValue = process3.env[varName];
-      if (envValue === void 0 && defaultValue === void 0) {
-        return err(HaiConfigError.CONFIG_ENV_VAR_MISSING, i18n.coreM("core_configEnvVarMissing", { params: { varName } }));
+      const expression = value.slice(start + 2, end);
+      const separator = expression.indexOf(":");
+      const key = separator < 0 ? expression : expression.slice(0, separator);
+      const fallback = separator < 0 ? void 0 : expression.slice(separator + 1);
+      if (environment[key] === void 0 && fallback === void 0 && options.missing !== "empty") {
+        missingNames.add(key);
+        throw new Error(key);
       }
-      result = result.replace(fullMatch, () => envValue ?? defaultValue ?? "");
+      parts.push(value.slice(consumed, start), environment[key] ?? fallback ?? "");
+      consumed = end + 1;
+      search = consumed;
+      full = start === 0 && consumed === value.length;
     }
-    if (FULL_VAR_PATTERN.test(value))
-      return ok(parseEnvValue(result));
-    return ok(result);
+    const resolved = parts.join("") + value.slice(consumed);
+    return full ? scalar(resolved, node, root) : resolved;
   }
-  if (Array.isArray(value)) {
-    const results = [];
-    for (const [index, item] of value.entries()) {
-      const r = resolveEnv(item, name, [...path2, String(index)]);
-      if (!r.success)
-        return r;
-      results.push(r.data);
+  try {
+    return ok(visit(options.value, prefix, root, literal, 0));
+  } catch (failure) {
+    const name = failure instanceof Error && /^[A-Z_]\w*$/i.test(failure.message) ? failure.message : prefix;
+    if (!missingNames.has(name)) {
+      return err(HaiConfigError.CONFIG_VALIDATION_ERROR, i18n.coreM("core_configValidationFailed"), {
+        fields: [name]
+      });
     }
-    return ok(results);
+    return err(HaiConfigError.CONFIG_ENV_VAR_MISSING, i18n.coreM("core_configEnvVarMissing", {
+      params: { varName: name }
+    }));
   }
-  if (typeUtils.isObject(value)) {
-    const results = {};
-    for (const [k, v] of Object.entries(value)) {
-      const r = resolveEnv(v, name, [...path2, k]);
-      if (!r.success)
-        return r;
-      results[k] = r.data;
+}
+function toEnv(options) {
+  const result = {};
+  const root = options.schema ? options.schema.toJSONSchema({ io: "input", unrepresentable: "any" }) : options.shape ?? {};
+  function visit(value, name, node) {
+    if (!/^[A-Z][A-Z0-9_]*$/.test(name))
+      throw new Error("Invalid environment variable name");
+    if (value === void 0)
+      return;
+    const input = object(value);
+    const candidates = shapes(node, root, value);
+    const properties = Object.assign({}, ...candidates.map((candidate) => object(candidate.properties) ?? {}));
+    const dynamic = candidates.some((candidate) => candidate.additionalProperties === true || object(candidate.additionalProperties));
+    if (input && Object.keys(input).length && !dynamic && Object.keys(input).every((key) => /^[a-z][a-zA-Z0-9]*$/.test(key))) {
+      for (const [key, item] of Object.entries(input))
+        visit(item, `${name}_${segment(key)}`, object(properties[key]) ?? {});
+    } else {
+      result[name] = value === null || typeof value === "object" ? JSON.stringify(value) : String(value);
     }
-    return ok(results);
   }
-  return ok(value);
+  visit(options.value, options.prefix, root);
+  return result;
 }
+
+// src/functions/core-function-config.node.ts
 var configCache = /* @__PURE__ */ new Map();
 var watchEntries = /* @__PURE__ */ new Map();
 function createNotLoadedError(name) {
-  const result = err(HaiConfigError.CONFIG_NOT_LOADED, i18n.coreM("core_configNotLoaded", { params: { name } }));
+  const result = err(HaiConfigError.CONFIG_NOT_LOADED, i18n.coreM("core_configNotLoaded", {
+    params: { name }
+  }));
   if (!result.success)
     return result.error;
   throw new Error("unreachable");
@@ -399,20 +657,24 @@ function notifyWatchCallbacks(name, result) {
     }
   }
 }
-function loadYaml(name, filePath) {
+function loadYaml(name, filePath, schema) {
   if (!existsSync(filePath)) {
-    return err(HaiConfigError.CONFIG_FILE_NOT_FOUND, i18n.coreM("core_configFileNotExist", { params: { filePath } }));
+    return err(HaiConfigError.CONFIG_FILE_NOT_FOUND, i18n.coreM("core_configFileNotExist", {
+      params: { filePath }
+    }));
   }
   try {
     const content = readFileSync(filePath, "utf-8");
     const parsed = parse(content);
-    return resolveEnv(parsed, name);
+    return resolveEnvironment({ name, value: parsed, schema });
   } catch (error) {
-    return err(HaiConfigError.CONFIG_PARSE_ERROR, i18n.coreM("core_configParseFailed", { params: { filePath } }), error);
+    return err(HaiConfigError.CONFIG_PARSE_ERROR, i18n.coreM("core_configParseFailed", {
+      params: { filePath }
+    }), error);
   }
 }
 function loadConfig(name, filePath, schema) {
-  const yamlResult = loadYaml(name, filePath);
+  const yamlResult = loadYaml(name, filePath, schema);
   if (!yamlResult.success)
     return yamlResult;
   const parseResult = schema.safeParse(yamlResult.data);
@@ -433,12 +695,27 @@ function loadAndCache(name, filePath, schema) {
   }
   return result;
 }
+function loadConfigStructure(name, filePath, schemaHint) {
+  const result = loadYaml(name, filePath, schemaHint);
+  if (result.success) {
+    configCache.set(name, {
+      data: result.data,
+      filePath,
+      schemaHint,
+      loadedAt: Date.now()
+    });
+  }
+  return result;
+}
 function validateLoadedConfig(name, schema) {
   const entry = configCache.get(name);
   if (!entry) {
     return err(createNotLoadedError(name));
   }
-  const parseResult = schema.safeParse(entry.data);
+  const resolved = resolveEnvironment({ name, value: entry.data, schema }, true);
+  if (!resolved.success)
+    return resolved;
+  const parseResult = schema.safeParse(resolved.data);
   if (!parseResult.success) {
     return err(HaiConfigError.CONFIG_VALIDATION_ERROR, i18n.coreM("core_configValidationFailed"), parseResult.error.issues);
   }
@@ -458,7 +735,7 @@ function reloadAndNotify(name) {
     notifyWatchCallbacks(name, result2);
     return result2;
   }
-  const result = entry.schema ? loadConfig(name, entry.filePath, entry.schema) : loadYaml(name, entry.filePath);
+  const result = entry.schema ? loadConfig(name, entry.filePath, entry.schema) : loadYaml(name, entry.filePath, entry.schemaHint);
   if (result.success) {
     configCache.set(name, {
       ...entry,
@@ -482,15 +759,18 @@ function startFileWatcher(name) {
       callbacks: /* @__PURE__ */ new Set(),
       debounceTimer: null
     };
-    const watcher = watch(entry.filePath, (eventType) => {
-      if (eventType === "change") {
-        if (watchEntry.debounceTimer)
-          clearTimeout(watchEntry.debounceTimer);
-        watchEntry.debounceTimer = setTimeout(() => {
-          watchEntry.debounceTimer = null;
+    const filePath = resolve(entry.filePath);
+    const fileName = basename(filePath);
+    const watcher = watch(dirname(filePath), (_eventType, changedName) => {
+      if (changedName !== null && changedName.toString() !== fileName)
+        return;
+      if (watchEntry.debounceTimer)
+        clearTimeout(watchEntry.debounceTimer);
+      watchEntry.debounceTimer = setTimeout(() => {
+        watchEntry.debounceTimer = null;
+        if (watchEntries.get(name) === watchEntry)
           reloadAndNotify(name);
-        }, 100);
-      }
+      }, 100);
     });
     watchEntry.watcher = watcher;
     watchEntries.set(name, watchEntry);
@@ -509,7 +789,7 @@ function registerWatch(name, callback) {
   entry.callbacks.add(callback);
   return () => {
     const current = watchEntries.get(name);
-    if (!current)
+    if (current !== entry)
       return;
     current.callbacks.delete(callback);
     if (current.callbacks.size === 0) {
@@ -548,10 +828,67 @@ function clearCache(name) {
   }
 }
 var config = {
+  /**
+   * 合并从低到高的环境来源；高来源父项替换旧节点，同来源细项覆盖父 JSON。
+   * @param layers - 按优先级排列的字面变量。
+   * @returns 合并后的变量，可能含秘密。
+   * @example
+   * ```ts
+   * import { core } from '@h-ai/core'
+   * const value = core.config.mergeEnv([{ HAI_APP_NAME: 'base' }, { HAI_APP_NAME: 'test' }])
+   * ```
+   */
+  mergeEnv,
+  /**
+   * 解析 dotenv 字面文本，拒绝重复键，不执行 shell 或变量展开。
+   * @param text - dotenv 文本，可能包含秘密。
+   * @returns 字面变量；重复键抛出不含变量值的错误。
+   * @example
+   * ```ts
+   * import { core } from '@h-ai/core'
+   * const value = core.config.parseEnv('HAI_APP_NAME=Example\n')
+   * ```
+   */
+  parseEnv: parseEnvironment,
+  /**
+   * 无损编码 dotenv，父变量排在细项前；含秘密时只能写入受保护文件。
+   * @param values - 字面变量，不进行脱敏。
+   * @param options - 输出语法目标，默认 Node dotenv。
+   * @param options.target - Compose 目标同时处理其美元符号插值规则。
+   * @returns dotenv 文本；非法变量名抛错。
+   * @example
+   * ```ts
+   * import { core } from '@h-ai/core'
+   * const value = core.config.stringifyEnv({ HAI_APP_NAME: 'Example' })
+   * ```
+   */
+  stringifyEnv,
+  /**
+   * 按已有结构或 Schema 解析父 JSON 和细项，不修改缓存或进程环境。
+   * @param options - 配置名、原始结构、变量、可选 Schema 和缺失插值规则。
+   * @returns 解析结果；调用方仍须执行最终 Schema 校验。
+   * @example
+   * ```ts
+   * import { core } from '@h-ai/core'
+   * const value = core.config.resolve({ name: 'app', value: { name: 'Example' }, environment: { HAI_APP_NAME: 'Test' } })
+   * ```
+   */
+  resolve: (options) => resolveEnvironment(options),
+  /**
+   * 默认将对象展开为细项；数组、动态字典和空对象保留 JSON。
+   * @param options - 完整变量前缀、配置值和可选 Schema。
+   * @returns 字面环境变量，不脱敏；非法名称抛错。
+   * @example
+   * ```ts
+   * import { core } from '@h-ai/core'
+   * const value = core.config.toEnv({ prefix: 'HAI_APP', value: { name: 'Example', tags: ['demo'] } })
+   * ```
+   */
+  toEnv,
   /**
    * 读取 dotenv 文件并按统一顺序合并，不修改进程环境。
    *
-   * 优先级：已有进程环境 > .env.local > .env.<mode> > .env。
+   * 优先级：已有进程环境 > .env.<mode>.local > .env.local > .env.<mode> > .env。
    * development/production 分别映射到 dev/prod；不存在的文件跳过。
    * 返回值可能包含私有配置，仅在 Node 启动/构建边界注入，不下发浏览器。
    * @param options - 文件所在目录及环境模式
@@ -570,21 +907,27 @@ var config = {
     const mode = options.mode === "development" ? "dev" : options.mode === "production" ? "prod" : options.mode;
     if (!/^[a-z0-9][\w-]*$/i.test(mode))
       return err(HaiConfigError.CONFIG_VALIDATION_ERROR, i18n.coreM("core_configValidationFailed"));
-    const envDir = options.envDir ?? process3.cwd();
+    const envDir = options.envDir ?? process4.cwd();
     try {
-      const merged = {};
-      for (const name of [".env", `.env.${mode}`, ".env.local"]) {
+      const layers = [];
+      for (const name of [
+        ".env",
+        `.env.${mode}`,
+        ".env.local",
+        `.env.${mode}.local`
+      ]) {
         const file = join(envDir, name);
         if (existsSync(file))
-          Object.assign(merged, parseEnv(readFileSync(file, "utf8")));
-      }
-      for (const name of Object.keys(merged)) {
-        if (process3.env[name] !== void 0)
-          merged[name] = process3.env[name];
+          layers.push(parseEnvironment(readFileSync(file, "utf8")));
       }
+      const declared = new Set(layers.flatMap((layer) => Object.keys(layer)));
+      layers.push(Object.fromEntries(Object.entries(process4.env).filter(([name]) => declared.has(name) || name.startsWith("HAI_"))));
+      const merged = mergeEnv(layers);
       return ok(merged);
     } catch {
-      return err(HaiConfigError.CONFIG_PARSE_ERROR, i18n.coreM("core_configParseFailed", { params: { filePath: envDir } }));
+      return err(HaiConfigError.CONFIG_PARSE_ERROR, i18n.coreM("core_configParseFailed", {
+        params: { filePath: envDir }
+      }));
     }
   },
   /**
@@ -664,7 +1007,9 @@ var config = {
   getOrThrow(name) {
     const data = this.get(name);
     if (data === void 0) {
-      throw new Error(i18n.coreM("core_configNotLoaded", { params: { name } }));
+      throw new Error(i18n.coreM("core_configNotLoaded", {
+        params: { name }
+      }));
     }
     return data;
   },
@@ -730,7 +1075,8 @@ var config = {
   /**
    * 监听配置文件变更并自动重载。
    *
-   * 文件变更时自动重新加载并调用回调。配置未加载时立即回调 NOT_LOADED 错误。
+   * 普通写入、原子替换及删除重建均触发重载；失败保留最近成功的缓存并通知错误。
+   * 配置未加载时立即回调 NOT_LOADED 错误。
    *
    * @param name - 配置名称
    * @param callback - 配置变更回调，接收新配置或错误
@@ -781,14 +1127,14 @@ var config = {
   }
 };
 var nodeRequire = createRequire(import.meta.url);
-if (process3.platform === "win32" && process3.stdout.isTTY) {
+if (process4.platform === "win32" && process4.stdout.isTTY) {
   try {
     execSync("chcp 65001 > nul", { stdio: "ignore" });
-    if (process3.stdout.setDefaultEncoding) {
-      process3.stdout.setDefaultEncoding("utf8");
+    if (process4.stdout.setDefaultEncoding) {
+      process4.stdout.setDefaultEncoding("utf8");
     }
-    if (process3.stderr.setDefaultEncoding) {
-      process3.stderr.setDefaultEncoding("utf8");
+    if (process4.stderr.setDefaultEncoding) {
+      process4.stderr.setDefaultEncoding("utf8");
     }
   } catch (_e) {
   }
@@ -806,8 +1152,12 @@ function configureLogger(config2) {
     globalFormat = config2.format;
     outputRevision++;
   }
-  if (config2.context)
-    globalContext = { ...globalContext, ...config2.context };
+  if (config2.context) {
+    globalContext = {
+      ...globalContext,
+      ...config2.context
+    };
+  }
   if (config2.redact) {
     globalRedact = [...config2.redact];
     outputRevision++;
@@ -830,11 +1180,21 @@ function wrapPino(resolvePino, resolveContext) {
     const output = resolvePino();
     if (!output.isLevelEnabled(level))
       return;
-    const context = sanitizeLogContext({ ...resolveContext(), ...ctx, ...requestContext.get() }) ?? {};
+    const context = sanitizeLogContext({
+      ...resolveContext(),
+      ...ctx,
+      ...requestContext.get()
+    }) ?? {};
     message = sanitize.sanitizeText(message);
     output[level](context, message);
-    if (!requestContext.get().suppressLogObservers)
-      emitLogRecord({ timestamp: Date.now(), level, message, context });
+    if (!requestContext.get().suppressLogObservers) {
+      emitLogRecord({
+        timestamp: Date.now(),
+        level,
+        message,
+        context
+      });
+    }
   };
   return {
     trace(message, ctx) {
@@ -856,12 +1216,18 @@ function wrapPino(resolvePino, resolveContext) {
       write("fatal", message, ctx);
     },
     child(childContext) {
-      return wrapPino(resolvePino, () => ({ ...resolveContext(), ...childContext }));
+      return wrapPino(resolvePino, () => ({
+        ...resolveContext(),
+        ...childContext
+      }));
     }
   };
 }
 function createLogger(options = {}) {
-  const localOptions = { ...options, context: { ...options.context } };
+  const localOptions = {
+    ...options,
+    context: { ...options.context }
+  };
   let revision = outputRevision;
   let output = createPinoOutput(localOptions);
   const resolvePino = () => {
@@ -876,7 +1242,10 @@ function createLogger(options = {}) {
       output.instance.level = level;
     return output.instance;
   };
-  return wrapPino(resolvePino, () => ({ ...globalContext, ...localOptions.context }));
+  return wrapPino(resolvePino, () => ({
+    ...globalContext,
+    ...localOptions.context
+  }));
 }
 function createPinoOutput(options) {
   const level = options.level ?? globalLevel;
@@ -919,7 +1288,10 @@ function createPinoOutput(options) {
   } else {
     pinoInstance = pino(pinoOptions);
   }
-  return { instance: pinoInstance, close: () => transport?.end() };
+  return {
+    instance: pinoInstance,
+    close: () => transport?.end()
+  };
 }
 function isPrettyTransportAvailable() {
   try {
@@ -1044,7 +1416,7 @@ function initCore(options = {}) {
         });
       }
     } else {
-      const result = config.load(item.name, item.filePath);
+      const result = loadConfigStructure(item.name, item.filePath, options.configSchemas?.[item.name]);
       if (result.success) {
         logger2.info(`[core] Config loaded: ${item.name} <- ${item.filePath}`);
       } else {