@o3co/ts.hocon 0.1.0

package/docs/superpowers/plans/2026-03-20-ts-hocon.md

@@ -0,0 +1,2412 @@
+# @o3co/ts.hocon Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** TypeScript 製 HOCON パーサーライブラリ `@o3co/ts.hocon` を実装する。
+
+**Architecture:** Lexer → Parser → Resolver（2パス） → Config API のパイプライン。内部値は discriminated union + Map ベース。外部 API は TypeScript イディオムに沿った関数 + Config クラス。Zod はオプション peer dependency として `src/zod.ts` に分離。
+
+**Tech Stack:** TypeScript 5, Vitest 3, tsup 8, Node.js (`fs`), Zod 3（optional peer dep）
+
+**Reference:** Go 実装 `/Volumes/Workspace/o3co/repos/go.hocon` — ロジックの参考にすること。Lightbend テストデータ `/Volumes/Workspace/o3co/repos/go.hocon/testdata/hocon/` を流用する。
+
+---
+
+## File Map
+
+```text
+src/
+├── index.ts                         # public exports
+├── parse.ts                         # parse / parseAsync / parseFile / parseFileAsync
+├── config.ts                        # Config クラス
+├── value.ts                         # HoconValue 型定義
+├── errors.ts                        # ParseError / ResolveError / ConfigError
+├── zod.ts                           # Zod インテグレーション（別エントリポイント）
+└── internal/
+    ├── lexer/
+    │   ├── token.ts                 # Token 型定義
+    │   └── lexer.ts                 # tokenize() 関数
+    ├── parser/
+    │   ├── ast.ts                   # AstNode 型定義
+    │   └── parser.ts                # parseTokens() 関数
+    └── resolver/
+        └── resolver.ts              # Resolver クラス（2パス）
+
+tests/
+├── errors.test.ts
+├── lexer.test.ts
+├── parser.test.ts
+├── resolver.test.ts
+├── config.test.ts
+├── parse.test.ts                    # end-to-end 統合テスト
+├── zod.test.ts
+└── lightbend/
+    ├── *.conf / *.json              # Lightbend 公式テストスイート（go.hocon からコピー）
+    └── lightbend.test.ts
+
+package.json
+tsconfig.json
+vitest.config.ts
+tsup.config.ts
+```
+
+---
+
+## Task 1: プロジェクト初期化
+
+**Files:**
+- Create: `package.json`
+- Create: `tsconfig.json`
+- Create: `vitest.config.ts`
+- Create: `tsup.config.ts`
+- Create: `src/index.ts`
+
+- [ ] **Step 1: npm init & 依存関係インストール**
+
+```bash
+cd /Volumes/Workspace/o3co/repos/ts.hocon
+npm init -y
+npm install -D typescript@^5 vitest@^3 tsup@^8 @types/node
+```
+
+- [ ] **Step 2: `package.json` のスクリプト・exports・peerDeps を設定**
+
+```json
+{
+  "name": "@o3co/ts.hocon",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    },
+    "./zod": {
+      "import": "./dist/zod.js",
+      "require": "./dist/zod.cjs",
+      "types": "./dist/zod.d.ts"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "zod": ">=3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": { "optional": true }
+  }
+}
+```
+
+- [ ] **Step 3: `tsconfig.json` を作成**
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "skipLibCheck": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+- [ ] **Step 4: `vitest.config.ts` を作成**
+
+```ts
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    include: ['tests/**/*.test.ts'],
+  },
+})
+```
+
+- [ ] **Step 5: `tsup.config.ts` を作成**
+
+```ts
+import { defineConfig } from 'tsup'
+
+export default defineConfig({
+  entry: {
+    index: 'src/index.ts',
+    zod: 'src/zod.ts',
+  },
+  format: ['esm', 'cjs'],
+  dts: true,
+  clean: true,
+  splitting: false,
+})
+```
+
+- [ ] **Step 6: `.gitignore` を作成**
+
+```text
+node_modules/
+dist/
+*.tsbuildinfo
+```
+
+- [ ] **Step 7: `src/index.ts` を作成（空のプレースホルダー）**
+
+```ts
+// exports will be added in later tasks
+export {}
+```
+
+- [ ] **Step 8: `tsc --noEmit` が通ることを確認**
+
+```bash
+npx tsc --noEmit
+```
+
+Expected: エラーなし
+
+- [ ] **Step 9: commit**
+
+```bash
+git init
+git add .gitignore package.json tsconfig.json vitest.config.ts tsup.config.ts src/index.ts
+git commit -m "feat: initialize @o3co/ts.hocon project scaffold"
+```
+
+---
+
+## Task 2: エラー型
+
+**Files:**
+- Create: `src/errors.ts`
+- Create: `tests/errors.test.ts`
+
+- [ ] **Step 1: テストを書く**
+
+```ts
+// tests/errors.test.ts
+import { describe, it, expect } from 'vitest'
+import { ParseError, ResolveError, ConfigError } from '../src/errors.js'
+
+describe('ParseError', () => {
+  it('is an Error with line/col', () => {
+    const e = new ParseError('unexpected token', 3, 10)
+    expect(e).toBeInstanceOf(Error)
+    expect(e.message).toBe('unexpected token')
+    expect(e.line).toBe(3)
+    expect(e.col).toBe(10)
+    expect(e.file).toBeUndefined()
+  })
+
+  it('accepts optional file path', () => {
+    const e = new ParseError('bad syntax', 1, 1, 'app.conf')
+    expect(e.file).toBe('app.conf')
+  })
+})
+
+describe('ResolveError', () => {
+  it('carries path and position', () => {
+    const e = new ResolveError('unresolved substitution', 'server.host', 5, 3)
+    expect(e).toBeInstanceOf(Error)
+    expect(e.path).toBe('server.host')
+    expect(e.line).toBe(5)
+    expect(e.col).toBe(3)
+  })
+
+  it('line/col can be 0 (no position info)', () => {
+    const e = new ResolveError('include failed', 'path', 0, 0, 'app.conf')
+    expect(e.line).toBe(0)
+    expect(e.col).toBe(0)
+    expect(e.file).toBe('app.conf')
+  })
+})
+
+describe('ConfigError', () => {
+  it('carries path', () => {
+    const e = new ConfigError('key not found', 'server.port')
+    expect(e).toBeInstanceOf(Error)
+    expect(e.path).toBe('server.port')
+  })
+})
+```
+
+- [ ] **Step 2: テストを実行（失敗を確認）**
+
+```bash
+npx vitest run tests/errors.test.ts
+```
+
+Expected: FAIL（`../src/errors.js` not found）
+
+- [ ] **Step 3: `src/errors.ts` を実装**
+
+```ts
+export class ParseError extends Error {
+  constructor(
+    message: string,
+    public readonly line: number,
+    public readonly col: number,
+    public readonly file?: string,
+  ) {
+    super(message)
+    this.name = 'ParseError'
+  }
+}
+
+export class ResolveError extends Error {
+  constructor(
+    message: string,
+    public readonly path: string,
+    public readonly line: number,
+    public readonly col: number,
+    public readonly file?: string,
+  ) {
+    super(message)
+    this.name = 'ResolveError'
+  }
+}
+
+export class ConfigError extends Error {
+  constructor(
+    message: string,
+    public readonly path: string,
+  ) {
+    super(message)
+    this.name = 'ConfigError'
+  }
+}
+```
+
+- [ ] **Step 4: テストを実行（pass を確認）**
+
+```bash
+npx vitest run tests/errors.test.ts
+```
+
+Expected: 5 tests pass
+
+- [ ] **Step 5: commit**
+
+```bash
+git add src/errors.ts tests/errors.test.ts
+git commit -m "feat: add error types (ParseError, ResolveError, ConfigError)"
+```
+
+---
+
+## Task 3: Lexer
+
+**Files:**
+- Create: `src/internal/lexer/token.ts`
+- Create: `src/internal/lexer/lexer.ts`
+- Create: `tests/lexer.test.ts`
+
+- [ ] **Step 1: `src/internal/lexer/token.ts` を作成（型定義のみ）**
+
+```ts
+export type TokenKind =
+  | 'lbrace' | 'rbrace'
+  | 'lbracket' | 'rbracket'
+  | 'comma' | 'colon' | 'equals' | 'plus_equals'
+  | 'newline'
+  | 'string'         // "..." quoted string
+  | 'triple_string'  // """..."""
+  | 'unquoted'       // bare word, number, true/false/null
+  | 'subst'          // ${path}
+  | 'opt_subst'      // ${?path}
+  | 'eof'
+
+export type Token = {
+  kind: TokenKind
+  value: string           // always string; parser converts to number/bool/null
+  line: number
+  col: number
+  isQuoted: boolean       // true for "..." and """..."""
+  precedingSpace: boolean // true if preceded by whitespace (concat detection)
+}
+```
+
+- [ ] **Step 2: テストを書く**
+
+```ts
+// tests/lexer.test.ts
+import { describe, it, expect } from 'vitest'
+import { tokenize } from '../src/internal/lexer/lexer.js'
+import { ParseError } from '../src/errors.js'
+
+describe('tokenize', () => {
+  it('tokenizes empty string', () => {
+    const tokens = tokenize('')
+    expect(tokens).toHaveLength(1)
+    expect(tokens[0].kind).toBe('eof')
+  })
+
+  it('tokenizes braces and brackets', () => {
+    const tokens = tokenize('{}[]')
+    expect(tokens.map(t => t.kind)).toEqual(['lbrace', 'rbrace', 'lbracket', 'rbracket', 'eof'])
+  })
+
+  it('tokenizes = and +=', () => {
+    const tokens = tokenize('=+=')
+    expect(tokens[0].kind).toBe('equals')
+    expect(tokens[1].kind).toBe('plus_equals')
+  })
+
+  it('tokenizes : and ,', () => {
+    const tokens = tokenize(':,')
+    expect(tokens.map(t => t.kind)).toEqual(['colon', 'comma', 'eof'])
+  })
+
+  it('skips // comments, keeps newline', () => {
+    const tokens = tokenize('// comment\nfoo')
+    expect(tokens[0].kind).toBe('newline')
+    expect(tokens[1].kind).toBe('unquoted')
+    expect(tokens[1].value).toBe('foo')
+  })
+
+  it('skips # comments', () => {
+    const tokens = tokenize('# comment\nfoo')
+    expect(tokens[0].kind).toBe('newline')
+    expect(tokens[1].value).toBe('foo')
+  })
+
+  it('tokenizes quoted strings', () => {
+    const [t] = tokenize('"hello world"')
+    expect(t.kind).toBe('string')
+    expect(t.value).toBe('hello world')
+    expect(t.isQuoted).toBe(true)
+  })
+
+  it('handles escape sequences', () => {
+    const [t] = tokenize('"a\\nb\\tc"')
+    expect(t.value).toBe('a\nb\tc')
+  })
+
+  it('handles \\u unicode escapes', () => {
+    const [t] = tokenize('"\\u0041"')
+    expect(t.value).toBe('A')
+  })
+
+  it('tokenizes triple-quoted strings', () => {
+    const [t] = tokenize('"""hello\nworld"""')
+    expect(t.kind).toBe('triple_string')
+    expect(t.value).toBe('hello\nworld')
+    expect(t.isQuoted).toBe(true)
+  })
+
+  it('strips leading newline from triple-quoted strings', () => {
+    const [t] = tokenize('"""\nhello"""')
+    expect(t.value).toBe('hello')
+  })
+
+  it('tokenizes unquoted strings', () => {
+    const [t] = tokenize('localhost')
+    expect(t.kind).toBe('unquoted')
+    expect(t.value).toBe('localhost')
+    expect(t.isQuoted).toBe(false)
+  })
+
+  it('tokenizes numbers as unquoted', () => {
+    const [t] = tokenize('8080')
+    expect(t.kind).toBe('unquoted')
+    expect(t.value).toBe('8080')
+  })
+
+  it('tokenizes substitutions', () => {
+    const [t] = tokenize('${server.host}')
+    expect(t.kind).toBe('subst')
+    expect(t.value).toBe('server.host')
+  })
+
+  it('tokenizes optional substitutions', () => {
+    const [t] = tokenize('${?foo}')
+    expect(t.kind).toBe('opt_subst')
+    expect(t.value).toBe('foo')
+  })
+
+  it('tokenizes newlines', () => {
+    const tokens = tokenize('a\nb')
+    expect(tokens[1].kind).toBe('newline')
+  })
+
+  it('deduplicates consecutive newlines', () => {
+    const tokens = tokenize('a\n\n\nb')
+    const newlines = tokens.filter(t => t.kind === 'newline')
+    expect(newlines).toHaveLength(1)
+  })
+
+  it('tracks line and col', () => {
+    const tokens = tokenize('a\nb')
+    expect(tokens[0].line).toBe(1)
+    expect(tokens[0].col).toBe(1)
+    expect(tokens[2].line).toBe(2)
+    expect(tokens[2].col).toBe(1)
+  })
+
+  it('sets precedingSpace on token after whitespace', () => {
+    const tokens = tokenize('a b')
+    expect(tokens[1].precedingSpace).toBe(true)
+    expect(tokens[0].precedingSpace).toBe(false)
+  })
+
+  it('strips UTF-8 BOM', () => {
+    const tokens = tokenize('\uFEFFfoo')
+    expect(tokens[0].value).toBe('foo')
+  })
+
+  it('stops unquoted scan at $ for concat', () => {
+    const tokens = tokenize('foo${bar}')
+    expect(tokens[0].kind).toBe('unquoted')
+    expect(tokens[0].value).toBe('foo')
+    expect(tokens[1].kind).toBe('subst')
+    expect(tokens[1].value).toBe('bar')
+    expect(tokens[1].precedingSpace).toBe(false)
+  })
+
+  it('throws ParseError on unterminated string', () => {
+    expect(() => tokenize('"unterminated')).toThrow(ParseError)
+  })
+
+  it('throws ParseError on unterminated substitution', () => {
+    expect(() => tokenize('${foo')).toThrow(ParseError)
+  })
+})
+```
+
+- [ ] **Step 3: テストを実行（失敗を確認）**
+
+```bash
+npx vitest run tests/lexer.test.ts
+```
+
+Expected: FAIL（lexer.ts not found）
+
+- [ ] **Step 4: `src/internal/lexer/lexer.ts` を実装**
+
+```ts
+import { ParseError } from '../../errors.js'
+import type { Token, TokenKind } from './token.js'
+
+export function tokenize(input: string): Token[] {
+  if (input.charCodeAt(0) === 0xfeff) input = input.slice(1)
+
+  const tokens: Token[] = []
+  let pos = 0
+  let line = 1
+  let col = 1
+  let hadSpace = false
+
+  function peek(offset = 0): string { return input[pos + offset] ?? '' }
+
+  function advance(): string {
+    const ch = input[pos++]!
+    if (ch === '\n') { line++; col = 1 } else { col++ }
+    return ch
+  }
+
+  function push(kind: TokenKind, value: string, l: number, c: number, isQuoted = false): void {
+    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()
+
+    // Whitespace (not newline)
+    if (ch === ' ' || ch === '\t' || ch === '\r') {
+      advance(); hadSpace = true; continue
+    }
+
+    // Newline
+    if (ch === '\n') {
+      advance()
+      if (tokens.length === 0 || tokens[tokens.length - 1]!.kind !== 'newline') {
+        push('newline', '\n', sl, sc)
+      }
+      continue
+    }
+
+    // Comments
+    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
+    }
+
+    // Single-char punctuation
+    const single: Record<string, TokenKind> = { '{': 'lbrace', '}': 'rbrace', '[': 'lbracket', ']': 'rbracket', ',': 'comma', ':': 'colon' }
+    if (ch in single) { advance(); push(single[ch]!, ch, sl, sc); continue }
+
+    // = and +=
+    if (ch === '=') { advance(); push('equals', '=', sl, sc); continue }
+    if (ch === '+' && peek(1) === '=') { advance(); advance(); push('plus_equals', '+=', sl, sc); continue }
+
+    // Substitution ${...} or ${?...}
+    if (ch === '$' && peek(1) === '{') {
+      advance(); advance()
+      const optional = peek() === '?'
+      if (optional) advance()
+      let path = ''
+      while (pos < input.length && peek() !== '}') {
+        if (peek() === '\n') throw new ParseError('unterminated substitution', sl, sc)
+        path += advance()
+      }
+      if (peek() !== '}') throw new ParseError('unterminated substitution', sl, sc)
+      advance()
+      push(optional ? 'opt_subst' : 'subst', path.trim(), sl, sc)
+      continue
+    }
+
+    // Triple-quoted string
+    if (ch === '"' && peek(1) === '"' && peek(2) === '"') {
+      advance(); advance(); advance()
+      let value = ''
+      while (!(peek() === '"' && peek(1) === '"' && peek(2) === '"')) {
+        if (pos >= input.length) throw new ParseError('unterminated triple-quoted string', sl, sc)
+        value += advance()
+      }
+      advance(); advance(); advance()
+      if (value.startsWith('\n')) value = value.slice(1)
+      push('triple_string', value, sl, sc, true)
+      continue
+    }
+
+    // Quoted string
+    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 += '\t'; 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': {
+              const hex = input.slice(pos, pos + 4)
+              value += String.fromCharCode(parseInt(hex, 16))
+              for (let i = 0; i < 4; i++) advance()
+              break
+            }
+            default: value += esc
+          }
+        } else {
+          value += advance()
+        }
+      }
+      if (peek() !== '"') throw new ParseError('unterminated string', sl, sc)
+      advance()
+      push('string', value, sl, sc, true)
+      continue
+    }
+
+    // Unquoted string (stops at terminators and $)
+    if (isUnquotedStart(ch)) {
+      let value = ''
+      while (pos < input.length && isUnquotedContinue(peek(), () => peek(1))) {
+        value += advance()
+      }
+      push('unquoted', value.trimEnd(), sl, sc)
+      continue
+    }
+
+    throw new ParseError(`unexpected character: ${JSON.stringify(ch)}`, sl, sc)
+  }
+
+  tokens.push({ kind: 'eof', value: '', line, col, isQuoted: false, precedingSpace: false })
+  return tokens
+}
+
+function isUnquotedStart(ch: string): boolean {
+  return ch !== '' && !'{}[],:=+#\n\r\t "$'.includes(ch)
+}
+
+function isUnquotedContinue(ch: string, nextFn: () => string): boolean {
+  if (ch === '' || '{}[],:=\n#"$'.includes(ch)) return false
+  if (ch === '+' && nextFn() === '=') return false
+  if (ch === '/' && nextFn() === '/') return false
+  return true
+}
+```
+
+- [ ] **Step 5: テストを実行（pass を確認）**
+
+```bash
+npx vitest run tests/lexer.test.ts
+```
+
+Expected: 全テスト pass
+
+- [ ] **Step 6: commit**
+
+```bash
+git add src/internal/lexer/ tests/lexer.test.ts
+git commit -m "feat: implement HOCON lexer (tokenize)"
+```
+
+---
+
+## Task 4: Parser
+
+**Files:**
+- Create: `src/internal/parser/ast.ts`
+- Create: `src/internal/parser/parser.ts`
+- Create: `tests/parser.test.ts`
+
+- [ ] **Step 1: `src/internal/parser/ast.ts` を作成（型定義のみ）**
+
+```ts
+export type Pos = { line: number; col: number; file?: string }
+
+export type AstNode =
+  | { kind: 'object'; fields: AstField[]; pos: Pos }
+  | { kind: 'array'; items: AstNode[]; pos: Pos }
+  | { kind: 'scalar'; value: string | number | boolean | null; pos: Pos }
+  | { kind: 'concat'; nodes: AstNode[]; pos: Pos }
+  | { kind: 'subst'; path: string; optional: boolean; pos: Pos }
+  | { kind: 'include'; path: string; pos: Pos }
+
+// key が空配列のとき include ディレクティブを表す（value は include ノード）
+export type AstField = {
+  key: string[]     // 各要素は ドット分割済み。quoted キーはドット分割しない
+  value: AstNode
+  append: boolean   // true なら += 演算子
+  pos: Pos
+}
+```
+
+- [ ] **Step 2: テストを書く**
+
+```ts
+// tests/parser.test.ts
+import { describe, it, expect } from 'vitest'
+import { tokenize } from '../src/internal/lexer/lexer.js'
+import { parseTokens } from '../src/internal/parser/parser.js'
+import type { AstNode } from '../src/internal/parser/ast.js'
+
+function parse(input: string): AstNode {
+  return parseTokens(tokenize(input))
+}
+
+describe('parseTokens', () => {
+  it('parses empty input as empty object', () => {
+    const node = parse('')
+    expect(node.kind).toBe('object')
+    if (node.kind === 'object') expect(node.fields).toHaveLength(0)
+  })
+
+  it('parses key = value', () => {
+    const node = parse('host = "localhost"')
+    expect(node.kind).toBe('object')
+    if (node.kind === 'object') {
+      expect(node.fields[0]!.key).toEqual(['host'])
+      expect(node.fields[0]!.value.kind).toBe('scalar')
+    }
+  })
+
+  it('parses key: value (colon syntax)', () => {
+    const node = parse('port: 8080')
+    if (node.kind === 'object') {
+      expect(node.fields[0]!.key).toEqual(['port'])
+    }
+  })
+
+  it('parses dot-notation keys', () => {
+    const node = parse('server.host = "localhost"')
+    if (node.kind === 'object') {
+      expect(node.fields[0]!.key).toEqual(['server', 'host'])
+    }
+  })
+
+  it('does not split quoted keys at dots', () => {
+    const node = parse('"a.b" = 1')
+    if (node.kind === 'object') {
+      expect(node.fields[0]!.key).toEqual(['a.b'])
+    }
+  })
+
+  it('parses nested objects (brace syntax)', () => {
+    const node = parse('server { host = "localhost" }')
+    expect(node.kind).toBe('object')
+    if (node.kind === 'object') {
+      expect(node.fields[0]!.key).toEqual(['server'])
+      expect(node.fields[0]!.value.kind).toBe('object')
+    }
+  })
+
+  it('parses arrays', () => {
+    const node = parse('list = [1, 2, 3]')
+    if (node.kind === 'object') {
+      const arr = node.fields[0]!.value
+      expect(arr.kind).toBe('array')
+      if (arr.kind === 'array') expect(arr.items).toHaveLength(3)
+    }
+  })
+
+  it('parses boolean and null scalars', () => {
+    const node = parse('a = true\nb = false\nc = null')
+    if (node.kind === 'object') {
+      const vals = node.fields.map(f => f.value)
+      expect(vals[0]!.kind === 'scalar' && vals[0]!.value).toBe(true)
+      expect(vals[1]!.kind === 'scalar' && vals[1]!.value).toBe(false)
+      expect(vals[2]!.kind === 'scalar' && vals[2]!.value).toBe(null)
+    }
+  })
+
+  it('parses integer scalars', () => {
+    const node = parse('port = 8080')
+    if (node.kind === 'object') {
+      const val = node.fields[0]!.value
+      expect(val.kind === 'scalar' && val.value).toBe(8080)
+    }
+  })
+
+  it('parses float scalars', () => {
+    const node = parse('ratio = 1.5')
+    if (node.kind === 'object') {
+      const val = node.fields[0]!.value
+      expect(val.kind === 'scalar' && val.value).toBe(1.5)
+    }
+  })
+
+  it('parses substitutions', () => {
+    const node = parse('host = ${server.host}')
+    if (node.kind === 'object') {
+      const val = node.fields[0]!.value
+      expect(val.kind).toBe('subst')
+      if (val.kind === 'subst') {
+        expect(val.path).toBe('server.host')
+        expect(val.optional).toBe(false)
+      }
+    }
+  })
+
+  it('parses optional substitutions', () => {
+    const node = parse('host = ${?server.host}')
+    if (node.kind === 'object') {
+      const val = node.fields[0]!.value
+      if (val.kind === 'subst') expect(val.optional).toBe(true)
+    }
+  })
+
+  it('parses concat (adjacent tokens on same line, no space)', () => {
+    const node = parse('url = "http://"${host}":8080"')
+    if (node.kind === 'object') {
+      expect(node.fields[0]!.value.kind).toBe('concat')
+    }
+  })
+
+  it('parses += append operator', () => {
+    const node = parse('list += 1')
+    if (node.kind === 'object') {
+      expect(node.fields[0]!.append).toBe(true)
+    }
+  })
+
+  it('parses include directive', () => {
+    const node = parse('include "other.conf"')
+    if (node.kind === 'object') {
+      expect(node.fields[0]!.key).toHaveLength(0)
+      expect(node.fields[0]!.value.kind).toBe('include')
+    }
+  })
+
+  it('parses include file(...) syntax', () => {
+    const node = parse('include file("other.conf")')
+    if (node.kind === 'object') {
+      expect(node.fields[0]!.value.kind).toBe('include')
+    }
+  })
+})
+```
+
+- [ ] **Step 3: テストを実行（失敗を確認）**
+
+```bash
+npx vitest run tests/parser.test.ts
+```
+
+Expected: FAIL（parser.ts not found）
+
+- [ ] **Step 4: `src/internal/parser/parser.ts` を実装**
+
+Parser の責務：
+1. Token 列を受け取り、ルートが `AstNode` の `object` である AST を返す
+2. ルートオブジェクトの外括弧は省略可（bare オブジェクト）
+3. concat 検出：同じ行内で直前に空白がなく隣接する値 → `concat` ノード
+4. `true`/`false`/`null` のキーワード変換、数値変換
+
+```ts
+import { ParseError } from '../../errors.js'
+import type { Token } from '../lexer/token.js'
+import type { AstNode, AstField, Pos } from './ast.js'
+
+export function parseTokens(tokens: Token[]): AstNode {
+  let pos = 0
+
+  function peek(): Token { return tokens[pos] ?? { kind: 'eof', value: '', line: 0, col: 0, isQuoted: false, precedingSpace: false } }
+  function advance(): Token { return tokens[pos++] ?? peek() }
+  function skip(...kinds: string[]): void {
+    while (kinds.includes(peek().kind)) advance()
+  }
+
+  function currentPos(): Pos {
+    const t = peek()
+    return { line: t.line, col: t.col }
+  }
+
+  function parseObject(expectClosingBrace: boolean): AstNode {
+    const p = currentPos()
+    const fields: AstField[] = []
+
+    while (true) {
+      skip('newline')
+      const t = peek()
+      if (t.kind === 'eof' || t.kind === 'rbrace') break
+
+      // include directive
+      if (t.kind === 'unquoted' && t.value === 'include') {
+        advance()
+        fields.push(parseInclude())
+        continue
+      }
+
+      // key
+      const keyPos = currentPos()
+      const key = parseKey()
+
+      // value separator (optional)
+      skip('newline')
+      let append = false
+      const sep = peek()
+      if (sep.kind === 'equals') advance()
+      else if (sep.kind === 'plus_equals') { advance(); append = true }
+      else if (sep.kind === 'colon') advance()
+      else if (sep.kind === 'lbrace') { /* key { ... } shorthand, no advance */ }
+      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()
+      fields.push({ key, value, append, pos: keyPos })
+
+      // trailing separator
+      skip('newline')
+      if (peek().kind === 'comma') advance()
+      skip('newline')
+    }
+
+    if (expectClosingBrace) {
+      const t = peek()
+      if (t.kind !== 'rbrace') throw new ParseError('expected }', t.line, t.col)
+      advance()
+    }
+
+    return { kind: 'object', fields, pos: p }
+  }
+
+  function parseKey(): string[] {
+    const segments: string[] = []
+    while (true) {
+      const t = peek()
+      if (t.kind === 'string') {
+        advance()
+        segments.push(t.value) // quoted: no dot split
+      } else if (t.kind === 'unquoted') {
+        advance()
+        // Split unquoted key at dots
+        segments.push(...t.value.split('.').filter(s => s.length > 0))
+      } else {
+        throw new ParseError(`expected key, got ${t.kind}`, t.line, t.col)
+      }
+      // dot-chained: "a"."b" or a.b (already split above for unquoted)
+      // For quoted segments chained with dots we need to check next token
+      if (peek().kind === 'unquoted' || peek().kind === 'string') {
+        // could be key value without separator — stop if no dot following
+        // Heuristic: if next is a quoted string after no precedingSpace — continue key
+        // Actually for simplicity, stop here; dot-chain within unquoted already handled by split
+        break
+      }
+      break
+    }
+    return segments
+  }
+
+  function parseInclude(): AstField {
+    const p = currentPos()
+    const t = peek()
+    let path: string
+
+    if (t.kind === 'string') {
+      path = advance().value
+    } else if (t.kind === 'unquoted' && t.value === 'file') {
+      advance()
+      const lp = peek()
+      if (lp.kind !== 'unquoted' || lp.value !== '(') {
+        // Actually: after `file` we expect `(` — but since `(` is unquoted, let's re-check
+        // The lexer produces `file` as unquoted and `(` as part of unquoted or a separate token
+        // Safer: just scan until we find the quoted path inside
+      }
+      // Consume `file("path")`
+      // Skip `(` — it may be tokenized as part of unquoted or separate
+      // Consume everything until we hit a quoted string
+      while (peek().kind !== 'string' && peek().kind !== 'eof') advance()
+      path = advance().value
+      // Consume closing `)`
+      while (peek().kind !== 'newline' && peek().kind !== 'rbrace' && peek().kind !== 'eof') advance()
+    } else {
+      throw new ParseError(`expected include path, got ${t.kind}`, t.line, t.col)
+    }
+
+    return {
+      key: [],
+      value: { kind: 'include', path, pos: p },
+      append: false,
+      pos: p,
+    }
+  }
+
+  function parseValue(): AstNode {
+    const p = currentPos()
+    const parts: AstNode[] = []
+
+    while (true) {
+      const t = peek()
+      if (t.kind === 'eof' || t.kind === 'newline' || t.kind === 'rbrace' || t.kind === 'rbracket' || t.kind === 'comma') break
+      if (parts.length > 0 && t.precedingSpace) break // space separates values in value position
+
+      let node: AstNode
+      if (t.kind === 'lbrace') {
+        advance()
+        node = parseObject(true)
+      } else if (t.kind === 'lbracket') {
+        advance()
+        node = parseArray()
+      } else if (t.kind === 'subst' || t.kind === 'opt_subst') {
+        advance()
+        node = { kind: 'subst', path: t.value, optional: t.kind === 'opt_subst', pos: { line: t.line, col: t.col } }
+      } else if (t.kind === 'string' || t.kind === 'triple_string') {
+        advance()
+        node = { kind: 'scalar', value: t.value, pos: { line: t.line, col: t.col } }
+      } else if (t.kind === 'unquoted') {
+        advance()
+        node = { kind: 'scalar', value: parseScalarValue(t.value), pos: { line: t.line, col: t.col } }
+      } else {
+        break
+      }
+      parts.push(node)
+    }
+
+    if (parts.length === 0) throw new ParseError('expected value', peek().line, peek().col)
+    if (parts.length === 1) return parts[0]!
+    return { kind: 'concat', nodes: parts, pos: p }
+  }
+
+  function parseArray(): AstNode {
+    const p = currentPos()
+    const items: AstNode[] = []
+
+    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 t = peek()
+    if (t.kind !== 'rbracket') throw new ParseError('expected ]', t.line, t.col)
+    advance()
+    return { kind: 'array', items, pos: p }
+  }
+
+  function parseScalarValue(raw: string): string | number | boolean | null {
+    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()
+    return parseObject(true)
+  }
+  return parseObject(false)
+}
+```
+
+**注意：** この実装は基本ケースをカバーするもの。Go 実装 (`/Volumes/Workspace/o3co/repos/go.hocon/internal/parser/parser.go`) を参照しながら、エッジケース（dot-chain quoted keys、value concatenation のルール等）を補完すること。
+
+- [ ] **Step 5: テストを実行（pass を確認）**
+
+```bash
+npx vitest run tests/parser.test.ts
+```
+
+Expected: 全テスト pass
+
+- [ ] **Step 6: commit**
+
+```bash
+git add src/internal/parser/ tests/parser.test.ts
+git commit -m "feat: implement HOCON AST parser"
+```
+
+---
+
+## Task 5: HoconValue 型 + Resolver（完全実装、include なし）
+
+**Files:**
+- Create: `src/value.ts`
+- Create: `src/internal/resolver/resolver.ts`
+- Create: `tests/resolver.test.ts`
+
+- [ ] **Step 1: `src/value.ts` を作成（型定義のみ）**
+
+```ts
+// JavaScript の Map は挿入順を保証するため keys フィールド不要
+export type HoconValue =
+  | { kind: 'object'; fields: Map<string, HoconValue> }
+  | { kind: 'array'; items: HoconValue[] }
+  | { kind: 'scalar'; value: string | number | boolean | null }
+```
+
+- [ ] **Step 2: Resolver (Pass 1) のテストを書く**
+
+```ts
+// tests/resolver.test.ts
+import { describe, it, expect } from 'vitest'
+import { tokenize } from '../src/internal/lexer/lexer.js'
+import { parseTokens } from '../src/internal/parser/parser.js'
+import { resolve } from '../src/internal/resolver/resolver.js'
+import type { HoconValue } from '../src/value.js'
+import { ResolveError } from '../src/errors.js'
+
+function resolveStr(input: string, env: Record<string, string> = {}): HoconValue {
+  const ast = parseTokens(tokenize(input))
+  return resolve(ast, { env, baseDir: undefined, readFileSync: () => { throw new Error('no fs') } })
+}
+
+function obj(v: HoconValue): Map<string, HoconValue> {
+  if (v.kind !== 'object') throw new Error('expected object')
+  return v.fields
+}
+
+describe('Resolver - Pass 1 (structure)', () => {
+  it('resolves simple string value', () => {
+    const v = resolveStr('host = "localhost"')
+    expect(obj(v).get('host')).toEqual({ kind: 'scalar', value: 'localhost' })
+  })
+
+  it('resolves number value', () => {
+    const v = resolveStr('port = 8080')
+    expect(obj(v).get('port')).toEqual({ kind: 'scalar', value: 8080 })
+  })
+
+  it('resolves nested objects', () => {
+    const v = resolveStr('server { host = "localhost" }')
+    const server = obj(v).get('server')
+    expect(server?.kind).toBe('object')
+  })
+
+  it('merges duplicate object keys', () => {
+    const v = resolveStr('server { host = "a" }\nserver { port = 8080 }')
+    const server = obj(v).get('server')
+    if (server?.kind === 'object') {
+      expect(server.fields.has('host')).toBe(true)
+      expect(server.fields.has('port')).toBe(true)
+    }
+  })
+
+  it('last value wins for scalar keys', () => {
+    const v = resolveStr('x = 1\nx = 2')
+    expect(obj(v).get('x')).toEqual({ kind: 'scalar', value: 2 })
+  })
+
+  it('resolves arrays', () => {
+    const v = resolveStr('list = [1, 2, 3]')
+    const arr = obj(v).get('list')
+    expect(arr?.kind).toBe('array')
+    if (arr?.kind === 'array') expect(arr.items).toHaveLength(3)
+  })
+
+  it('handles += on existing array', () => {
+    const v = resolveStr('list = [1, 2]\nlist += 3')
+    const arr = obj(v).get('list')
+    if (arr?.kind === 'array') expect(arr.items).toHaveLength(3)
+  })
+
+  it('handles += on missing key (starts from empty array)', () => {
+    const v = resolveStr('list += 1')
+    const arr = obj(v).get('list')
+    if (arr?.kind === 'array') expect(arr.items).toHaveLength(1)
+  })
+
+  it('preserves Map insertion order', () => {
+    const v = resolveStr('c = 3\na = 1\nb = 2')
+    const keys = [...obj(v).keys()]
+    expect(keys).toEqual(['c', 'a', 'b'])
+  })
+})
+
+describe('Resolver - Pass 2 (substitutions)', () => {
+  it('resolves ${path} substitution', () => {
+    const v = resolveStr('host = "localhost"\nurl = ${host}')
+    expect(obj(v).get('url')).toEqual({ kind: 'scalar', value: 'localhost' })
+  })
+
+  it('resolves nested path substitution', () => {
+    const v = resolveStr('server { host = "x" }\nhost = ${server.host}')
+    expect(obj(v).get('host')).toEqual({ kind: 'scalar', value: 'x' })
+  })
+
+  it('resolves ${?path} optional substitution (path exists)', () => {
+    const v = resolveStr('a = 1\nb = ${?a}')
+    expect(obj(v).get('b')).toEqual({ kind: 'scalar', value: 1 })
+  })
+
+  it('drops field for ${?path} optional substitution (path missing)', () => {
+    const v = resolveStr('b = ${?missing}')
+    expect(obj(v).get('b')).toBeUndefined()
+  })
+
+  it('throws ResolveError for unresolved mandatory substitution', () => {
+    expect(() => resolveStr('b = ${missing}')).toThrow(ResolveError)
+  })
+
+  it('falls back to env for unresolved substitution', () => {
+    const v = resolveStr('b = ${MY_VAR}', { MY_VAR: 'hello' })
+    expect(obj(v).get('b')).toEqual({ kind: 'scalar', value: 'hello' })
+  })
+
+  it('resolves self-referential substitution', () => {
+    const v = resolveStr('path = "/usr"\npath = ${path}:/extra')
+    // concat resolves: "/usr" + ":/extra" = "/usr:/extra"
+    const result = obj(v).get('path')
+    if (result?.kind === 'scalar') expect(String(result.value)).toContain('/usr')
+  })
+
+  it('resolves string concat with substitution', () => {
+    const v = resolveStr('host = "localhost"\nurl = "http://"${host}')
+    const result = obj(v).get('url')
+    expect(result?.kind === 'scalar' && result.value).toBe('http://localhost')
+  })
+
+  it('throws ResolveError on circular substitution', () => {
+    expect(() => resolveStr('a = ${b}\nb = ${a}')).toThrow(ResolveError)
+  })
+})
+```
+
+- [ ] **Step 3: テストを実行（失敗を確認）**
+
+```bash
+npx vitest run tests/resolver.test.ts
+```
+
+Expected: FAIL（resolver.ts not found）
+
+- [ ] **Step 4: `src/internal/resolver/resolver.ts` を実装（Pass 1 + Pass 2、include なし）**
+
+Go 版 `/Volumes/Workspace/o3co/repos/go.hocon/internal/resolver/resolver.go` を参照すること。
+
+```ts
+import { ResolveError } from '../../errors.js'
+import type { AstNode, AstField } from '../parser/ast.js'
+import type { HoconValue } from '../../../value.js'
+
+// ---- Internal placeholder types (not exported) ----
+// _kind strings match the spec exactly
+type SubstPlaceholder = {
+  _kind: 'subst-placeholder'
+  path: string
+  optional: boolean
+  line: number
+  col: number
+}
+type ConcatPlaceholder = {
+  _kind: 'concat-placeholder'
+  nodes: ResolverValue[]
+}
+// AppendPlaceholder for += operator
+type AppendPlaceholder = {
+  _kind: 'append-placeholder'
+  existing: ResolverValue
+  elem: ResolverValue
+}
+
+// ResObj: internal object node (discriminated by _kind so TypeScript can narrow it)
+type ResObj = {
+  _kind: 'res-obj'
+  fields: Map<string, ResolverValue>
+  priorValues: Map<string, ResolverValue>
+}
+
+type ResolverValue = HoconValue | SubstPlaceholder | ConcatPlaceholder | AppendPlaceholder | ResObj
+
+function isSubst(v: ResolverValue): v is SubstPlaceholder {
+  return (v as SubstPlaceholder)._kind === 'subst-placeholder'
+}
+function isConcat(v: ResolverValue): v is ConcatPlaceholder {
+  return (v as ConcatPlaceholder)._kind === 'concat-placeholder'
+}
+function isAppend(v: ResolverValue): v is AppendPlaceholder {
+  return (v as AppendPlaceholder)._kind === 'append-placeholder'
+}
+function isResObj(v: ResolverValue): v is ResObj {
+  return (v as ResObj)._kind === 'res-obj'
+}
+
+function makeResObj(): ResObj {
+  return { _kind: 'res-obj', fields: new Map(), priorValues: new Map() }
+}
+
+export type ResolveOptions = {
+  env: Record<string, string>
+  baseDir: string | undefined
+  readFileSync: (filePath: string) => string
+  includeStack?: string[]
+}
+
+// ---- Public entry point ----
+
+export function resolve(ast: AstNode, opts: ResolveOptions): HoconValue {
+  // Pass 1
+  const root = buildResObj(ast, opts)
+  // Pass 2
+  const resolving = new Set<string>()
+  const resolvedCache = new Map<string, HoconValue>()
+  return resolveResObj(root, root, resolving, resolvedCache, opts)
+}
+
+// ---- Pass 1: structure building ----
+
+function buildResObj(ast: AstNode, opts: ResolveOptions): ResObj {
+  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) {
+    applyField(obj, field, opts)
+  }
+  return obj
+}
+
+function applyField(obj: ResObj, field: AstField, opts: ResolveOptions): void {
+  // include directive: key is empty, value is include node
+  if (field.key.length === 0 && field.value.kind === 'include') {
+    const included = loadInclude(field.value.path, opts)
+    deepMergeResObjInto(obj, included)
+    return
+  }
+
+  const [head, ...tail] = field.key
+  if (!head) return
+
+  if (tail.length > 0) {
+    // Nested key: server.host = "x" → create synthetic object AST
+    const syntheticAst: AstNode = {
+      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) {
+    // +=: append elem to existing array (or start from [])
+    const existing: ResolverValue = obj.fields.get(head) ?? ({ kind: 'array', items: [] } satisfies HoconValue)
+    obj.priorValues.set(head, existing)
+    obj.fields.set(head, {
+      _kind: 'append-placeholder',
+      existing,
+      elem: astToResolverValue(field.value),
+    })
+    return
+  }
+
+  // Normal assignment
+  const existing = obj.fields.get(head)
+  const newVal = astToResolverValue(field.value)
+
+  // Save prior value for self-referential substitution resolution
+  if (existing !== undefined) {
+    obj.priorValues.set(head, existing)
+  }
+
+  // Deep merge if both are ResObj
+  if (existing !== undefined && isResObj(existing) && isResObj(newVal)) {
+    deepMergeResObjInto(existing, newVal)
+    // existing already in fields — no re-set needed
+    return
+  }
+
+  obj.fields.set(head, newVal)
+}
+
+function astToResolverValue(ast: AstNode): ResolverValue {
+  switch (ast.kind) {
+    case 'scalar':
+      return { kind: 'scalar', value: ast.value }
+    case 'array':
+      return { kind: 'array', items: ast.items.map(i => astToResolverValue(i) as HoconValue) }
+    case 'object': {
+      // Nested object literal: build a ResObj for Pass 2 processing
+      // opts are not available here, but includes inside object literals are rare;
+      // pass a no-op readFileSync — include in nested objects will throw at resolve time
+      const inner = buildResObj(ast, { env: {}, baseDir: undefined, readFileSync: () => { throw new ResolveError('include in nested object literal not supported here', '', 0, 0) } })
+      return inner
+    }
+    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(astToResolverValue) }
+    case 'include':
+      return { kind: 'scalar', value: null } // handled by applyField; should not reach here
+  }
+}
+
+function deepMergeResObjInto(dst: ResObj, src: ResObj): void {
+  for (const [k, srcVal] of src.fields) {
+    const dstVal = dst.fields.get(k)
+    if (dstVal !== undefined && isResObj(dstVal) && isResObj(srcVal)) {
+      // Both are objects: recurse
+      deepMergeResObjInto(dstVal, srcVal)
+    } else {
+      if (dstVal !== undefined) dst.priorValues.set(k, dstVal)
+      dst.fields.set(k, srcVal)
+    }
+  }
+}
+
+// ---- Pass 2: substitution resolution ----
+
+function resolveResObj(
+  obj: ResObj,
+  root: ResObj,
+  resolving: Set<string>,
+  resolvedCache: Map<string, HoconValue>,
+  opts: ResolveOptions,
+): HoconValue {
+  const result = new Map<string, HoconValue>()
+  for (const [key, val] of obj.fields) {
+    const resolved = resolveVal(val, obj, root, resolving, resolvedCache, opts)
+    if (resolved !== undefined) result.set(key, resolved)
+  }
+  return { kind: 'object', fields: result }
+}
+
+function resolveVal(
+  v: ResolverValue,
+  scope: ResObj,
+  root: ResObj,
+  resolving: Set<string>,
+  resolvedCache: Map<string, HoconValue>,
+  opts: ResolveOptions,
+): HoconValue | undefined {
+  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 as HoconValue
+  if (hv.kind === 'array') {
+    return {
+      kind: 'array',
+      items: hv.items.map(item =>
+        resolveVal(item as ResolverValue, scope, root, resolving, resolvedCache, opts)
+        ?? ({ kind: 'scalar', value: null } satisfies HoconValue)
+      ),
+    }
+  }
+  return hv
+}
+
+function resolveSubst(
+  s: SubstPlaceholder,
+  scope: ResObj,
+  root: ResObj,
+  resolving: Set<string>,
+  resolvedCache: Map<string, HoconValue>,
+  opts: ResolveOptions,
+): HoconValue | undefined {
+  if (resolvedCache.has(s.path)) return resolvedCache.get(s.path)!
+
+  if (resolving.has(s.path)) {
+    // Cycle detected: try prior value for self-referential substitutions
+    const rootSeg = s.path.split('.')[0]!
+    const prior = scope.priorValues.get(rootSeg)
+    if (prior !== undefined) {
+      return resolveVal(prior, scope, root, new Set(resolving), resolvedCache, opts)
+    }
+    throw new ResolveError(`circular substitution: ${s.path}`, s.path, s.line, s.col)
+  }
+
+  resolving.add(s.path)
+  try {
+    const found = lookupPath(root, s.path.split('.'))
+    if (found !== undefined) {
+      const result = resolveVal(found, scope, root, resolving, resolvedCache, opts)
+      if (result !== undefined) resolvedCache.set(s.path, result)
+      return result
+    }
+
+    // Env var fallback
+    const envVal = opts.env[s.path]
+    if (envVal !== undefined) {
+      const result: HoconValue = { kind: 'scalar', value: envVal }
+      resolvedCache.set(s.path, result)
+      return result
+    }
+
+    if (s.optional) return undefined
+    throw new ResolveError(`could not resolve substitution: \${${s.path}}`, s.path, s.line, s.col)
+  } finally {
+    resolving.delete(s.path)
+  }
+}
+
+function resolveConcat(
+  nodes: ResolverValue[],
+  scope: ResObj,
+  root: ResObj,
+  resolving: Set<string>,
+  resolvedCache: Map<string, HoconValue>,
+  opts: ResolveOptions,
+): HoconValue {
+  const resolved = nodes
+    .map(n => resolveVal(n, scope, root, resolving, resolvedCache, opts))
+    .filter((v): v is HoconValue => v !== undefined)
+
+  if (resolved.length === 0) return { kind: 'scalar', value: null }
+  if (resolved.length === 1) return resolved[0]!
+
+  // Array concatenation: if any element is an array, treat all as array elements
+  if (resolved.some(v => v.kind === 'array')) {
+    const items: HoconValue[] = []
+    for (const v of resolved) {
+      if (v.kind === 'array') items.push(...v.items)
+      else items.push(v)
+    }
+    return { kind: 'array', items }
+  }
+
+  // String concatenation
+  const str = resolved.map(v => v.kind === 'scalar' ? String(v.value ?? '') : JSON.stringify(v)).join('')
+  return { kind: 'scalar', value: str }
+}
+
+function resolveAppend(
+  a: AppendPlaceholder,
+  scope: ResObj,
+  root: ResObj,
+  resolving: Set<string>,
+  resolvedCache: Map<string, HoconValue>,
+  opts: ResolveOptions,
+): HoconValue {
+  const existing = resolveVal(a.existing, scope, root, resolving, resolvedCache, opts)
+    ?? ({ kind: 'array', items: [] } satisfies HoconValue)
+  const elem = resolveVal(a.elem, scope, root, resolving, resolvedCache, opts)
+  const items: HoconValue[] = existing.kind === 'array' ? [...existing.items] : [existing]
+  if (elem !== undefined) items.push(elem)
+  return { kind: 'array', items }
+}
+
+function lookupPath(root: ResObj, segments: string[]): ResolverValue | undefined {
+  const [head, ...tail] = segments
+  if (!head) return undefined
+  const val = root.fields.get(head)
+  if (val === undefined) return undefined
+  if (tail.length === 0) return val
+  if (isResObj(val)) return lookupPath(val, tail)
+  return undefined
+}
+
+// loadInclude: stub — implemented in Task 6
+function loadInclude(includePath: string, opts: ResolveOptions): ResObj {
+  throw new ResolveError(`include not yet supported: ${includePath}`, includePath, 0, 0)
+}
+```
+
+- [ ] **Step 5: テストを実行（pass を確認）**
+
+```bash
+npx vitest run tests/resolver.test.ts
+```
+
+Expected: 全テスト pass（include テストはまだないため全件 pass）
+
+- [ ] **Step 6: commit**
+
+```bash
+git add src/value.ts src/internal/resolver/ tests/resolver.test.ts
+git commit -m "feat: implement HoconValue types and Resolver (Pass 1 + Pass 2, no include)"
+```
+
+---
+
+## Task 6: Resolver — include ディレクティブ対応
+
+**Files:**
+
+- Modify: `src/internal/resolver/resolver.ts`（`loadInclude` を実装）
+- Modify: `tests/resolver.test.ts`（include テストを追加）
+
+- [ ] **Step 1: include テストを `tests/resolver.test.ts` に追加**
+
+```ts
+// tests/resolver.test.ts の末尾に追加
+
+describe('Resolver - include', () => {
+  function resolveWithFs(input: string, files: Record<string, string>): HoconValue {
+    const ast = parseTokens(tokenize(input))
+    return resolve(ast, {
+      env: {},
+      baseDir: '/fake',
+      readFileSync: (p: string) => {
+        const key = p.replace('/fake/', '')
+        if (!(key in files)) throw new Error(`file not found: ${p}`)
+        return files[key]!
+      },
+    })
+  }
+
+  it('merges included file into current object', () => {
+    const v = resolveWithFs('include "other.conf"\nport = 8080', {
+      'other.conf': 'host = "localhost"',
+    })
+    expect(obj(v).get('host')).toEqual({ kind: 'scalar', value: 'localhost' })
+    expect(obj(v).get('port')).toEqual({ kind: 'scalar', value: 8080 })
+  })
+
+  it('throws ResolveError on circular include', () => {
+    expect(() =>
+      resolveWithFs('include "a.conf"', {
+        'a.conf': 'include "b.conf"',
+        'b.conf': 'include "a.conf"',
+      })
+    ).toThrow(ResolveError)
+  })
+})
+```
+
+- [ ] **Step 2: テストを実行（失敗を確認）**
+
+```bash
+npx vitest run tests/resolver.test.ts -t "include"
+```
+
+Expected: FAIL（`loadInclude` throws "not yet supported"）
+
+- [ ] **Step 3: `loadInclude` を `resolver.ts` で実装（stub を置き換える）**
+
+ファイル先頭に以下の static import を追加する（`await import` は使わない）：
+
+```ts
+import * as nodePath from 'node:path'
+import { tokenize } from '../lexer/lexer.js'
+import { parseTokens } from '../parser/parser.js'
+```
+
+`loadInclude` 関数を以下で置き換える：
+
+```ts
+function loadInclude(includePath: string, opts: ResolveOptions): ResObj {
+  const { baseDir, readFileSync, includeStack = [], env } = opts
+  const absPath = baseDir
+    ? nodePath.resolve(baseDir, includePath)
+    : nodePath.resolve(includePath)
+
+  if (includeStack.includes(absPath)) {
+    throw new ResolveError(`circular include: ${absPath}`, absPath, 0, 0)
+  }
+
+  const content = readFileSync(absPath)
+  const ast = parseTokens(tokenize(content))
+  return buildResObj(ast, {
+    env,
+    baseDir: nodePath.dirname(absPath),
+    readFileSync,
+    includeStack: [...includeStack, absPath],
+  })
+}
+```
+
+- [ ] **Step 4: 全 Resolver テストを実行（pass を確認）**
+
+```bash
+npx vitest run tests/resolver.test.ts
+```
+
+Expected: 全テスト pass
+
+- [ ] **Step 5: commit**
+
+```bash
+git add src/internal/resolver/resolver.ts tests/resolver.test.ts
+git commit -m "feat: implement include directive support in Resolver"
+```
+
+---
+
+## Task 7: Config クラス
+
+**Files:**
+- Create: `src/config.ts`
+- Create: `tests/config.test.ts`
+
+- [ ] **Step 1: テストを書く**
+
+```ts
+// tests/config.test.ts
+import { describe, it, expect } from 'vitest'
+import { Config } from '../src/config.js'
+import type { HoconValue } from '../src/value.js'
+import { ConfigError } from '../src/errors.js'
+
+function makeConfig(obj: Record<string, HoconValue>): Config {
+  return new Config({ kind: 'object', fields: new Map(Object.entries(obj)) })
+}
+
+describe('Config', () => {
+  it('get() returns value at path', () => {
+    const c = makeConfig({ host: { kind: 'scalar', value: 'localhost' } })
+    expect(c.get('host')).toBe('localhost')
+  })
+
+  it('get() returns nested value at dot-path', () => {
+    const inner = new Map([['host', { kind: 'scalar', value: 'localhost' } satisfies HoconValue]])
+    const c = new Config({ kind: 'object', fields: new Map([['server', { kind: 'object', fields: inner }]]) })
+    expect(c.get('server.host')).toBe('localhost')
+  })
+
+  it('get() returns undefined for missing path', () => {
+    const c = makeConfig({})
+    expect(c.get('missing')).toBeUndefined()
+  })
+
+  it('getString() returns string value', () => {
+    const c = makeConfig({ host: { kind: 'scalar', value: 'localhost' } })
+    expect(c.getString('host')).toBe('localhost')
+  })
+
+  it('getString() throws ConfigError for non-string', () => {
+    const c = makeConfig({ port: { kind: 'scalar', value: 8080 } })
+    expect(() => c.getString('port')).toThrow(ConfigError)
+  })
+
+  it('getNumber() returns number value', () => {
+    const c = makeConfig({ port: { kind: 'scalar', value: 8080 } })
+    expect(c.getNumber('port')).toBe(8080)
+  })
+
+  it('getNumber() throws ConfigError for non-number', () => {
+    const c = makeConfig({ host: { kind: 'scalar', value: 'localhost' } })
+    expect(() => c.getNumber('host')).toThrow(ConfigError)
+  })
+
+  it('getBoolean() returns boolean value', () => {
+    const c = makeConfig({ debug: { kind: 'scalar', value: true } })
+    expect(c.getBoolean('debug')).toBe(true)
+  })
+
+  it('getConfig() returns sub-config', () => {
+    const inner = new Map([['host', { kind: 'scalar', value: 'localhost' } satisfies HoconValue]])
+    const c = new Config({ kind: 'object', fields: new Map([['server', { kind: 'object', fields: inner }]]) })
+    const sub = c.getConfig('server')
+    expect(sub).toBeInstanceOf(Config)
+    expect(sub.getString('host')).toBe('localhost')
+  })
+
+  it('getList() returns array as unknown[]', () => {
+    const items: HoconValue[] = [{ kind: 'scalar', value: 1 }, { kind: 'scalar', value: 2 }]
+    const c = makeConfig({ list: { kind: 'array', items } })
+    expect(c.getList('list')).toEqual([1, 2])
+  })
+
+  it('has() returns true for existing key', () => {
+    const c = makeConfig({ host: { kind: 'scalar', value: 'localhost' } })
+    expect(c.has('host')).toBe(true)
+  })
+
+  it('has() returns true for null value', () => {
+    const c = makeConfig({ x: { kind: 'scalar', value: null } })
+    expect(c.has('x')).toBe(true)
+  })
+
+  it('has() returns false for missing key', () => {
+    const c = makeConfig({})
+    expect(c.has('missing')).toBe(false)
+  })
+
+  it('keys() returns top-level keys in order', () => {
+    const c = new Config({ kind: 'object', fields: new Map([['b', { kind: 'scalar', value: 2 }], ['a', { kind: 'scalar', value: 1 }]]) })
+    expect(c.keys()).toEqual(['b', 'a'])
+  })
+
+  it('withFallback() receiver wins', () => {
+    const c1 = makeConfig({ host: { kind: 'scalar', value: 'prod' } })
+    const c2 = makeConfig({ host: { kind: 'scalar', value: 'dev' }, port: { kind: 'scalar', value: 8080 } })
+    const merged = c1.withFallback(c2)
+    expect(merged.getString('host')).toBe('prod')
+    expect(merged.getNumber('port')).toBe(8080)
+  })
+
+  it('toObject() converts to plain JS object recursively', () => {
+    const inner = new Map([['host', { kind: 'scalar', value: 'localhost' } satisfies HoconValue]])
+    const c = new Config({ kind: 'object', fields: new Map([['server', { kind: 'object', fields: inner }]]) })
+    expect(c.toObject()).toEqual({ server: { host: 'localhost' } })
+  })
+})
+```
+
+- [ ] **Step 2: テストを実行（失敗を確認）**
+
+```bash
+npx vitest run tests/config.test.ts
+```
+
+Expected: FAIL
+
+- [ ] **Step 3: `src/config.ts` を実装**
+
+```ts
+import { ConfigError } from './errors.js'
+import type { HoconValue } from './value.js'
+
+export class Config {
+  constructor(private readonly root: HoconValue & { kind: 'object' }) {}
+
+  get(path: string): unknown {
+    const v = this.lookup(path)
+    if (v === undefined) return undefined
+    return hoconToJs(v)
+  }
+
+  getString(path: string): string {
+    const v = this.requireScalar(path)
+    if (typeof v !== 'string') throw new ConfigError(`expected string at ${path}, got ${typeof v}`, path)
+    return v
+  }
+
+  getNumber(path: string): number {
+    const v = this.requireScalar(path)
+    if (typeof v !== 'number') throw new ConfigError(`expected number at ${path}, got ${typeof v}`, path)
+    return v
+  }
+
+  getBoolean(path: string): boolean {
+    const v = this.requireScalar(path)
+    if (typeof v !== 'boolean') throw new ConfigError(`expected boolean at ${path}, got ${typeof v}`, path)
+    return v
+  }
+
+  getConfig(path: string): Config {
+    const v = this.lookupNode(path)
+    if (v === undefined) throw new ConfigError(`path not found: ${path}`, path)
+    if (v.kind !== 'object') throw new ConfigError(`expected object at ${path}`, path)
+    return new Config(v)
+  }
+
+  getList(path: string): unknown[] {
+    const v = this.lookupNode(path)
+    if (v === undefined) throw new ConfigError(`path not found: ${path}`, path)
+    if (v.kind !== 'array') throw new ConfigError(`expected array at ${path}`, path)
+    return v.items.map(hoconToJs)
+  }
+
+  has(path: string): boolean {
+    return this.lookupNode(path) !== undefined
+  }
+
+  keys(): string[] {
+    return [...this.root.fields.keys()]
+  }
+
+  withFallback(fallback: Config): Config {
+    const merged = deepMergeHocon(this.root, fallback.root)
+    return new Config(merged)
+  }
+
+  toObject(): unknown {
+    return hoconToJs(this.root)
+  }
+
+  private lookupNode(path: string): HoconValue | undefined {
+    const segments = path.split('.')
+    let current: HoconValue = this.root
+    for (const seg of segments) {
+      if (current.kind !== 'object') return undefined
+      const next = current.fields.get(seg)
+      if (next === undefined) return undefined
+      current = next
+    }
+    return current
+  }
+
+  private lookup(path: string): HoconValue | undefined {
+    return this.lookupNode(path)
+  }
+
+  private requireScalar(path: string): string | number | boolean | null {
+    const v = this.lookupNode(path)
+    if (v === undefined) throw new ConfigError(`path not found: ${path}`, path)
+    if (v.kind !== 'scalar') throw new ConfigError(`expected scalar at ${path}, got ${v.kind}`, path)
+    return v.value
+  }
+}
+
+function hoconToJs(v: HoconValue): unknown {
+  switch (v.kind) {
+    case 'scalar': return v.value
+    case 'array': return v.items.map(hoconToJs)
+    case 'object': {
+      const obj: Record<string, unknown> = {}
+      for (const [k, val] of v.fields) obj[k] = hoconToJs(val)
+      return obj
+    }
+  }
+}
+
+function deepMergeHocon(
+  receiver: HoconValue & { kind: 'object' },
+  fallback: HoconValue & { kind: 'object' },
+): HoconValue & { kind: 'object' } {
+  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))
+    } else {
+      merged.set(k, v)
+    }
+  }
+  return { kind: 'object', fields: merged }
+}
+```
+
+- [ ] **Step 4: テストを実行（pass を確認）**
+
+```bash
+npx vitest run tests/config.test.ts
+```
+
+Expected: 全テスト pass
+
+- [ ] **Step 5: commit**
+
+```bash
+git add src/config.ts tests/config.test.ts
+git commit -m "feat: implement Config class"
+```
+
+---
+
+## Task 8: Parse 関数 + public exports
+
+**Files:**
+- Create: `src/parse.ts`
+- Modify: `src/index.ts`
+- Create: `tests/parse.test.ts`
+
+- [ ] **Step 1: 統合テストを書く**
+
+```ts
+// tests/parse.test.ts
+import { describe, it, expect } from 'vitest'
+import { parse, parseAsync } from '../src/parse.js'
+import { ParseError, ResolveError } from '../src/errors.js'
+
+describe('parse()', () => {
+  it('parses basic config', () => {
+    const c = parse('server { host = "localhost"\nport = 8080 }')
+    expect(c.getString('server.host')).toBe('localhost')
+    expect(c.getNumber('server.port')).toBe(8080)
+  })
+
+  it('resolves substitutions end-to-end', () => {
+    const c = parse('base = "hello"\ngreeting = ${base}" world"')
+    expect(c.getString('greeting')).toBe('hello world')
+  })
+
+  it('uses env option for substitution fallback', () => {
+    const c = parse('val = ${MY_ENV}', { env: { MY_ENV: 'from-env' } })
+    expect(c.getString('val')).toBe('from-env')
+  })
+
+  it('uses process.env as default env', () => {
+    process.env['HOCON_TEST_VAR'] = 'test-value'
+    const c = parse('val = ${HOCON_TEST_VAR}')
+    expect(c.getString('val')).toBe('test-value')
+    delete process.env['HOCON_TEST_VAR']
+  })
+
+  it('throws ParseError for syntax errors', () => {
+    expect(() => parse('{ unclosed')).toThrow(ParseError)
+  })
+
+  it('throws ResolveError for unresolved substitution', () => {
+    expect(() => parse('x = ${missing}')).toThrow(ResolveError)
+  })
+})
+
+describe('parseAsync()', () => {
+  it('parses basic config asynchronously', async () => {
+    const c = await parseAsync('host = "localhost"')
+    expect(c.getString('host')).toBe('localhost')
+  })
+})
+```
+
+- [ ] **Step 2: テストを実行（失敗を確認）**
+
+```bash
+npx vitest run tests/parse.test.ts
+```
+
+Expected: FAIL
+
+- [ ] **Step 3: `src/parse.ts` を実装**
+
+```ts
+import { tokenize } from './internal/lexer/lexer.js'
+import { parseTokens } from './internal/parser/parser.js'
+import { resolve } from './internal/resolver/resolver.js'
+import { Config } from './config.js'
+import type { ResolveOptions } from './internal/resolver/resolver.js'
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+
+export type ParseOptions = {
+  baseDir?: string
+  env?: Record<string, string>
+  readFile?: (filePath: string) => Promise<string>
+  readFileSync?: (filePath: string) => string
+}
+
+function getEnv(opts: ParseOptions): Record<string, string> {
+  if (opts.env !== undefined) return opts.env
+  if (typeof process !== 'undefined' && process.env) return process.env as Record<string, string>
+  return {}
+}
+
+function defaultReadFileSync(filePath: string): string {
+  return fs.readFileSync(filePath, 'utf-8')
+}
+
+async function defaultReadFile(filePath: string): Promise<string> {
+  return fs.promises.readFile(filePath, 'utf-8')
+}
+
+export function parse(input: string, opts: ParseOptions = {}): Config {
+  const tokens = tokenize(input)
+  const ast = parseTokens(tokens)
+  const resolveOpts: ResolveOptions = {
+    env: getEnv(opts),
+    baseDir: opts.baseDir,
+    readFileSync: opts.readFileSync ?? defaultReadFileSync,
+  }
+  const value = resolve(ast, resolveOpts)
+  if (value.kind !== 'object') throw new Error('resolved value is not an object')
+  return new Config(value)
+}
+
+export async function parseAsync(input: string, opts: ParseOptions = {}): Promise<Config> {
+  // string input: sync parse, wrap in Promise
+  // (if include triggers readFile, that will be async in a future implementation)
+  return Promise.resolve(parse(input, opts))
+}
+
+export function parseFile(filePath: string, opts: ParseOptions = {}): Config {
+  if (typeof process === 'undefined' && !opts.readFileSync) {
+    throw new Error('parseFile is not supported in browser environments. Provide opts.readFileSync or use parse() instead.')
+  }
+  const resolvedPath = path.resolve(filePath)
+  const readFileSync = opts.readFileSync ?? defaultReadFileSync
+  const input = readFileSync(resolvedPath)
+  return parse(input, {
+    ...opts,
+    baseDir: opts.baseDir ?? path.dirname(resolvedPath),
+    readFileSync,
+  })
+}
+
+export async function parseFileAsync(filePath: string, opts: ParseOptions = {}): Promise<Config> {
+  if (typeof process === 'undefined' && !opts.readFile) {
+    throw new Error('parseFileAsync is not supported in browser environments. Provide opts.readFile or use parseAsync() instead.')
+  }
+  const resolvedPath = path.resolve(filePath)
+  const readFile = opts.readFile ?? defaultReadFile
+  const input = await readFile(resolvedPath)
+  return parse(input, {
+    ...opts,
+    baseDir: opts.baseDir ?? path.dirname(resolvedPath),
+    readFileSync: opts.readFileSync ?? defaultReadFileSync,
+  })
+}
+```
+
+- [ ] **Step 4: `src/index.ts` を更新**
+
+```ts
+export { parse, parseAsync, parseFile, parseFileAsync } from './parse.js'
+export type { ParseOptions } from './parse.js'
+export { Config } from './config.js'
+export { ParseError, ResolveError, ConfigError } from './errors.js'
+export type { HoconValue } from './value.js'
+```
+
+- [ ] **Step 5: テストを実行（pass を確認）**
+
+```bash
+npx vitest run tests/parse.test.ts
+```
+
+Expected: 全テスト pass
+
+- [ ] **Step 6: 全テストをまとめて実行**
+
+```bash
+npx vitest run
+```
+
+Expected: 全テスト pass
+
+- [ ] **Step 7: commit**
+
+```bash
+git add src/parse.ts src/index.ts tests/parse.test.ts
+git commit -m "feat: add parse functions and public exports"
+```
+
+---
+
+## Task 9: Lightbend 仕様準拠テスト
+
+**Files:**
+- Create: `tests/lightbend/` ディレクトリ（go.hocon からコピー）
+- Create: `tests/lightbend/lightbend.test.ts`
+
+- [ ] **Step 1: テストデータをコピー**
+
+```bash
+cp -r /Volumes/Workspace/o3co/repos/go.hocon/testdata/hocon tests/lightbend/testdata
+```
+
+- [ ] **Step 2: lightbend テストを書く**
+
+Go 版の `/Volumes/Workspace/o3co/repos/go.hocon/lightbend_test.go` を参考に、各グループの `*.conf` を parse して対応する `*.json` と一致するか検証する。
+
+```ts
+// tests/lightbend/lightbend.test.ts
+import { describe, it, expect } from 'vitest'
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import { parse } from '../../src/parse.js'
+
+const dataDir = new URL('./testdata', import.meta.url).pathname
+
+// Relative paths (from dataDir) to skip — unsupported features in v1
+const SKIP = new Set([
+  'equiv03/includes.conf',  // requires .properties file support
+])
+
+// Relative paths expected to throw (invalid HOCON)
+const EXPECT_THROW = new Set([
+  'cycle.conf',
+  'validate-invalid.conf',
+])
+
+function findConfFiles(dir: string): string[] {
+  const results: string[] = []
+  for (const entry of readdirSync(dir)) {
+    const fullPath = join(dir, entry)
+    if (statSync(fullPath).isDirectory()) {
+      results.push(...findConfFiles(fullPath))
+    } else if (entry.endsWith('.conf')) {
+      results.push(fullPath)
+    }
+  }
+  return results
+}
+
+const confFiles = findConfFiles(dataDir)
+
+describe('Lightbend HOCON spec compliance', () => {
+  for (const confPath of confFiles) {
+    const rel = relative(dataDir, confPath)
+    if (SKIP.has(rel)) continue
+
+    it(rel, () => {
+      const baseDir = confPath.substring(0, confPath.lastIndexOf('/'))
+      const confContent = readFileSync(confPath, 'utf-8')
+
+      if (EXPECT_THROW.has(rel)) {
+        expect(() => parse(confContent, { baseDir })).toThrow()
+        return
+      }
+
+      const jsonPath = confPath.replace('.conf', '.json')
+      let expected: unknown
+      try {
+        expected = JSON.parse(readFileSync(jsonPath, 'utf-8'))
+      } catch {
+        // No corresponding JSON — just check no throw
+        expect(() => parse(confContent, { baseDir })).not.toThrow()
+        return
+      }
+
+      const config = parse(confContent, { baseDir })
+      expect(config.toObject()).toEqual(expected)
+    })
+  }
+})
+```
+
+- [ ] **Step 3: Lightbend テストを実行（初回: 何件 pass するか確認）**
+
+```bash
+npx vitest run tests/lightbend/lightbend.test.ts
+```
+
+Expected: 一部 fail（現時点での実装カバレッジを確認）
+
+- [ ] **Step 4: 失敗している項目を修正（Go 版の実装を参照しながら）**
+
+失敗しているテストを見て、`lexer.ts` / `parser.ts` / `resolver.ts` の不足を補う。
+主な修正候補：
+- multiline strings
+- object merging edge cases
+- duration/bytes 文字列（Lightbend では `toObject()` に文字列として残るため特別な処理は不要）
+- include directive
+
+- [ ] **Step 5: 全 Lightbend テストが pass することを確認**
+
+```bash
+npx vitest run tests/lightbend/lightbend.test.ts
+```
+
+Expected: go.hocon と同等の合格率（12/13 グループ）
+
+- [ ] **Step 6: commit**
+
+```bash
+git add tests/lightbend/
+git commit -m "test: add Lightbend HOCON spec compliance tests"
+```
+
+---
+
+## Task 10: Zod インテグレーション
+
+**Files:**
+- Create: `src/zod.ts`
+- Create: `tests/zod.test.ts`
+
+- [ ] **Step 1: Zod を devDependency としてインストール（テスト用）**
+
+```bash
+npm install -D zod
+```
+
+- [ ] **Step 2: テストを書く**
+
+```ts
+// tests/zod.test.ts
+import { describe, it, expect } from 'vitest'
+import { z } from 'zod'
+import { parse } from '../src/parse.js'
+import { validate, getValidated } from '../src/zod.js'
+
+const cfg = parse(`
+  server {
+    host = "localhost"
+    port = 8080
+  }
+  debug = false
+`)
+
+describe('validate()', () => {
+  it('validates and returns typed object', () => {
+    const Schema = z.object({
+      server: z.object({
+        host: z.string(),
+        port: z.number().int(),
+      }),
+      debug: z.boolean(),
+    })
+    const result = validate(cfg, Schema)
+    expect(result.server.host).toBe('localhost')
+    expect(result.server.port).toBe(8080)
+    expect(result.debug).toBe(false)
+  })
+
+  it('throws ZodError on schema mismatch', () => {
+    const Schema = z.object({ server: z.object({ host: z.number() }) })
+    expect(() => validate(cfg, Schema)).toThrow()
+  })
+
+  it('supports Zod transforms (e.g., coerce)', () => {
+    const c = parse('timeout = "30"')
+    const Schema = z.object({ timeout: z.coerce.number() })
+    const result = validate(c, Schema)
+    expect(result.timeout).toBe(30)
+  })
+})
+
+describe('getValidated()', () => {
+  it('returns typed value at path', () => {
+    const port = getValidated(cfg, 'server.port', z.number().int())
+    expect(port).toBe(8080)
+    // TypeScript should infer `port` as `number`
+    const _check: number = port
+  })
+
+  it('throws ZodError on schema mismatch at path', () => {
+    expect(() => getValidated(cfg, 'server.host', z.number())).toThrow()
+  })
+
+  it('throws ConfigError on missing path', () => {
+    expect(() => getValidated(cfg, 'missing.path', z.string())).toThrow()
+  })
+})
+```
+
+- [ ] **Step 3: テストを実行（失敗を確認）**
+
+```bash
+npx vitest run tests/zod.test.ts
+```
+
+Expected: FAIL
+
+- [ ] **Step 4: `src/zod.ts` を実装**
+
+```ts
+import type { ZodType } from 'zod'
+import type { Config } from './config.js'
+
+export function validate<T>(config: Config, schema: ZodType<T>): T {
+  const plain = config.toObject()
+  return schema.parse(plain)
+}
+
+export function getValidated<T>(config: Config, path: string, schema: ZodType<T>): T {
+  const val = config.get(path)
+  return schema.parse(val)
+}
+```
+
+- [ ] **Step 5: テストを実行（pass を確認）**
+
+```bash
+npx vitest run tests/zod.test.ts
+```
+
+Expected: 全テスト pass
+
+- [ ] **Step 6: commit**
+
+```bash
+git add src/zod.ts tests/zod.test.ts
+git commit -m "feat: add Zod integration (validate, getValidated)"
+```
+
+---
+
+## Task 11: ビルド設定と最終確認
+
+**Files:**
+- Verify: `tsup.config.ts`
+- Verify: `package.json`
+
+- [ ] **Step 1: 全テストを通す**
+
+```bash
+npx vitest run
+```
+
+Expected: 全テスト pass
+
+- [ ] **Step 2: TypeScript 型チェック**
+
+```bash
+npx tsc --noEmit
+```
+
+Expected: エラーなし
+
+- [ ] **Step 3: ビルドを実行**
+
+```bash
+npx tsup
+```
+
+Expected: `dist/` に以下が生成される
+- `dist/index.js`（ESM）
+- `dist/index.cjs`（CJS）
+- `dist/index.d.ts`（型定義）
+- `dist/zod.js`, `dist/zod.cjs`, `dist/zod.d.ts`
+
+- [ ] **Step 4: ビルド成果物の動作確認（Node.js で require）**
+
+```bash
+node -e "const { parse } = require('./dist/index.cjs'); const c = parse('x = 1'); console.log(c.getNumber('x'))"
+```
+
+Expected: `1` が出力される
+
+- [ ] **Step 5: ビルド成果物の動作確認（ESM）**
+
+```bash
+node --input-type=module -e "import { parse } from './dist/index.js'; const c = parse('x = 1'); console.log(c.getNumber('x'))"
+```
+
+Expected: `1` が出力される
+
+- [ ] **Step 6: final commit**
+
+```bash
+git add -A
+git commit -m "feat: complete @o3co/ts.hocon v0.1.0 initial implementation"
+```
+
+---
+
+## 実装上の注意点
+
+- Go 実装 (`/Volumes/Workspace/o3co/repos/go.hocon/`) を逐次参照すること。特に resolver のアルゴリズムは Go 版と同じロジックを踏む。
+- HOCON の concat ルールは複雑。Go 版の `lexer_test.go` と `parser_test.go` のテストケースを参考にすること。
+- `include` ディレクティブのパス解決は `node:path` の `path.resolve` / `path.dirname` を使うこと。
+- ブラウザ環境では `fs` が使えないため、`parse()` / `parseAsync()` のデフォルト `readFileSync` は実際には呼ばれない（`include` なしの場合）。