• ARCA 0.1.15

    hanyul released this 2026-10-03 10:53:07 +09:00

    0.1.15 ea001ce2b3 554 commits

    ARCA 0.1.15 변경 사항

    이전 버전: 0.1.14. Builder 입력 오류 code와 player SDK 실패 분류를 바로잡고, 공식 RTP 다운로드를 무수신 timeout·재시도·이어받기로 바꾸고, release 출력 덮어쓰기 방지와 smoke 도구를 정리한 release다. native runtime(mkxp-z core JS·WASM)은 0.1.13·0.1.14와 같다. 새 공개 export·schema·오류 code·CLI 명령·Builder subcommand는 없고 삭제된 공개 API도 없다. rgss23-runtime-status-v1, 오류 code enum, inspection v1/fingerprint ABI, Builder 기본 출력·exit code는 그대로다.

    업그레이드 시 확인할 동작 변경

    삭제된 공개 API는 없다. 다만 아래는 기존 host가 관찰하는 결과가 달라질 수 있으므로 pin 갱신 전에 확인한다.

    • Builder 입력 오류 code: 0.1.14가 BUILDER_INTERNAL로 보고하던 입력 오류를 BUILDER_SOURCE_INVALID(game mkxp.json의 JSON parse 오류·object 아님·기존 fontSub·preloadScript·postloadScript 형식 오류, sanitizeInvalidPngTrns가 고른 tRNS PNG의 구조 오류)와 BUILDER_CONFIG_INVALID(build.json fontSubstitutions 값 형식 오류. source를 읽기 전 config 단계에서 거부)로 보고한다. 새 code는 없고 새 message는 mkxp.json must be valid UTF-8. 하나다. --failure-report code에서 BUILDER_INTERNAL만 가정한 host 분기는 확인이 필요하다.
    • Builder 입력 수용 범위: 비 UTF-8 game mkxp.json은 U+FFFD로 바뀐 채 성공하던 것이 BUILDER_SOURCE_INVALID로 거부된다. sanitizeInvalidPngTrns: true는 inspect와 같은 chunk-header 판정으로 gray+alpha·RGBA인데 tRNS가 있는 PNG만 읽어 고치므로, tRNS 없는 손상 PNG 때문에 실패하던 입력은 그 PNG를 그대로 담아 성공한다. inspector는 64 MiB를 넘는 Scripts를 읽지 않고 같은 finding을 낸다(출력 불변). 제공 VX·VX Ace의 package SHA-256과 inspect v1·v2 출력은 0.1.14와 같다. UTF-8 BOM Game.ini 미지원은 유지한다.
    • player SDK launch abort 분류: runtime 준비·mount·시작 중 launch signal이 abort되면 MOUNT_FAILED(runtime-prepare-failed·runtime-mount-failed)나 RUNTIME_ABORTED/runtime-start-failed 대신 RUNTIME_ABORTED/aborted로 보고한다. 같은 시점에 native fatal이 먼저 났으면 runtime-fatal이 우선한다. runtime factory가 abort를 무시하고 반환해도 runtime을 시작하지 않는다. 이때 2단계 prepareRgss23Player()는 prepared로 resolve한 뒤 failed로 바뀌는 대신 같은 오류로 reject한다.
    • save commit 충돌: SAVE_COMMIT_FAILED의 revision 충돌은 retryable: false다(0.1.14는 true). 같은 player가 다시 시도해도 같은 expectedRevision을 보내므로 최신 save를 restore하는 relaunch가 필요하다. restore(SAVE_RESTORE_FAILED) 충돌은 그대로 true다.
    • 공식 RTP 다운로드: 재시도 없는 300초 전체 timeout 대신 60초 동안 데이터를 받지 못하면 그 시도를 끝내고 전체는 1시간까지 허용한다. 한 prepareArcaRtp() 호출 안에서 네트워크 전송 오류·HTTP 5xx·429·무수신을 최대 3회 다시 시도하고(약 2·8·30초 backoff와 jitter, 5xx·429의 Retry-After보다 짧게 기다리지 않으며 5분을 넘는 Retry-After면 중단), 서버가 받은 위치·전체 크기가 맞는 206·Content-Range로 응답할 때만 이어 받는다. 계속 멈추는 서버는 약 4~5분 뒤 실패로 보고된다. host 자체 timeout·재시도와 겹치는지 확인한다.
    • RTP timeout 오류 분류: ARCA 내부 무수신·전체 시간 초과는 0.1.14의 TimeoutError 대신 ARCA_RTP_DOWNLOAD_FAILED이고 error.cause.name이 TimeoutError다. 호출자 signal의 AbortError·TimeoutError는 그대로다.
    • contracts fixture 값: @rgss23/contracts/builder의 createRgss23BuilderInspectionV2Fixture().scripts가 0.1.14에서는 escape 누락으로 DataScripts.rvdata였고 Data\Scripts.rvdata로 고쳤다. Rgss23BuilderFindingSeverity는 이름·구조가 같고 d.ts에서 Rgss23FindingSeverity alias로 표기된다.
    • artifact identity: runtime ZIP은 SDK module(dist/rgss23-player.mjs)·provenance.json·SHA256SUMS만, contracts tgz는 dist/builder.* 3개와 package.json만 0.1.14와 다르다. inspector·packager 변경으로 Builder OCI digest가 바뀌었다. host는 새 release pin·Builder digest를 함께 적용한다.

    추가된 API·계약

    없다. 공개 export·schema·오류 code·CLI 명령·Builder subcommand와 flag를 추가하거나 삭제하지 않았다. packager README에 Builder가 이미 적용하던 build.json 규칙을 Builder 설정 계약으로 문서화했다(contracts schema·parser는 아니다).

    성능

    • getArcaRelease(): integrity.json이 이미 hash한 release artifact를 다시 읽지 않고 그 digest와 파일 크기를 manifest·pin과 대조한다. 0.1.14 package 사본의 로컬 측정에서 호출당 읽기가 250.9 MiB에서 149.5 MiB로 줄었다. 오류 code·message는 같다. 성능 보장이 아니다.
    • player SDK의 runtime JS/WASM staging chunk 복사를 1회 줄였다(관측 동작 동일).

    저장소·도구 정리

    • release 출력 덮어쓰기 방지: release:build·release:builder·release:npm은 같은 version 출력이 있으면 아무것도 지우거나 쓰기 전에 거부한다(--replace-unpublished만 예외). release:build와 standalone release:npm은 tracked 변경(staged 포함)과 packages/·tools/release/의 비추적 파일을 생성 전에 거부한다(--allow-dirty만 예외, 그 출력은 게시하지 않는다).
    • release script가 Windows에서 %SystemRoot%\System32\tar.exe(bsdtar)를 직접 사용해 release:test·release:verify·release:npm:test가 Git Bash에서도 실행된다. release 단계 contracts tarball 검증은 npm /deploy와 같은 내부 reader로 unsafe 경로·header 손상을 ARCA_CONTRACTS_* code로 거부한다. typecheck가 package를 먼저 build한다.
    • 참조 없는 script(release:archives, raw package:vx-ace), 비공개 packager barrel의 소비자 없는 export(packagePortableRpgVxRtp·packageFixtureRgssProjectWithInspection)와 호출자 없는 verifyPortableRgssOverlay, pnpm-workspace.yaml의 onlyBuiltDependencies(pnpm 11.9.0 미사용)를 지웠다. player SDK 오류 판정 helper를 내부 모듈로 모았다.
    • reference app은 restore한 save와 같은 bytes를 OPFS에 다시 쓰지 않는다.
    • smoke 도구: VX Ace RTP를 쓰는 runtime·browser smoke가 검증된 로컬 pin cache(rtp:vx-ace:acquire)를 공유하고, package:rpgvx-rtp는 lock과 일치하는 기존 출력을 재사용한다. 실패 run의 report·PNG와 failure-evidence.json을 보존하고, build를 엔진당 한 번만 실행하는 browser:smoke:batch를 추가했다. Edge no-input 관찰 창이 timer 조기 기상 때 계약 하한보다 1 ms 짧게 기록되던 간헐 실패를 고쳤다. 계약 판정 기준·gold·report 형식은 그대로다.
    • 문서: README를 프로젝트 소개 중심으로 다시 구성하고 출하 README(packager·npm)의 0.1.15 변경·RTP 재시도 서술을 코드와 맞췄다.

    검증 범위와 알려진 제한

    합성·단위 검증, 제공 fixture 자동화와 사람의 입력·실제 청취·완전 종료 저장 acceptance는 별도 판정한다. 이번 release는 새 사용자 acceptance를 포함하지 않으며 사람 검토, 실제 청취, LINKS 통합과 장시간 검증은 NOT RUN이다.

    • 공식 RTP 다운로드의 재시도·Range 이어받기·무수신 경로는 loopback mock server로만 검증했다. 실제 공식 서버 다운로드는 1회 PASS였고 그 실행에서 재시도 경로는 확인하지 않았다.
    • browser·runtime smoke는 0.1.14 이후 정리 통합 tree에서 대표 시나리오(Edge VX Ace save-load·movement-cancel, Firefox VX Ace action-event, Edge VX action-event·cancel-menu, runtime:smoke:isolated-player·restart)만 자동 PASS다. gold가 있는 22개 전체 재실행은 이번 release에서 하지 않았다.
    • native runtime clean rebuild 재현: FAIL(0.1.14와 같은 상태). 같은 lock·recipe·patch로 다시 빌드한 WASM이 0.1.13과 다르다(CRuby/WASI Stage 1 산출물 비결정). 0.1.15는 0.1.13·0.1.14와 같은 runtime export를 사용하므로 배포 runtime에는 영향이 없다.
    • LINKS형 기본 저장소 경로는 package를 WASM heap에 복사한다. 로컬 측정에서 WASM memory는 VX Ace 597 MiB, 제공 VX 1,045 MiB(2 GiB 한도의 51%)였다. 큰 게임에서는 메모리 여유를 확인한다.
    • UTF-8 BOM이 있는 Game.ini는 지원하지 않는다(형식 오류로 처리).
    • Linux release 재현은 NOT RUN이다.

    게시 identity와 registry 검증은 현재 상태, 상세 값은 해당 release manifest/pin을 따른다.

    배포 검증

    • release source: ea001ce2b3
    • manifest SHA-256: 8edfa50823ae3bd5f633671b31c500649da985dd2b2dcfdae177f37929bdf826
    • Builder digest: sha256:8c258f8a30b6af3d0c9f4237ef4871505f6625ab4e7e5cad91bbffb7120646e1
    • native runtime: rgss23-core.js 1e9d9349…, rgss23-core.wasm 5e0e8586…, core·frontend provenance, configuration, license 45개가 0.1.14 runtime ZIP과 byte 단위로 같다.
    • 단위 테스트 376개, 타입 검사, release 회귀 33개(PowerShell·Git Bash), browser 도구 회귀 36개, native patch 정적 검사 6개, native lock·recipe 검증: PASS.
    • release build·verify, npm 생성, source-free SDK/types/contracts/runtime 결속/Builder/CLI 소비: PASS. release Builder gate와 consumer gate는 공개 helper arcaBuilderRunArguments()의 격리 인자로 실행된다.
    • 0.1.15 Builder OCI에서 v2 inspect·진행 파일·failure report 실행(생성된 npm package helper 사용): PASS. 제공 VX Ace archive는 browser fixture package와 hash가 같다.
    • verifyArcaRuntimeDirectory()(53개 파일)·verifyArcaContracts()(45개 파일)·arca-release verify-contracts: PASS.
    • 공식 RTP Windows 다운로드·추출·cache: PASS.
    • 별도 clean worktree에서 runtime export를 입력으로 고정한 release pin·artifact·Builder digest·npm bytes 재현: PASS.
    • npm: @rgss23/arca@0.1.15 (Forgejo registry).

    0.1.14 대비 전체 변경

    Downloads 9