---
status: PEER_REPLICA_REPAIR_MAILBOX_SELF_TESTED_DEFAULT_OFF_NOT_LIVE
candidate_version: 1.4.81-node-bound-distinct-upnp-port-default-off-locked
candidate_bytes: 481811
candidate_sha256: bbac9679202b815127ec270ea8646f56d1abb872ff6e652e3bfc9556f358ce96
production_repair_activated: false
production_storage_touched: false
router_mapping_changed: false
operator_signing_used: false
validator_signing_used: false
---

# 메인 독립 peer replica-repair mailbox staging

## 목적

기존 3복제·노드 상실·4번째 노드 보충 canary는 데이터 경로를 증명했지만 repair assignment는 메인 AISFOR 프로세스가 계산했다. 이번 단계는 동일한 ciphertext manifest와 적격 노드 집합을 받은 PC들이 메인 없이 같은 repair winner를 계산하고, 3개 peer vote와 짧은 fencing lease가 없으면 수리를 실행하지 못하게 하는 control plane을 staging한다.

## 프로토콜

`E:\aisfor\services\peerReplicaRepairProtocol.js`는 다음을 검증한다.

1. finalized RPC block과 proposal의 chain/epoch/block hash 결합
2. candidate별 유효한 permissionless admission certificate, `storage` capability, failure-domain commitment, 가용 용량
3. 후보 순서와 무관한 deterministic repair election
4. 기존 healthy replica와 다른 failure domain 우선
5. 서로 다른 node key 3표와 failure domain 최소 2개
6. proposal/election/selected nodes/expiry를 묶은 fencing token
7. epoch rollback과 동일 epoch equivocation 거부
8. 선택된 node key만 ciphertext hash·bytes가 일치하는 repair receipt에 서명 가능

순수 protocol self-test는 후보 순서 결정성, 3표/3-domain 집계, 2표·동일 domain·rollback·equivocation·미선택 노드·receipt 변조 거부를 통과했다.

## PC Sync 연결

후보 `1.4.81-node-bound-distinct-upnp-port-default-off-locked`에 다음 endpoint가 추가됐다.

- `POST /gateway/replica-repair/proposal`
- `GET|POST /gateway/replica-repair/vote`
- `GET /gateway/replica-repair/certificate`
- `POST /gateway/replica-repair/execute`

feature `peerReplicaRepairEnabled`와 환경 잠금 `AISFOR_PEER_REPLICA_REPAIR_ENABLED`는 capability admission, public relay, RPC attestation, stateless capsule gate 뒤에 있다. rollout policy와 직접 환경 설정이 모두 기본 false다.

embedded self-test는 admission certificate가 있는 storage node 한 대를 deterministic winner로 선택하고, 3개 증인 vote/3개 failure domain을 집계해 fencing token을 생성했으며 2표를 거부했다. 선택 노드는 임시 디렉터리에 4096-byte ciphertext를 저장·재읽기·hash 검증하고 Ed25519 receipt를 만들었다. 미선택 노드와 변조 ciphertext는 거부됐다. self-test는 production chunk·DB·router를 사용하지 않았다.

증거: `evidence/peer-replica-repair-self-test-redacted.json`

## 운영 안정성 관찰

read-only PM2 확인 중 기존 `persistentStore`가 고정 `ledger.json.tmp`를 rename하다 Windows `EPERM`으로 종료된 흔적을 발견했다. 새 replica 기능과 무관한 기존 파일 교체 경로다. 실행 중 프로세스는 재시작하지 않고 다음 정상 배포에 적용될 소스만 보강했다.

- temp 파일명을 PID+UUID로 분리
- `EPERM`, `EBUSY`, `EACCES`, `ENOTEMPTY`, `EEXIST`만 최대 8회 bounded retry
- `ENOENT` 등 비재시도 오류는 즉시 실패
- 성공·실패 뒤 unique temp 정리
- ledger와 Mongo read snapshot writer에 동일 helper 사용

`scripts/atomic-file-replace-self-test.js`는 두 번의 simulated `EPERM` 뒤 성공, 비재시도 오류 즉시 실패, 실제 임시 디렉터리 atomic replacement와 잔여 temp 없음까지 확인했다. production data file은 건드리지 않았다.

## 남은 live gate

실제 PC ciphertext repair와 peer manifest 승격은 아직 하지 않았다. 다음은 명시적 public-PC/router 승인 후에만 수행한다.

1. 실제 PC들이 동일 proposal을 독립 검증하고 3표 certificate를 교환
2. 선택된 node만 fencing lease 안에서 ciphertext를 받아 hash 검증 후 보관
3. 미선택·만료·이전 epoch 요청 거부
4. 메인 cache를 쓰지 않고 peer manifest에 repaired replica receipt 반영
5. 별도 outage window에서 메인 격리 상태의 loss→election→repair→restore 증명
