Skip to content

Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.

11.6 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""`sprite-request.json` 의 read-modify-write 는 격리 도메인 **하나** 안에서만 일어난다
(plan sprite-gen/state-revision-read-mutation).

이 파일이 소유하는 계약은 조회 무변(그건 `test_request_read_no_mutation.py` 가 갖는다)이
아니라 **쓰기끼리의 상호배제**다:

- request 를 read-modify-write 하는 모든 프로덕션 경로 — 이관 writer(`migrate_request_file`),
  리롤 테이크 기록(`reroll.record_take`), 트윈 테이크 기록(`interpolate.write_take`), 뷰의
  fps POST — 는 **같은 `publish_guard` 배타락** 안에서 락 획득 **후** fresh 재독하고 원자
  교체한다. 그래서 lost update 가 구조적으로 불가능하다.

왜 이 파일이 생겼나 (노을이 검수 note 1, 2026-08-02): 이관 writer 는 문서를 락 **밖에서**
읽고 나서 `.sprite-gen.lock` (파이프라인 단계용 단일 writer 락)을 잡았다. 두 가지가 동시에
틀렸다 — (a) read-then-lock 이라 읽은 뒤 잡기 전 사이의 편집을 stale 문서로 덮고,
(b) 편집 writer 들은 `publish_guard` 를 쓰므로 **서로 배제하지 않는 두 도메인**이었다.
밀리초 창이지만 리롤이 방금 기록한 테이크가 이관 한 번에 통째로 사라질 수 있었다.
"""

from __future__ import annotations

import ast
import json
import threading
import time
from pathlib import Path

from PIL import Image

from sprite_gen.effects import interpolate, reroll
from sprite_gen.spec import runio
from sprite_gen.spec.runio import REQUEST_FILENAME, migrate_request_file

# 이관 writer 가 문서를 읽은 **뒤** 쓰기 전까지 편집자에게 주는 시간. 배제되지 않는 두 도메인
# (수리 전 코드)이라면 이 창 안에서 편집이 통째로 완료되고, 이관이 그것을 덮어 잃는다.
# 배제되면 편집자는 이 시간 동안 락에서 대기만 하고 아무것도 잃지 않는다.
RACE_WINDOW_SECONDS = 0.3


def _write_request(run_dir: Path, fit: dict) -> None:
    run_dir.mkdir(parents=True, exist_ok=True)
    (run_dir / REQUEST_FILENAME).write_text(json.dumps({
        "version": 1, "kind": "sprite-gen-request", "engine": "component-row",
        "character": {"id": "racebot", "description": "", "base_image": None},
        "cell": {"shape": "square", "width": 96, "height": 96, "safe_margin_x": 8,
                 "safe_margin_y": 8, "size": 96, "safe_margin": 8},
        "chroma_key": {"name": "magenta", "hex": "#FF00FF", "rgb": [255, 0, 255],
                       "selection": "fallback"},
        "states": {"walk": {"frames": 2, "fps": 8, "loop": True, "action": "x"}},
        "fit": fit,
    }, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")


def _run_the_race(monkeypatch, run_dir: Path, edit) -> None:
    """이관 writer 의 read→write 사이에 편집 writer 를 밀어 넣고 둘 다 끝날 때까지 기다린다.

    이관자가 문서를 읽은 직후 `read_done` 을 올리고, 편집자가 "지금 들어간다"(`edit_attempted`)
    를 올릴 때까지 기다린 뒤 `RACE_WINDOW_SECONDS` 를 더 준다. 배제가 없으면 편집이 그 창
    안에서 완주하고 이관의 stale 쓰기에 지워진다. 배제되면 편집자는 창 내내 락 대기다."""
    read_done = threading.Event()
    edit_attempted = threading.Event()
    failures: list[BaseException] = []
    real_read = runio._read_request_document

    def hooked(target_dir):
        document = real_read(target_dir)
        if threading.current_thread().name == "migrator":
            read_done.set()
            edit_attempted.wait(5.0)
            time.sleep(RACE_WINDOW_SECONDS)
        return document

    monkeypatch.setattr(runio, "_read_request_document", hooked)

    def migrate() -> None:
        try:
            migrate_request_file(run_dir, apply=True)
        except BaseException as exc:                      # noqa: BLE001 - 스레드 밖으로 옮긴다
            failures.append(exc)
            read_done.set()

    def editor() -> None:
        try:
            read_done.wait(5.0)
            edit_attempted.set()
            edit()
        except BaseException as exc:                      # noqa: BLE001
            failures.append(exc)

    threads = [threading.Thread(target=migrate, name="migrator"),
               threading.Thread(target=editor, name="editor")]
    for thread in threads:
        thread.start()
    for thread in threads:
        thread.join(30.0)
        assert not thread.is_alive(), f"{thread.name} 스레드가 끝나지 않았다 (락 교착 의심)"
    assert not failures, failures


def test_migration_racing_a_reroll_take_loses_neither_write(tmp_path, monkeypatch) -> None:
    """이관 vs 리롤 테이크 기록: 둘 다 살아남는다 (lost update 불가).

    수리 전에는 이관자가 락 밖에서 읽은 stale 문서를 원자 교체해, 그 사이 리롤이 기록한
    `states.walk.takes` 가 흔적 없이 사라졌다 (반대 순서면 이관이 조용히 되돌아간다)."""
    run_dir = tmp_path / "run"
    _write_request(run_dir, {"pixel_perfect": True, "logical_height": 48})

    _run_the_race(monkeypatch, run_dir,
                  lambda: reroll.record_take(run_dir, "walk", "reroll1", 2))

    on_disk = json.loads((run_dir / REQUEST_FILENAME).read_text(encoding="utf-8"))
    assert on_disk["fit"] == {"logical_height": 48, "pixel_unfake": True}, "이관이 사라졌다"
    assert on_disk["states"]["walk"].get("takes") == [{"label": "reroll1", "frames": 2}], (
        "리롤이 기록한 테이크가 이관의 stale 쓰기에 지워졌다 — 두 writer 가 서로 배제되지 않는다")


def test_migration_racing_an_interpolate_take_loses_neither_write(tmp_path, monkeypatch) -> None:
    """이관 vs 트윈 테이크 기록: 같은 계약, 같은 락 (`interpolate.write_take`)."""
    run_dir = tmp_path / "run"
    _write_request(run_dir, {"pixel_perfect": True, "logical_height": 48})
    request = json.loads((run_dir / REQUEST_FILENAME).read_text(encoding="utf-8"))
    image = Image.new("RGBA", (8, 8), (255, 0, 255, 255))

    _run_the_race(monkeypatch, run_dir,
                  lambda: interpolate.write_take(run_dir, request, "walk", "tween1", image))

    on_disk = json.loads((run_dir / REQUEST_FILENAME).read_text(encoding="utf-8"))
    assert on_disk["fit"] == {"logical_height": 48, "pixel_unfake": True}, "이관이 사라졌다"
    assert on_disk["states"]["walk"].get("takes") == [{"label": "tween1", "frames": 1}], (
        "트윈이 기록한 테이크가 이관의 stale 쓰기에 지워졌다")


def test_migration_does_not_take_the_pipeline_writer_lock(tmp_path) -> None:
    """이관은 `.sprite-gen.lock` 도메인을 쓰지 않는다 — 그 락은 request 를 지키지 않는다.

    파이프라인 락이 지키는 것은 프레임·아틀라스 같은 단계 산출물이고, 추출·굽기는
    `sprite-request.json` 을 쓰지 않는다. 안 만지는 자원의 락을 잡으면 보호받는다는 착시만
    남는다 — 실제 경쟁자(리롤·트윈·fps 편집)는 그 락을 안 잡으므로 그대로 통과했다.
    한 자원에 격리 도메인은 하나이고, request 의 도메인은 `publish_guard` 다."""
    from sprite_gen.spec.runio import LOCK_FILENAME

    run_dir = tmp_path / "run"
    _write_request(run_dir, {"pixel_perfect": True})
    # 다른 살아있는 홀더의 최소 모형 (pid 1 = launchd/init) — 이관은 이걸 보지 않는다
    (run_dir / LOCK_FILENAME).write_text(
        json.dumps({"owner": "extract", "pid": 1, "started": 0}), encoding="utf-8")

    assert migrate_request_file(run_dir, apply=True) == ["fit.pixel_perfect -> fit.pixel_unfake"]
    assert json.loads((run_dir / REQUEST_FILENAME).read_text(
        encoding="utf-8"))["fit"] == {"pixel_unfake": True}
    # 남의 락을 소비하지도 않는다 (파일은 그대로)
    assert json.loads((run_dir / LOCK_FILENAME).read_text(encoding="utf-8"))["owner"] == "extract"


def test_migration_leaves_no_lock_residue_in_the_run_dir(tmp_path) -> None:
    """이관이 끝나면 런 디렉터리에 새로 남는 파일이 없다 — request 하나만 바뀐다.

    publish rwlock 사이드카는 런 디렉터리 **밖**(`.<name>.sg-rwlock`)에 산다. 안에 남으면
    이관 한 번이 그 런의 파일 목록·세대 판정을 건드린다."""
    from sprite_gen.spec.runio import LOCK_FILENAME

    run_dir = tmp_path / "run"
    _write_request(run_dir, {"pixel_perfect": True})
    before = {p.name for p in run_dir.iterdir()}

    migrate_request_file(run_dir, apply=True)

    assert {p.name for p in run_dir.iterdir()} == before
    assert not (run_dir / LOCK_FILENAME).exists()


def _callee_name(func: ast.expr) -> str | None:
    if isinstance(func, ast.Attribute):
        return func.attr
    if isinstance(func, ast.Name):
        return func.id
    return None


def _calls_inside_publish_guard(tree: ast.AST) -> set[int]:
    """`with publish_guard(...)` 블록 안에 있는 Call 노드 id 집합."""
    guarded: set[int] = set()
    for node in ast.walk(tree):
        if not isinstance(node, (ast.With, ast.AsyncWith)):
            continue
        if not any(isinstance(item.context_expr, ast.Call)
                   and _callee_name(item.context_expr.func) == "publish_guard"
                   for item in node.items):
            continue
        for child in ast.walk(node):
            if isinstance(child, ast.Call):
                guarded.add(id(child))
    return guarded


def test_every_request_write_is_inside_the_publish_guard() -> None:
    """구조 단정: request 를 되쓰는 프로덕션 호출은 전부 `publish_guard` 블록 안에 있다.

    런타임 경쟁 테스트만 두면 새 편집 진입점(다음 POST 핸들러)이 락 밖에서 `write_request`
    를 부르는 회귀를 못 잡는다 — 그 경로를 밟는 fixture 가 없으면 초록으로 지나간다. 그래서
    "락 안에 있다" 를 AST 로 본다.

    범위: 되쓰기 게이트(`write_request`) 호출 전부 + 이관 writer 의 원자 교체. 새 런을
    **만드는** 경로(`prepare`, `unpack_atlas` 의 스테이징)는 제외한다 — 기존 문서를 읽어
    고치는 것이 아니라 처음 발행하는 것이고, unpack 의 발행 스왑 자체는 `_publish_run` 의
    `publish_guard` 안에서 일어난다."""
    root = Path(__file__).resolve().parents[2]
    offenders: list[str] = []
    for path in sorted((root / "sprite_gen").rglob("*.py")):
        tree = ast.parse(path.read_text(encoding="utf-8"))
        guarded = _calls_inside_publish_guard(tree)
        for node in ast.walk(tree):
            if not isinstance(node, ast.Call) or _callee_name(node.func) != "write_request":
                continue
            if id(node) not in guarded:
                offenders.append(f"{path.relative_to(root)}:{node.lineno} write_request()")

    runio_path = root / "sprite_gen" / "spec" / "runio.py"
    runio_tree = ast.parse(runio_path.read_text(encoding="utf-8"))
    runio_guarded = _calls_inside_publish_guard(runio_tree)
    for node in ast.walk(runio_tree):
        if not isinstance(node, ast.FunctionDef) or node.name != "migrate_request_file":
            continue
        for child in ast.walk(node):
            if (isinstance(child, ast.Call) and _callee_name(child.func) == "atomic_write_text"
                    and id(child) not in runio_guarded):
                offenders.append(f"sprite_gen/spec/runio.py:{child.lineno} "
                                 f"atomic_write_text() in migrate_request_file()")

    assert not offenders, (
        "publish_guard 밖에서 request 를 되쓰는 경로:\n  " + "\n  ".join(offenders)
        + "\n→ 락 획득 후 fresh 재독 → 원자 교체. request 의 격리 도메인은 publish_guard 하나다")