fix(#213): name conversions by the original's full filename to end stem collisions

ingest derived the conversion path from the original's stem (src.stem +
out_suffix), so same-folder/same-stem/different-extension originals
(report.hwpx, report.pptx) collided on one runs/sources/report.md: the first
converted won, the second was skipped as 'up to date', and its content was
silently lost while sources/coverage mispaired both originals to the one file.

Name each conversion by the original's *full* filename plus the out-suffix
(report.hwpx -> runs/sources/report.hwpx.md, report.pptx ->
runs/sources/report.pptx.md), and key source_rel_key() to match: an original
keeps its extension, a conversion drops only its out-suffix, so each original
pairs 1:1 with exactly its own conversion. Subdir mirroring is preserved
(sources/sub/x.pdf -> runs/sources/sub/x.pdf.md).

Cross-cutting mapping sites updated for the new key, all with a legacy stem-key
fallback so pre-#213 conversions keep pairing until a KB is re-ingested:
  - factlog/common.py: source_rel_key() (full-name/last-suffix rule) +
    new source_stem_key() legacy fallback helper
  - cli.py cmd_ingest: dst = original full name + out_suffix
  - cli.py cmd_sources, cmd_status, tools/coverage.py: pair on full-name key,
    fall back to legacy stem key
  - cli.py eject matches()/--orphans: provenance header stays the primary
    signal; stem/relkey fallbacks made naming-consistent and a legacy stem-key
    set added to orphan pairing so legacy mirrored conversions are not
    false-flagged (preserves #103 cross-subtree orphan detection)

Tests: new #213 stem-collision case in test_ingest.sh (both preserved, correct
content, idempotent re-run, sources pairing); updated conversion output names in
test_ingest/pptx/hwpx and unit test_source_paths for the new key semantics.
Docs (README, SKILL.md) updated with the new naming + migration note.

Author: SeoyunL

README.md

@@ -251,23 +251,29 @@ python3 -m factlog init --target ~/wiki   # scaffold the KB layout
 
 `factlog ingest` 는 변환된 텍스트를 KB의 **`runs/sources/`** 디렉터리(다른 생성
 런 아티팩트와 같은 위치)에 기록합니다 — 사용자의 원본이 그대로 남아 있어야 하는
-**`sources/` 에는 결코 쓰지 않습니다**. 하위 디렉터리에 있는 원본은 그 하위
-구조를 그대로 미러링하므로(`sources/sub/report.pdf` → `runs/sources/sub/report.md`),
-서로 다른 폴더의 동일 이름 파일이 충돌하지 않습니다. 원본은 손대지 않으며,
-변환본에는 출처(provenance) 헤더(소스, 변환기, 날짜)가 붙습니다. `sources/` 와
-`runs/sources/` 모두 추출이 읽는 유효한 소스 루트입니다.
-
-> **업그레이드 안내:** 하위 디렉터리 미러링은 기존의 평면(flat) 레이아웃보다
-> 나중에 도입되었습니다. 이전에 적재된 KB는 중첩 원본에 대해 평면 변환본
-> (`runs/sources/report.md`)을 가지고 있는데, 이는 더 이상 짝이 맞지 않으므로
-> 중첩 바이너리가 커버리지/`factlog sources` 누락으로 다시 나타날 수 있습니다.
-> `factlog ingest --scan --force` 를 다시 실행해 변환본을 미러링된 경로로
-> 옮기십시오(이후 남은 평면 변환본은 삭제). 최상위(비중첩) 소스는 영향받지 않습니다.
+**`sources/` 에는 결코 쓰지 않습니다**. 변환본 파일명은 **원본의 전체 파일명(확장자
+포함) + 변환 확장자**로 만들어지므로(`report.hwpx` → `runs/sources/report.hwpx.md`,
+`report.pptx` → `runs/sources/report.pptx.md`), 같은 폴더에 이름이 같고 확장자만 다른
+두 원본이 하나의 변환본으로 **충돌해 유실되는 일이 없습니다**. 하위 디렉터리에 있는
+원본은 그 하위 구조를 그대로 미러링하므로(`sources/sub/report.pdf` →
+`runs/sources/sub/report.pdf.md`), 서로 다른 폴더의 동일 이름 파일도 충돌하지 않습니다.
+원본은 손대지 않으며, 변환본에는 출처(provenance) 헤더(소스, 변환기, 날짜)가 붙습니다.
+`sources/` 와 `runs/sources/` 모두 추출이 읽는 유효한 소스 루트입니다.
+
+> **업그레이드 안내(#213):** 변환본 파일명 규칙이 바뀌었습니다. 예전에는 원본의
+> **어간(stem)**만 써서 `report.pdf` → `runs/sources/report.md` 였지만, 이제는
+> 원본의 **전체 이름**을 써서 `runs/sources/report.pdf.md` 로 만듭니다. 이 덕분에
+> 같은 폴더의 `report.hwpx`·`report.pptx` 가 각각 별도 변환본으로 보존됩니다.
+> 기존에 적재된 KB의 구(舊) 어간 변환본(`runs/sources/report.md`)은 `factlog
+> sources`/`coverage`/`status` 가 **어간 기반 폴백으로 계속 원본과 짝지어** 인식하므로
+> 조용히 유실되지 않습니다. 새 레이아웃으로 옮기려면 `factlog ingest --scan --force`
+> 를 다시 실행하십시오(이후 남은 구 변환본은 `factlog eject --orphans` 로 정리).
+> 특히 어간이 충돌하던 KB는 재적재해야 유실되었던 원본이 복원됩니다.
 
 *터미널에서 실행:*
 
 ```bash
-factlog ingest report.docx --target ~/wiki   # → ~/wiki/runs/sources/report.md (pandoc)
+factlog ingest report.docx --target ~/wiki   # → ~/wiki/runs/sources/report.docx.md (pandoc)
 factlog ingest --scan --target ~/wiki        # auto-convert every binary under sources/
 ```
 
@@ -456,8 +462,9 @@ factlog ignore --remove drafts/*.md               # remove a pattern
 `factlog eject <source>` 는 적재(ingest)를 되돌립니다. `runs/sources/` 변환본을
 삭제하고, 해당 소스에서 추출된 행을 `runs/*.json` 에서 제거하며, 그 소스를 인용하는
 사실을 폐기합니다. 소스는 파일명, 어간(stem), 또는 KB 기준 상대 경로로 지정할 수
-있습니다 — 바이너리 원본(예: `report.pdf`)을 지정하면 그 `runs/sources/<stem>`
-변환본도 함께 매칭되고, 어간만 주면 같은 어간을 가진 모든 소스가 매칭됩니다.
+있습니다 — 바이너리 원본(예: `report.pdf`)을 지정하면 그 `runs/sources/<원본이름>.md`
+변환본도 함께 매칭되고(변환본의 provenance 헤더로 짝을 확인), 어간만 주면 같은 어간을
+가진 모든 소스가 매칭됩니다.
 
 ```bash
 factlog eject report.pdf                 # delete conversion; mark citing facts superseded (kept for audit)

factlog/cli.py

@@ -597,7 +597,7 @@ def cmd_sources(args: argparse.Namespace) -> int:
     import unicodedata
     from pathlib import Path
 
-    from factlog.common import is_sync_ignored, source_rel_key, sync_ignore_patterns
+    from factlog.common import is_sync_ignored, source_rel_key, source_stem_key, sync_ignore_patterns
 
     def nfc(s: str) -> str:
         return unicodedata.normalize("NFC", s)
@@ -634,7 +634,10 @@ def nfc(s: str) -> str:
         if not p.is_file() or p.name.startswith("."):
             continue
         orig_ref = nfc(p.relative_to(target).as_posix())
-        conv_ref = conv.get(source_rel_key(orig_ref), "")
+        # Pair on the full-name key (#213); fall back to the legacy stem key so a
+        # conversion made before #213 (named by the bare stem) still pairs until
+        # the KB is re-ingested.
+        conv_ref = conv.get(source_rel_key(orig_ref)) or conv.get(source_stem_key(orig_ref), "")
         fact_ref = conv_ref or orig_ref  # facts attach to the conversion when present
         entries.append((counts.get(fact_ref, 0), orig_ref, conv_ref))
         listed.add(orig_ref)
@@ -1429,7 +1432,12 @@ def cmd_status(args: argparse.Namespace) -> int:
         if ref not in cited
         and ref.startswith("sources/")
         and not common.is_text_source(p)
-        and common.source_rel_key(ref) in covered_keys
+        # Pair on the full-name key (#213); fall back to the legacy stem key so a
+        # pre-#213 conversion (named by the bare stem) still pairs pre-re-ingest.
+        and (
+            common.source_rel_key(ref) in covered_keys
+            or common.source_stem_key(ref) in covered_keys
+        )
     )
     covered = direct + via
     total = len(refs)
@@ -1768,15 +1776,21 @@ def cmd_ingest(args: argparse.Namespace) -> int:
 
         tool, out_suffix, build = chosen
         # Mirror the original's subdirectory under runs/sources/ so a nested
-        # source (sources/sub/x.pdf) converts to runs/sources/sub/x.md — never a
-        # flat name that would collide with a same-stem file in another subdir.
-        # An explicitly-named path outside sources/ has no subtree to mirror, so
-        # it falls back to a flat output name.
+        # source (sources/sub/x.pdf) converts to runs/sources/sub/x.pdf.md —
+        # never a flat name that would collide with a same-name file in another
+        # subdir. An explicitly-named path outside sources/ has no subtree to
+        # mirror, so it falls back to a flat output name.
         try:
             rel_parent = src.resolve().relative_to(sources_dir).parent
         except (ValueError, OSError):
             rel_parent = Path()
-        dst = derived / rel_parent / (src.stem + out_suffix)
+        # Keep the original's *full* filename (extension included) and append the
+        # out-suffix, so same-stem/different-extension originals (report.hwpx,
+        # report.pptx) convert to distinct outputs (report.hwpx.md,
+        # report.pptx.md) instead of colliding on one file and silently dropping
+        # the loser (#213). source_rel_key() mirrors this to pair each original
+        # with exactly its own conversion.
+        dst = derived / rel_parent / (src.name + out_suffix)
         dst.parent.mkdir(parents=True, exist_ok=True)
         if dst.exists() and not args.force and dst.stat().st_mtime >= src.stat().st_mtime:
             print(f"factlog ingest: {dst.relative_to(target).as_posix()} up to date; skipping {src.name}")
@@ -1919,8 +1933,18 @@ def matches(ref: str, name: str) -> bool:
             if not is_conv:
                 return rp.name == np_.name  # an original with that filename
             origin = conv_origin.get(ref)  # the conversion made from this original
-            return origin == np_.name if origin else rp.stem == np_.stem
-        return rp.stem == np_.stem  # bare stem: every source with that stem
+            # Provenance is the reliable signal. A headerless conversion falls
+            # back to its own name minus the ingest out-suffix: since ingest now
+            # keeps the original's extension (report.pptx -> report.pptx.md), the
+            # conversion's rp.stem ("report.pptx") is the original's full name.
+            return origin == np_.name if origin else rp.stem == np_.name
+        # bare stem: every original with that stem, and a conversion made from
+        # one (matched via its recorded origin so the source's own extension in
+        # the new naming — report.pptx.md — does not defeat the stem compare).
+        if is_conv:
+            origin = conv_origin.get(ref)
+            return Path(origin if origin else rp.name).stem == np_.stem
+        return rp.stem == np_.stem
 
     matched: set[str] = set()
     if args.orphans:
@@ -1943,8 +1967,26 @@ def matches(ref: str, name: str) -> bool:
         #    original ingested without a subtree to mirror) has no subdir, so
         #    the provenance basename is the only origin signal; fall back to it
         #    and keep erring toward retention.
+        from pathlib import PurePosixPath
+
+        def _legacy_stem_key(r: str) -> str:
+            # An original keyed the pre-#213 way: root prefix stripped, suffix
+            # dropped (sources/a/report.pdf -> a/report). Pairs a legacy
+            # conversion (runs/sources/a/report.md, keyed 'a/report') that
+            # predates the new full-name naming with its still-present original.
+            for root in ("runs/sources/", "sources/"):
+                if r.startswith(root):
+                    r = r[len(root):]
+                    break
+            return PurePosixPath(r).with_suffix("").as_posix()
+
         src_basenames = {Path(r).name for r in disk_refs if not r.startswith("runs/sources/")}
         src_relkeys = {source_rel_key(r) for r in disk_refs if not r.startswith("runs/sources/")}
+        # Legacy conversions key by the original's stem, not its full name, so
+        # also pair a mirrored conversion against the legacy stem key. Same-stem
+        # originals in different subtrees stay distinct (subdir is in the key),
+        # so #103's cross-subtree orphan detection is preserved for both layouts.
+        src_stemkeys = {_legacy_stem_key(r) for r in disk_refs if not r.startswith("runs/sources/")}
         for ref in all_refs:
             if ref.startswith("runs/sources/"):
                 if ref in disk_refs:
@@ -1953,7 +1995,10 @@ def matches(ref: str, name: str) -> bool:
                     # (hand-placed conversions are kept).
                     if origin is not None:
                         ck = source_rel_key(ref)
-                        paired = ck in src_relkeys if "/" in ck else origin in src_basenames
+                        if "/" in ck:
+                            paired = ck in src_relkeys or ck in src_stemkeys
+                        else:
+                            paired = origin in src_basenames
                         if not paired:
                             matched.add(ref)  # the original it was made from is gone
                 else:

factlog/common.py

@@ -217,15 +217,54 @@ def read_csv(path: Path) -> list[dict[str, str]]:
 
 
 def source_rel_key(ref: str) -> str:
-    """A source ref minus its source-root prefix and file suffix.
-
-    This is the key that pairs a binary original with its runs/sources/<rel>
-    conversion now that `factlog ingest` mirrors the original's subdirectory:
-        'sources/a/report.pdf'      -> 'a/report'
-        'runs/sources/a/report.md'  -> 'a/report'   (pairs with the line above)
-        'sources/report.pdf'        -> 'report'      (top-level: unchanged)
-    Subdirectory-aware, so same-stem files in different subtrees no longer
-    collide. NFC-normalised. (Uses PurePosixPath since refs are posix-style.)
+    """The key that pairs a binary original with its runs/sources/ conversion.
+
+    `factlog ingest` names a conversion by appending the converter's out-suffix
+    to the original's *full* filename (extension included) and mirrors the
+    original's subdirectory, so same-stem/different-extension originals no longer
+    collide on one output file (#213). The pairing key therefore keeps the
+    original's extension and drops only the conversion's final (out-)suffix:
+        'sources/a/report.hwpx'         -> 'a/report.hwpx'
+        'runs/sources/a/report.hwpx.md' -> 'a/report.hwpx'  (pairs with above)
+        'sources/report.pptx'           -> 'report.pptx'
+        'runs/sources/report.pptx.md'   -> 'report.pptx'    (pairs with above)
+    An original under sources/ keeps its full name; a conversion under
+    runs/sources/ drops one suffix. Subdirectory-aware, so same-name files in
+    different subtrees never collide. NFC-normalised. (PurePosixPath: refs are
+    posix-style.)
+
+    Backward compatibility: a legacy conversion made before #213 is named by the
+    bare stem (`runs/sources/report.md` from `report.pdf`), so its key is the
+    stem (`report`) and no longer equals the new full-name original key
+    (`report.pdf`). Such conversions pair through their provenance header where
+    that signal exists (eject/orphan); otherwise re-run `factlog ingest --force`
+    to migrate them to the new layout. See the migration note in the #213 PR.
+    """
+    ref = unicodedata.normalize("NFC", ref)
+    is_conversion = False
+    for rootname in SOURCE_ROOTS:
+        prefix = rootname + "/"
+        if ref.startswith(prefix):
+            is_conversion = rootname == "runs/sources"
+            ref = ref[len(prefix):]
+            break
+    p = PurePosixPath(ref)
+    # Conversion: drop the out-suffix (.md/.txt) added by ingest, keeping the
+    # original's own extension. Original: keep the full name so its extension is
+    # part of the key and can't be confused with a same-stem sibling.
+    return (p.with_suffix("") if is_conversion else p).as_posix()
+
+
+def source_stem_key(ref: str) -> str:
+    """The pre-#213 pairing key: source-root prefix stripped, one suffix dropped.
+
+        'sources/a/report.pdf'     -> 'a/report'
+        'runs/sources/a/report.md' -> 'a/report'   (legacy naming)
+
+    Used only as a *fallback* to keep a legacy conversion (named by the bare
+    stem, before #213 kept the original's extension) pairing with its original.
+    A fresh/re-ingested KB matches on source_rel_key() and never needs this.
+    Subdirectory-aware; NFC-normalised. See the #213 migration note.
     """
     ref = unicodedata.normalize("NFC", ref)
     for rootname in SOURCE_ROOTS:

skills/factlog/SKILL.md

@@ -43,7 +43,7 @@ produced by `factlog ingest`).
 Examples:
 - `"sources/my-doc.md"`
 - `"sources/subdir/notes.md#section-heading"`
-- `"runs/sources/report.md"`  (a converted `.docx`/`.pdf` original)
+- `"runs/sources/report.pdf.md"`  (a converted `.docx`/`.pdf` original — the conversion keeps the original's full name, extension included, so same-stem originals never collide; #213)
 
 Bare filenames (e.g. `"my-doc.md"`) are NOT valid and will be silently dropped
 by `merge_candidates.py`. Always include the `sources/` or `runs/sources/` prefix.
@@ -216,8 +216,9 @@ first:
 
 `--scan` auto-discovers every binary file under `sources/` and writes a text
 conversion (with a provenance header) into `runs/sources/` — never into
-`sources/`, mirroring the original's subdirectory (`sources/sub/x.pdf` →
-`runs/sources/sub/x.md`). It is idempotent (unchanged files are skipped).
+`sources/`, mirroring the original's subdirectory and keeping the original's
+full name so same-stem originals never collide (`sources/sub/x.pdf` →
+`runs/sources/sub/x.pdf.md`; #213). It is idempotent (unchanged files are skipped).
 Sources matching `policy/sync-ignore.md` are skipped. Then extract from **both**
 `sources/` (native text) and `runs/sources/` (conversions).
 
@@ -439,7 +440,7 @@ it is correctly reported as a gap, not "covered":
   `/factlog sync` (or investigate why nothing was extracted).
 - **binary gap** — a binary source under `sources/` with **no conversion** at
   all: it needs conversion first via `factlog ingest`. A binary that already has
-  a `runs/sources/<stem>` conversion is **not** a gap — facts attach to the
+  a `runs/sources/<original-name>.md` conversion is **not** a gap — facts attach to the
   conversion, so the original is reported as *covered via conversion* (it counts
   toward "covered", with a `(N via conversion)` note in the summary). A binary
   under `runs/sources/` is instead flagged as an anomaly (that directory holds

tests/test_hwpx_ingest.sh

@@ -56,8 +56,8 @@ PY
 # --- explicit ingest ----------------------------------------------------------
 make_hwpx "$KB/sources/sample.hwpx"
 set +e; out="$("$PYTHON" -m factlog ingest --target "$KB" "$KB/sources/sample.hwpx" 2>&1)"; rc=$?; set -e
-md="$KB/runs/sources/sample.md"
-[ "$rc" -eq 0 ] && [ -f "$md" ] && ok "hwpx ingests to runs/sources/<stem>.md (rc 0)" || bad "hwpx ingest failed (rc=$rc)"
+md="$KB/runs/sources/sample.hwpx.md"  # #213: conversion keeps the original's full name
+[ "$rc" -eq 0 ] && [ -f "$md" ] && ok "hwpx ingests to runs/sources/<name>.md (rc 0)" || bad "hwpx ingest failed (rc=$rc)"
 head -1 "$md" | grep -qF "ingested-by-factlog" && head -1 "$md" | grep -qF "factlog-hwpx" && ok "provenance header written" || bad "provenance header missing"
 grep -qx "첫째 문단" "$md" && ok "multiple <hp:t> runs join into one line" || bad "runs not joined"
 grep -qx "태그제거" "$md" && ok "inline tags stripped" || bad "inline tag not stripped"
@@ -70,7 +70,7 @@ grep -qx "둘째 섹션" "$md" && ok "text from a second section included" || ba
 rm -f "$md"
 make_hwpx "$KB/sources/scanned.hwpx"
 set +e; "$PYTHON" -m factlog ingest --target "$KB" --scan >/dev/null 2>&1; rc=$?; set -e
-[ "$rc" -eq 0 ] && [ -f "$KB/runs/sources/scanned.md" ] && ok "--scan auto-discovers and converts hwpx" || bad "--scan did not convert hwpx (rc=$rc)"
+[ "$rc" -eq 0 ] && [ -f "$KB/runs/sources/scanned.hwpx.md" ] && ok "--scan auto-discovers and converts hwpx" || bad "--scan did not convert hwpx (rc=$rc)"
 
 # --- corrupt hwpx: explicit fails, --scan reports but does not fail ------------
 printf 'not a zip file' > "$KB/sources/broken.hwpx"