• ARCA 0.1.14

    hanyul released this 2026-10-03 02:06:55 +09:00

    0.1.14 33eb223935 661 commits

    ARCA 0.1.14 변경 사항

    이전 버전: 0.1.13. host 통합 helper·launch lifecycle·Builder 계약을 더하고 packager 성능과 release 재현성을 고친 release다. native runtime(mkxp-z core JS·WASM)은 0.1.13과 같다. 게시된 0.1.x 공개 API·rgss23-runtime-status-v1·오류 code enum·inspection v1/fingerprint ABI·Builder subcommand는 바꾸지 않았고, 새 정보는 opt-in 옵션·새 export·새 schema로만 추가했다.

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

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

    • player SDK 실패 분류: 일부 launch 실패의 code·retryable이 바뀐다. 다운로드 stream 실패·조기 종료는 ARTIFACT_INVALID(retryable), cache writer·조회 실패는 CACHE_UNAVAILABLE(quota는 retryable false), prepareLayout 중 abort는 RUNTIME_ABORTED, 빈 save 적용 실패는 SAVE_RESTORE_FAILED. 이전에는 주로 LAUNCH_INVALID(재시도 불가)였다. LAUNCH_INVALID만 가정한 host 분기는 갱신이 필요하다.
    • 손상 cache 자가 복구: 기본 저장소 cache의 크기·hash 불일치 때 artifact별 1회 source에서 다시 받는다(cacheRecovery: "fail"로 끌 수 있다). 기본 저장소 artifactCache.put 실패는 기본 best-effort다(artifactCacheWrite: "required"면 기존처럼 실패).
    • 입력 해제: 창 blur·hidden·pagehide·canvas focus 이탈·pointer lock 해제 때 눌린 키와 mouse button을 놓는다.
    • save key: 기본 저장소가 Windows device name segment(CON, aux.rvdata2, com1.dat 등)를 그대로 key로 써 SAVE_COMMIT_FAILED가 나던 결함을 고쳤다. 그런 경로만 arca-path-v1/로 escape하며 기존 key는 byte 단위로 같다.
    • Builder 사전 거부: package는 VX config의 syntaxTransform이 2가 아니거나 rtpManifest가 game engine·Game.ini RTP와 맞지 않으면 거부한다. inspect는 path·classic ZIP 한계·대소문자 충돌을 blocked finding으로 먼저 보고하고, script masking이 불확실하면 scripts:lexer-uncertain으로 보고한다(이때 package-bound report의 staticInspection이 partial). 엔진 data가 섞인 source는 Scripts 확장자로 판정하고 warning을 남긴다(이전에는 실패).
    • Builder 입력 계약: Game.ini root 탐색·[Game] parse·Library·Scripts·RTP 대조 규칙을 공개 입력 계약으로 명시했다. 동작 변경은 대소문자만 다른 복수 Game.ini 중 inspect가 읽을 파일을 UTF-8 byte 순으로 정한 것뿐이다(Node 24 기존 결과와 같다).
    • RTP 오류 code: getArcaRtp()·prepareArcaRtp() 실패에 실패 단계의 ARCA_RTP_* code가 붙는다(새 ARCA_RTP_OUTPUT_FAILED). message는 0.1.13과 같고, 하위 오류는 같은 message의 새 Error로 감싸질 수 있다(원래 오류는 cause).
    • arca-release 실패 출력: stack trace 대신 stderr CODE: message 한 줄로 출력한다. exit 1은 같다.
    • artifact identity: contracts·npm tgz의 gzip header OS byte를 build OS와 무관하게 0x03으로 고정했다(0.1.13은 0x0a). Builder·inspector·packager 변경으로 Builder OCI digest가 바뀌었다. host는 새 release pin·Builder digest를 함께 적용한다.

    추가된 API·계약

    • @rgss23/arca/deploy: verifyArcaRuntimeDirectory()(해제한 runtime 디렉터리를 release manifest의 runtime ZIP과 1:1 대조, ARCA_RUNTIME_*), verifyArcaContracts()(package contracts/가 pin된 contracts tarball과 같은지 검증, ARCA_CONTRACTS_*), Builder 실행 helper getArcaBuilderIsolation()·arcaBuilderRunArguments()·loadArcaBuilder()(ARCA_BUILDER_*), getArcaRelease()·stageArcaRelease()의 ARCA_RELEASE_* code. CLI verify-contracts·builder-isolation·builder-load·--help.
    • player SDK: prepareRgss23Player()(준비와 사용자 클릭 시작 분리), onLaunchProgress(rgss23-launch-progress-v1), onLaunchMetrics(rgss23-launch-metrics-v1), Rgss23PlayerError.reason·artifactRole, Rgss23CacheIntegrityError, cacheRecovery, artifactCacheWrite, host cache get 요청의 onProgress, keyboard.passthrough.
    • @rgss23/contracts: /launch-lifecycle(실패 reason·진행률·계측 schema·parser·fixture), /builder(rgss23-builder-failure-v1, rgss23-builder-inspection-v2, rgss23-builder-progress-v1).
    • Builder OCI: 세 subcommand의 opt-in --failure-report /output/<name>.json, --progress stderr|/output/<name>.ndjson, inspect --format rgss23-builder-inspection-v2(검토용 권장 build 설정이며 자동 적용하지 않는다). library onProgress.

    성능

    • packager: CRC32를 node:zlib로 바꾸고 archive hash를 쓰기 중 계산하며, verifier를 1 MiB 단일 순차 pass·상수 메모리로 바꿨다. 출력 bytes는 같다. 로컬 측정(Node 24, Windows): 300 MiB 단일 파일 Builder package 5.3 s/400 MiB RSS → 2.4 s/82 MiB, locked Ace RTP cache 검증 약 2 s → 0.25 s, 공식 RTP 최초 준비 peak 약 617 MiB → 168 MiB. 성능 보장이 아니다.

    저장소·도구 정리

    • 제공 VX overlay와 native-vx-compatible.lock.json의 source fingerprint를 inspector의 UTF-8 byte 정렬 기준으로 갱신했다. 2026-08-09 정렬 고정 이후 package:vx:browser:compatible·browser:prepare:vx가 fingerprint 불일치로 실패하던 저장소 결함이다. 원본과 compatible archive hash는 같다.
    • 더 이상 쓰지 않는 VX Ace native 진단 chain(tools/native-vx-ace/, native:vx-ace:* script, builder·runner·baseline lock)을 삭제했다. 0.1.12·0.1.13 release note의 VX Ace native baseline verifier 실패는 이 chain과 함께 사라졌다. VX Ace legacy RTP cache 취득은 rtp:vx-ace:acquire로 옮겼다.
    • 비공개 manifest package를 inspector에 병합하고 비공개 package의 미사용 bin·subpath·script를 제거했다. browser·runtime smoke 공통 모듈을 정리했다.
    • browser smoke gold를 decoded RGBA SHA-256으로 비교하고 browser version 불일치는 실패와 구분된 drift로 보고한다. VX·VX Ace save-load smoke의 입력·캡처 timing flaky를 결정적으로 고쳤다.
    • 문서를 현재 계약 중심으로 통합·축소하고 README를 프로젝트 소개로 다시 썼다.

    검증 범위와 알려진 제한

    합성·단위 검증, 제공 fixture 자동화와 사람의 입력·실제 청취·완전 종료 저장 acceptance는 별도 판정한다. 갱신된 smoke gold의 사람 검토, 실제 청취, LINKS 통합과 장시간 검증은 NOT RUN이다.

    • native runtime clean rebuild 재현: FAIL. 같은 lock·recipe·patch로 다시 빌드한 WASM이 0.1.13과 다르다(CRuby/WASI Stage 1 산출물 비결정, 0.1.0/0.1.3·0.1.6/0.1.8에서도 있던 성질). 0.1.14는 0.1.13 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: 33eb223935
    • manifest SHA-256: d79c78ea1d44e04787ed13d06960218ef4f0d691e7b9650e3541d957e116b81d
    • Builder digest: sha256:d53f140824c038bd32dbacd4a39e97b767e5c78afb858a9e95edbb4bdf21c332
    • native runtime: rgss23-core.js 1e9d9349…, rgss23-core.wasm 5e0e8586…, core·frontend provenance, configuration, license 45개가 0.1.13 runtime ZIP과 byte 단위로 같다.
    • 단위 테스트 352개, 타입 검사, release 회귀 24개, native lock·recipe 검증: PASS.
    • release build·verify, npm 생성, source-free SDK/types/contracts/runtime 결속/Builder/CLI 소비: PASS.
    • release Builder gate가 공개 helper와 같은 격리(user 10001:10001, init, read-only rootfs, network none, cap_drop ALL, no-new-privileges, tmpfs, memory 1 GiB)로 실행됨을 확인: PASS. 0.1.14 Builder OCI에서 v2 inspect·진행 파일·failure report 실행: PASS.
    • 공식 RTP Windows 다운로드·추출·cache: PASS.
    • 별도 clean worktree에서 runtime export를 입력으로 고정한 release pin·artifact·Builder digest·npm bytes 재현: PASS.
    • browser smoke(0.1.13 runtime, Edge 154·Chrome 154·Firefox 153): gold가 있는 22개 자동 PASS.
    • npm: @rgss23/arca@0.1.14 (Forgejo registry).

    0.1.13 대비 전체 변경

    Downloads 9