@o3co/ts.hocon 1.0.0 → 1.2.0

package/dist/index.cjs

@@ -42,6 +42,7 @@ __export(src_exports, {
 module.exports = __toCommonJS(src_exports);
 
 // src/coerce.ts
+var DECIMAL_NUMBER_RE = /^-?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/;
 var TRUTHY = /* @__PURE__ */ new Set(["true", "yes", "on"]);
 var FALSY = /* @__PURE__ */ new Set(["false", "no", "off"]);
 function coerceBoolean(value) {
@@ -51,7 +52,7 @@ function coerceBoolean(value) {
   return void 0;
 }
 function coerceNumber(value) {
-  if (!/^-?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/.test(value)) return void 0;
+  if (!DECIMAL_NUMBER_RE.test(value)) return void 0;
   return Number(value);
 }
 var DURATION_UNITS = {
@@ -207,6 +208,23 @@ var ConfigError = class extends Error {
   }
 };
 
+// src/value/numeric-array.ts
+function numericObjectToArray(value) {
+  if (value.kind !== "object") return null;
+  if (value.fields.size === 0) return null;
+  const canonicalInt = /^(0|[1-9][0-9]*)$/;
+  const eligible = [];
+  for (const [key, val] of value.fields) {
+    if (!canonicalInt.test(key)) continue;
+    const n = Number(key);
+    if (!Number.isInteger(n) || n > 2147483647) continue;
+    eligible.push({ n, v: val });
+  }
+  if (eligible.length === 0) return null;
+  eligible.sort((a, b) => a.n - b.n);
+  return eligible.map((e) => e.v);
+}
+
 // src/config.ts
 var Config = class _Config {
   constructor(root) {
@@ -219,39 +237,36 @@ var Config = class _Config {
   }
   getString(path2) {
     const v = this.requireScalar(path2);
-    if (typeof v !== "string") throw new ConfigError(`expected string at ${path2}, got ${typeof v}`, path2);
-    return v;
+    return v.raw;
   }
   getNumber(path2) {
     const v = this.requireScalar(path2);
-    if (typeof v === "number") return v;
-    if (typeof v === "string") {
-      const coerced = coerceNumber(v);
-      if (coerced !== void 0) return coerced;
-    }
-    throw new ConfigError(`expected number at ${path2}, got ${typeof v}`, path2);
+    const coerced = coerceNumber(v.raw);
+    if (coerced !== void 0) return coerced;
+    throw new ConfigError(`expected number at ${path2}, got ${v.valueType}`, path2);
   }
   getBoolean(path2) {
     const v = this.requireScalar(path2);
-    if (typeof v === "boolean") return v;
-    if (typeof v === "string") {
-      const coerced = coerceBoolean(v);
-      if (coerced !== void 0) return coerced;
-    }
-    throw new ConfigError(`expected boolean at ${path2}, got ${typeof v}`, path2);
+    const coerced = coerceBoolean(v.raw);
+    if (coerced !== void 0) return coerced;
+    throw new ConfigError(`expected boolean at ${path2}, got ${v.valueType}`, path2);
   }
   getDuration(path2, unit) {
     const v = this.requireScalar(path2);
-    if (typeof v !== "string") throw new ConfigError(`expected duration string at ${path2}, got ${typeof v}`, path2);
-    const result = parseDuration(v, unit);
-    if (Number.isNaN(result)) throw new ConfigError(`invalid duration at ${path2}: ${JSON.stringify(v)}`, path2);
+    if (v.valueType !== "string" && v.valueType !== "number") {
+      throw new ConfigError(`expected duration at ${path2}, got ${v.valueType}`, path2);
+    }
+    const result = parseDuration(v.raw, unit);
+    if (Number.isNaN(result)) throw new ConfigError(`invalid duration at ${path2}: ${JSON.stringify(v.raw)}`, path2);
     return result;
   }
   getBytes(path2, unit) {
     const v = this.requireScalar(path2);
-    if (typeof v !== "string") throw new ConfigError(`expected byte size string at ${path2}, got ${typeof v}`, path2);
-    const result = parseBytes(v, unit);
-    if (Number.isNaN(result)) throw new ConfigError(`invalid byte size at ${path2}: ${JSON.stringify(v)}`, path2);
+    if (v.valueType !== "string" && v.valueType !== "number") {
+      throw new ConfigError(`expected byte size at ${path2}, got ${v.valueType}`, path2);
+    }
+    const result = parseBytes(v.raw, unit);
+    if (Number.isNaN(result)) throw new ConfigError(`invalid byte size at ${path2}: ${JSON.stringify(v.raw)}`, path2);
     return result;
   }
   getConfig(path2) {
@@ -263,6 +278,10 @@ var Config = class _Config {
   getList(path2) {
     const v = this.lookupNode(path2);
     if (v === void 0) throw new ConfigError(`path not found: ${path2}`, path2);
+    if (v.kind === "object") {
+      const converted = numericObjectToArray(v);
+      if (converted !== null) return converted.map(hoconToJs);
+    }
     if (v.kind !== "array") throw new ConfigError(`expected array at ${path2}`, path2);
     return v.items.map(hoconToJs);
   }
@@ -294,7 +313,7 @@ var Config = class _Config {
     const v = this.lookupNode(path2);
     if (v === void 0) throw new ConfigError(`path not found: ${path2}`, path2);
     if (v.kind !== "scalar") throw new ConfigError(`expected scalar at ${path2}, got ${v.kind}`, path2);
-    return v.value;
+    return v;
   }
 };
 function splitConfigPath(path2) {
@@ -336,10 +355,22 @@ function splitConfigPath(path2) {
   }
   return segments;
 }
+function scalarToJs(raw, valueType) {
+  switch (valueType) {
+    case "null":
+      return null;
+    case "boolean":
+      return raw === "true";
+    case "number":
+      return Number(raw);
+    case "string":
+      return raw;
+  }
+}
 function hoconToJs(v) {
   switch (v.kind) {
     case "scalar":
-      return v.value;
+      return scalarToJs(v.raw, v.valueType);
     case "array":
       return v.items.map(hoconToJs);
     case "object": {
@@ -363,281 +394,494 @@ function deepMergeHocon(receiver, fallback) {
 }
 
 // src/internal/lexer/lexer.ts
-function tokenize(input) {
-  if (input.charCodeAt(0) === 65279) input = input.slice(1);
-  const tokens = [];
-  let pos = 0;
-  let line = 1;
-  let col = 1;
-  let hadSpace = false;
-  function peek(offset = 0) {
-    return input[pos + offset] ?? "";
-  }
-  function advance() {
-    const ch = input[pos++] ?? "";
-    if (ch === "\n") {
-      line++;
-      col = 1;
-    } else {
-      col++;
-    }
-    return ch;
-  }
-  function push(kind, value, l, c, isQuoted = false) {
-    tokens.push({ kind, value, line: l, col: c, isQuoted, precedingSpace: hadSpace });
-    hadSpace = false;
-  }
-  while (pos < input.length) {
-    const sl = line, sc = col;
-    const ch = peek();
-    if (ch === " " || ch === "	" || ch === "\r") {
-      advance();
-      hadSpace = true;
-      continue;
-    }
-    if (ch === "\n") {
-      advance();
-      if (tokens[tokens.length - 1]?.kind !== "newline") {
-        push("newline", "\n", sl, sc);
+function isHoconWhitespace(ch) {
+  const cp = ch.codePointAt(0) ?? -1;
+  if (cp === 9 || cp === 10 || cp === 11 || cp === 12 || cp === 13) return true;
+  if (cp >= 28 && cp <= 31) return true;
+  if (cp === 32 || cp === 160 || cp === 65279) return true;
+  if (cp === 5760) return true;
+  if (cp >= 8192 && cp <= 8202) return true;
+  if (cp === 8232 || cp === 8233 || cp === 8239 || cp === 8287) return true;
+  if (cp === 12288) return true;
+  return false;
+}
+function isHoconNewline(ch) {
+  return ch === "\n";
+}
+var SINGLE_CHAR_TOKENS = {
+  "{": "lbrace",
+  "}": "rbrace",
+  "[": "lbracket",
+  "]": "rbracket",
+  ",": "comma",
+  ":": "colon"
+};
+var Lexer = class {
+  constructor(input) {
+    this.input = input;
+    this.pos = 0;
+    this.line = 1;
+    this.col = 1;
+    this.hadSpace = false;
+    this.tokens = [];
+    if (input.charCodeAt(0) === 65279) this.input = input.slice(1);
+  }
+  tokenize() {
+    while (this.pos < this.input.length) {
+      const sl = this.line, sc = this.col;
+      const ch = this.peek();
+      if (isHoconNewline(ch)) {
+        this.advance();
+        if (this.tokens[this.tokens.length - 1]?.kind !== "newline") {
+          this.push("newline", "\n", sl, sc);
+        }
+        continue;
       }
-      continue;
-    }
-    if (ch === "/" && peek(1) === "/") {
-      while (pos < input.length && peek() !== "\n") advance();
-      hadSpace = true;
-      continue;
-    }
-    if (ch === "#") {
-      while (pos < input.length && peek() !== "\n") advance();
-      hadSpace = true;
-      continue;
-    }
-    const single = { "{": "lbrace", "}": "rbrace", "[": "lbracket", "]": "rbracket", ",": "comma", ":": "colon" };
-    if (ch in single) {
-      advance();
-      push(single[ch], ch, sl, sc);
-      continue;
-    }
-    if (ch === "=") {
-      advance();
-      push("equals", "=", sl, sc);
-      continue;
-    }
-    if (ch === "+" && peek(1) === "=") {
-      advance();
-      advance();
-      push("plus_equals", "+=", sl, sc);
-      continue;
-    }
-    if (ch === "$" && peek(1) === "{") {
-      advance();
-      advance();
-      const optional = peek() === "?";
-      if (optional) advance();
-      let path2 = "";
-      while (pos < input.length && peek() !== "}") {
-        if (peek() === "\n") throw new ParseError("unterminated substitution", sl, sc);
-        path2 += advance();
+      if (isHoconWhitespace(ch)) {
+        this.advance();
+        this.hadSpace = true;
+        continue;
       }
-      if (peek() !== "}") throw new ParseError("unterminated substitution", sl, sc);
-      advance();
-      push(optional ? "opt_subst" : "subst", path2.trim(), sl, sc);
-      continue;
-    }
-    if (ch === '"' && peek(1) === '"' && peek(2) === '"') {
-      advance();
-      advance();
-      advance();
-      let value = "";
-      let closed = false;
-      while (pos < input.length) {
-        if (peek() === '"') {
-          let quoteCount = 0;
-          while (pos < input.length && peek() === '"') {
-            quoteCount++;
-            advance();
+      if (ch === "/" && this.peek(1) === "/") {
+        while (this.pos < this.input.length && this.peek() !== "\n") this.advance();
+        this.hadSpace = true;
+        continue;
+      }
+      if (ch === "#") {
+        while (this.pos < this.input.length && this.peek() !== "\n") this.advance();
+        this.hadSpace = true;
+        continue;
+      }
+      if (ch in SINGLE_CHAR_TOKENS) {
+        this.advance();
+        this.push(SINGLE_CHAR_TOKENS[ch], ch, sl, sc);
+        continue;
+      }
+      if (ch === "=") {
+        this.advance();
+        this.push("equals", "=", sl, sc);
+        continue;
+      }
+      if (ch === "+" && this.peek(1) === "=") {
+        this.advance();
+        this.advance();
+        this.push("plus_equals", "+=", sl, sc);
+        continue;
+      }
+      if (ch === "$" && this.peek(1) === "{") {
+        this.advance();
+        this.advance();
+        const payload = this.parseSubstBody(sl, sc);
+        const value = payload.segments.map((s) => {
+          const t = s.text;
+          if (t === "" || t.includes(".") || t.includes(" ") || t.includes("	") || t.includes('"') || t.includes("\\") || t !== t.trim()) {
+            const escaped = t.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+            return `"${escaped}"`;
           }
-          if (quoteCount >= 3) {
-            for (let i = 0; i < quoteCount - 3; i++) value += '"';
-            closed = true;
-            break;
+          return t;
+        }).join(".");
+        this.pushSubst(payload, value, sl, sc);
+        continue;
+      }
+      if (ch === '"' && this.peek(1) === '"' && this.peek(2) === '"') {
+        this.advance();
+        this.advance();
+        this.advance();
+        let value = "";
+        let closed = false;
+        while (this.pos < this.input.length) {
+          if (this.peek() === '"') {
+            let quoteCount = 0;
+            while (this.pos < this.input.length && this.peek() === '"') {
+              quoteCount++;
+              this.advance();
+            }
+            if (quoteCount >= 3) {
+              for (let i = 0; i < quoteCount - 3; i++) value += '"';
+              closed = true;
+              break;
+            }
+            for (let i = 0; i < quoteCount; i++) value += '"';
+            continue;
           }
-          for (let i = 0; i < quoteCount; i++) value += '"';
-          continue;
+          value += this.advance();
+        }
+        if (!closed) {
+          throw new ParseError("unterminated triple-quoted string", sl, sc);
         }
-        value += advance();
+        if (value.startsWith("\n")) value = value.slice(1);
+        this.push("triple_string", value, sl, sc, true);
+        continue;
       }
-      if (!closed) {
-        throw new ParseError("unterminated triple-quoted string", sl, sc);
+      if (ch === '"') {
+        this.advance();
+        const value = this.readQuotedStringBody(sl, sc);
+        this.push("string", value, sl, sc, true);
+        continue;
       }
-      if (value.startsWith("\n")) value = value.slice(1);
-      push("triple_string", value, sl, sc, true);
-      continue;
-    }
-    if (ch === '"') {
-      advance();
-      let value = "";
-      while (pos < input.length && peek() !== '"') {
-        if (peek() === "\n") throw new ParseError("unterminated string", sl, sc);
-        if (peek() === "\\") {
-          advance();
-          const esc = advance();
-          switch (esc) {
-            case "n":
-              value += "\n";
-              break;
-            case "t":
-              value += "	";
-              break;
-            case "r":
-              value += "\r";
-              break;
-            case '"':
-              value += '"';
-              break;
-            case "\\":
-              value += "\\";
-              break;
-            case "/":
-              value += "/";
-              break;
-            case "b":
-              value += "\b";
-              break;
-            case "f":
-              value += "\f";
-              break;
-            case "u": {
-              if (pos + 4 > input.length) {
-                throw new ParseError("Invalid unicode escape: not enough characters", line, col);
-              }
-              const hex = input.slice(pos, pos + 4);
-              if (!/^[0-9a-fA-F]{4}$/.test(hex)) {
-                throw new ParseError(`Invalid unicode escape: \\u${hex}`, line, col);
-              }
-              value += String.fromCharCode(parseInt(hex, 16));
-              for (let i = 0; i < 4; i++) advance();
-              break;
+      if (isUnquotedStart(ch)) {
+        if (ch === "-" && !isDecimalDigit(this.peek(1))) {
+          const after = this.peek(1) === "" ? "EOF" : JSON.stringify(this.peek(1));
+          throw new ParseError(
+            `unquoted string cannot begin with '-' unless followed by a digit (got '-' then ${after}, HOCON.md L270-276)`,
+            sl,
+            sc
+          );
+        }
+        let value = "";
+        while (this.pos < this.input.length && isUnquotedContinue(this.peek(), () => this.peek(1))) {
+          value += this.advance();
+        }
+        this.push("unquoted", value.trimEnd(), sl, sc);
+        continue;
+      }
+      throw new ParseError(`unexpected character: ${JSON.stringify(ch)}`, sl, sc);
+    }
+    this.tokens.push({ kind: "eof", value: "", line: this.line, col: this.col, isQuoted: false, precedingSpace: false });
+    return this.tokens;
+  }
+  peek(offset = 0) {
+    return this.input[this.pos + offset] ?? "";
+  }
+  advance() {
+    const ch = this.input[this.pos++] ?? "";
+    if (ch === "\n") {
+      this.line++;
+      this.col = 1;
+    } else {
+      this.col++;
+    }
+    return ch;
+  }
+  push(kind, value, l, c, isQuoted = false) {
+    this.tokens.push({ kind, value, line: l, col: c, isQuoted, precedingSpace: this.hadSpace });
+    this.hadSpace = false;
+  }
+  pushSubst(payload, value, l, c) {
+    this.tokens.push({ kind: "subst", value, line: l, col: c, isQuoted: false, precedingSpace: this.hadSpace, subst: payload });
+    this.hadSpace = false;
+  }
+  /**
+   * Read body of a quoted string. Opening `"` must already be consumed.
+   * Returns decoded string. Throws ParseError on unterminated/invalid-escape.
+   * openLine/openCol are the position of the opening `"` for error reporting.
+   */
+  readQuotedStringBody(openLine, openCol) {
+    let value = "";
+    while (this.pos < this.input.length && this.peek() !== '"') {
+      if (this.peek() === "\n") throw new ParseError("unterminated string", openLine, openCol);
+      if (this.peek() === "\\") {
+        const escCol = this.col;
+        this.advance();
+        if (this.pos >= this.input.length) {
+          throw new ParseError("unterminated string", openLine, openCol);
+        }
+        const esc = this.advance();
+        switch (esc) {
+          case "n":
+            value += "\n";
+            break;
+          case "t":
+            value += "	";
+            break;
+          case "r":
+            value += "\r";
+            break;
+          case '"':
+            value += '"';
+            break;
+          case "\\":
+            value += "\\";
+            break;
+          case "/":
+            value += "/";
+            break;
+          case "b":
+            value += "\b";
+            break;
+          case "f":
+            value += "\f";
+            break;
+          case "u": {
+            if (this.pos + 4 > this.input.length) {
+              throw new ParseError("invalid unicode escape", openLine, escCol);
             }
-            default:
-              throw new ParseError(`Unknown escape sequence: \\${esc}`, line, col);
+            const hex = this.input.slice(this.pos, this.pos + 4);
+            if (!/^[0-9a-fA-F]{4}$/.test(hex)) {
+              throw new ParseError("invalid unicode escape", openLine, escCol);
+            }
+            const code = parseInt(hex, 16);
+            value += String.fromCharCode(code);
+            for (let i = 0; i < 4; i++) this.advance();
+            break;
           }
-        } else {
-          value += advance();
+          default:
+            throw new ParseError(`unknown escape sequence: \\${esc}`, openLine, escCol);
         }
+      } else {
+        value += this.advance();
       }
-      if (peek() !== '"') throw new ParseError("unterminated string", sl, sc);
-      advance();
-      push("string", value, sl, sc, true);
-      continue;
-    }
-    if (isUnquotedStart(ch)) {
-      let value = "";
-      while (pos < input.length && isUnquotedContinue(peek(), () => peek(1))) {
-        value += advance();
+    }
+    if (this.pos >= this.input.length || this.peek() !== '"') {
+      throw new ParseError("unterminated string", openLine, openCol);
+    }
+    this.advance();
+    return value;
+  }
+  /**
+   * Parse the body of a `${...}` substitution (called after `${` has been consumed).
+   * Implements Appendix A state machine from the cross-language spec.
+   */
+  parseSubstBody(startLine, startCol) {
+    let optional = false;
+    if (this.peek() === "?") {
+      this.advance();
+      optional = true;
+    }
+    let curText = "";
+    let curStarted = false;
+    let curLine = 0;
+    let curCol = 0;
+    let pendingWs = "";
+    const segments = [];
+    let lastDot = null;
+    while (true) {
+      if (this.pos >= this.input.length) {
+        throw new ParseError("unterminated substitution", startLine, startCol);
+      }
+      const ch = this.peek();
+      if (ch === "}") {
+        this.advance();
+        pendingWs = "";
+        break;
+      } else if (ch === '"') {
+        const qLine = startLine;
+        const qCol = this.col;
+        if (curStarted) {
+          curText += pendingWs;
+        }
+        pendingWs = "";
+        this.advance();
+        const decoded = this.readQuotedStringBody(qLine, qCol);
+        curText += decoded;
+        if (!curStarted) {
+          curLine = qLine;
+          curCol = qCol;
+          curStarted = true;
+        }
+      } else if (isUnquotedSubstChar(ch)) {
+        if (ch === "-" && !curStarted && !isDecimalDigit(this.peek(1))) {
+          const after = this.peek(1) === "" ? "EOF" : JSON.stringify(this.peek(1));
+          throw new ParseError(
+            `unquoted path segment cannot begin with '-' unless followed by a digit (got '-' then ${after}, HOCON.md L270-276)`,
+            startLine,
+            this.col
+          );
+        }
+        const uCol = this.col;
+        if (curStarted) {
+          curText += pendingWs;
+        }
+        pendingWs = "";
+        if (!curStarted) {
+          curLine = startLine;
+          curCol = uCol;
+          curStarted = true;
+        }
+        while (this.pos < this.input.length && isUnquotedSubstChar(this.peek())) {
+          curText += this.advance();
+        }
+      } else if (ch === ".") {
+        const dotCol = this.col;
+        pendingWs = "";
+        if (!curStarted) {
+          throw new ParseError("empty segment in path", startLine, dotCol);
+        }
+        segments.push({ text: curText, line: curLine, col: curCol });
+        curText = "";
+        curStarted = false;
+        curLine = 0;
+        curCol = 0;
+        lastDot = [startLine, dotCol];
+        this.advance();
+      } else if (isHoconNewline(ch)) {
+        throw new ParseError("unterminated substitution", startLine, startCol);
+      } else if (isHoconWhitespace(ch)) {
+        pendingWs += ch;
+        this.advance();
+      } else {
+        throw new ParseError(`unexpected character in substitution path: ${JSON.stringify(ch)}`, startLine, this.col);
       }
-      push("unquoted", value.trimEnd(), sl, sc);
-      continue;
     }
-    throw new ParseError(`unexpected character: ${JSON.stringify(ch)}`, sl, sc);
+    if (curStarted) {
+      segments.push({ text: curText, line: curLine, col: curCol });
+    } else if (segments.length === 0) {
+      throw new ParseError("empty substitution path", startLine, startCol);
+    } else {
+      const [errLine, errCol] = lastDot ?? [startLine, startCol];
+      throw new ParseError("empty segment in path", errLine, errCol);
+    }
+    return { segments, optional };
   }
-  tokens.push({ kind: "eof", value: "", line, col, isQuoted: false, precedingSpace: false });
-  return tokens;
+};
+function tokenize(input) {
+  return new Lexer(input).tokenize();
+}
+function isUnquotedSubstChar(ch) {
+  if (ch === "" || isHoconWhitespace(ch)) return false;
+  if ('"\\'.includes(ch)) return false;
+  if ("{}[]".includes(ch)) return false;
+  if (":=,+#`^?!@*&$.".includes(ch)) return false;
+  return true;
+}
+function isDecimalDigit(ch) {
+  return ch >= "0" && ch <= "9";
 }
 function isUnquotedStart(ch) {
-  return ch !== "" && !'{}[],:=+#\n\r	 "$?!@*&^\\'.includes(ch);
+  if (ch === "" || isHoconWhitespace(ch)) return false;
+  if ('{}[],:=+#"$?!@*&^\\'.includes(ch)) return false;
+  return true;
 }
 function isUnquotedContinue(ch, nextFn) {
-  if (ch === "" || '{}[],:=\n\r	 #"$?!@*&^\\'.includes(ch) || ch === " ") return false;
+  if (ch === "" || isHoconWhitespace(ch)) return false;
+  if ('{}[],:=#"$?!@*&^\\'.includes(ch)) return false;
   if (ch === "+" && nextFn() === "=") return false;
   if (ch === "/" && nextFn() === "/") return false;
   return true;
 }
 
 // src/internal/parser/parser.ts
-function parseTokens(tokens) {
-  let pos = 0;
-  function peek() {
-    return tokens[pos] ?? { kind: "eof", value: "", line: 0, col: 0, isQuoted: false, precedingSpace: false };
+var EOF_TOKEN = { kind: "eof", value: "", line: 0, col: 0, isQuoted: false, precedingSpace: false, subst: void 0 };
+var Parser = class {
+  constructor(tokens) {
+    this.tokens = tokens;
+    this.pos = 0;
+  }
+  parse() {
+    this.skip("newline");
+    const t = this.peek();
+    if (t.kind === "lbrace") {
+      this.advance();
+      const first = this.parseObject(true);
+      const allFields = first.kind === "object" ? [...first.fields] : [];
+      while (true) {
+        this.skip("newline");
+        if (this.peek().kind === "eof") break;
+        if (this.peek().kind === "lbrace") {
+          this.advance();
+          const extra = this.parseObject(true);
+          if (extra.kind === "object") allFields.push(...extra.fields);
+        } else {
+          const rest = this.parseObject(false);
+          if (rest.kind === "object") allFields.push(...rest.fields);
+          break;
+        }
+      }
+      this.skip("newline");
+      const remaining = this.peek();
+      if (remaining.kind !== "eof") {
+        throw new ParseError(`Unexpected token '${remaining.value}' after closing brace`, remaining.line, remaining.col);
+      }
+      return { kind: "object", fields: allFields, pos: first.pos };
+    }
+    return this.parseObject(false);
+  }
+  peek(offset = 0) {
+    return this.tokens[this.pos + offset] ?? EOF_TOKEN;
   }
-  function advance() {
-    const t2 = tokens[pos];
-    if (pos < tokens.length) pos++;
-    return t2 ?? { kind: "eof", value: "", line: 0, col: 0, isQuoted: false, precedingSpace: false };
+  advance() {
+    const t = this.tokens[this.pos];
+    if (this.pos < this.tokens.length) this.pos++;
+    return t ?? EOF_TOKEN;
   }
-  function skip(...kinds) {
-    while (kinds.includes(peek().kind)) advance();
+  skip(...kinds) {
+    while (kinds.includes(this.peek().kind)) this.advance();
   }
-  function currentPos() {
-    const t2 = peek();
-    return { line: t2.line, col: t2.col };
+  currentPos() {
+    const t = this.peek();
+    return { line: t.line, col: t.col };
   }
-  function parseObject(expectClosingBrace) {
-    const p = currentPos();
+  parseObject(expectClosingBrace) {
+    const p = this.currentPos();
     const fields = [];
     while (true) {
-      skip("newline");
-      const t2 = peek();
-      if (t2.kind === "eof" || t2.kind === "rbrace") break;
-      if (t2.kind === "unquoted" && t2.value === "include") {
-        advance();
-        fields.push(parseInclude());
-        skip("newline");
-        if (peek().kind === "comma") advance();
-        skip("newline");
+      this.skip("newline");
+      const t = this.peek();
+      if (t.kind === "eof" || t.kind === "rbrace") break;
+      if (t.kind === "unquoted" && t.value === "include") {
+        this.advance();
+        fields.push(this.parseInclude());
+        this.skip("newline");
+        if (this.peek().kind === "comma") this.advance();
+        this.skip("newline");
         continue;
       }
-      const keyPos = currentPos();
-      const key = parseKey();
-      skip("newline");
+      const keyPos = this.currentPos();
+      const key = this.parseKey();
+      this.skip("newline");
       let append = false;
-      const sep = peek();
-      if (sep.kind === "equals") advance();
+      const sep = this.peek();
+      if (sep.kind === "equals") this.advance();
       else if (sep.kind === "plus_equals") {
-        advance();
+        this.advance();
         append = true;
-      } else if (sep.kind === "colon") advance();
+      } else if (sep.kind === "colon") this.advance();
       else if (sep.kind === "lbrace") {
       } else if (sep.kind !== "newline" && sep.kind !== "eof") {
         throw new ParseError(`unexpected token after key: ${sep.kind}`, sep.line, sep.col);
       }
-      skip("newline");
-      const value = parseValue();
+      this.skip("newline");
+      const value = this.parseValue();
       fields.push({ key, value, append, pos: keyPos });
-      skip("newline");
-      if (peek().kind === "comma") advance();
-      skip("newline");
+      this.skip("newline");
+      if (this.peek().kind === "comma") this.advance();
+      this.skip("newline");
     }
     if (expectClosingBrace) {
-      const t2 = peek();
-      if (t2.kind !== "rbrace") throw new ParseError("expected }", t2.line, t2.col);
-      advance();
+      const t = this.peek();
+      if (t.kind !== "rbrace") throw new ParseError("expected }", t.line, t.col);
+      this.advance();
     }
     return { kind: "object", fields, pos: p };
   }
-  function parseKey() {
+  parseKey() {
     const segments = [];
     let trailingDot = false;
     while (true) {
-      const t2 = peek();
-      if (t2.kind === "string") {
-        advance();
-        segments.push(t2.value);
+      const t = this.peek();
+      if (t.kind === "string") {
+        this.advance();
+        segments.push(t.value);
         trailingDot = false;
-      } else if (t2.kind === "unquoted") {
-        advance();
-        const parts = t2.value.split(".");
+      } else if (t.kind === "unquoted") {
+        this.advance();
+        const raw = t.value.startsWith(".") && segments.length > 0 && !t.precedingSpace ? t.value.slice(1) : t.value;
+        const parts = raw.split(".");
         const filtered = parts.filter((s) => s.length > 0);
+        for (const seg of filtered) {
+          if (seg[0] === "-" && !(seg.length >= 2 && seg[1] >= "0" && seg[1] <= "9")) {
+            const after = seg.length >= 2 ? JSON.stringify(seg[1]) : "EOF";
+            throw new ParseError(
+              `unquoted key segment cannot begin with '-' unless followed by a digit (got '-' then ${after} in ${JSON.stringify(seg)}, HOCON.md L270-276)`,
+              t.line,
+              t.col
+            );
+          }
+        }
         segments.push(...filtered);
-        trailingDot = t2.value.endsWith(".");
+        trailingDot = raw.endsWith(".");
       } else {
-        if (segments.length === 0) throw new ParseError(`expected key, got ${t2.kind}`, t2.line, t2.col);
+        if (segments.length === 0) throw new ParseError(`expected key, got ${t.kind}`, t.line, t.col);
         break;
       }
       if (trailingDot) continue;
-      const next = peek();
+      const next = this.peek();
       if (next.kind === "unquoted" && next.value === "." && !next.precedingSpace) {
-        advance();
+        this.advance();
+        trailingDot = true;
+        continue;
+      }
+      if (next.kind === "unquoted" && next.value.startsWith(".") && !next.precedingSpace) {
         trailingDot = true;
         continue;
       }
@@ -645,147 +889,230 @@ function parseTokens(tokens) {
     }
     return segments;
   }
-  function parseInclude() {
-    const p = currentPos();
-    skip("newline");
-    const t2 = peek();
+  parseInclude() {
+    const p = this.currentPos();
+    this.skip("newline");
+    const t = this.peek();
     let path2;
     let required = false;
-    if (t2.kind === "unquoted" && (t2.value === "required(" || t2.value === "required" || t2.value.startsWith("required("))) {
-      if (t2.value === "required") {
-        const next2 = tokens[pos + 1] ?? { kind: "eof", value: "" };
+    let isFile = false;
+    if (t.kind === "unquoted" && (t.value === "required(" || t.value === "required" || t.value.startsWith("required("))) {
+      if (t.value === "required") {
+        const next2 = this.peek(1);
         if (next2.kind !== "unquoted" || !next2.value.startsWith("(")) {
-          throw new ParseError("include required must be followed by (", t2.line, t2.col);
+          throw new ParseError("include required must be followed by (", t.line, t.col);
         }
       }
       required = true;
-      advance();
-      const innerPrefix = t2.value.startsWith("required(") ? t2.value.slice("required(".length) : "";
+      this.advance();
+      const innerPrefix = t.value.startsWith("required(") ? t.value.slice("required(".length) : "";
       if (innerPrefix.startsWith("url") || innerPrefix.startsWith("classpath")) {
-        throw new ParseError("include url(...) and classpath(...) are not supported", t2.line, t2.col);
+        throw new ParseError("include url(...) and classpath(...) are not supported", t.line, t.col);
       }
-      const next = peek();
+      if (innerPrefix.startsWith("file")) {
+        isFile = true;
+      }
+      const next = this.peek();
       if (next.kind === "unquoted" && (next.value === "url" || next.value.startsWith("url(") || next.value === "classpath" || next.value.startsWith("classpath("))) {
         throw new ParseError("include url(...) and classpath(...) are not supported", next.line, next.col);
       }
-      while (peek().kind !== "string" && peek().kind !== "eof") advance();
-      if (peek().kind === "eof") throw new ParseError("expected include path", t2.line, t2.col);
-      path2 = advance().value;
-      while (peek().kind !== "newline" && peek().kind !== "rbrace" && peek().kind !== "eof" && peek().kind !== "comma") advance();
-    } else if (t2.kind === "string") {
-      path2 = advance().value;
-    } else if (t2.kind === "unquoted" && (t2.value === "file(" || t2.value === "file")) {
-      advance();
-      while (peek().kind !== "string" && peek().kind !== "eof") advance();
-      if (peek().kind === "eof") throw new ParseError("expected include path", t2.line, t2.col);
-      path2 = advance().value;
-      while (peek().kind !== "newline" && peek().kind !== "rbrace" && peek().kind !== "eof" && peek().kind !== "comma") advance();
-    } else if (t2.kind === "unquoted" && (t2.value === "url" || t2.value.startsWith("url("))) {
-      throw new ParseError("include url(...) is not supported", t2.line, t2.col);
-    } else if (t2.kind === "unquoted" && (t2.value === "classpath" || t2.value.startsWith("classpath("))) {
-      throw new ParseError("include classpath(...) is not supported", t2.line, t2.col);
+      if (next.kind === "unquoted" && (next.value === "file(" || next.value === "file" || next.value.startsWith("file("))) {
+        isFile = true;
+      }
+      while (this.peek().kind !== "string" && this.peek().kind !== "eof") this.advance();
+      if (this.peek().kind === "eof") throw new ParseError("expected include path", t.line, t.col);
+      path2 = this.advance().value;
+      while (this.peek().kind !== "newline" && this.peek().kind !== "rbrace" && this.peek().kind !== "eof" && this.peek().kind !== "comma") this.advance();
+    } else if (t.kind === "string") {
+      path2 = this.advance().value;
+    } else if (t.kind === "unquoted" && (t.value === "file(" || t.value === "file")) {
+      isFile = true;
+      this.advance();
+      while (this.peek().kind !== "string" && this.peek().kind !== "eof") this.advance();
+      if (this.peek().kind === "eof") throw new ParseError("expected include path", t.line, t.col);
+      path2 = this.advance().value;
+      while (this.peek().kind !== "newline" && this.peek().kind !== "rbrace" && this.peek().kind !== "eof" && this.peek().kind !== "comma") this.advance();
+    } else if (t.kind === "unquoted" && (t.value === "url" || t.value.startsWith("url("))) {
+      throw new ParseError("include url(...) is not supported", t.line, t.col);
+    } else if (t.kind === "unquoted" && (t.value === "classpath" || t.value.startsWith("classpath("))) {
+      throw new ParseError("include classpath(...) is not supported", t.line, t.col);
     } else {
-      throw new ParseError(`expected include path, got ${t2.kind}`, t2.line, t2.col);
+      throw new ParseError(`expected include path, got ${t.kind}`, t.line, t.col);
     }
     return {
       key: [],
-      value: { kind: "include", path: path2, required, pos: p },
+      value: { kind: "include", path: path2, required, ...isFile ? { isFile: true } : {}, pos: p },
       append: false,
       pos: p
     };
   }
-  function parseValue() {
-    const p = currentPos();
+  parseValue() {
+    const p = this.currentPos();
     const parts = [];
     while (true) {
-      const t2 = peek();
-      if (t2.kind === "eof" || t2.kind === "newline" || t2.kind === "rbrace" || t2.kind === "rbracket" || t2.kind === "comma") break;
-      const hadSpace = t2.precedingSpace && parts.length > 0;
+      const t = this.peek();
+      if (t.kind === "eof" || t.kind === "newline" || t.kind === "rbrace" || t.kind === "rbracket" || t.kind === "comma") break;
+      const hadSpace = t.precedingSpace && parts.length > 0;
       let node;
-      if (t2.kind === "lbrace") {
-        advance();
-        node = parseObject(true);
-      } else if (t2.kind === "lbracket") {
-        advance();
-        node = parseArray();
-      } else if (t2.kind === "subst" || t2.kind === "opt_subst") {
-        advance();
-        node = { kind: "subst", path: t2.value, optional: t2.kind === "opt_subst", pos: { line: t2.line, col: t2.col } };
-      } else if (t2.kind === "string" || t2.kind === "triple_string") {
-        advance();
-        node = { kind: "scalar", value: t2.value, pos: { line: t2.line, col: t2.col } };
-      } else if (t2.kind === "unquoted") {
-        advance();
-        node = { kind: "scalar", value: parseScalarValue(t2.value), pos: { line: t2.line, col: t2.col } };
-      } else if ((t2.kind === "colon" || t2.kind === "equals") && parts.length > 0) {
-        advance();
-        node = { kind: "scalar", value: t2.value, pos: { line: t2.line, col: t2.col } };
+      if (t.kind === "lbrace") {
+        this.advance();
+        node = this.parseObject(true);
+      } else if (t.kind === "lbracket") {
+        this.advance();
+        node = this.parseArray();
+      } else if (t.kind === "subst") {
+        this.advance();
+        if (!t.subst) {
+          throw new ParseError(`internal: subst token missing payload`, t.line, t.col);
+        }
+        const payload = t.subst;
+        node = { kind: "subst", segments: payload.segments, optional: payload.optional, pos: { line: t.line, col: t.col } };
+      } else if (t.kind === "string" || t.kind === "triple_string") {
+        this.advance();
+        node = { kind: "scalar", raw: t.value, valueType: "string", pos: { line: t.line, col: t.col } };
+      } else if (t.kind === "unquoted") {
+        this.advance();
+        node = { kind: "scalar", raw: t.value, valueType: this.scalarValueType(t.value), pos: { line: t.line, col: t.col } };
+      } else if ((t.kind === "colon" || t.kind === "equals") && parts.length > 0) {
+        this.advance();
+        node = { kind: "scalar", raw: t.value, valueType: "string", pos: { line: t.line, col: t.col } };
       } else {
         break;
       }
       if (hadSpace) {
-        parts.push({ kind: "scalar", value: " ", pos: { line: t2.line, col: t2.col }, _separator: true });
+        parts.push({ kind: "scalar", raw: " ", valueType: "string", pos: { line: t.line, col: t.col }, _separator: true });
       }
       parts.push(node);
     }
-    if (parts.length === 0) throw new ParseError("expected value", peek().line, peek().col);
+    if (parts.length === 0) throw new ParseError("expected value", this.peek().line, this.peek().col);
     if (parts.length === 1) return parts[0];
     return { kind: "concat", nodes: parts, pos: p };
   }
-  function parseArray() {
-    const p = currentPos();
+  parseArray() {
+    const p = this.currentPos();
     const items = [];
     while (true) {
-      skip("newline");
-      if (peek().kind === "rbracket" || peek().kind === "eof") break;
-      items.push(parseValue());
-      skip("newline");
-      if (peek().kind === "comma") advance();
-      skip("newline");
-    }
-    const t2 = peek();
-    if (t2.kind !== "rbracket") throw new ParseError("expected ]", t2.line, t2.col);
-    advance();
+      this.skip("newline");
+      if (this.peek().kind === "rbracket" || this.peek().kind === "eof") break;
+      items.push(this.parseValue());
+      this.skip("newline");
+      if (this.peek().kind === "comma") this.advance();
+      this.skip("newline");
+    }
+    const t = this.peek();
+    if (t.kind !== "rbracket") throw new ParseError("expected ]", t.line, t.col);
+    this.advance();
     return { kind: "array", items, pos: p };
   }
-  function parseScalarValue(raw) {
-    if (raw === "true") return true;
-    if (raw === "false") return false;
-    if (raw === "null") return null;
-    const n = Number(raw);
-    if (!isNaN(n) && raw.trim() !== "") return n;
-    return raw;
-  }
-  skip("newline");
-  const t = peek();
-  if (t.kind === "lbrace") {
-    advance();
-    const first = parseObject(true);
-    const allFields = first.kind === "object" ? [...first.fields] : [];
-    while (true) {
-      skip("newline");
-      if (peek().kind === "eof") break;
-      if (peek().kind === "lbrace") {
-        advance();
-        const extra = parseObject(true);
-        if (extra.kind === "object") allFields.push(...extra.fields);
-      } else {
-        const rest = parseObject(false);
-        if (rest.kind === "object") allFields.push(...rest.fields);
-        break;
-      }
+  scalarValueType(raw) {
+    if (raw === "true" || raw === "false") return "boolean";
+    if (raw === "null") return "null";
+    if (raw.length > 0 && (raw.charCodeAt(0) >= 48 && raw.charCodeAt(0) <= 57 || raw.charCodeAt(0) === 45)) {
+      if (DECIMAL_NUMBER_RE.test(raw)) return "number";
+    }
+    return "string";
+  }
+};
+function parseTokens(tokens) {
+  return new Parser(tokens).parse();
+}
+
+// src/internal/resolver/types.ts
+var separatorValues = /* @__PURE__ */ new WeakSet();
+function isSubst(v) {
+  return v._kind === "subst-placeholder";
+}
+function isConcat(v) {
+  return v._kind === "concat-placeholder";
+}
+function isAppend(v) {
+  return v._kind === "append-placeholder";
+}
+function isResObj(v) {
+  return v._kind === "res-obj";
+}
+function makeResObj() {
+  return { _kind: "res-obj", fields: /* @__PURE__ */ new Map(), priorValues: /* @__PURE__ */ new Map() };
+}
+
+// src/internal/resolver/utils.ts
+function segmentsToKey(segments) {
+  return segments.map((s) => {
+    const t = s.text;
+    if (t === "" || /[^a-zA-Z0-9\-_]/.test(t)) {
+      return `"${t.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+    }
+    return t;
+  }).join(".");
+}
+function lookupPath(root, segments) {
+  const [head, ...tail] = segments;
+  if (head === void 0) return void 0;
+  const key = head.text;
+  const val = root.fields.get(key);
+  if (val === void 0) return void 0;
+  if (tail.length === 0) return val;
+  if (isResObj(val)) return lookupPath(val, tail);
+  return void 0;
+}
+function lookupResObj(root, segments) {
+  let cur = root;
+  for (const seg of segments) {
+    const val = cur.fields.get(seg.text);
+    if (val === void 0 || !isResObj(val)) return void 0;
+    cur = val;
+  }
+  return cur;
+}
+function deepMergeHoconValues(base, overlay) {
+  const merged = new Map(base.fields);
+  for (const [k, v] of overlay.fields) {
+    const existing = merged.get(k);
+    if (existing?.kind === "object" && v.kind === "object") {
+      merged.set(k, deepMergeHoconValues(existing, v));
+    } else {
+      merged.set(k, v);
     }
-    skip("newline");
-    const remaining = peek();
-    if (remaining.kind !== "eof") {
-      throw new ParseError(`Unexpected token '${remaining.value}' after closing brace`, remaining.line, remaining.col);
+  }
+  return { kind: "object", fields: merged };
+}
+function deepMergeResObjInto(dst, src) {
+  for (const [k, srcVal] of src.fields) {
+    const dstVal = dst.fields.get(k);
+    if (dstVal !== void 0 && isResObj(dstVal) && isResObj(srcVal)) {
+      deepMergeResObjInto(dstVal, srcVal);
+    } else {
+      if (dstVal !== void 0) dst.priorValues.set(k, dstVal);
+      dst.fields.set(k, srcVal);
+    }
+  }
+  for (const [k, srcPrior] of src.priorValues) {
+    if (!dst.priorValues.has(k)) {
+      dst.priorValues.set(k, srcPrior);
     }
-    return { kind: "object", fields: allFields, pos: first.pos };
   }
-  return parseObject(false);
+}
+function hoconValueToResObj(hv) {
+  const obj = makeResObj();
+  if (hv.kind !== "object") return obj;
+  for (const [key, val] of hv.fields) {
+    if (val.kind === "object") {
+      obj.fields.set(key, hoconValueToResObj(val));
+    } else {
+      obj.fields.set(key, val);
+    }
+  }
+  return obj;
+}
+function isFileNotFoundError(e) {
+  if (!(e instanceof Error)) return false;
+  const code = e.code;
+  if (code === "ENOENT" || code === "MODULE_NOT_FOUND") return true;
+  const msg = e.message.toLowerCase();
+  return msg.includes("not found") || msg.includes("no such file") || msg.includes("enoent");
 }
 
-// src/internal/resolver/resolver.ts
+// src/internal/resolver/include-loader.ts
 var nodePath = __toESM(require("path"), 1);
 
 // src/internal/properties/properties.ts
@@ -832,7 +1159,7 @@ function recordToHoconValue(obj) {
   const fields = /* @__PURE__ */ new Map();
   for (const [key, val] of Object.entries(obj)) {
     if (typeof val === "string") {
-      fields.set(key, { kind: "scalar", value: val });
+      fields.set(key, { kind: "scalar", raw: val, valueType: "string" });
     } else if (val !== null && typeof val === "object") {
       fields.set(key, recordToHoconValue(val));
     }
@@ -840,497 +1167,571 @@ function recordToHoconValue(obj) {
   return { kind: "object", fields };
 }
 
-// src/internal/resolver/resolver.ts
-var separatorValues = /* @__PURE__ */ new WeakSet();
-function isSubst(v) {
-  return v._kind === "subst-placeholder";
-}
-function isConcat(v) {
-  return v._kind === "concat-placeholder";
-}
-function isAppend(v) {
-  return v._kind === "append-placeholder";
-}
-function isResObj(v) {
-  return v._kind === "res-obj";
-}
-function makeResObj() {
-  return { _kind: "res-obj", fields: /* @__PURE__ */ new Map(), priorValues: /* @__PURE__ */ new Map() };
-}
-function resolve2(ast, opts) {
-  const root = buildResObj(ast, opts);
-  const resolving = /* @__PURE__ */ new Set();
-  const resolvedCache = /* @__PURE__ */ new Map();
-  return resolveResObj(root, root, resolving, resolvedCache, opts);
-}
-async function resolveAsync(ast, opts) {
-  const root = await buildResObjAsync(ast, opts);
-  const resolving = /* @__PURE__ */ new Set();
-  const resolvedCache = /* @__PURE__ */ new Map();
-  return resolveResObj(root, root, resolving, resolvedCache, opts);
-}
-function buildResObj(ast, opts) {
-  if (ast.kind !== "object") {
-    throw new ResolveError("root AST must be an object", "", ast.pos.line, ast.pos.col);
+// src/internal/resolver/include-loader.ts
+var IncludeLoader = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  /**
+   * Resolve an include path to an absolute path.
+   * - file() includes resolve relative to CWD (or as absolute paths),
+   *   NOT relative to the including file's directory.
+   * - Bare includes resolve relative to the including file's directory (baseDir).
+   */
+  resolveIncludePath(includePath, baseDir, isFile) {
+    return isFile ? nodePath.resolve(includePath) : baseDir ? nodePath.resolve(baseDir, includePath) : nodePath.resolve(includePath);
+  }
+  load(includePath, required, isFile) {
+    const { baseDir, includeStack = [] } = this.opts;
+    const absPath = this.resolveIncludePath(includePath, baseDir, !!isFile);
+    if (includeStack.includes(absPath)) {
+      throw new ResolveError(`circular include: ${absPath}`, absPath, 0, 0);
+    }
+    if (includeStack.length >= 50) {
+      throw new ResolveError(`include depth limit exceeded (max 50)`, includePath, 0, 0);
+    }
+    const hasExplicitExt = absPath.endsWith(".conf") || absPath.endsWith(".json") || absPath.endsWith(".properties");
+    if (hasExplicitExt) {
+      const result = this.loadSingle(absPath);
+      if (result !== void 0) return result;
+      if (required) {
+        throw new ResolveError(`required include file not found: ${includePath}`, includePath, 0, 0);
+      }
+      return makeResObj();
+    }
+    const merged = makeResObj();
+    let foundAny = false;
+    const probeExts = [".properties", ".json", ".conf"];
+    for (const ext of probeExts) {
+      const obj = this.loadSingle(`${absPath}${ext}`);
+      if (obj !== void 0) {
+        deepMergeResObjInto(merged, obj);
+        foundAny = true;
+      }
+    }
+    if (!foundAny && required) {
+      throw new ResolveError(`required include file not found: ${includePath}`, includePath, 0, 0);
+    }
+    return merged;
   }
-  const obj = makeResObj();
-  for (const field of ast.fields) {
-    applyField(obj, field, opts);
+  async loadAsync(includePath, required, isFile) {
+    const { baseDir, includeStack = [] } = this.opts;
+    const absPath = this.resolveIncludePath(includePath, baseDir, !!isFile);
+    if (includeStack.includes(absPath)) {
+      throw new ResolveError(`circular include: ${absPath}`, absPath, 0, 0);
+    }
+    if (includeStack.length >= 50) {
+      throw new ResolveError(`include depth limit exceeded (max 50)`, includePath, 0, 0);
+    }
+    const hasExplicitExt = absPath.endsWith(".conf") || absPath.endsWith(".json") || absPath.endsWith(".properties");
+    if (hasExplicitExt) {
+      const result = await this.loadSingleAsync(absPath);
+      if (result !== void 0) return result;
+      if (required) {
+        throw new ResolveError(`required include file not found: ${includePath}`, includePath, 0, 0);
+      }
+      return makeResObj();
+    }
+    const merged = makeResObj();
+    let foundAny = false;
+    const probeExts = [".properties", ".json", ".conf"];
+    for (const ext of probeExts) {
+      const obj = await this.loadSingleAsync(`${absPath}${ext}`);
+      if (obj !== void 0) {
+        deepMergeResObjInto(merged, obj);
+        foundAny = true;
+      }
+    }
+    if (!foundAny && required) {
+      throw new ResolveError(`required include file not found: ${includePath}`, includePath, 0, 0);
+    }
+    return merged;
   }
-  return obj;
-}
-function applyField(obj, field, opts) {
-  if (field.key.length === 0 && field.value.kind === "include") {
-    const included = loadInclude(field.value.path, field.value.required, opts);
-    deepMergeResObjInto(obj, included);
-    return;
-  }
-  const [head, ...tail] = field.key;
-  if (!head) return;
-  if (tail.length > 0) {
-    const syntheticAst = {
-      kind: "object",
-      fields: [{ key: tail, value: field.value, append: field.append, pos: field.pos }],
-      pos: field.pos
-    };
-    applyField(obj, { key: [head], value: syntheticAst, append: false, pos: field.pos }, opts);
-    return;
-  }
-  if (field.append) {
-    const existing2 = obj.fields.get(head) ?? { kind: "array", items: [] };
-    obj.priorValues.set(head, existing2);
-    obj.fields.set(head, {
-      _kind: "append-placeholder",
-      existing: existing2,
-      elem: astToResolverValue(field.value, opts)
+  loadSingle(candidate) {
+    const { readFileSync: readFileSync2, includeStack = [], env } = this.opts;
+    if (includeStack.includes(candidate)) {
+      throw new ResolveError(`circular include: ${candidate}`, candidate, 0, 0);
+    }
+    let content;
+    try {
+      content = readFileSync2(candidate);
+    } catch (e) {
+      if (isFileNotFoundError(e)) return void 0;
+      throw e;
+    }
+    if (candidate.endsWith(".properties")) {
+      return hoconValueToResObj(propertiesToHoconValue(content));
+    }
+    const ast = parseTokens(tokenize(content));
+    return this.onBuildResObj(ast, {
+      env,
+      baseDir: nodePath.dirname(candidate),
+      readFileSync: readFileSync2,
+      includeStack: [...includeStack, candidate]
     });
-    return;
   }
-  const existing = obj.fields.get(head);
-  const newVal = astToResolverValue(field.value, opts);
-  if (existing !== void 0) {
-    obj.priorValues.set(head, existing);
-  }
-  if (existing !== void 0 && isResObj(existing) && isResObj(newVal)) {
-    deepMergeResObjInto(existing, newVal);
-    return;
-  }
-  obj.fields.set(head, newVal);
-}
-function astToResolverValue(ast, opts) {
-  switch (ast.kind) {
-    case "scalar": {
-      const sv = { kind: "scalar", value: ast.value };
-      if (ast._separator) separatorValues.add(sv);
-      return sv;
+  async loadSingleAsync(candidate) {
+    const { readFile, readFileSync: readFileSync2, includeStack = [], env } = this.opts;
+    const read = readFile ? async (p) => readFile(p) : async (p) => readFileSync2(p);
+    if (includeStack.includes(candidate)) {
+      throw new ResolveError(`circular include: ${candidate}`, candidate, 0, 0);
     }
-    case "array":
-      return { kind: "array", items: ast.items.map((i) => astToResolverValue(i, opts)) };
-    case "object": {
-      const inner = buildResObj(ast, opts);
-      return inner;
+    let content;
+    try {
+      content = await read(candidate);
+    } catch (e) {
+      if (isFileNotFoundError(e)) return void 0;
+      throw e;
+    }
+    if (candidate.endsWith(".properties")) {
+      return hoconValueToResObj(propertiesToHoconValue(content));
     }
-    case "subst":
-      return { _kind: "subst-placeholder", path: ast.path, optional: ast.optional, line: ast.pos.line, col: ast.pos.col };
-    case "concat":
-      return { _kind: "concat-placeholder", nodes: ast.nodes.map((n) => astToResolverValue(n, opts)) };
-    case "include":
-      return { kind: "scalar", value: null };
+    const ast = parseTokens(tokenize(content));
+    return this.onBuildResObjAsync(ast, {
+      env,
+      baseDir: nodePath.dirname(candidate),
+      readFileSync: readFileSync2,
+      readFile,
+      includeStack: [...includeStack, candidate]
+    });
   }
-}
-function hoconValueToResObj(hv) {
-  const obj = makeResObj();
-  if (hv.kind !== "object") return obj;
-  for (const [key, val] of hv.fields) {
-    if (val.kind === "object") {
-      obj.fields.set(key, hoconValueToResObj(val));
-    } else {
-      obj.fields.set(key, val);
+};
+
+// src/internal/resolver/structure-builder.ts
+var StructureBuilder = class _StructureBuilder {
+  constructor(opts) {
+    this.opts = opts;
+    this.loader = new IncludeLoader(opts);
+    this.loader.onBuildResObj = (a, o) => new _StructureBuilder(o).build(a);
+    this.loader.onBuildResObjAsync = async (a, o) => new _StructureBuilder(o).buildAsync(a);
+  }
+  build(ast, pathPrefix = []) {
+    if (ast.kind !== "object") {
+      throw new ResolveError("root AST must be an object", "", ast.pos.line, ast.pos.col);
+    }
+    const obj = makeResObj();
+    for (const field of ast.fields) {
+      this.applyField(obj, field, pathPrefix);
     }
+    return obj;
   }
-  return obj;
-}
-function deepMergeResObjInto(dst, src) {
-  for (const [k, srcVal] of src.fields) {
-    const dstVal = dst.fields.get(k);
-    if (dstVal !== void 0 && isResObj(dstVal) && isResObj(srcVal)) {
-      deepMergeResObjInto(dstVal, srcVal);
-    } else {
-      if (dstVal !== void 0) dst.priorValues.set(k, dstVal);
-      dst.fields.set(k, srcVal);
+  async buildAsync(ast, pathPrefix = []) {
+    if (ast.kind !== "object") {
+      throw new ResolveError("root AST must be an object", "", ast.pos.line, ast.pos.col);
     }
+    const obj = makeResObj();
+    for (const field of ast.fields) {
+      await this.applyFieldAsync(obj, field, pathPrefix);
+    }
+    return obj;
   }
-}
-function resolveResObj(obj, root, resolving, resolvedCache, opts) {
-  const result = /* @__PURE__ */ new Map();
-  for (const [key, val] of obj.fields) {
-    const resolved = resolveVal(val, obj, root, resolving, resolvedCache, opts);
-    if (resolved !== void 0) {
-      result.set(key, resolved);
-    } else {
-      const prior = obj.priorValues.get(key);
-      if (prior !== void 0) {
-        const priorResolved = resolveVal(prior, obj, root, resolving, resolvedCache, opts);
-        if (priorResolved !== void 0) result.set(key, priorResolved);
+  applyField(obj, field, pathPrefix) {
+    if (field.key.length === 0 && field.value.kind === "include") {
+      const included = this.loader.load(field.value.path, field.value.required, field.value.isFile);
+      if (pathPrefix.length > 0) {
+        this.relativizeResObj(included, pathPrefix);
       }
+      deepMergeResObjInto(obj, included);
+      return;
     }
+    const [head, ...tail] = field.key;
+    if (head === void 0) return;
+    if (tail.length > 0) {
+      const syntheticAst = {
+        kind: "object",
+        fields: [{ key: tail, value: field.value, append: field.append, pos: field.pos }],
+        pos: field.pos
+      };
+      this.applyField(obj, { key: [head], value: syntheticAst, append: false, pos: field.pos }, pathPrefix);
+      return;
+    }
+    const childPrefix = [...pathPrefix, head];
+    if (field.append) {
+      const existing2 = obj.fields.get(head) ?? { kind: "array", items: [] };
+      obj.priorValues.set(head, existing2);
+      obj.fields.set(head, {
+        _kind: "append-placeholder",
+        existing: existing2,
+        elem: this.astToResolverValue(field.value, childPrefix)
+      });
+      return;
+    }
+    const existing = obj.fields.get(head);
+    const newVal = this.astToResolverValue(field.value, childPrefix);
+    if (existing !== void 0) {
+      obj.priorValues.set(head, existing);
+    }
+    if (existing !== void 0 && isResObj(existing) && isResObj(newVal)) {
+      deepMergeResObjInto(existing, newVal);
+      return;
+    }
+    obj.fields.set(head, newVal);
   }
-  return { kind: "object", fields: result };
-}
-function resolveVal(v, scope, root, resolving, resolvedCache, opts) {
-  if (isSubst(v)) return resolveSubst(v, scope, root, resolving, resolvedCache, opts);
-  if (isConcat(v)) return resolveConcat(v.nodes, scope, root, resolving, resolvedCache, opts);
-  if (isAppend(v)) return resolveAppend(v, scope, root, resolving, resolvedCache, opts);
-  if (isResObj(v)) return resolveResObj(v, root, resolving, resolvedCache, opts);
-  const hv = v;
-  if (hv.kind === "array") {
-    return {
-      kind: "array",
-      items: hv.items.map(
-        (item) => resolveVal(item, scope, root, resolving, resolvedCache, opts) ?? { kind: "scalar", value: null }
-      )
-    };
-  }
-  return hv;
-}
-function resolveSubst(s, scope, root, resolving, resolvedCache, opts) {
-  if (resolvedCache.has(s.path)) return resolvedCache.get(s.path);
-  if (resolving.has(s.path)) {
-    const rootSeg = parseSubstPath(s.path)[0] ?? "";
-    const prior = scope.priorValues.get(rootSeg) ?? root.priorValues.get(rootSeg);
-    if (prior !== void 0) {
-      return resolveVal(prior, scope, root, new Set(resolving), resolvedCache, opts);
-    }
-    if (s.optional) return void 0;
-    throw new ResolveError(`circular substitution: ${s.path}`, s.path, s.line, s.col);
-  }
-  resolving.add(s.path);
-  try {
-    const found = lookupPath(root, parseSubstPath(s.path));
-    if (found !== void 0) {
-      if (isSubst(found) || isConcat(found)) {
-        const rootSeg = parseSubstPath(s.path)[0] ?? "";
-        const prior = scope.priorValues.get(rootSeg) ?? root.priorValues.get(rootSeg);
-        if (prior !== void 0) {
-          const result2 = resolveVal(prior, scope, root, resolving, resolvedCache, opts);
-          if (result2 !== void 0) resolvedCache.set(s.path, result2);
-          return result2;
-        }
+  async applyFieldAsync(obj, field, pathPrefix) {
+    if (field.key.length === 0 && field.value.kind === "include") {
+      const included = await this.loader.loadAsync(field.value.path, field.value.required, field.value.isFile);
+      if (pathPrefix.length > 0) {
+        this.relativizeResObj(included, pathPrefix);
       }
-      const result = resolveVal(found, scope, root, resolving, resolvedCache, opts);
-      if (result !== void 0) resolvedCache.set(s.path, result);
-      return result;
+      deepMergeResObjInto(obj, included);
+      return;
+    }
+    const [head, ...tail] = field.key;
+    if (head === void 0) return;
+    if (tail.length > 0) {
+      const syntheticAst = {
+        kind: "object",
+        fields: [{ key: tail, value: field.value, append: field.append, pos: field.pos }],
+        pos: field.pos
+      };
+      await this.applyFieldAsync(obj, { key: [head], value: syntheticAst, append: false, pos: field.pos }, pathPrefix);
+      return;
     }
-    const envVal = opts.env[s.path];
-    if (envVal !== void 0) {
-      const result = { kind: "scalar", value: envVal };
-      resolvedCache.set(s.path, result);
-      return result;
+    const childPrefix = [...pathPrefix, head];
+    if (field.append) {
+      const existing2 = obj.fields.get(head) ?? { kind: "array", items: [] };
+      obj.priorValues.set(head, existing2);
+      obj.fields.set(head, {
+        _kind: "append-placeholder",
+        existing: existing2,
+        elem: await this.astToResolverValueAsync(field.value, childPrefix)
+      });
+      return;
+    }
+    const existing = obj.fields.get(head);
+    const newVal = await this.astToResolverValueAsync(field.value, childPrefix);
+    if (existing !== void 0) {
+      obj.priorValues.set(head, existing);
+    }
+    if (existing !== void 0 && isResObj(existing) && isResObj(newVal)) {
+      deepMergeResObjInto(existing, newVal);
+      return;
+    }
+    obj.fields.set(head, newVal);
+  }
+  astToResolverValue(ast, pathPrefix) {
+    switch (ast.kind) {
+      case "scalar": {
+        const sv = { kind: "scalar", raw: ast.raw, valueType: ast.valueType };
+        if (ast._separator) separatorValues.add(sv);
+        return sv;
+      }
+      case "array":
+        return { kind: "array", items: ast.items.map((i) => this.astToResolverValue(i, pathPrefix)) };
+      case "object": {
+        const inner = this.build(ast, pathPrefix);
+        return inner;
+      }
+      case "subst":
+        return { _kind: "subst-placeholder", segments: ast.segments, optional: ast.optional, line: ast.pos.line, col: ast.pos.col, prefixLen: 0 };
+      case "concat":
+        return { _kind: "concat-placeholder", nodes: ast.nodes.map((n) => this.astToResolverValue(n, pathPrefix)) };
+      case "include":
+        return { kind: "scalar", raw: "null", valueType: "null" };
     }
-    if (s.optional) return void 0;
-    throw new ResolveError(`could not resolve substitution: \${${s.path}}`, s.path, s.line, s.col);
-  } finally {
-    resolving.delete(s.path);
   }
-}
-function resolveConcat(nodes, scope, root, resolving, resolvedCache, opts) {
-  const resolved = nodes.map((n) => resolveVal(n, scope, root, resolving, resolvedCache, opts)).filter((v) => v !== void 0);
-  if (resolved.length === 0) return { kind: "scalar", value: null };
-  if (resolved.length === 1) return resolved[0];
-  const nonSep = resolved.filter((v) => !separatorValues.has(v));
-  if (nonSep.length > 0 && nonSep.every((v) => v.kind === "object")) {
-    const merged = /* @__PURE__ */ new Map();
-    for (const v of nonSep) {
-      if (v.kind === "object") {
-        for (const [k, val] of v.fields) {
-          const existing = merged.get(k);
-          if (existing?.kind === "object" && val.kind === "object") {
-            merged.set(k, deepMergeHoconValues(existing, val));
-          } else {
-            merged.set(k, val);
-          }
+  async astToResolverValueAsync(ast, pathPrefix) {
+    switch (ast.kind) {
+      case "scalar": {
+        const sv = { kind: "scalar", raw: ast.raw, valueType: ast.valueType };
+        if (ast._separator) separatorValues.add(sv);
+        return sv;
+      }
+      case "array": {
+        const items = [];
+        for (const i of ast.items) {
+          items.push(await this.astToResolverValueAsync(i, pathPrefix));
         }
+        return { kind: "array", items };
       }
+      case "object":
+        return await this.buildAsync(ast, pathPrefix);
+      case "subst":
+        return { _kind: "subst-placeholder", segments: ast.segments, optional: ast.optional, line: ast.pos.line, col: ast.pos.col, prefixLen: 0 };
+      case "concat": {
+        const nodes = [];
+        for (const n of ast.nodes) {
+          nodes.push(await this.astToResolverValueAsync(n, pathPrefix));
+        }
+        return { _kind: "concat-placeholder", nodes };
+      }
+      case "include":
+        return { kind: "scalar", raw: "null", valueType: "null" };
     }
-    return { kind: "object", fields: merged };
   }
-  if (resolved.some((v) => v.kind === "array")) {
-    const items = [];
-    for (const v of resolved) {
-      if (v.kind === "array") items.push(...v.items);
-      else items.push(v);
+  // ---- Relativize substitution paths for nested includes ----
+  relativizeSubstPaths(val, prefixSegments) {
+    if (isSubst(val)) {
+      const prefixAsSegments = prefixSegments.map((text) => ({ text, line: 0, col: 0 }));
+      val.segments = [...prefixAsSegments, ...val.segments];
+      val.prefixLen += prefixSegments.length;
+      return;
     }
-    return { kind: "array", items };
-  }
-  const str = resolved.map((v) => v.kind === "scalar" ? String(v.value) : JSON.stringify(v)).join("");
-  return { kind: "scalar", value: str };
-}
-function deepMergeHoconValues(base, overlay) {
-  const merged = new Map(base.fields);
-  for (const [k, v] of overlay.fields) {
-    const existing = merged.get(k);
-    if (existing?.kind === "object" && v.kind === "object") {
-      merged.set(k, deepMergeHoconValues(existing, v));
-    } else {
-      merged.set(k, v);
+    if (isConcat(val)) {
+      for (const node of val.nodes) {
+        this.relativizeSubstPaths(node, prefixSegments);
+      }
+      return;
     }
-  }
-  return { kind: "object", fields: merged };
-}
-function resolveAppend(a, scope, root, resolving, resolvedCache, opts) {
-  const existing = resolveVal(a.existing, scope, root, resolving, resolvedCache, opts) ?? { kind: "array", items: [] };
-  const elem = resolveVal(a.elem, scope, root, resolving, resolvedCache, opts);
-  const items = existing.kind === "array" ? [...existing.items] : [existing];
-  if (elem !== void 0) items.push(elem);
-  return { kind: "array", items };
-}
-function lookupPath(root, segments) {
-  const [head, ...tail] = segments;
-  if (head === void 0 || head === "") {
-    if (segments.length > 0) {
-      const val2 = root.fields.get("");
-      if (val2 === void 0) return void 0;
-      if (tail.length === 0) return val2;
-      if (isResObj(val2)) return lookupPath(val2, tail);
-      return void 0;
+    if (isAppend(val)) {
+      this.relativizeSubstPaths(val.existing, prefixSegments);
+      this.relativizeSubstPaths(val.elem, prefixSegments);
+      return;
     }
-    return void 0;
-  }
-  const val = root.fields.get(head);
-  if (val === void 0) return void 0;
-  if (tail.length === 0) return val;
-  if (isResObj(val)) return lookupPath(val, tail);
-  return void 0;
-}
-function parseSubstPath(raw) {
-  const segments = [];
-  let i = 0;
-  while (i < raw.length) {
-    while (i < raw.length && (raw[i] === " " || raw[i] === "	")) i++;
-    if (i >= raw.length) break;
-    if (raw[i] === '"') {
-      i++;
-      let seg = "";
-      while (i < raw.length && raw[i] !== '"') {
-        seg += raw[i];
-        i++;
-      }
-      if (i < raw.length) i++;
-      segments.push(seg);
-      while (i < raw.length && (raw[i] === " " || raw[i] === "	")) i++;
-      if (i < raw.length && raw[i] === ".") i++;
-    } else if (raw[i] === ".") {
-      segments.push("");
-      i++;
-    } else {
-      let seg = "";
-      while (i < raw.length && raw[i] !== ".") {
-        seg += raw[i];
-        i++;
+    if (isResObj(val)) {
+      this.relativizeResObj(val, prefixSegments);
+      return;
+    }
+    const hv = val;
+    if (hv.kind === "array") {
+      for (const item of hv.items) {
+        this.relativizeSubstPaths(item, prefixSegments);
       }
-      segments.push(seg.trim());
-      if (i < raw.length && raw[i] === ".") i++;
     }
   }
-  return segments;
-}
-function isFileNotFoundError(e) {
-  if (!(e instanceof Error)) return false;
-  const code = e.code;
-  if (code === "ENOENT" || code === "MODULE_NOT_FOUND") return true;
-  const msg = e.message.toLowerCase();
-  return msg.includes("not found") || msg.includes("no such file") || msg.includes("enoent");
-}
-function loadSingleInclude(candidate, opts) {
-  const { readFileSync: readFileSync2, includeStack = [], env } = opts;
-  if (includeStack.includes(candidate)) {
-    throw new ResolveError(`circular include: ${candidate}`, candidate, 0, 0);
-  }
-  let content;
-  try {
-    content = readFileSync2(candidate);
-  } catch (e) {
-    if (isFileNotFoundError(e)) return void 0;
-    throw e;
-  }
-  if (candidate.endsWith(".properties")) {
-    return hoconValueToResObj(propertiesToHoconValue(content));
-  }
-  const ast = parseTokens(tokenize(content));
-  return buildResObj(ast, {
-    env,
-    baseDir: nodePath.dirname(candidate),
-    readFileSync: readFileSync2,
-    includeStack: [...includeStack, candidate]
-  });
-}
-function loadInclude(includePath, required, opts) {
-  const { baseDir, includeStack = [] } = opts;
-  const absPath = baseDir ? nodePath.resolve(baseDir, includePath) : nodePath.resolve(includePath);
-  if (includeStack.includes(absPath)) {
-    throw new ResolveError(`circular include: ${absPath}`, absPath, 0, 0);
-  }
-  if (includeStack.length >= 50) {
-    throw new ResolveError(`include depth limit exceeded (max 50)`, includePath, 0, 0);
-  }
-  const hasExplicitExt = absPath.endsWith(".conf") || absPath.endsWith(".json") || absPath.endsWith(".properties");
-  if (hasExplicitExt) {
-    const result = loadSingleInclude(absPath, opts);
-    if (result !== void 0) return result;
-    if (required) {
-      throw new ResolveError(`required include file not found: ${includePath}`, includePath, 0, 0);
+  relativizeResObj(obj, prefixSegments) {
+    for (const val of obj.fields.values()) {
+      this.relativizeSubstPaths(val, prefixSegments);
     }
-    return makeResObj();
-  }
-  const merged = makeResObj();
-  let foundAny = false;
-  const probeExts = [".properties", ".json", ".conf"];
-  for (const ext of probeExts) {
-    const obj = loadSingleInclude(`${absPath}${ext}`, opts);
-    if (obj !== void 0) {
-      deepMergeResObjInto(merged, obj);
-      foundAny = true;
+    for (const val of obj.priorValues.values()) {
+      this.relativizeSubstPaths(val, prefixSegments);
     }
   }
-  if (!foundAny && required) {
-    throw new ResolveError(`required include file not found: ${includePath}`, includePath, 0, 0);
-  }
-  return merged;
-}
-async function buildResObjAsync(ast, opts) {
-  if (ast.kind !== "object") {
-    throw new ResolveError("root AST must be an object", "", ast.pos.line, ast.pos.col);
-  }
-  const obj = makeResObj();
-  for (const field of ast.fields) {
-    await applyFieldAsync(obj, field, opts);
-  }
-  return obj;
-}
-async function applyFieldAsync(obj, field, opts) {
-  if (field.key.length === 0 && field.value.kind === "include") {
-    const included = await loadIncludeAsync(field.value.path, field.value.required, opts);
-    deepMergeResObjInto(obj, included);
-    return;
-  }
-  const [head, ...tail] = field.key;
-  if (!head) return;
-  if (tail.length > 0) {
-    const syntheticAst = {
-      kind: "object",
-      fields: [{ key: tail, value: field.value, append: field.append, pos: field.pos }],
-      pos: field.pos
-    };
-    await applyFieldAsync(obj, { key: [head], value: syntheticAst, append: false, pos: field.pos }, opts);
-    return;
-  }
-  if (field.append) {
-    const existing2 = obj.fields.get(head) ?? { kind: "array", items: [] };
-    obj.priorValues.set(head, existing2);
-    obj.fields.set(head, {
-      _kind: "append-placeholder",
-      existing: existing2,
-      elem: await astToResolverValueAsync(field.value, opts)
-    });
-    return;
-  }
-  const existing = obj.fields.get(head);
-  const newVal = await astToResolverValueAsync(field.value, opts);
-  if (existing !== void 0) {
-    obj.priorValues.set(head, existing);
-  }
-  if (existing !== void 0 && isResObj(existing) && isResObj(newVal)) {
-    deepMergeResObjInto(existing, newVal);
-    return;
-  }
-  obj.fields.set(head, newVal);
-}
-async function astToResolverValueAsync(ast, opts) {
-  switch (ast.kind) {
-    case "scalar": {
-      const sv = { kind: "scalar", value: ast.value };
-      if (ast._separator) separatorValues.add(sv);
-      return sv;
-    }
-    case "array": {
-      const items = [];
-      for (const i of ast.items) {
-        items.push(await astToResolverValueAsync(i, opts));
+};
+
+// src/internal/resolver/substitution-resolver.ts
+var SubstitutionResolver = class {
+  constructor(root, opts) {
+    this.root = root;
+    this.opts = opts;
+    this.resolving = /* @__PURE__ */ new Set();
+    this.cache = /* @__PURE__ */ new Map();
+  }
+  resolve() {
+    return this.resolveResObj(this.root);
+  }
+  resolveResObj(obj) {
+    const result = /* @__PURE__ */ new Map();
+    for (const [key, val] of obj.fields) {
+      const resolved = this.resolveVal(val, obj);
+      if (resolved !== void 0) {
+        if (resolved.kind === "object") {
+          const prior = obj.priorValues.get(key);
+          if (prior !== void 0) {
+            const priorResolved = this.resolveVal(prior, obj);
+            if (priorResolved !== void 0 && priorResolved.kind === "object") {
+              result.set(
+                key,
+                deepMergeHoconValues(
+                  priorResolved,
+                  resolved
+                )
+              );
+              continue;
+            }
+          }
+        }
+        result.set(key, resolved);
+      } else {
+        const prior = obj.priorValues.get(key);
+        if (prior !== void 0) {
+          const priorResolved = this.resolveVal(prior, obj);
+          if (priorResolved !== void 0) result.set(key, priorResolved);
+        }
+      }
+    }
+    return { kind: "object", fields: result };
+  }
+  resolveVal(v, scope) {
+    if (isSubst(v)) return this.resolveSubst(v, scope);
+    if (isConcat(v)) return this.resolveConcat(v.nodes, scope);
+    if (isAppend(v)) return this.resolveAppend(v, scope);
+    if (isResObj(v)) return this.resolveResObj(v);
+    const hv = v;
+    if (hv.kind === "array") {
+      return {
+        kind: "array",
+        items: hv.items.map(
+          (item) => this.resolveVal(item, scope) ?? { kind: "scalar", raw: "null", valueType: "null" }
+        )
+      };
+    }
+    return hv;
+  }
+  segmentsEqual(a, b) {
+    return a.length === b.length && a.every((seg, i) => seg.text === b[i]?.text);
+  }
+  resolveSubst(s, scope) {
+    const key = segmentsToKey(s.segments);
+    if (this.cache.has(key)) return this.cache.get(key);
+    if (this.resolving.has(key)) {
+      let prior;
+      if (s.prefixLen > 0) {
+        const leafSeg = s.segments[s.segments.length - 1]?.text ?? "";
+        const parentScope = lookupResObj(
+          this.root,
+          s.segments.slice(0, s.segments.length - 1)
+        );
+        prior = parentScope?.priorValues.get(leafSeg);
+      } else {
+        const rootSeg = s.segments[0]?.text ?? "";
+        prior = scope.priorValues.get(rootSeg) ?? this.root.priorValues.get(rootSeg);
       }
-      return { kind: "array", items };
-    }
-    case "object":
-      return await buildResObjAsync(ast, opts);
-    case "subst":
-      return { _kind: "subst-placeholder", path: ast.path, optional: ast.optional, line: ast.pos.line, col: ast.pos.col };
-    case "concat": {
-      const nodes = [];
-      for (const n of ast.nodes) {
-        nodes.push(await astToResolverValueAsync(n, opts));
+      if (prior !== void 0) {
+        const saved = this.resolving;
+        this.resolving = new Set(saved);
+        try {
+          return this.resolveVal(prior, scope);
+        } finally {
+          this.resolving = saved;
+        }
       }
-      return { _kind: "concat-placeholder", nodes };
+      if (s.optional) return void 0;
+      throw new ResolveError(
+        `circular substitution: ${key}`,
+        key,
+        s.line,
+        s.col
+      );
     }
-    case "include":
-      return { kind: "scalar", value: null };
-  }
-}
-async function loadSingleIncludeAsync(candidate, opts) {
-  const { readFile, readFileSync: readFileSync2, includeStack = [], env } = opts;
-  const read = readFile ? async (p) => readFile(p) : async (p) => readFileSync2(p);
-  if (includeStack.includes(candidate)) {
-    throw new ResolveError(`circular include: ${candidate}`, candidate, 0, 0);
-  }
-  let content;
-  try {
-    content = await read(candidate);
-  } catch (e) {
-    if (isFileNotFoundError(e)) return void 0;
-    throw e;
-  }
-  if (candidate.endsWith(".properties")) {
-    return hoconValueToResObj(propertiesToHoconValue(content));
-  }
-  const ast = parseTokens(tokenize(content));
-  return buildResObjAsync(ast, {
-    env,
-    baseDir: nodePath.dirname(candidate),
-    readFileSync: readFileSync2,
-    readFile,
-    includeStack: [...includeStack, candidate]
-  });
-}
-async function loadIncludeAsync(includePath, required, opts) {
-  const { baseDir, includeStack = [] } = opts;
-  const absPath = baseDir ? nodePath.resolve(baseDir, includePath) : nodePath.resolve(includePath);
-  if (includeStack.includes(absPath)) {
-    throw new ResolveError(`circular include: ${absPath}`, absPath, 0, 0);
-  }
-  if (includeStack.length >= 50) {
-    throw new ResolveError(`include depth limit exceeded (max 50)`, includePath, 0, 0);
-  }
-  const hasExplicitExt = absPath.endsWith(".conf") || absPath.endsWith(".json") || absPath.endsWith(".properties");
-  if (hasExplicitExt) {
-    const result = await loadSingleIncludeAsync(absPath, opts);
-    if (result !== void 0) return result;
-    if (required) {
-      throw new ResolveError(`required include file not found: ${includePath}`, includePath, 0, 0);
+    this.resolving.add(key);
+    try {
+      const found = lookupPath(this.root, s.segments);
+      if (found !== void 0) {
+        if (isSubst(found) || isConcat(found)) {
+          const isSelfRef = isSubst(found) ? this.segmentsEqual(found.segments, s.segments) : isConcat(found) && found.nodes.some(
+            (n) => isSubst(n) && this.segmentsEqual(n.segments, s.segments)
+          );
+          if (isSelfRef) {
+            let prior;
+            if (s.prefixLen > 0) {
+              const leafSeg = s.segments[s.segments.length - 1]?.text ?? "";
+              const parentScope = lookupResObj(
+                this.root,
+                s.segments.slice(0, s.segments.length - 1)
+              );
+              prior = parentScope?.priorValues.get(leafSeg);
+            } else {
+              const rootSeg = s.segments[0]?.text ?? "";
+              prior = scope.priorValues.get(rootSeg) ?? this.root.priorValues.get(rootSeg);
+            }
+            if (prior !== void 0) {
+              const result2 = this.resolveVal(prior, scope);
+              if (result2 !== void 0) this.cache.set(key, result2);
+              return result2;
+            }
+          }
+        }
+        let result = this.resolveVal(found, scope);
+        const effectiveLen = s.segments.length - s.prefixLen;
+        if (effectiveLen === 1 && result !== void 0 && result.kind === "object") {
+          const leafSeg = s.segments[s.segments.length - 1]?.text ?? "";
+          let prior;
+          if (s.prefixLen > 0) {
+            const parentScope = lookupResObj(
+              this.root,
+              s.segments.slice(0, s.segments.length - 1)
+            );
+            prior = parentScope?.priorValues.get(leafSeg);
+          } else {
+            prior = scope.priorValues.get(leafSeg) ?? this.root.priorValues.get(leafSeg);
+          }
+          if (prior !== void 0) {
+            const priorResolved = this.resolveVal(prior, scope);
+            if (priorResolved !== void 0 && priorResolved.kind === "object") {
+              result = deepMergeHoconValues(
+                priorResolved,
+                result
+              );
+            }
+          }
+        }
+        if (result !== void 0) this.cache.set(key, result);
+        return result;
+      }
+      const envKey = s.segments.map((seg) => seg.text).join(".");
+      const envVal = this.opts.env[envKey] ?? (s.prefixLen > 0 ? this.opts.env[s.segments.slice(s.prefixLen).map((seg) => seg.text).join(".")] : void 0);
+      if (envVal !== void 0) {
+        const result = { kind: "scalar", raw: envVal, valueType: "string" };
+        this.cache.set(key, result);
+        return result;
+      }
+      if (s.optional) return void 0;
+      throw new ResolveError(
+        `could not resolve substitution: \${${key}}`,
+        key,
+        s.line,
+        s.col
+      );
+    } finally {
+      this.resolving.delete(key);
     }
-    return makeResObj();
   }
-  const merged = makeResObj();
-  let foundAny = false;
-  const probeExts = [".properties", ".json", ".conf"];
-  for (const ext of probeExts) {
-    const obj = await loadSingleIncludeAsync(`${absPath}${ext}`, opts);
-    if (obj !== void 0) {
-      deepMergeResObjInto(merged, obj);
-      foundAny = true;
+  resolveConcat(nodes, scope) {
+    const resolved = nodes.map((n) => this.resolveVal(n, scope)).filter((v) => v !== void 0);
+    if (resolved.length === 0) return { kind: "scalar", raw: "null", valueType: "null" };
+    if (resolved.length === 1) return resolved[0];
+    const nonSep = resolved.filter((v) => !separatorValues.has(v));
+    if (nonSep.length === 0) {
+      const str = resolved.map((v) => v.kind === "scalar" ? v.raw : JSON.stringify(v)).join("");
+      return { kind: "scalar", raw: str, valueType: "string" };
     }
+    const joinPair = (left, right) => {
+      if (left.kind === "object" && right.kind === "object") {
+        return deepMergeHoconValues(left, right);
+      }
+      if (left.kind === "array" && right.kind === "object") {
+        const converted = numericObjectToArray(right);
+        if (converted !== null) {
+          return { kind: "array", items: [...left.items, ...converted] };
+        }
+        return { kind: "array", items: [...left.items, right] };
+      }
+      if (left.kind === "object" && right.kind === "array") {
+        const converted = numericObjectToArray(left);
+        if (converted !== null) {
+          return { kind: "array", items: [...converted, ...right.items] };
+        }
+        return { kind: "array", items: [left, ...right.items] };
+      }
+      if (left.kind === "array" && right.kind === "array") {
+        return { kind: "array", items: [...left.items, ...right.items] };
+      }
+      if (left.kind === "array") {
+        return { kind: "array", items: [...left.items, right] };
+      }
+      if (right.kind === "array") {
+        return { kind: "array", items: [left, ...right.items] };
+      }
+      const leftStr = left.kind === "scalar" ? left.raw : JSON.stringify(left);
+      const rightStr = right.kind === "scalar" ? right.raw : JSON.stringify(right);
+      return { kind: "scalar", raw: leftStr + rightStr, valueType: "string" };
+    };
+    const [head, ...tail] = nonSep;
+    const folded = tail.reduce(joinPair, head);
+    if (folded.kind === "scalar") {
+      const str = resolved.map((v) => v.kind === "scalar" ? v.raw : JSON.stringify(v)).join("");
+      return { kind: "scalar", raw: str, valueType: "string" };
+    }
+    return folded;
   }
-  if (!foundAny && required) {
-    throw new ResolveError(`required include file not found: ${includePath}`, includePath, 0, 0);
+  resolveAppend(a, scope) {
+    const existing = this.resolveVal(a.existing, scope) ?? { kind: "array", items: [] };
+    const elem = this.resolveVal(a.elem, scope);
+    const items = existing.kind === "array" ? [...existing.items] : [existing];
+    if (elem !== void 0) items.push(elem);
+    return { kind: "array", items };
   }
-  return merged;
+};
+
+// src/internal/resolver/resolver.ts
+function resolve2(ast, opts) {
+  const root = new StructureBuilder(opts).build(ast);
+  return new SubstitutionResolver(root, opts).resolve();
+}
+async function resolveAsync(ast, opts) {
+  const root = await new StructureBuilder(opts).buildAsync(ast);
+  return new SubstitutionResolver(root, opts).resolve();
 }
 
 // src/parse.ts