mvschwarz/openrig-upgrade

OpenRig 업그레이드

업그레이드는 하나의 명령어 뒤에 숨겨진 트랜잭션이 아니라, 관찰되는 에이전트 워크플로입니다. 호스트는 저마다 다르고, 프로세스 상태는 변하며, 로컬 플러그인 파일은 누적되고, 실패한 단계에 대한 유용한 대응은 여전히 살아있는 것에 따라 달라집니다.

에이전트가 순서를 통제합니다. 모든 변경 후에 중단하고, 다음 단계를 선택하기 전에 실제 효과를 관찰하십시오. 의도적으로 종단 간 업그레이드 서브커맨드는 존재하지 않습니다.

안전 모델

다음 평면들을 분리하여 유지하십시오:

• 시트(seats)는 일반적으로 tmux에 존재하며 데몬 재시작 후에도 유지될 수 있습니다.
• 데몬, 데이터베이스, 래퍼(wrappers), 관리형 플러그인 프로젝션(projection)이 변경되는 제어 평면(control plane)입니다.
• rig down은 시트를 종료합니다. 연속성을 유지하는 업그레이드의 일부가 아닙니다.

작업을 수행하기 전에 연속성이 중요한 rig와 시트의 이름을 지정하십시오. 프로덕션 호스트에서는 호스트의 일반 운영자 의례(operator ceremony)를 사용하십시오. 복구에 적합한 빌드 VM에서는 오케스트레이터가 테스트된 런타임을 직접 채택할 수 있지만, 여전히 각 단계를 관찰하고 설명되지 않은 변동이 있으면 중단합니다.

복구가 인스턴스 경계를 넘을 때

두 레인(lane) 중 하나가 런타임 상태를 변경하기 전에 호스트로 한정된 실행기(executor) 하나를 기록하고, 복구 판정을 소유할 큐 저장소(queue store)를 명시적으로 선택하십시오. 원래 소유자가 계속 진행하는지, 대기하는지, 또는 이전하는지 상태를 명시하십시오. 다른 저장소에 있는 미해결 의무는 이 판정에 대한 배타적 관리권이 아닙니다. 원래 저장소가 다운된 경우, 살아있는 판정에 그 소유자의 처분을 보존하고, 경쟁 실행기가 작업을 수행하기 전에 해당 소유자에게 이를 전달하십시오.

거부된 클레임(claim)은 이후의 런타임 작업 전에 판정 소유자와 소유권을 조정해야 함을 의미합니다. 별도의 오래된 행(row) 아래에서 계속 진행하는 것을 허용하지 않습니다. 반환(return)은 전체 실행기 주소와 의도적으로 선택된 저장소를 명시합니다. 재개(resume)하기 전에 해당 행의 소스, 대상, 본문, 원래 소유자의 처분을 포함한 결과를 읽으십시오. 수신 생성(receipt creation)만으로는 대기 중인 레인이 전송을 수신했거나 수락했음을 입증하지 않습니다.

루프

각 단계마다:

1. 검사(Inspect). 라이브 호스트에서 현재 사실을 도출합니다.
2. 결정(Decide). 하나의 제한된 변경을 선택하고 예상 효과를 명시합니다.
3. 한 번만 수행(Act once). 다음 변경을 함께 묶지 마십시오.
4. 관찰(Observe). 단계가 변경했을 수 있는 프로세스, 리스너, 데이터베이스, 플러그인, 시트 표면을 확인합니다.
5. 계속, 조정, 또는 중단(Continue, adapt, or stop). 실패한 예상은 에이전트를 위한 정보이지, 맹목적인 재시도를 허용하는 것이 아닙니다.

제한된 헬퍼

SKILL_DIR을 이 SKILL.md가 포함된 디렉터리라고 합니다. 이 스크립트들은 JSON을 출력하며 업그레이드 순서를 결정하지 않습니다.

현재 사실 검사

node "$SKILL_DIR/scripts/inspect-upgrade.mjs"

이 스크립트는 설치된 rig의 버전, 데몬 상태, 노드 인벤토리, 플러그인 인벤토리를 조회합니다. 누락된 표면은 제안된 다음 탐사(probe)와 함께 표시됩니다. ready: false는 에이전트가 해결하거나 의식적으로 경계를 정해야 함을 의미합니다. 스크립트가 아무것도 변경해서는 안 된다는 뜻은 아닙니다.

SQLite 백업

먼저 연속성 스냅샷을 생성하십시오:

rig snapshot <rig-id>
node "$SKILL_DIR/scripts/backup-sqlite.mjs" \
  --source "$OPENRIG_HOME/openrig.sqlite" \
  --destination "/safe/path/openrig-before-upgrade.sqlite"

헬퍼는 대상(destination)을 덮어쓰지 않으며, 가능한 경우 sqlite3 CLI .backup 명령을 사용하고(CLI가 없을 경우 node:sqlite를 통한 인-프로세스 백업으로 폴백), PRAGMA integrity_check로 백업을 검증합니다. 데몬을 중단시키거나 데이터베이스를 복원하지 않습니다.

안전한 관리형 플러그인 새로고침 계획 또는 적용

플러그인 트리에는 스킬뿐만 아니라 훅(hooks)과 메타데이터도 포함될 수 있습니다. 마지막으로 패키징된 상위(ancestor), 대상 패키지, 라이브 설치 트리를 비교하십시오:

node "$SKILL_DIR/scripts/refresh-managed-plugin.mjs" \
  --ancestor /path/to/previous/package/plugin \
  --target /path/to/target/package/plugin \
  --live "$OPENRIG_HOME/plugins/<plugin>"

정렬된 결정들을 검토하십시오. refresh-safe 및 add-safe 파일만 적용하려면:

node "$SKILL_DIR/scripts/refresh-managed-plugin.mjs" \
  --ancestor /path/to/previous/package/plugin \
  --target /path/to/target/package/plugin \
  --live "$OPENRIG_HOME/plugins/<plugin>" \
  --apply-safe

헬퍼는 라이브 파일을 절대 삭제하지 않으며 로컬 수정을 절대 덮어쓰지 않습니다. 로컬 삭제, 라이브 전용 파일, 대상 제거, 모호한 유형은 에이전트가 해결할 수 있도록 보고됩니다. 수동 해결 후 계획을 다시 실행하십시오.

사전 0.5.9 버전 인스턴스 레이아웃 마이그레이션

버전 0.5.9는 컨텍스트 사용량 텔레메트리를 $OPENRIG_HOME/state/context-usage에, 프로바이더 텔레메트리를 state/provider-usage에, 주소 지정 가능한 라이브러리를 context/ 아래에, 기본 System World를 context/system/system-world.yaml에 배치합니다. 기존 0.5.8 홈(homes)은 에이전트 운영 마이그레이션(Agent-Operated Migration) 을 통해 이 경계를 넘습니다. 대상 런타임은 모든 새 쓰기가 표준 상태 루트를 사용하는 동안 표준 우선, 레거시 폴백을 읽습니다. 명시적으로 구성된 사용자 정의 컨텍스트 라이브러리 루트는 활성화 전반에 걸쳐 안정적으로 유지됩니다.

헬퍼는 제한적이고 검사 가능한 연산을 제공합니다. 에이전트가 그 순서와 그 사이의 대상 런타임 활성화를 소유합니다. 정확한 보호된 프리이미지(preimage) 경로로, 먼저 검사한 다음 표준 디렉터리, 기본 System World, 기존 라이브러리에 대한 구성 핀(config pin)을 준비합니다. 준비는 텔레메트리를 복사하거나, 라이브 수집기 설정을 다시 쓰거나, 라이프사이클 작업을 실행하지 않습니다.

--help는 인스턴스를 인벤토리하지 않고 단계 문법을 출력합니다. 단계 플래그가 없으면 헬퍼는 의도적으로 읽기 전용 계획을 실행합니다. 알 수 없는 옵션은 계획 또는 변경 전에 0이 아닌 값으로 실패합니다.

node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" --help

node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" \
  --home "$OPENRIG_HOME"

node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" \
  --home "$OPENRIG_HOME" \
  --apply-state \
  --preimage "$OPENRIG_HOME/backups/layout-0.5.9-before"

일반 업그레이드 워크플로를 사용하여 정확한 대상 런타임을 활성화하십시오. 그런 다음 모든 제한된 사후 적용(post-apply) 레거시 테일(tail) 뒤에 동일한 시트에 대한 새로운 쌍을 이루는 새 루트 샘플이 나올 때까지 기다리십시오. 이는 전면적인 프로세스 교체 없이 시간적 수렴을 증명합니다. 이후의 레거시 쓰기는 하드 스탑입니다. 검증 JSON을 캡처하십시오. 복사된 오래된 사이드카는 증거가 아닙니다:

node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" \
  --home "$OPENRIG_HOME" \
  --verify \
  --preimage "$OPENRIG_HOME/backups/layout-0.5.9-before" \
  > /safe/path/layout-0.5.9-verify.json

성공적인 수신만이 별도로 호출되는 비파괴적 최종화(finalizer)를 승인합니다. 아무것도 덮어쓰지 않고 구성되지 않은 레거시 라이브러리를 표준 루트로 복사합니다. 사용자 정의 컨텍스트 라이브러리 루트는 안정적으로 유지됩니다:

node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" \
  --home "$OPENRIG_HOME" \
  --apply-library \
  --preimage "$OPENRIG_HOME/backups/layout-0.5.9-before" \
  --verification /safe/path/layout-0.5.9-verify.json

보고된 모든 문제(잘못된 형식 또는 외부 텔레메트리, 예약된 경로 충돌, 라이브러리 충돌, 구성 변동, 재개된 레거시 쓰기, 바이트 변동, 누락된 신규 이중 샘플 등)에서 중단하고 계속하기 전에 명명된 복구가 필요합니다. 검증은 정확히 허용된 꼬리 바이트를 쌍을 이루는 새 샘플에 바인딩합니다. 최종화는 구성을 전환하기 직전에 이를 재검증합니다. 헬퍼는 레거시 텔레메트리나 라이브러리를 절대 제거하지 않습니다. 이후의 폐기는 안정적인 런타임, 라이터, 리더, 복구 증명 후 별도의 에이전트 결정입니다. 데몬을 시작/중지하거나, 시트를 실행하거나, 데이터베이스를 건드리거나, 업그레이드 진행 여부를 결정하지 않습니다.

복구하려면 에이전트 주도 워크플로에 따라 이전 런타임을 복원한 다음, 헬퍼가 소유한 구성, System World, 빈 디렉터리, 복사된 라이브러리 효과만 되돌리십시오. 실제 상태 샘플과 두 레거시 복구 소스는 검사를 위해 남아 있습니다:

node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" \
  --home "$OPENRIG_HOME" \
  --rollback "$OPENRIG_HOME/backups/layout-0.5.9-before"

에이전트 주도 연속성 업그레이드

이것은 명령어 레시피가 아닌 결정 가이드입니다. 현재 호스트에 맞게 경로와 검사를 조정하십시오.

1. 헬퍼를 사용하여 현재 CLI, 데몬, 노드, 플러그인을 검사합니다.
2. 활성 작업을 체크포인트하고 정확한 보호된 tmux/세션 인구 조사를 기록합니다.
3. 보호되는 각 rig에 대해 rig snapshot <rig-id>를 실행합니다.
4. SQLite 백업을 생성하고 검증합니다.
5. 대상 런타임을 별도로 빌드 또는 스테이징합니다. 라이브 데몬을 건드리기 전에 버전과 소스 정체성을 증명하십시오.
6. rig daemon stop을 실행합니다. 리스너와 식별된 데몬 프로세스가 모두 사라졌는지 확인하십시오. 둘 중 하나라도 남아 있는 상태에서 명령이 반환되면 중단하십시오. 정체성을 검사하고 호스트의 승인된 복구 절차를 사용하십시오. PID에 맹목적으로 시그널을 보내지 마십시오.
7. 대상을 시작하기 전에 대상의 시작 시 관리형 플러그인 및 표시된 글로벌 스킬 새로고침을 설명하십시오. 이 런타임은 대체된 파일을 $OPENRIG_HOME/backups/managed-refresh/ 아래에 보존하고 각 복구 경로를 보고합니다. 대상에 해당 보존 기능이 없으면 먼저 해당 트리를 복사하십시오. rig daemon start 또는 호스트의 알려진 래퍼로 시작하십시오. 데몬 상태, 프로세스 경로, 리스너, 버전, 데이터베이스 무결성을 확인하십시오. 복구 복사본은 바이트를 보존합니다. 새로고침 후 사용자 정의 동작이 활성 상태로 유지된다는 것을 보장하지 않습니다.
8. 플러그인 새로고침 헬퍼를 계획 모드로 실행하십시오. 계획은 헬퍼의 이후 쓰기만 제어하며, 이미 발생한 시작 쓰기는 제어하지 않습니다. 세 루트와 분류가 이해된 후에만 안전한 쓰기를 적용하십시오. 필요한 경우 보존된 경로를 하나씩 해결하십시오.
9. rig ps --nodes -A --json, 대표적인 rig capture, 해당되는 경우 rig restore-check로 보호된 시트를 확인하십시오. -A는 필수입니다. 이것 없이 노드 읽기는 현재 rig만 읽으며, 데몬 업그레이드는 호스트의 모든 rig에 걸쳐 시트를 보호하므로 좁은 형식은 성공을 보고하지만 rig 외부의 시트는 확인되지 않은 상태로 남습니다.
10. 해당 호스트가 래퍼를 소유하는 방식을 도출한 후에만 래퍼를 정렬하십시오. 기존 메커니즘을 사용하십시오. 이 스킬은 런처를 다시 작성하지 않습니다.
11. 관찰된 결과, 남은 로컬 보존 결정, 정확한 롤백 런타임 및 백업을 기록합니다.
12. 새 버전에서 변경된 사항(rig context get reference/whats-new.md)을 읽고, 사용자에게 작업 방식을 변경하는 내용이 있으면 알려주십시오.

다음 상황에서 중단하고 반환하십시오

• 업그레이드 전에 보호된 tmux 세션이 누락된 경우
• 데이터베이스 무결성 또는 백업 검증이 실패한 경우
• 실행 중인 프로세스 또는 리스너가 예상 런타임과 일치하지 않는 경우
• 데몬 중지가 성공을 보고했지만 식별된 프로세스 또는 리스너가 남아 있는 경우
• 대상이 기존 데이터베이스에 대해 시작할 수 없는 경우
• 플러그인 루트를 알려진 상위 및 대상에 연결할 수 없는 경우
• 필수 플러그인 경로가 로컬 수정 또는 삭제됨으로 분류되고 올바른 소유권 결정이 명확하지 않은 경우
• 계속하려면 rig down, 파괴적 복원, 자격 증명 변경, 또는 운영자가 가진 것보다 더 넓은 권한이 필요한 경우

중단할 때, 마지막으로 양호한 상태, 첫 번째 실패한 예상, 정확한 증거, 소유자로부터 필요한 가장 작은 결정을 보고하십시오. 복구에서 특별히 요구하지 않는 한 라이브 시트와 데이터베이스를 보존하십시오.

롤백도 에이전트 주도입니다

여전히 유효한 데이터베이스에 대해 이전에 알려진 런타임을 시작하는 것을 선호하십시오. 마이그레이션이나 손상 발견이 필요할 때만 데이터베이스 백업을 복원하십시오. 저하된 프로젝션만으로는 데이터베이스를 교체해야 한다는 증거가 아닙니다. 롤백 후에는 순방향 경로에서 사용된 것과 동일한 프로세스, 리스너, 데이터베이스, 플러그인, 시트 관찰을 반복하십시오.