@o3co/ts.hocon 1.2.0 → 1.4.0

package/dist/index.js

@@ -1,5 +1,26 @@
 // src/coerce.ts
 var DECIMAL_NUMBER_RE = /^-?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/;
+function isHoconWs(cp) {
+  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 trimHoconWs(s) {
+  let start = 0;
+  let end = s.length;
+  while (start < end && isHoconWs(s.charCodeAt(start))) {
+    start++;
+  }
+  while (end > start && isHoconWs(s.charCodeAt(end - 1))) {
+    end--;
+  }
+  return s.slice(start, end);
+}
 var TRUTHY = /* @__PURE__ */ new Set(["true", "yes", "on"]);
 var FALSY = /* @__PURE__ */ new Set(["false", "no", "off"]);
 function coerceBoolean(value) {
@@ -45,22 +66,29 @@ var OUTPUT_DURATION_UNITS = {
   d: 864e5
 };
 function parseDuration(value, outputUnit = "ms") {
-  const trimmed = value.trim();
+  const trimmed = trimHoconWs(value);
   let i = 0;
   while (i < trimmed.length) {
     const ch = trimmed[i];
-    if (ch !== "-" && ch !== "." && (ch < "0" || ch > "9")) break;
+    if (i === 0 && (ch === "-" || ch === "+")) {
+      i++;
+      continue;
+    }
+    if (ch !== "." && (ch < "0" || ch > "9")) break;
     i++;
   }
   if (i === 0) return NaN;
   const num = Number(trimmed.slice(0, i));
   if (Number.isNaN(num)) return NaN;
-  const unit = trimmed.slice(i).trim().toLowerCase();
+  const unit = trimHoconWs(trimmed.slice(i)).toLowerCase();
+  const divisor = OUTPUT_DURATION_UNITS[outputUnit];
+  if (divisor === void 0) return NaN;
+  if (unit === "") {
+    return num / divisor;
+  }
   const mult = DURATION_UNITS[unit];
   if (mult === void 0) return NaN;
   const ms = num * mult;
-  const divisor = OUTPUT_DURATION_UNITS[outputUnit];
-  if (divisor === void 0) return NaN;
   return ms / divisor;
 }
 var BYTE_UNITS = {
@@ -91,6 +119,22 @@ var BYTE_UNITS = {
   TiB: 1099511627776,
   tebibyte: 1099511627776,
   tebibytes: 1099511627776,
+  // S21.4 — HOCON.md L1385: single-letter abbreviations → powers of two (java -Xmx convention).
+  // Lightbend typesafe-config 1.4.3 verified: 1K=1024, 1M=1048576, etc.
+  // Both upper- and lowercase accepted per Lightbend behaviour.
+  // Z/Y (2^70/2^80) are deferred — they overflow MAX_SAFE_INTEGER and require BigInt accessor.
+  K: 1024,
+  k: 1024,
+  M: 1024 ** 2,
+  m: 1024 ** 2,
+  G: 1024 ** 3,
+  g: 1024 ** 3,
+  T: 1024 ** 4,
+  t: 1024 ** 4,
+  P: 1024 ** 5,
+  p: 1024 ** 5,
+  E: 1024 ** 6,
+  e: 1024 ** 6,
   // lowercase short-form aliases
   b: 1,
   kb: 1e3,
@@ -114,25 +158,39 @@ var OUTPUT_BYTE_UNITS = {
   TiB: 1099511627776
 };
 function parseBytes(value, outputUnit = "B") {
-  const trimmed = value.trim();
+  const trimmed = trimHoconWs(value);
   let i = 0;
   while (i < trimmed.length) {
     const ch = trimmed[i];
-    if (ch !== "-" && ch !== "." && (ch < "0" || ch > "9")) break;
+    if (i === 0 && (ch === "-" || ch === "+")) {
+      i++;
+      continue;
+    }
+    if (ch !== "." && (ch < "0" || ch > "9")) break;
     i++;
   }
   if (i === 0) return NaN;
   const num = Number(trimmed.slice(0, i));
   if (Number.isNaN(num)) return NaN;
-  const unit = trimmed.slice(i).trim();
+  const unit = trimHoconWs(trimmed.slice(i));
+  const divisor = OUTPUT_BYTE_UNITS[outputUnit];
+  if (divisor === void 0) return NaN;
+  if (unit === "") {
+    const bytes2 = Math.trunc(num);
+    if (Math.abs(bytes2) > Number.MAX_SAFE_INTEGER) {
+      throw new RangeError("byte size overflows representable range (max 2^53-1 bytes)");
+    }
+    return bytes2 / divisor;
+  }
   let mult = BYTE_UNITS[unit];
   if (mult === void 0) {
     mult = BYTE_UNITS[unit.toLowerCase()];
   }
   if (mult === void 0) return NaN;
   const bytes = num * mult;
-  const divisor = OUTPUT_BYTE_UNITS[outputUnit];
-  if (divisor === void 0) return NaN;
+  if (Math.abs(bytes) > Number.MAX_SAFE_INTEGER) {
+    throw new RangeError("byte size overflows representable range (max 2^53-1 bytes)");
+  }
   const result = bytes / divisor;
   return outputUnit === "B" ? Math.round(result) : result;
 }
@@ -157,6 +215,14 @@ var ResolveError = class extends Error {
     this.name = "ResolveError";
   }
 };
+var PackageLookupError = class extends ResolveError {
+  constructor(message, identifier, packageFile, line, col) {
+    super(message, `${identifier}/${packageFile}`, line, col);
+    this.identifier = identifier;
+    this.packageFile = packageFile;
+    this.name = "PackageLookupError";
+  }
+};
 var ConfigError = class extends Error {
   constructor(message, path2) {
     super(message);
@@ -164,190 +230,155 @@ var ConfigError = class extends Error {
     this.name = "ConfigError";
   }
 };
-
-// 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 });
+var NotResolvedError = class extends ConfigError {
+  constructor(path2) {
+    super(`value at path "${path2}" is not resolved (call resolve() first)`, path2);
+    this.name = "NotResolvedError";
   }
-  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) {
-    this.root = root;
-  }
-  get(path2) {
-    const v = this.lookupNode(path2);
-    if (v === void 0) return void 0;
-    return hoconToJs(v);
-  }
-  getString(path2) {
-    const v = this.requireScalar(path2);
-    return v.raw;
-  }
-  getNumber(path2) {
-    const v = this.requireScalar(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);
-    const coerced = coerceBoolean(v.raw);
-    if (coerced !== void 0) return coerced;
-    throw new ConfigError(`expected boolean at ${path2}, got ${v.valueType}`, path2);
+// 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() };
+}
+function mergeUnresolved(receiver, fallback) {
+  const result = makeResObj();
+  for (const [k, v] of fallback.fields) {
+    result.fields.set(k, v);
   }
-  getDuration(path2, unit) {
-    const v = this.requireScalar(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;
+  for (const [k, v] of fallback.priorValues) {
+    result.priorValues.set(k, v);
   }
-  getBytes(path2, unit) {
-    const v = this.requireScalar(path2);
-    if (v.valueType !== "string" && v.valueType !== "number") {
-      throw new ConfigError(`expected byte size at ${path2}, got ${v.valueType}`, path2);
+  for (const [k, rv] of receiver.fields) {
+    const existing = result.fields.get(k);
+    if (existing !== void 0) {
+      const recPrior = receiver.priorValues.get(k);
+      if (recPrior !== void 0 && !isResObj(recPrior)) {
+        result.fields.set(k, rv);
+        continue;
+      }
+      if (isResObj(rv) && isResObj(existing)) {
+        result.fields.set(k, mergeUnresolved(rv, existing));
+        continue;
+      }
+      result.priorValues.set(k, existing);
     }
-    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) {
-    const v = this.lookupNode(path2);
-    if (v === void 0) throw new ConfigError(`path not found: ${path2}`, path2);
-    if (v.kind !== "object") throw new ConfigError(`expected object at ${path2}`, path2);
-    return new _Config(v);
+    result.fields.set(k, rv);
   }
-  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);
+  for (const [k, v] of receiver.priorValues) {
+    if (receiver.fields.has(k)) {
+      result.priorValues.set(k, v);
     }
-    if (v.kind !== "array") throw new ConfigError(`expected array at ${path2}`, path2);
-    return v.items.map(hoconToJs);
-  }
-  has(path2) {
-    return this.lookupNode(path2) !== void 0;
-  }
-  keys() {
-    return [...this.root.fields.keys()];
-  }
-  withFallback(fallback) {
-    const merged = deepMergeHocon(this.root, fallback.root);
-    return new _Config(merged);
-  }
-  toObject() {
-    return hoconToJs(this.root);
   }
-  lookupNode(path2) {
-    const segments = splitConfigPath(path2);
-    let current = this.root;
-    for (const seg of segments) {
-      if (current.kind !== "object") return void 0;
-      const next = current.fields.get(seg);
-      if (next === void 0) return void 0;
-      current = next;
+  return result;
+}
+
+// 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 current;
-  }
-  requireScalar(path2) {
-    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;
+    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;
   }
-};
-function splitConfigPath(path2) {
-  const segments = [];
-  let i = 0;
-  while (i < path2.length) {
-    if (path2[i] === '"') {
-      i++;
-      let segment = "";
-      let closed = false;
-      while (i < path2.length) {
-        const ch = path2[i];
-        if (ch === "\\" && i + 1 < path2.length) {
-          const next = path2[i + 1];
-          segment += next;
-          i += 2;
-          continue;
-        }
-        if (ch === '"') {
-          closed = true;
-          i++;
-          break;
-        }
-        segment += ch;
-        i++;
-      }
-      if (!closed) throw new ConfigError(`unterminated quoted path segment: ${path2}`, path2);
-      segments.push(segment);
-      if (i < path2.length && path2[i] === ".") i++;
+  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 {
-      const dot = path2.indexOf(".", i);
-      if (dot === -1) {
-        segments.push(path2.slice(i));
-        break;
-      }
-      segments.push(path2.slice(i, dot));
-      i = dot + 1;
+      merged.set(k, v);
     }
   }
-  return segments;
+  return { kind: "object", fields: merged };
 }
-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 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);
+    }
   }
-}
-function hoconToJs(v) {
-  switch (v.kind) {
-    case "scalar":
-      return scalarToJs(v.raw, v.valueType);
-    case "array":
-      return v.items.map(hoconToJs);
-    case "object": {
-      const obj = {};
-      for (const [k, val] of v.fields) obj[k] = hoconToJs(val);
-      return obj;
+  for (const [k, srcPrior] of src.priorValues) {
+    if (!dst.priorValues.has(k)) {
+      dst.priorValues.set(k, srcPrior);
     }
   }
 }
-function deepMergeHocon(receiver, fallback) {
-  const merged = new Map(fallback.fields);
-  for (const [k, v] of receiver.fields) {
-    const fb = merged.get(k);
-    if (fb?.kind === "object" && v.kind === "object") {
-      merged.set(k, deepMergeHocon(v, fb));
+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 {
-      merged.set(k, v);
+      obj.fields.set(key, val);
     }
   }
-  return { kind: "object", fields: merged };
+  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/include-loader.ts
+import { createRequire } from "module";
+import * as nodePath from "path";
+
+// src/internal/parser/empty-check.ts
+function hasContentTokens(tokens) {
+  return tokens.some((t) => t.kind !== "eof" && t.kind !== "newline");
+}
+function assertNonEmptyDocument(tokens, sourceDescriptor) {
+  if (!hasContentTokens(tokens)) {
+    throw new ParseError(
+      `empty file is not a valid HOCON document (HOCON.md L130): ${sourceDescriptor}`,
+      1,
+      1
+    );
+  }
 }
 
 // src/internal/lexer/lexer.ts
@@ -477,14 +508,6 @@ var Lexer = class {
         continue;
       }
       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();
@@ -588,6 +611,10 @@ var Lexer = class {
   /**
    * Parse the body of a `${...}` substitution (called after `${` has been consumed).
    * Implements Appendix A state machine from the cross-language spec.
+   *
+   * S13c extension: if the segment-collection loop encounters `[`, it delegates to
+   * `parseListSuffix()` which consumes the literal `[]` and sets `listSuffix=true`.
+   * ASCII space/tab before `[` is buffered in `pendingWs` and discarded (E7).
    */
   parseSubstBody(startLine, startCol) {
     let optional = false;
@@ -602,6 +629,7 @@ var Lexer = class {
     let pendingWs = "";
     const segments = [];
     let lastDot = null;
+    let listSuffix = false;
     while (true) {
       if (this.pos >= this.input.length) {
         throw new ParseError("unterminated substitution", startLine, startCol);
@@ -611,6 +639,23 @@ var Lexer = class {
         this.advance();
         pendingWs = "";
         break;
+      } else if (ch === "[") {
+        if (!curStarted) {
+          throw new ParseError("empty segment before '[]' suffix in substitution path", startLine, this.col);
+        }
+        for (const w of pendingWs) {
+          if (w !== " " && w !== "	") {
+            throw new ParseError(
+              `only ASCII space or tab allowed between substitution path and '[]' suffix (got ${JSON.stringify(w)}, HOCON extra-spec E7)`,
+              startLine,
+              this.col
+            );
+          }
+        }
+        segments.push({ text: curText, line: curLine, col: curCol });
+        pendingWs = "";
+        listSuffix = this.parseListSuffix(startLine);
+        break;
       } else if (ch === '"') {
         const qLine = startLine;
         const qCol = this.col;
@@ -670,15 +715,47 @@ var Lexer = class {
         throw new ParseError(`unexpected character in substitution path: ${JSON.stringify(ch)}`, startLine, this.col);
       }
     }
-    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);
+    if (!listSuffix) {
+      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, listSuffix };
+  }
+  /**
+   * Consume the literal `[]` suffix inside a substitution body.
+   * Called after the `[` has been detected (but not yet consumed).
+   * Requires the next character to be `[`, then exactly `]`, then `}`.
+   * Whitespace inside `[]` is not permitted (per spec Decision §1).
+   * Returns true (always — only called when listSuffix path is taken).
+   */
+  parseListSuffix(startLine) {
+    this.advance();
+    const afterBracket = this.peek();
+    if (afterBracket !== "]") {
+      const desc = afterBracket === "" ? "EOF" : JSON.stringify(afterBracket);
+      throw new ParseError(
+        `expected ']' after '[' in substitution list suffix (got ${desc})`,
+        startLine,
+        this.col
+      );
+    }
+    this.advance();
+    if (this.peek() !== "}") {
+      const desc = this.peek() === "" ? "EOF" : JSON.stringify(this.peek());
+      throw new ParseError(
+        `expected '}' after '[]' in substitution list suffix (got ${desc})`,
+        startLine,
+        this.col
+      );
     }
-    return { segments, optional };
+    this.advance();
+    return true;
   }
 };
 function tokenize(input) {
@@ -766,6 +843,14 @@ var Parser = class {
       const t = this.peek();
       if (t.kind === "eof" || t.kind === "rbrace") break;
       if (t.kind === "unquoted" && t.value === "include") {
+        const next = this.peek(1);
+        if (next.kind === "equals" || next.kind === "colon" || next.kind === "plus_equals" || next.kind === "lbrace") {
+          throw new ParseError(
+            `'include' is reserved at the start of a key path expression; use "include" (quoted) to use it as a key`,
+            t.line,
+            t.col
+          );
+        }
         this.advance();
         fields.push(this.parseInclude());
         this.skip("newline");
@@ -774,7 +859,14 @@ var Parser = class {
         continue;
       }
       const keyPos = this.currentPos();
-      const key = this.parseKey();
+      const { segments: key, firstWasQuoted } = this.parseKey();
+      if (key[0] === "include" && !firstWasQuoted) {
+        throw new ParseError(
+          `'include' is reserved at the start of a key path expression; use "include".foo (quoted) or rename the key`,
+          keyPos.line,
+          keyPos.col
+        );
+      }
       this.skip("newline");
       let append = false;
       const sep = this.peek();
@@ -804,10 +896,12 @@ var Parser = class {
   parseKey() {
     const segments = [];
     let trailingDot = false;
+    let firstWasQuoted = false;
     while (true) {
       const t = this.peek();
       if (t.kind === "string") {
         this.advance();
+        if (segments.length === 0) firstWasQuoted = true;
         segments.push(t.value);
         trailingDot = false;
       } else if (t.kind === "unquoted") {
@@ -844,64 +938,143 @@ var Parser = class {
       }
       break;
     }
-    return segments;
+    return { segments, firstWasQuoted };
   }
   parseInclude() {
     const p = this.currentPos();
     this.skip("newline");
     const t = this.peek();
-    let path2;
-    let required = false;
-    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("(")) {
+        const next = this.peek(1);
+        if (next.kind !== "unquoted" || !next.value.startsWith("(")) {
           throw new ParseError("include required must be followed by (", t.line, t.col);
         }
       }
-      required = true;
       this.advance();
       const innerPrefix = t.value.startsWith("required(") ? t.value.slice("required(".length) : "";
-      if (innerPrefix.startsWith("url") || innerPrefix.startsWith("classpath")) {
+      if (innerPrefix === "url" || innerPrefix.startsWith("url(") || innerPrefix === "classpath" || innerPrefix.startsWith("classpath(")) {
         throw new ParseError("include url(...) and classpath(...) are not supported", t.line, t.col);
       }
-      if (innerPrefix.startsWith("file")) {
-        isFile = true;
+      const nextTok = this.peek();
+      if (innerPrefix === "package" || innerPrefix.startsWith("package(") || innerPrefix === "" && nextTok.kind === "unquoted" && (nextTok.value === "package(" || nextTok.value.startsWith("package("))) {
+        const consumePackageToken = innerPrefix === "";
+        const { qualifier, path: path3 } = this.parsePackageArgs(consumePackageToken);
+        return this.makeIncludeField(qualifier, path3, true, p);
       }
-      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);
-      }
-      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;
+      if (innerPrefix === "file" || innerPrefix.startsWith("file(") || innerPrefix === "" && nextTok.kind === "unquoted" && (nextTok.value === "file(" || nextTok.value === "file")) {
+        if (innerPrefix === "") {
+          this.advance();
+        }
+        const path3 = this.parseQuotedPathSkipWrapper(t);
+        return this.makeIncludeField({ kind: "file" }, path3, true, p);
+      }
+      if (innerPrefix === "" && nextTok.kind === "unquoted" && (nextTok.value === "url" || nextTok.value.startsWith("url(") || nextTok.value === "classpath" || nextTok.value.startsWith("classpath("))) {
+        throw new ParseError("include url(...) and classpath(...) are not supported", nextTok.line, nextTok.col);
+      }
+      if (innerPrefix !== "") {
+        if (innerPrefix === ")") {
+          throw new ParseError("include required(...) must contain a path", t.line, t.col);
+        }
+        const name = innerPrefix.replace(/\(.*$/, "").replace(/\).*$/, "");
+        throw new ParseError(`unknown include qualifier inside required(): "${name}"`, t.line, t.col);
+      }
+      const path2 = this.parseQuotedPathSkipWrapper(t);
+      return this.makeIncludeField({ kind: "bare" }, path2, true, p);
+    }
+    if (t.kind === "string") {
+      const path2 = this.advance().value;
+      return this.makeIncludeField({ kind: "bare" }, path2, false, p);
+    }
+    if (t.kind === "unquoted" && (t.value === "file(" || t.value === "file")) {
       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("))) {
+      const path2 = this.parseQuotedPathSkipWrapper(t);
+      return this.makeIncludeField({ kind: "file" }, path2, false, p);
+    }
+    if (t.kind === "unquoted" && (t.value === "package(" || t.value.startsWith("package("))) {
+      const { qualifier, path: path2 } = this.parsePackageArgs();
+      return this.makeIncludeField(qualifier, path2, false, p);
+    }
+    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("))) {
+    }
+    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 ${t.kind}`, t.line, t.col);
     }
-    return {
-      key: [],
-      value: { kind: "include", path: path2, required, ...isFile ? { isFile: true } : {}, pos: p },
-      append: false,
-      pos: p
-    };
+    throw new ParseError(`expected include path, got ${t.kind}`, t.line, t.col);
+  }
+  makeIncludeField(qualifier, path2, required, pos) {
+    return { key: [], value: { kind: "include", qualifier, path: path2, required, pos }, append: false, pos };
+  }
+  /**
+   * Skip past include-syntax wrapper tokens to find the quoted path string.
+   * Strict: only allows `(`, `)`, and bare qualifier keywords (file / file( /
+   * package / package( / url / url( / classpath / classpath() between the
+   * directive and the quoted path. Anything else is a parse error rather than
+   * silently swallowed (see ts#113).
+   */
+  parseQuotedPathSkipWrapper(errTok) {
+    while (this.isIncludeWrapperToken(this.peek())) this.advance();
+    if (this.peek().kind !== "string") {
+      const tok = this.peek();
+      if (tok.kind === "eof") throw new ParseError("expected include path", errTok.line, errTok.col);
+      const desc = tok.kind === "unquoted" ? `unquoted "${tok.value}"` : tok.kind;
+      throw new ParseError(`expected quoted include path, got ${desc}`, tok.line, tok.col);
+    }
+    const path2 = this.advance().value;
+    while (this.peek().kind === "unquoted" && (this.peek().value === ")" || this.peek().value === "))")) {
+      this.advance();
+    }
+    const after = this.peek();
+    if (after.kind !== "newline" && after.kind !== "rbrace" && after.kind !== "eof" && after.kind !== "comma") {
+      const desc = after.kind === "unquoted" ? `unquoted "${after.value}"` : after.kind;
+      throw new ParseError(`unexpected token after include path: ${desc}`, after.line, after.col);
+    }
+    return path2;
+  }
+  isIncludeWrapperToken(tok) {
+    return tok.kind === "unquoted" && tok.value === "(";
+  }
+  /**
+   * Parse the body of `package("identifier", "file")`.
+   *
+   * @param consumePackageToken - When true (default), the current token is `package(` and
+   *   must be consumed first. When false, the lexer already bundled `package(` into the
+   *   preceding token (e.g. `required(package("`), so we are already positioned at the
+   *   first string argument.
+   */
+  parsePackageArgs(consumePackageToken = true) {
+    const pkgTok = consumePackageToken ? this.advance() : this.peek();
+    this.skip("newline");
+    const idTok = this.peek();
+    if (idTok.kind !== "string") {
+      throw new ParseError("include package: expected quoted identifier as first argument", pkgTok.line, pkgTok.col);
+    }
+    const identifier = this.advance().value;
+    this.skip("newline");
+    if (this.peek().kind !== "comma") {
+      const after = this.peek();
+      throw new ParseError(
+        after.kind === "string" ? "include package: missing comma between identifier and file arguments" : "include package: requires exactly two arguments (identifier, file) \u2014 one-arg form is not supported",
+        pkgTok.line,
+        pkgTok.col
+      );
+    }
+    this.advance();
+    this.skip("newline");
+    const fileTok = this.peek();
+    if (fileTok.kind !== "string") {
+      throw new ParseError(
+        "include package: requires exactly two arguments (identifier, file) \u2014 one-arg form is not supported",
+        pkgTok.line,
+        pkgTok.col
+      );
+    }
+    const filePath = this.advance().value;
+    while (this.peek().kind !== "newline" && this.peek().kind !== "rbrace" && this.peek().kind !== "eof" && this.peek().kind !== "comma") {
+      this.advance();
+    }
+    return { qualifier: { kind: "package", identifier }, path: filePath };
   }
   parseValue() {
     const p = this.currentPos();
@@ -923,7 +1096,7 @@ var Parser = class {
           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 } };
+        node = { kind: "subst", segments: payload.segments, optional: payload.optional, listSuffix: payload.listSuffix, 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 } };
@@ -942,7 +1115,9 @@ var Parser = class {
       parts.push(node);
     }
     if (parts.length === 0) throw new ParseError("expected value", this.peek().line, this.peek().col);
-    if (parts.length === 1) return parts[0];
+    if (parts.length === 1) {
+      return parts[0];
+    }
     return { kind: "concat", nodes: parts, pos: p };
   }
   parseArray() {
@@ -974,107 +1149,10 @@ 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);
-    }
-  }
-  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);
-    }
-  }
-}
-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/include-loader.ts
-import * as nodePath from "path";
-
 // src/internal/properties/properties.ts
 function parseProperties(input) {
   const root = /* @__PURE__ */ Object.create(null);
+  const pairs = [];
   for (const line of input.split("\n")) {
     const trimmed = line.trim();
     if (trimmed === "" || trimmed.startsWith("#") || trimmed.startsWith("!")) continue;
@@ -1083,6 +1161,10 @@ function parseProperties(input) {
     const key = trimmed.slice(0, sepIdx).trim();
     const value = trimmed.slice(sepIdx + 1).trim();
     if (key === "") continue;
+    pairs.push([key, value]);
+  }
+  pairs.sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+  for (const [key, value] of pairs) {
     setNested(root, key.split("."), value);
   }
   return root;
@@ -1106,6 +1188,7 @@ function setNested(obj, segments, value) {
   }
   const last = segments[segments.length - 1];
   if (last === void 0 || DANGEROUS_KEYS.has(last)) return;
+  if (typeof current[last] === "object" && current[last] !== null) return;
   current[last] = value;
 }
 function propertiesToHoconValue(input) {
@@ -1125,6 +1208,84 @@ function recordToHoconValue(obj) {
 }
 
 // src/internal/resolver/include-loader.ts
+var _require = createRequire(import.meta.url);
+function isPnpPath(p) {
+  return p.includes(".yarn/cache") || p.includes(".pnp.cjs") || p.includes(".pnp.loader");
+}
+function validatePackageFile(file, identifier) {
+  if (file.length === 0) {
+    throw new ParseError(`include package("${identifier}", ...): file argument must be non-empty`, 0, 0);
+  }
+  if (file.includes("\\")) {
+    throw new ParseError(
+      `include package("${identifier}", "${file}"): backslash not allowed in file argument (use forward slash)`,
+      0,
+      0
+    );
+  }
+  if (file.startsWith("/")) {
+    throw new ParseError(
+      `include package("${identifier}", "${file}"): absolute path not allowed in file argument`,
+      0,
+      0
+    );
+  }
+  if (/(?:^|\/)\.\.?(?:\/|$)/u.test(file)) {
+    throw new ParseError(
+      `include package("${identifier}", "${file}"): path traversal (. or ..) not allowed in file argument`,
+      0,
+      0
+    );
+  }
+  if (file.includes("//")) {
+    throw new ParseError(
+      `include package("${identifier}", "${file}"): consecutive slashes not allowed in file argument`,
+      0,
+      0
+    );
+  }
+}
+function validatePackageIdentifier(identifier) {
+  if (identifier.length === 0) {
+    throw new ParseError("include package: identifier argument must be non-empty", 0, 0);
+  }
+}
+function defaultPackageResolver(identifier, file, includingFile, baseDir, resolveFrom) {
+  const from = resolveFrom ? Array.isArray(resolveFrom) ? resolveFrom : [resolveFrom] : baseDir ? [baseDir] : includingFile ? [nodePath.dirname(includingFile)] : [process.cwd()];
+  let resolved;
+  try {
+    resolved = _require.resolve(`${identifier}/${file}`, { paths: from });
+  } catch {
+    throw new PackageLookupError(
+      `include package("${identifier}", "${file}"): module not found (starting from: ${from.join(", ")})`,
+      identifier,
+      file,
+      0,
+      0
+    );
+  }
+  if (isPnpPath(resolved)) {
+    throw new ResolveError(
+      `include package("${identifier}", "${file}"): Yarn Berry PnP store paths are not supported. Provide a custom packageResolver option to handle PnP resolution.`,
+      `${identifier}/${file}`,
+      0,
+      0
+    );
+  }
+  const fileParts = file.split("/");
+  const expectedBasename = fileParts[fileParts.length - 1] ?? file;
+  const resolvedBasename = nodePath.basename(resolved);
+  if (resolvedBasename !== expectedBasename) {
+    throw new PackageLookupError(
+      `include package("${identifier}", "${file}"): case mismatch \u2014 resolved "${resolvedBasename}" but expected "${expectedBasename}" (E11 decision 5: case-sensitive)`,
+      identifier,
+      file,
+      0,
+      0
+    );
+  }
+  return resolved;
+}
 var IncludeLoader = class {
   constructor(opts) {
     this.opts = opts;
@@ -1204,8 +1365,77 @@ var IncludeLoader = class {
     }
     return merged;
   }
+  /**
+   * Resolve and load `include package("identifier", "file")`.
+   * Validates the identifier and file arguments, resolves via the package resolver,
+   * performs cycle detection using a JSON-serialised cycle key, and parses the content.
+   */
+  // `required` is reserved for future optional-package semantics (E11 decision 7);
+  // currently all package lookup failures throw regardless of this flag.
+  loadPackage(identifier, file, _required) {
+    validatePackageIdentifier(identifier);
+    validatePackageFile(file, identifier);
+    const { includeStack = [], baseDir, resolveFrom, packageResolver, readFileSync: readFileSync2 } = this.opts;
+    const cycleKey = JSON.stringify(["package", identifier, file]);
+    if (includeStack.includes(cycleKey)) {
+      throw new ResolveError(
+        `circular include: package("${identifier}", "${file}")`,
+        `${identifier}/${file}`,
+        0,
+        0
+      );
+    }
+    if (includeStack.length >= 50) {
+      throw new ResolveError(`include depth limit exceeded (max 50)`, `${identifier}/${file}`, 0, 0);
+    }
+    const resolver = packageResolver ?? ((id, f, includingFile, bDir) => defaultPackageResolver(id, f, includingFile, bDir, resolveFrom));
+    const resolvedPath = resolver(identifier, file, void 0, baseDir);
+    const content = readFileSync2(resolvedPath);
+    if (content.length === 0) return makeResObj();
+    const tokens = tokenize(content);
+    assertNonEmptyDocument(tokens, resolvedPath);
+    const ast = parseTokens(tokens);
+    return this.onBuildResObj(ast, {
+      ...this.opts,
+      baseDir: nodePath.dirname(resolvedPath),
+      includeStack: [...includeStack, cycleKey]
+    });
+  }
+  /**
+   * Async variant of `loadPackage`.
+   */
+  async loadPackageAsync(identifier, file, _required) {
+    validatePackageIdentifier(identifier);
+    validatePackageFile(file, identifier);
+    const { includeStack = [], baseDir, resolveFrom, packageResolver, readFile, readFileSync: readFileSync2 } = this.opts;
+    const cycleKey = JSON.stringify(["package", identifier, file]);
+    if (includeStack.includes(cycleKey)) {
+      throw new ResolveError(
+        `circular include: package("${identifier}", "${file}")`,
+        `${identifier}/${file}`,
+        0,
+        0
+      );
+    }
+    if (includeStack.length >= 50) {
+      throw new ResolveError(`include depth limit exceeded (max 50)`, `${identifier}/${file}`, 0, 0);
+    }
+    const resolver = packageResolver ?? ((id, f, includingFile, bDir) => defaultPackageResolver(id, f, includingFile, bDir, resolveFrom));
+    const resolvedPath = resolver(identifier, file, void 0, baseDir);
+    const read = readFile ? async (p) => readFile(p) : async (p) => readFileSync2(p);
+    const content = await read(resolvedPath);
+    if (content.length === 0) return makeResObj();
+    const tokens = tokenize(content);
+    assertNonEmptyDocument(tokens, resolvedPath);
+    const ast = parseTokens(tokens);
+    return this.onBuildResObjAsync(ast, {
+      ...this.opts,
+      baseDir: nodePath.dirname(resolvedPath),
+      includeStack: [...includeStack, cycleKey]
+    });
+  }
   loadSingle(candidate) {
-    const { readFileSync: readFileSync2, includeStack = [], env } = this.opts;
+    const { readFileSync: readFileSync2, includeStack = [] } = this.opts;
     if (includeStack.includes(candidate)) {
       throw new ResolveError(`circular include: ${candidate}`, candidate, 0, 0);
     }
@@ -1219,16 +1449,17 @@ var IncludeLoader = class {
     if (candidate.endsWith(".properties")) {
       return hoconValueToResObj(propertiesToHoconValue(content));
     }
-    const ast = parseTokens(tokenize(content));
+    const tokens = tokenize(content);
+    assertNonEmptyDocument(tokens, candidate);
+    const ast = parseTokens(tokens);
     return this.onBuildResObj(ast, {
-      env,
+      ...this.opts,
       baseDir: nodePath.dirname(candidate),
-      readFileSync: readFileSync2,
       includeStack: [...includeStack, candidate]
     });
   }
   async loadSingleAsync(candidate) {
-    const { readFile, readFileSync: readFileSync2, includeStack = [], env } = this.opts;
+    const { readFile, readFileSync: readFileSync2, includeStack = [] } = 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);
@@ -1243,12 +1474,12 @@ var IncludeLoader = class {
     if (candidate.endsWith(".properties")) {
       return hoconValueToResObj(propertiesToHoconValue(content));
     }
-    const ast = parseTokens(tokenize(content));
+    const tokens = tokenize(content);
+    assertNonEmptyDocument(tokens, candidate);
+    const ast = parseTokens(tokens);
     return this.onBuildResObjAsync(ast, {
-      env,
+      ...this.opts,
       baseDir: nodePath.dirname(candidate),
-      readFileSync: readFileSync2,
-      readFile,
       includeStack: [...includeStack, candidate]
     });
   }
@@ -1257,7 +1488,6 @@ var IncludeLoader = class {
 // 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);
@@ -1284,7 +1514,13 @@ var StructureBuilder = class _StructureBuilder {
   }
   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);
+      const { qualifier, path: path2, required } = field.value;
+      let included;
+      if (qualifier.kind === "package") {
+        included = this.loader.loadPackage(qualifier.identifier, path2, required);
+      } else {
+        included = this.loader.load(path2, required, qualifier.kind === "file");
+      }
       if (pathPrefix.length > 0) {
         this.relativizeResObj(included, pathPrefix);
       }
@@ -1326,7 +1562,13 @@ var StructureBuilder = class _StructureBuilder {
   }
   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);
+      const { qualifier, path: path2, required } = field.value;
+      let included;
+      if (qualifier.kind === "package") {
+        included = await this.loader.loadPackageAsync(qualifier.identifier, path2, required);
+      } else {
+        included = await this.loader.loadAsync(path2, required, qualifier.kind === "file");
+      }
       if (pathPrefix.length > 0) {
         this.relativizeResObj(included, pathPrefix);
       }
@@ -1380,9 +1622,9 @@ var StructureBuilder = class _StructureBuilder {
         return inner;
       }
       case "subst":
-        return { _kind: "subst-placeholder", segments: ast.segments, optional: ast.optional, line: ast.pos.line, col: ast.pos.col, prefixLen: 0 };
+        return { _kind: "subst-placeholder", segments: ast.segments, optional: ast.optional, listSuffix: ast.listSuffix, 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)) };
+        return { _kind: "concat-placeholder", nodes: ast.nodes.map((n) => this.astToResolverValue(n, pathPrefix)), line: ast.pos.line, col: ast.pos.col };
       case "include":
         return { kind: "scalar", raw: "null", valueType: "null" };
     }
@@ -1404,13 +1646,13 @@ var StructureBuilder = class _StructureBuilder {
       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 };
+        return { _kind: "subst-placeholder", segments: ast.segments, optional: ast.optional, listSuffix: ast.listSuffix, 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 };
+        return { _kind: "concat-placeholder", nodes, line: ast.pos.line, col: ast.pos.col };
       }
       case "include":
         return { kind: "scalar", raw: "null", valueType: "null" };
@@ -1456,6 +1698,23 @@ var StructureBuilder = class _StructureBuilder {
   }
 };
 
+// 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/internal/resolver/substitution-resolver.ts
 var SubstitutionResolver = class {
   constructor(root, opts) {
@@ -1463,6 +1722,23 @@ var SubstitutionResolver = class {
     this.opts = opts;
     this.resolving = /* @__PURE__ */ new Set();
     this.cache = /* @__PURE__ */ new Map();
+    // Tracks ConcatPlaceholder nodes currently being iterated by resolveConcat.
+    // Used by isSelfRef detection: fires only when found === a concat currently
+    // mid-iteration (i.e. we are inside found's own resolution), preventing the
+    // "foofoo" double-count without misfiring when an external field looks up the
+    // same concat via a substitution (multi-reviewer convergence fix).
+    //
+    // Spec deviation: the S13a.13 spec ★1 decision #1 specified path-equality
+    // preservation for self-ref detection. Round-2 multi-agent-review surfaced a
+    // false-positive on external lookups (`a = ${?a}foo; b = ${a}`), so the
+    // criterion was tightened to node-membership-in-iterating-set — strictly
+    // narrower than path-equality. Spec amendment deferred to a follow-up
+    // xx.hocon PR (see Phase 6 #3f close-out notes).
+    this.resolvingConcats = /* @__PURE__ */ new WeakSet();
+  }
+  /** Returns a prefix for error messages, including origin info when set. */
+  originPrefix() {
+    return this.opts.originDescription ? `${this.opts.originDescription}: ` : "";
   }
   resolve() {
     return this.resolveResObj(this.root);
@@ -1501,7 +1777,15 @@ var SubstitutionResolver = class {
   }
   resolveVal(v, scope) {
     if (isSubst(v)) return this.resolveSubst(v, scope);
-    if (isConcat(v)) return this.resolveConcat(v.nodes, scope);
+    if (isConcat(v)) {
+      this.resolvingConcats.add(v);
+      try {
+        const concatResult = this.resolveConcat(v.nodes, scope, v.line, v.col);
+        return concatResult;
+      } finally {
+        this.resolvingConcats.delete(v);
+      }
+    }
     if (isAppend(v)) return this.resolveAppend(v, scope);
     if (isResObj(v)) return this.resolveResObj(v);
     const hv = v;
@@ -1515,15 +1799,12 @@ var SubstitutionResolver = class {
     }
     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);
+    const key = s.listSuffix ? `${segmentsToKey(s.segments)}[]` : segmentsToKey(s.segments);
     if (this.cache.has(key)) return this.cache.get(key);
     if (this.resolving.has(key)) {
       let prior;
-      if (s.prefixLen > 0) {
+      if (s.segments.length > 1) {
         const leafSeg = s.segments[s.segments.length - 1]?.text ?? "";
         const parentScope = lookupResObj(
           this.root,
@@ -1545,7 +1826,7 @@ var SubstitutionResolver = class {
       }
       if (s.optional) return void 0;
       throw new ResolveError(
-        `circular substitution: ${key}`,
+        this.originPrefix() + `circular substitution: ${key}`,
         key,
         s.line,
         s.col
@@ -1555,29 +1836,31 @@ var SubstitutionResolver = class {
     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;
-            }
+        if (isConcat(found) && this.resolvingConcats.has(found)) {
+          let prior;
+          if (s.segments.length > 1) {
+            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;
           }
+          if (s.optional) return void 0;
+          throw new ResolveError(
+            `${this.originPrefix()}could not resolve substitution: \${${key}}`,
+            key,
+            s.line,
+            s.col
+          );
         }
         let result = this.resolveVal(found, scope);
         const effectiveLen = s.segments.length - s.prefixLen;
@@ -1606,16 +1889,45 @@ var SubstitutionResolver = class {
         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.listSuffix && this.opts.useSystemEnvironment !== false) {
+        const result = this.resolveEnvList(s);
+        if (result !== void 0) {
+          this.cache.set(key, result);
+          return result;
+        }
+        if (s.optional) return void 0;
+        const envBase = s.segments.map((seg) => seg.text).join(".");
+        throw new ResolveError(
+          `${this.originPrefix()}could not resolve substitution: \${${key}} (no environment variables ${envBase}_0, ${envBase}_1, \u2026 set)`,
+          key,
+          s.line,
+          s.col
+        );
+      } else if (s.listSuffix) {
+        if (s.optional) return void 0;
+        if (this.opts.allowUnresolved) return s;
+        throw new ResolveError(
+          `${this.originPrefix()}could not resolve substitution: \${${key}}`,
+          key,
+          s.line,
+          s.col
+        );
+      }
+      if (this.opts.useSystemEnvironment !== false) {
+        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;
+      if (this.opts.allowUnresolved) {
+        return s;
+      }
       throw new ResolveError(
-        `could not resolve substitution: \${${key}}`,
+        `${this.originPrefix()}could not resolve substitution: \${${key}}`,
         key,
         s.line,
         s.col
@@ -1624,9 +1936,52 @@ var SubstitutionResolver = class {
       this.resolving.delete(key);
     }
   }
-  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" };
+  /**
+   * S13c: scan environment for NAME_0, NAME_1, … and return an Array<Scalar(String)>.
+   *
+   * Candidate bases follow the same fully-qualified→bare order used by the scalar
+   * env fallback. The first base whose _0 key is present wins entirely — no
+   * cross-base merging (spec §Relativized fallback precedence rules).
+   *
+   * Returns the HoconValue Array if any candidate base has _0, or undefined if
+   * none do (caller applies optional/required handling).
+   */
+  resolveEnvList(s) {
+    const bases = this.candidateBases(s);
+    for (const base of bases) {
+      const key0 = base + "_0";
+      if (!(key0 in this.opts.env)) continue;
+      const items = [];
+      for (let i = 0; ; i++) {
+        const k = base + "_" + i;
+        if (!(k in this.opts.env)) break;
+        items.push({ kind: "scalar", raw: this.opts.env[k], valueType: "string" });
+      }
+      return { kind: "array", items };
+    }
+    return void 0;
+  }
+  /**
+   * Return the candidate base names for env-var-list lookup, in precedence order.
+   * Mirrors the fully-qualified→bare fallback used by the scalar env path.
+   */
+  candidateBases(s) {
+    const full = s.segments.map((seg) => seg.text).join(".");
+    if (s.prefixLen === 0) return [full];
+    const bare = s.segments.slice(s.prefixLen).map((seg) => seg.text).join(".");
+    return [full, bare];
+  }
+  resolveConcat(nodes, scope, line = 0, col = 0) {
+    const rawResolved = nodes.map((n) => this.resolveVal(n, scope));
+    if (this.opts.allowUnresolved) {
+      for (const v of rawResolved) {
+        if (v !== void 0 && isSubst(v)) {
+          return v;
+        }
+      }
+    }
+    const resolved = rawResolved.filter((v) => v !== void 0);
+    if (resolved.length === 0) return void 0;
     if (resolved.length === 1) return resolved[0];
     const nonSep = resolved.filter((v) => !separatorValues.has(v));
     if (nonSep.length === 0) {
@@ -1642,27 +1997,45 @@ var SubstitutionResolver = class {
         if (converted !== null) {
           return { kind: "array", items: [...left.items, ...converted] };
         }
-        return { kind: "array", items: [...left.items, right] };
+        throw new ResolveError(
+          "cannot concatenate array with object: value concatenation requires same-kind operands (S10.4)",
+          "",
+          line,
+          col
+        );
       }
       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] };
+        throw new ResolveError(
+          "cannot concatenate object with array: value concatenation requires same-kind operands (S10.4)",
+          "",
+          line,
+          col
+        );
       }
       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 (left.kind === "array" || right.kind === "array") {
+        throw new ResolveError(
+          `cannot concatenate ${left.kind} with ${right.kind}: arrays and objects may not appear in string value concatenation (S10.13)`,
+          "",
+          line,
+          col
+        );
       }
-      if (right.kind === "array") {
-        return { kind: "array", items: [left, ...right.items] };
+      if (left.kind === "object" || right.kind === "object") {
+        throw new ResolveError(
+          `cannot concatenate ${left.kind} with ${right.kind}: arrays and objects may not appear in string value concatenation (S10.13)`,
+          "",
+          line,
+          col
+        );
       }
-      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" };
+      return { kind: "scalar", raw: left.raw + right.raw, valueType: "string" };
     };
     const [head, ...tail] = nonSep;
     const folded = tail.reduce(joinPair, head);
@@ -1682,18 +2055,503 @@ var SubstitutionResolver = class {
 };
 
 // src/internal/resolver/resolver.ts
+function buildTree(ast, opts) {
+  return new StructureBuilder(opts).build(ast);
+}
+function resolveTree(tree, opts) {
+  return new SubstitutionResolver(tree, opts).resolve();
+}
+function containsPlaceholders(tree) {
+  for (const val of tree.fields.values()) {
+    if (valContainsPlaceholders(val)) return true;
+  }
+  return false;
+}
+function valContainsPlaceholders(v) {
+  const rv = v;
+  if (isSubst(rv) || isConcat(rv) || isAppend(rv)) return true;
+  if (isResObj(rv)) return containsPlaceholders(rv);
+  const hv = v;
+  if (hv?.kind === "array") {
+    return hv.items.some((item) => valContainsPlaceholders(item));
+  }
+  return false;
+}
+function buildPartialHoconFromResObj(tree) {
+  const fields = /* @__PURE__ */ new Map();
+  for (const [k, v] of tree.fields) {
+    if (!isSubst(v) && !isConcat(v) && !isAppend(v)) {
+      if (isResObj(v)) {
+        fields.set(k, buildPartialHoconFromResObj(v));
+      } else {
+        if (!valContainsPlaceholders(v)) {
+          fields.set(k, v);
+        }
+      }
+    }
+  }
+  return { kind: "object", fields };
+}
+function hoconValueToResObj2(value) {
+  const obj = makeResObj();
+  for (const [k, v] of value.fields) {
+    if (v.kind === "object") {
+      obj.fields.set(k, hoconValueToResObj2(v));
+    } else {
+      obj.fields.set(k, v);
+    }
+  }
+  return obj;
+}
 function resolve2(ast, opts) {
-  const root = new StructureBuilder(opts).build(ast);
-  return new SubstitutionResolver(root, opts).resolve();
+  const tree = buildTree(ast, opts);
+  return resolveTree(tree, { ...opts, useSystemEnvironment: true, allowUnresolved: false });
 }
 async function resolveAsync(ast, opts) {
   const root = await new StructureBuilder(opts).buildAsync(ast);
-  return new SubstitutionResolver(root, opts).resolve();
+  return resolveTree(root, { ...opts, useSystemEnvironment: true, allowUnresolved: false });
+}
+
+// src/config.ts
+var Config = class _Config {
+  constructor(root, opts) {
+    this.root = root;
+    this._resolved = opts?.resolved ?? true;
+    this._parseBaseDir = opts?.parseBaseDir;
+    this._originDescription = opts?.originDescription;
+    this._resObjRoot = opts?.resObjRoot;
+    this._resolveOpts = opts?.resolveOpts;
+  }
+  /** Returns true when the Config's value tree contains no unresolved
+   *  substitution placeholders. Whole-config granularity (E12 decision 11). */
+  isResolved() {
+    return this._resolved;
+  }
+  /** @internal Test-only: construct a resolved Config from a HoconValue. */
+  static _fromResolvedValue(root, opts) {
+    return new _Config(root, { resolved: true, originDescription: opts?.originDescription });
+  }
+  /** @internal Construct an unresolved Config carrying a ResObj tree.
+   *  Used by parseStringWithOptions (deferred path) in T6. */
+  static _fromUnresolvedResObj(tree, opts) {
+    const partialRoot = buildPartialHoconFromResObj(tree);
+    return new _Config(partialRoot, {
+      resolved: opts.resolved,
+      parseBaseDir: opts.parseBaseDir,
+      originDescription: opts.originDescription,
+      resObjRoot: tree,
+      resolveOpts: opts.resolveOpts
+    });
+  }
+  get(path2) {
+    const v = this.lookupNode(path2);
+    if (v === void 0) return void 0;
+    return hoconToJs(v);
+  }
+  getString(path2) {
+    const v = this.requireScalar(path2);
+    return v.raw;
+  }
+  getNumber(path2) {
+    const v = this.requireScalar(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);
+    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 (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 (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);
+    if (result < 0) throw new ConfigError(`byte size must be non-negative at ${path2}: ${JSON.stringify(v.raw)}`, path2);
+    return result;
+  }
+  getConfig(path2) {
+    const v = this.lookupNode(path2);
+    if (v === void 0) {
+      if (!this._resolved && this._resObjRootSubtreeHasPlaceholders(path2)) {
+        throw new NotResolvedError(path2);
+      }
+      throw new ConfigError(`path not found: ${path2}`, path2);
+    }
+    if (v.kind !== "object") throw new ConfigError(`expected object at ${path2}`, path2);
+    if (!this._resolved && this._resObjRootSubtreeHasPlaceholders(path2)) {
+      throw new NotResolvedError(path2);
+    }
+    return new _Config(v, { resolved: this._resolved });
+  }
+  getList(path2) {
+    const v = this.lookupNode(path2);
+    if (v === void 0) {
+      if (!this._resolved && this._resObjRootSubtreeHasPlaceholders(path2)) {
+        throw new NotResolvedError(path2);
+      }
+      throw new ConfigError(`path not found: ${path2}`, path2);
+    }
+    if (!this._resolved && this._resObjRootSubtreeHasPlaceholders(path2)) {
+      throw new NotResolvedError(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);
+  }
+  has(path2) {
+    return this.lookupNode(path2) !== void 0;
+  }
+  keys() {
+    return [...this.root.fields.keys()];
+  }
+  withFallback(fallback) {
+    if (fallback == null) return this;
+    const selfTree = this._resObjRoot ?? hoconValueToResObj2(this.root);
+    const fbTree = fallback._resObjRoot ?? hoconValueToResObj2(fallback.root);
+    const merged = mergeUnresolved(selfTree, fbTree);
+    const hasPlaceholders = containsPlaceholders(merged);
+    const partialRoot = buildPartialHoconFromResObj(merged);
+    return new _Config(partialRoot, {
+      resolved: !hasPlaceholders,
+      parseBaseDir: this._parseBaseDir,
+      originDescription: this._originDescription,
+      resObjRoot: merged,
+      resolveOpts: this._resolveOpts ?? fallback._resolveOpts
+    });
+  }
+  /**
+   * Runs substitution resolution (phase 2) on the stored unresolved tree.
+   * Idempotent: calling resolve() on an already-resolved Config returns an
+   * equivalent resolved Config.
+   *
+   * opts.allowUnresolved (default false) — when true, leaves unresolved
+   * non-optional placeholders in place rather than throwing.
+   * opts.useSystemEnvironment (default true) — when false, env var lookups
+   * are suppressed (hermetic resolution).
+   *
+   * E12 decision 3.
+   */
+  resolve(opts = {}) {
+    if (this._resolved) {
+      return new _Config(this.root, {
+        resolved: true,
+        parseBaseDir: this._parseBaseDir,
+        originDescription: this._originDescription
+      });
+    }
+    const tree = this._resObjRoot;
+    if (!tree) {
+      return new _Config(this.root, { resolved: true });
+    }
+    const resolveOpts = {
+      ...this._resolveOpts ?? { env: {}, baseDir: void 0, readFileSync: () => {
+        throw new Error("no files");
+      } },
+      allowUnresolved: opts.allowUnresolved ?? false,
+      useSystemEnvironment: opts.useSystemEnvironment ?? true,
+      originDescription: this._originDescription
+    };
+    const resolved = resolveTree(tree, resolveOpts);
+    if (resolved.kind !== "object") throw new Error("resolve: expected object root");
+    if (opts.allowUnresolved) {
+      const { stripped, hadPlaceholders } = stripPlaceholderFields(resolved);
+      return new _Config(stripped, {
+        resolved: !hadPlaceholders,
+        parseBaseDir: this._parseBaseDir,
+        originDescription: this._originDescription,
+        resObjRoot: hadPlaceholders ? tree : void 0,
+        resolveOpts: hadPlaceholders ? resolveOpts : void 0
+      });
+    }
+    return new _Config(resolved, {
+      resolved: true,
+      parseBaseDir: this._parseBaseDir,
+      originDescription: this._originDescription
+    });
+  }
+  /**
+   * Resolves receiver substitutions using source as lookup context.
+   * Source's keys are NOT merged into the result — differs from
+   * `this.withFallback(source).resolve()` which includes source keys.
+   *
+   * Precondition (E12 decision 10): source must be resolved. If
+   * source.isResolved() is false, throws NotResolvedError.
+   *
+   * On an already-resolved receiver, resolveWith is a no-op (returns an
+   * equivalent resolved Config, source keys not included).
+   *
+   * E12 decisions 9, 10.
+   */
+  resolveWith(source, opts = {}) {
+    if (!source.isResolved()) {
+      throw new NotResolvedError("source");
+    }
+    if (this._resolved) {
+      return new _Config(this.root, {
+        resolved: true,
+        parseBaseDir: this._parseBaseDir,
+        originDescription: this._originDescription
+      });
+    }
+    const receiverTree = this._resObjRoot ?? hoconValueToResObj2(this.root);
+    const srcTree = hoconValueToResObj2(source.root);
+    const merged = mergeUnresolved(receiverTree, srcTree);
+    const resolveOpts = {
+      ...this._resolveOpts ?? { env: {}, baseDir: void 0, readFileSync: () => {
+        throw new Error("no files");
+      } },
+      allowUnresolved: opts.allowUnresolved ?? false,
+      useSystemEnvironment: opts.useSystemEnvironment ?? true,
+      originDescription: this._originDescription
+    };
+    const resolved = resolveTree(merged, resolveOpts);
+    if (resolved.kind !== "object") throw new Error("resolveWith: expected object root");
+    const receiverShapeForFilter = resObjToKeyShape(receiverTree);
+    const filtered = filterByReceiverShape(resolved, receiverShapeForFilter);
+    if (opts.allowUnresolved) {
+      const { stripped, hadPlaceholders } = stripPlaceholderFields(filtered);
+      return new _Config(stripped, {
+        resolved: !hadPlaceholders,
+        parseBaseDir: this._parseBaseDir,
+        originDescription: this._originDescription,
+        resObjRoot: hadPlaceholders ? receiverTree : void 0,
+        resolveOpts: hadPlaceholders ? resolveOpts : void 0
+      });
+    }
+    return new _Config(filtered, {
+      resolved: true,
+      parseBaseDir: this._parseBaseDir,
+      originDescription: this._originDescription
+    });
+  }
+  toObject() {
+    return hoconToJs(this.root);
+  }
+  /**
+   * @internal Test-only: renders this resolved Config's value tree as canonical
+   * JSON (sorted keys, no whitespace). Used by Layer-2 fixture tests to compare
+   * against Lightbend ground truth. NOT part of the public API.
+   *
+   * Throws if the Config is unresolved (contains placeholders).
+   */
+  _renderJSONForTest() {
+    return renderHoconAsJSON(this.root);
+  }
+  lookupNode(path2) {
+    const segments = splitConfigPath(path2);
+    let current = this.root;
+    for (const seg of segments) {
+      if (current.kind !== "object") return void 0;
+      const next = current.fields.get(seg);
+      if (next === void 0) return void 0;
+      current = next;
+    }
+    return current;
+  }
+  /**
+   * _resObjRootSubtreeHasPlaceholders — walk _resObjRoot to the given path and
+   * return true if the subtree there contains any unresolved placeholder.
+   * Used by getConfig / getList (T2) to detect transitive unresolved placeholders
+   * in object / array subtrees that would otherwise appear to be "resolved" in the
+   * partial HoconValue root (because individual leaf fields are omitted rather than
+   * the whole subtree when their value is a direct placeholder scalar, but object
+   * sub-containers are retained in the partial root with the placeholder-keyed
+   * fields omitted from them — so the object appears "present but empty-ish").
+   */
+  _resObjRootSubtreeHasPlaceholders(path2) {
+    const tree = this._resObjRoot;
+    if (!tree) return false;
+    const segments = splitConfigPath(path2);
+    let cur = tree;
+    for (const seg of segments) {
+      const val = cur.fields.get(seg);
+      if (val === void 0) return false;
+      if (isResObj(val)) {
+        cur = val;
+      } else {
+        return valContainsPlaceholders(val);
+      }
+    }
+    return containsPlaceholders(cur);
+  }
+  requireScalar(path2) {
+    const v = this.lookupNode(path2);
+    if (v === void 0) {
+      if (!this._resolved && this._resObjRootSubtreeHasPlaceholders(path2)) {
+        throw new NotResolvedError(path2);
+      }
+      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;
+  }
+};
+function splitConfigPath(path2) {
+  const segments = [];
+  let i = 0;
+  while (i < path2.length) {
+    if (path2[i] === '"') {
+      i++;
+      let segment = "";
+      let closed = false;
+      while (i < path2.length) {
+        const ch = path2[i];
+        if (ch === "\\" && i + 1 < path2.length) {
+          const next = path2[i + 1];
+          segment += next;
+          i += 2;
+          continue;
+        }
+        if (ch === '"') {
+          closed = true;
+          i++;
+          break;
+        }
+        segment += ch;
+        i++;
+      }
+      if (!closed) throw new ConfigError(`unterminated quoted path segment: ${path2}`, path2);
+      segments.push(segment);
+      if (i < path2.length && path2[i] === ".") i++;
+    } else {
+      const dot = path2.indexOf(".", i);
+      if (dot === -1) {
+        segments.push(path2.slice(i));
+        break;
+      }
+      segments.push(path2.slice(i, dot));
+      i = dot + 1;
+    }
+  }
+  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 scalarToJs(v.raw, v.valueType);
+    case "array":
+      return v.items.map(hoconToJs);
+    case "object": {
+      const obj = /* @__PURE__ */ Object.create(null);
+      for (const [k, val] of v.fields) obj[k] = hoconToJs(val);
+      return Object.assign({}, obj);
+    }
+  }
+}
+function resObjToKeyShape(tree) {
+  const fields = /* @__PURE__ */ new Map();
+  for (const [k, v] of tree.fields) {
+    if (isSubst(v) || isConcat(v) || isAppend(v)) {
+      fields.set(k, { kind: "scalar", raw: "", valueType: "null" });
+    } else if (isResObj(v)) {
+      fields.set(k, resObjToKeyShape(v));
+    } else {
+      fields.set(k, v);
+    }
+  }
+  return { kind: "object", fields };
+}
+function stripPlaceholderFields(v) {
+  const fields = /* @__PURE__ */ new Map();
+  let hadPlaceholders = false;
+  for (const [k, val] of v.fields) {
+    if (val._kind === "subst-placeholder" || val._kind === "concat-placeholder" || val._kind === "append-placeholder") {
+      hadPlaceholders = true;
+    } else if (val.kind === "object") {
+      const inner = stripPlaceholderFields(val);
+      if (inner.hadPlaceholders) hadPlaceholders = true;
+      fields.set(k, inner.stripped);
+    } else {
+      fields.set(k, val);
+    }
+  }
+  return { stripped: { kind: "object", fields }, hadPlaceholders };
+}
+function filterByReceiverShape(resolved, receiverShape) {
+  const fields = /* @__PURE__ */ new Map();
+  for (const [k, rv] of resolved.fields) {
+    if (!receiverShape.fields.has(k)) continue;
+    const receiverVal = receiverShape.fields.get(k);
+    if (rv.kind === "object" && receiverVal.kind === "object") {
+      fields.set(k, filterByReceiverShape(rv, receiverVal));
+    } else {
+      fields.set(k, rv);
+    }
+  }
+  return { kind: "object", fields };
+}
+function renderHoconAsJSON(v) {
+  switch (v.kind) {
+    case "scalar": {
+      switch (v.valueType) {
+        case "null":
+          return "null";
+        case "boolean":
+          return v.raw;
+        case "number": {
+          const n = Number(v.raw);
+          if (Number.isFinite(n)) return v.raw;
+          return JSON.stringify(v.raw);
+        }
+        case "string":
+          return JSON.stringify(v.raw);
+      }
+      break;
+    }
+    case "array": {
+      const items = v.items.map(renderHoconAsJSON);
+      return `[${items.join(",")}]`;
+    }
+    case "object": {
+      const keys = [...v.fields.keys()].sort();
+      const pairs = keys.map((k) => {
+        const val = v.fields.get(k);
+        return `${JSON.stringify(k)}:${renderHoconAsJSON(val)}`;
+      });
+      return `{${pairs.join(",")}}`;
+    }
+  }
+  throw new Error(`renderHoconAsJSON: unsupported value kind (unresolved placeholder?)`);
 }
 
 // src/parse.ts
 import * as fs from "fs";
 import * as path from "path";
+function defaultParseOptions() {
+  return { resolveSubstitutions: true };
+}
+function defaultResolveOptions() {
+  return { useSystemEnvironment: true, allowUnresolved: false };
+}
 function getEnv(opts) {
   if (opts.env !== void 0) return opts.env;
   if (typeof process !== "undefined" && process.env) return process.env;
@@ -1707,12 +2565,16 @@ async function defaultReadFile(filePath) {
 }
 function buildResolveContext(input, opts) {
   const tokens = tokenize(input);
+  assertNonEmptyDocument(tokens, "input");
   const ast = parseTokens(tokens);
   const resolveOpts = {
     env: getEnv(opts),
     baseDir: opts.baseDir,
     readFileSync: opts.readFileSync ?? defaultReadFileSync,
-    readFile: opts.readFile
+    readFile: opts.readFile,
+    originDescription: opts.originDescription,
+    resolveFrom: opts.resolveFrom,
+    packageResolver: opts.packageResolver
   };
   return { ast, resolveOpts };
 }
@@ -1720,7 +2582,38 @@ function parse(input, opts = {}) {
   const { ast, resolveOpts } = buildResolveContext(input, opts);
   const value = resolve2(ast, resolveOpts);
   if (value.kind !== "object") throw new Error("resolved value is not an object");
-  return new Config(value);
+  return new Config(value, { resolved: true, originDescription: opts.originDescription });
+}
+var parseString = parse;
+function parseStringWithOptions(input, opts = {}) {
+  const resolveSubstitutions = opts.resolveSubstitutions ?? true;
+  const { ast, resolveOpts } = buildResolveContext(input, opts);
+  if (resolveSubstitutions) {
+    const value = resolve2(ast, resolveOpts);
+    if (value.kind !== "object") throw new Error("resolved value is not an object");
+    return new Config(value, { resolved: true, originDescription: opts.originDescription });
+  }
+  const tree = buildTree(ast, resolveOpts);
+  const hasPlaceholders = containsPlaceholders(tree);
+  return Config._fromUnresolvedResObj(tree, {
+    parseBaseDir: opts.baseDir,
+    originDescription: opts.originDescription,
+    resolved: !hasPlaceholders,
+    resolveOpts
+  });
+}
+function parseFileWithOptions(filePath, opts = {}) {
+  if (typeof process === "undefined" && !opts.readFileSync) {
+    throw new Error("parseFileWithOptions is not supported in browser environments without opts.readFileSync.");
+  }
+  const resolvedPath = path.resolve(filePath);
+  const readFileSync2 = opts.readFileSync ?? defaultReadFileSync;
+  const input = readFileSync2(resolvedPath);
+  return parseStringWithOptions(input, {
+    ...opts,
+    baseDir: opts.baseDir ?? path.dirname(resolvedPath),
+    readFileSync: readFileSync2
+  });
 }
 async function parseAsync(input, opts = {}) {
   const { ast, resolveOpts } = buildResolveContext(input, opts);
@@ -1755,13 +2648,89 @@ async function parseFileAsync(filePath, opts = {}) {
     readFileSync: opts.readFileSync ?? defaultReadFileSync
   });
 }
+
+// src/value-factory.ts
+function fromMap(values, originDescription) {
+  const fields = coerceObject(values, "");
+  const root = { kind: "object", fields };
+  return Config._fromResolvedValue(root, { originDescription });
+}
+function empty(originDescription) {
+  const root = { kind: "object", fields: /* @__PURE__ */ new Map() };
+  return Config._fromResolvedValue(root, { originDescription });
+}
+function coerceObject(obj, atPath) {
+  const fields = /* @__PURE__ */ new Map();
+  for (const [k, v] of Object.entries(obj)) {
+    const childPath = atPath ? `${atPath}.${k}` : k;
+    fields.set(k, coerceValue(v, childPath));
+  }
+  return fields;
+}
+function coerceValue(v, atPath) {
+  if (v === null) {
+    return { kind: "scalar", raw: "null", valueType: "null" };
+  }
+  if (v === void 0) {
+    throw new ConfigError(
+      `fromMap: undefined is not a valid HOCON value at path "${atPath}"`,
+      atPath
+    );
+  }
+  switch (typeof v) {
+    case "string":
+      return { kind: "scalar", raw: v, valueType: "string" };
+    case "number": {
+      if (Number.isNaN(v) || !Number.isFinite(v)) {
+        throw new ConfigError(
+          `fromMap: ${v} is not representable in HOCON (NaN/Infinity not allowed) at path "${atPath}"`,
+          atPath
+        );
+      }
+      return { kind: "scalar", raw: String(v), valueType: "number" };
+    }
+    case "boolean":
+      return { kind: "scalar", raw: v ? "true" : "false", valueType: "boolean" };
+    case "bigint": {
+      if (v > BigInt(Number.MAX_SAFE_INTEGER) || v < BigInt(Number.MIN_SAFE_INTEGER)) {
+        throw new ConfigError(
+          `fromMap: bigint ${v} exceeds Number.MAX_SAFE_INTEGER (not representable as HOCON number) at path "${atPath}"`,
+          atPath
+        );
+      }
+      return { kind: "scalar", raw: String(v), valueType: "number" };
+    }
+    case "object": {
+      if (Array.isArray(v)) {
+        const items = v.map((item, i) => coerceValue(item, `${atPath}[${i}]`));
+        return { kind: "array", items };
+      }
+      const fields = coerceObject(v, atPath);
+      return { kind: "object", fields };
+    }
+    default:
+      throw new ConfigError(
+        `fromMap: unsupported value type "${typeof v}" at path "${atPath}"`,
+        atPath
+      );
+  }
+}
 export {
   Config,
   ConfigError,
+  NotResolvedError,
+  PackageLookupError,
   ParseError,
   ResolveError,
+  defaultParseOptions,
+  defaultResolveOptions,
+  empty,
+  fromMap,
   parse,
   parseAsync,
   parseFile,
-  parseFileAsync
+  parseFileAsync,
+  parseFileWithOptions,
+  parseString,
+  parseStringWithOptions
 };