feat: 문서 출처 DocumentSource 메타 IR 추가

DanMeon · claude · DanMeon · commit 75d0f6845089 · 2026-04-24T14:45:50.000+09:00
변경사항:
- DocumentSource 모델 신설 (uri: str) — HwpDocument.source 타입을 Provenance | None 에서 DocumentSource | None 으로 교체
- rhwp.parse(path) 경로가 IR 의 source.uri 에 원본 경로를 주입 (normalize 미수행 — 소비자 책임)
- Document.source_uri getter 추가 — IR 생성 없이도 출처 조회 가능
- InlineRun.raw_style_id description 보강 — None 은 char_shape 없는 손상 입력 방어 경로임을 명시
- 테스트 5건 추가 (HWP/HWPX 경로, getter, null 직접 구성, JSON null roundtrip, frozen 위반)
- JSON Schema 재생성 + ir.md 에 LLM strict-mode 후처리 주의 반영

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/docs/roadmap/v0.2.0/ir.md b/docs/roadmap/v0.2.0/ir.md
@@ -102,7 +102,7 @@ v0.2.0 의 원안은 `rhwp` 커맨드라인 도구 제공이었으나(`docs/road
 HwpDocument (root)
 ├── schema_name: Literal["HwpDocument"]
 ├── schema_version: Literal["1.0"]             # 인스턴스 버전 추적
-├── source                                     # Provenance — 원본 경로/해시
+├── source: DocumentSource | None              # 문서 출처 (uri) — RAG 역추적
 ├── metadata: DocumentMetadata                 # 제목/작성자/생성일 등
 ├── sections: list[Section]                    # 구역(용지·단 정의 포함)
 │
@@ -121,6 +121,7 @@ HwpDocument (root)
 v0.2.0 에서 구현 완료되는 구체 타입:
 
 - `HwpDocument` — 문서 루트 (`schema_name`/`schema_version`/`source?`/`metadata`/`sections`/`body`/`furniture`)
+- `DocumentSource` — 문서 출처. `uri: str` 만 필수 (파일 경로·URL·custom 식별자). `format`/`bytes_size`/`sha256` 등 재현성 필드는 기본값 있는 옵셔널로 향후 MINOR 확장. `rhwp.parse(path)` 경로는 `uri` 에 원본 path 를 그대로 기록 (normalize 미수행 — 소비자 책임). **LLM Strict-mode 주의**: `HwpDocument.source` 는 기본값 `null` 을 가지므로 Pydantic 이 root `required` 에 올리지 않는다. OpenAI Structured Outputs `strict=true` 소비자는 (a) `source` 를 root `required` 에 명시 추가 + (b) `anyOf: [$ref, null]` → 동일 형태 유지하되 `required` 재계산, 후처리가 필요하다. 옵셔널 필드가 추가될수록 동일 패턴이 반복된다
 - `DocumentMetadata` — `title`/`author`/`creation_time`/`modification_time` — 전부 `str | None`. S2 에서 `datetime` 교체는 MINOR 호환 (optional 필드 타입 확장)
 - `Section` — v0.2.0 S1 은 `section_idx: int` 만. 용지·단·헤더 레퍼런스는 S2 Rust 매핑 시점에 MINOR 확장
 - `ParagraphBlock` — 단락, `kind="paragraph"` + `text`/`inlines: list[InlineRun]`/`prov`
diff --git a/python/rhwp/__init__.pyi b/python/rhwp/__init__.pyi
@@ -40,6 +40,9 @@ class Document:
     직접 생성자를 호출하거나 :func:`parse` 를 사용할 수 있다.
     """
 
+    source_uri: str | None
+    """생성자에 전달된 원본 경로. IR 의 ``source.uri`` 와 동일 값 — IR 을 생성하지 않고도 출처 조회 가능."""
+
     section_count: int
     """섹션 수."""
 
diff --git a/python/rhwp/ir/__init__.pyi b/python/rhwp/ir/__init__.pyi
@@ -9,6 +9,9 @@ from rhwp.ir.nodes import (
 from rhwp.ir.nodes import (
     DocumentMetadata as DocumentMetadata,
 )
+from rhwp.ir.nodes import (
+    DocumentSource as DocumentSource,
+)
 from rhwp.ir.nodes import (
     Furniture as Furniture,
 )
@@ -56,6 +59,7 @@ __all__ = [
     "CURRENT_SCHEMA_VERSION",
     "Block",
     "DocumentMetadata",
+    "DocumentSource",
     "Furniture",
     "HwpDocument",
     "InlineRun",
diff --git a/python/rhwp/ir/nodes.py b/python/rhwp/ir/nodes.py
@@ -22,6 +22,7 @@
     "CURRENT_SCHEMA_VERSION",
     "Block",
     "DocumentMetadata",
+    "DocumentSource",
     "Furniture",
     "HwpDocument",
     "InlineRun",
@@ -86,7 +87,33 @@ class InlineRun(BaseModel):
     strikethrough: bool = False
     href: str | None = None
     ruby: str | None = None
-    raw_style_id: int | None = None
+    raw_style_id: int | None = Field(
+        default=None,
+        description=(
+            "Upstream doc_info 스타일 인덱스. 폰트/크기/색상 등 non-binary 서식을 escape 한다. "
+            "None 은 char_shape 레코드가 없는 손상/비정상 입력 방어 경로 — "
+            "정상 HWP 는 모든 런이 char_shape 에 대응되어 항상 값이 채워진다."
+        ),
+    )
+
+
+class DocumentSource(BaseModel):
+    """문서 출처 — RAG 응답 역추적 시 "이 답이 어느 파일에서 나왔나" 에 응답한다.
+
+    스키마는 ``uri`` 형식을 강제하지 않으므로 소비자가 file://, https://, 혹은
+    ``mem://{hash}`` 같은 custom 스킴으로 정규화할 수 있다. 향후 ``format``,
+    ``bytes_size``, ``sha256`` 등 재현성 필드는 기본값 있는 옵셔널로만 추가 —
+    이 경로는 기존 JSON 과 MINOR 호환 유지.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    uri: str = Field(
+        description=(
+            "파일 시스템 경로, URL, 혹은 소비자 정의 식별자. "
+            "RFC 3986 URI reference 로 해석 가능한 문자열이면 충분하다."
+        ),
+    )
 
 
 class DocumentMetadata(BaseModel):
@@ -206,7 +233,9 @@ def _block_discriminator(v: Any) -> str:
 
 
 Block = Annotated[
-    Annotated[ParagraphBlock, Tag("paragraph")] | Annotated[TableBlock, Tag("table")] | Annotated[UnknownBlock, Tag("unknown")],
+    Annotated[ParagraphBlock, Tag("paragraph")]
+    | Annotated[TableBlock, Tag("table")]
+    | Annotated[UnknownBlock, Tag("unknown")],
     Discriminator(_block_discriminator),
 ]
 
@@ -235,7 +264,7 @@ class HwpDocument(BaseModel):
 
     schema_name: Annotated[str, StringConstraints(pattern=r"^HwpDocument$")] = "HwpDocument"
     schema_version: SchemaVersion = CURRENT_SCHEMA_VERSION
-    source: Provenance | None = None
+    source: DocumentSource | None = None
     metadata: DocumentMetadata = Field(default_factory=DocumentMetadata)
     sections: list[Section] = Field(default_factory=list)
     body: list["Block"] = Field(default_factory=list)
diff --git a/python/rhwp/ir/schema/hwp_ir_v1.json b/python/rhwp/ir/schema/hwp_ir_v1.json
@@ -58,6 +58,22 @@
       "title": "DocumentMetadata",
       "type": "object"
     },
+    "DocumentSource": {
+      "additionalProperties": false,
+      "description": "문서 출처 — RAG 응답 역추적 시 \"이 답이 어느 파일에서 나왔나\" 에 응답한다.\n\n스키마는 ``uri`` 형식을 강제하지 않으므로 소비자가 file://, https://, 혹은\n``mem://{hash}`` 같은 custom 스킴으로 정규화할 수 있다. 향후 ``format``,\n``bytes_size``, ``sha256`` 등 재현성 필드는 기본값 있는 옵셔널로만 추가 —\n이 경로는 기존 JSON 과 MINOR 호환 유지.",
+      "properties": {
+        "uri": {
+          "description": "파일 시스템 경로, URL, 혹은 소비자 정의 식별자. RFC 3986 URI reference 로 해석 가능한 문자열이면 충분하다.",
+          "title": "Uri",
+          "type": "string"
+        }
+      },
+      "required": [
+        "uri"
+      ],
+      "title": "DocumentSource",
+      "type": "object"
+    },
     "Furniture": {
       "additionalProperties": false,
       "description": "장식 노드 컨테이너 — RAG 가 임베딩에서 필터링 가능.\n\n현재 파서는 본문 블록을 넣지 않으므로 세 리스트는 기본적으로 비어있다.",
@@ -179,6 +195,7 @@
             }
           ],
           "default": null,
+          "description": "Upstream doc_info 스타일 인덱스. 폰트/크기/색상 등 non-binary 서식을 escape 한다. None 은 char_shape 레코드가 없는 손상/비정상 입력 방어 경로 — 정상 HWP 는 모든 런이 char_shape 에 대응되어 항상 값이 채워진다.",
           "title": "Raw Style Id"
         }
       },
@@ -472,7 +489,7 @@
     "source": {
       "anyOf": [
         {
-          "$ref": "#/$defs/Provenance"
+          "$ref": "#/$defs/DocumentSource"
         },
         {
           "type": "null"
diff --git a/src/document.rs b/src/document.rs
@@ -11,6 +11,8 @@ use crate::ir;
 #[pyclass(name = "Document", module = "rhwp", unsendable)]
 pub struct PyDocument {
     pub(crate) inner: rhwp::document_core::DocumentCore,
+    // ^ 생성자에 전달된 파일 경로 — IR `DocumentSource.uri` 로 전파. RAG 응답 역추적 경로.
+    source_uri: Option<String>,
     // ^ 첫 to_ir() 호출 시 1회 구성, 이후 재사용. unsendable 단일-스레드 보장 덕에 lock 불필요
     ir_cache: OnceCell<Py<PyAny>>,
 }
@@ -27,15 +29,23 @@ impl PyDocument {
     fn new(py: Python<'_>, path: &str) -> PyResult<Self> {
         // ^ py.detach 로 파일 I/O + 파싱 동안 GIL 해제 (DocumentCore 는 클로저 내부에서만 생성)
         let path_owned = path.to_owned();
+        let source_uri = path_owned.clone();
         let doc = py
             .detach(move || load_document(path_owned))
             .map_err(parse_error_to_py)?;
         Ok(PyDocument {
             inner: doc,
+            source_uri: Some(source_uri),
             ir_cache: OnceCell::new(),
         })
     }
 
+    #[getter]
+    fn source_uri(&self) -> Option<&str> {
+        // ^ IR 을 만들지 않고도 출처 확인 가능 — 관찰성·디버깅용. to_ir() 후의 ir.source.uri 와 동일 값
+        self.source_uri.as_deref()
+    }
+
     #[getter]
     fn section_count(&self) -> usize {
         self.inner.document().sections.len()
@@ -146,7 +156,7 @@ impl PyDocument {
         if let Some(cached) = self.ir_cache.get() {
             return Ok(cached.clone_ref(py));
         }
-        let ir = ir::build_hwp_document(py, self.inner.document())?;
+        let ir = ir::build_hwp_document(py, self.inner.document(), self.source_uri.as_deref())?;
         self.ir_cache
             .set(ir)
             .expect("ir_cache was empty just above");
diff --git a/src/ir.rs b/src/ir.rs
@@ -22,16 +22,36 @@ static HWP_DOCUMENT_CLASS: PyOnceLock<Py<PyType>> = PyOnceLock::new();
 ///
 /// 호출 경로 전체가 GIL 유지 구간에서 실행된다 — dict 생성과 Pydantic 호출 모두
 /// Python heap 접근을 요구하기 때문.
-pub fn build_hwp_document(py: Python<'_>, doc: &Document) -> PyResult<Py<PyAny>> {
-    let raw = build_document_dict(py, doc)?;
+///
+/// `source_uri` 는 `HwpDocument.source.uri` 로 주입된다 — 파일 경로/URL/custom 식별자.
+/// `None` 이면 `source` 가 `None` 으로 남는다 (메모리 bytes 파싱 등 출처 불명 경로).
+pub fn build_hwp_document(
+    py: Python<'_>,
+    doc: &Document,
+    source_uri: Option<&str>,
+) -> PyResult<Py<PyAny>> {
+    let raw = build_document_dict(py, doc, source_uri)?;
     let hwp_class = HWP_DOCUMENT_CLASS.import(py, "rhwp.ir.nodes", "HwpDocument")?;
     let ir = hwp_class.call_method1("model_validate", (raw,))?;
     Ok(ir.unbind())
 }
 
-fn build_document_dict<'py>(py: Python<'py>, doc: &Document) -> PyResult<Bound<'py, PyDict>> {
+fn build_document_dict<'py>(
+    py: Python<'py>,
+    doc: &Document,
+    source_uri: Option<&str>,
+) -> PyResult<Bound<'py, PyDict>> {
     let dict = PyDict::new(py);
 
+    match source_uri {
+        Some(uri) => {
+            let source = PyDict::new(py);
+            source.set_item("uri", uri)?;
+            dict.set_item("source", source)?;
+        }
+        None => dict.set_item("source", py.None())?,
+    }
+
     let metadata = PyDict::new(py);
     metadata.set_item("title", py.None())?;
     metadata.set_item("author", py.None())?;
diff --git a/tests/test_ir_roundtrip.py b/tests/test_ir_roundtrip.py
@@ -14,10 +14,12 @@
 Table 전용 검증은 ``test_ir_tables.py``.
 """
 
+from pathlib import Path
+
 import pytest
 import rhwp
 from pydantic import ValidationError
-from rhwp.ir.nodes import HwpDocument, ParagraphBlock, TableBlock
+from rhwp.ir.nodes import DocumentSource, HwpDocument, ParagraphBlock, TableBlock
 
 # * 반환 타입 / 캐시
 
@@ -205,3 +207,53 @@ def test_metadata_fields_are_none(parsed_hwp: rhwp.Document):
     assert md.author is None
     assert md.creation_time is None
     assert md.modification_time is None
+
+
+# * source — rhwp.parse(path) 경로는 uri 에 원본 경로를 기록한다
+
+
+def test_source_uri_matches_parse_path(parsed_hwp: rhwp.Document, hwp_sample: Path):
+    """rhwp.parse(str(path)) 경로는 `HwpDocument.source.uri == str(path)` 를 보장한다.
+
+    RAG 응답 역추적 경로. normalize 는 수행하지 않는다 — 소비자 책임.
+    """
+    ir = parsed_hwp.to_ir()
+    assert isinstance(ir.source, DocumentSource)
+    assert ir.source.uri == str(hwp_sample)
+
+
+def test_source_uri_matches_parse_path_hwpx(parsed_hwpx: rhwp.Document, hwpx_sample: Path):
+    """HWPX 경로도 동일 계약."""
+    ir = parsed_hwpx.to_ir()
+    assert isinstance(ir.source, DocumentSource)
+    assert ir.source.uri == str(hwpx_sample)
+
+
+def test_document_source_uri_property(parsed_hwp: rhwp.Document, hwp_sample: Path):
+    """``Document.source_uri`` getter 는 IR 생성 없이도 출처를 조회할 수 있어야 한다."""
+    assert parsed_hwp.source_uri == str(hwp_sample)
+
+
+def test_hwp_document_direct_construction_allows_null_source():
+    """Python 소비자가 IR 을 직접 구성하는 경로 (loader 등) — source=None 허용."""
+    ir = HwpDocument()
+    assert ir.source is None
+    assert ir.schema_name == "HwpDocument"
+    assert ir.schema_version == "1.0"
+
+
+def test_hwp_document_json_null_source_roundtrip():
+    """source=None 상태의 JSON 도 Pydantic 재파싱 가능 — forward-compat 경로."""
+    import json
+
+    original = HwpDocument()
+    dumped = original.model_dump_json()
+    parsed = HwpDocument.model_validate(json.loads(dumped))
+    assert parsed.source is None
+
+
+def test_document_source_is_frozen():
+    """``DocumentSource`` 는 ``frozen=True`` — 재할당은 ValidationError 로 거부."""
+    src = DocumentSource(uri="file:///tmp/example.hwp")
+    with pytest.raises(ValidationError):
+        src.uri = "file:///tmp/other.hwp"  # type: ignore[misc]
diff --git a/tests/test_ir_schema_export.py b/tests/test_ir_schema_export.py
@@ -42,7 +42,7 @@ def test_export_schema_root_additional_properties_false():
 
 
 def test_export_schema_defs_are_exactly_the_known_nodes():
-    """`$defs` 는 HwpDocument (root) 를 제외한 9개 노드 정확히 일치.
+    """`$defs` 는 HwpDocument (root) 를 제외한 10개 노드 정확히 일치.
 
     새 block variant 가 v0.3.0+ 에 추가되면 이 set 도 갱신해야 한다 — 의도적인
     강한 계약으로 스키마 형상 회귀를 조기에 탐지한다.
@@ -53,6 +53,7 @@ def test_export_schema_defs_are_exactly_the_known_nodes():
         "Provenance",
         "InlineRun",
         "DocumentMetadata",
+        "DocumentSource",
         "Section",
         "ParagraphBlock",
         "TableBlock",
